Skip to main content

Tool Architecture

Two Tool Patterns​

The site uses two different patterns for tool pages:

1. Iframe-Embedded Tools​

External applications embedded via iframe. Managed centrally through src/config/tool-registry.ts.

Pages:

  • /product-list → https://novastar.show/
  • /calibration-request → https://calib.novastar.wiki/
  • /download → /proxy/download (forwarded by Pages Functions)

2. Native React Tools​

Self-contained React components built directly into the site. No iframe, full control over UI and state.

Pages:

  • /h-series-configurator → src/components/h-series/HSeriesConfigurator.tsx
  • /fiber-converter-compatible-tools → src/components/compatible-tools/CompatibleTools.tsx
  • /loading-capacity-calculator → src/components/loading-capacity/LoadingCapacityCalculator.tsx

Iframe Tool Code Structure​

  • src/config/tool-registry.ts
    • Centralized tool configuration (title, description, iframe URL, timeout, new-tab URL, etc.).
  • src/components/ui/EmbeddedToolFrame.tsx
    • Renders iframe in a unified way and handles loading, timeout, errors, and retries.
    • Supports reusing the same iframe instance across routes to reduce reloads during navbar navigation.
  • src/pages/*.tsx
    • Pages only read registry config and render EmbeddedToolFrame.

Iframe Configuration Fields​

Main fields of EmbeddedToolConfig:

  • id: Unique tool identifier, also used as the iframe reuse key.
  • pageTitle / description: Page metadata.
  • iframeTitle: iframe title.
  • src: iframe source URL.
  • openInNewTabUrl: URL to open in a new tab when loading fails.
  • timeoutMs: iframe loading timeout in milliseconds.
  • persistAcrossNavigation: Whether to keep iframe alive across route navigation.
  • sandbox: iframe sandbox attribute (configure per page requirements).
  • referrerPolicy: iframe referrer policy.

Iframe Page Integration Pattern​

import React from 'react'
import Layout from '@theme/Layout'

import { EmbeddedToolFrame } from '../components/ui'
import { EMBEDDED_TOOLS } from '../config/tool-registry'

export default function ProductListPage() {
  const tool = EMBEDDED_TOOLS.productList

  return (
    <Layout title={tool.pageTitle} description={tool.description}>
      <main className="w-full">
        <div id="tw-scope" className="w-full">
          <EmbeddedToolFrame config={tool} />
        </div>
      </main>
    </Layout>
  )
}

Shared UI Components​

Native React tools share common components from src/components/ui/:

SearchableSelect​

A searchable dropdown component used across multiple tool pages for consistent UX.

import { SearchableSelect, SelectOption } from '../components/ui'

const options: SelectOption[] = [
  { id: 'item-1', label: 'Item One', sublabel: 'Optional detail' },
]

<SearchableSelect
  label="Field Label"
  options={options}
  value={selectedId}
  onChange={(id) => setSelectedId(id)}
  placeholder="Select an item..."
/>

Props:

  • options: Array of { id, label, sublabel? } objects.
  • value: Currently selected item ID (or null).
  • onChange: Callback when selection changes.
  • label: Section heading above the dropdown.
  • placeholder: Placeholder text when nothing is selected.

EmbeddedToolFrame​

See iframe integration pattern above.

Verification Commands​

npm run typecheck
npm run build