port-calculator

name	port-calculator
description	Port an HTML calculator from MechEngine to MechCodex Next.js. Follows the bending-stress gold standard template exactly — 6 tabs, KaTeX theory, v3 SVG diagrams, auto-calc, section-aware Compare, 6 Design tools.
metadata	{"priority":9,"promptSignals":{"phrases":["port calculator","port this calculator","convert to Next.js","port to mechcodex","html to react","mechengine to mechcodex"],"minScore":5}}

Port Calculator — MechCodex Skill

Reference

Gold standard: /Users/mihirpatel/Downloads/MechEngine/strength-of-materials/bending-stress.html Port template: /Users/mihirpatel/Downloads/mechcodex/components/calculators/native/bending-stress/

File Structure (must match exactly)

components/calculators/native/<slug>/
├── <Slug>Calculator.tsx       # top-level: calc-shell > calc-main > Sidebar + Content
├── Sidebar.tsx                 # inputs, section selector, unit toggles
├── Content.tsx                 # tab routing
├── tabs/
│   ├── ResultsTab.tsx          # outputs + SVG diagrams
│   ├── TheoryTab.tsx           # 11+ sections, KaTeX, term tables
│   ├── ChartTab.tsx            # 4 canvas charts 2×2 grid
│   ├── CompareTab.tsx          # section comparison bar chart
│   └── DesignTab.tsx           # 6 reverse-solve panels
├── diagrams/
│   └── <Name>DiagramV3.tsx    # v3 layered SVG diagram
├── <slug>.css                  # @import "../bending-stress/bending-stress.css"; + overrides
lib/calculators/engines/<slug>.ts   # pure math — all formulas
lib/calculators/hooks/use<Slug>.ts  # state, calc trigger, outputs

Step 1: Read Source HTML

Read the HTML source carefully:

• Identify ALL inputs (fields, units, section type, geometry)
• Identify ALL outputs (metrics, charts, design panel fields)
• Extract ALL theory text — every section, every formula
• Note which section database type is used (W, C, HSS, pipe, etc.)

Step 2: Engine (pure math, no React)

// lib/calculators/engines/<slug>.ts
export interface <Slug>Inputs { ... }
export interface <Slug>Outputs { ... }
export function solve<Slug>(inputs: <Slug>Inputs): <Slug>Outputs {
  // All math here. No UI, no state, no side effects.
  // Use same formulas as HTML source — verify against Shigley/Hibbeler
}

Step 3: Hook

// lib/calculators/hooks/use<Slug>.ts
export function use<Slug>() {
  const [inputs, setInputs] = useState<default values>
  const outputs = useMemo(() => solve<Slug>(inputs), [inputs])
  return { inputs, setInputs, outputs }
}

Step 4: Theory Tab (CRITICAL — 11+ sections minimum)

Each section MUST have:

• Explanation paragraph (age-10 accessible)
• Full formula in KaTeX via <MathBlock> from components/ui/Math.tsx
• Term table: Symbol | Name | Meaning | Imperial | SI
• At least 2 sections get an SVG shape diagram (v3 pattern)
• One worked example section

Use String.raw for LaTeX with curly braces:

<MathBlock>{String.raw`\sigma = \frac{Mc}{I}`}</MathBlock>

Step 5: SVG Diagrams (v3 Layered Pattern)

// diagrams/<Name>DiagramV3.tsx
export function <Name>DiagramV3({ outputs }: Props) {
  const containerRef = useRef<HTMLDivElement>(null)
  return (
    <div style={{ position:'relative', overflow:'auto', minWidth:720 }}>
      <div ref={containerRef} style={{ position:'relative', aspectRatio:'viewBox-ratio' }}>
        <svg viewBox="0 0 800 400" style={{ width:'100%', height:'auto' }}>
          {/* shapes ONLY — no text */}
        </svg>
        {/* Labels as absolute-positioned divs */}
        <div style={{ position:'absolute', left:'45%', top:'50%', transform:'translate(-50%,-50%)' }}>
          σ = {outputs.sigma.toFixed(1)} MPa
        </>
      
    
  )
}

Step 6: Quality Audit Checklist

Before marking complete, verify ALL of:

• Theory: ≥ 11 sections with complete formulas and term tables
• Theory: ≥ 2 SVG shape diagrams
• Theory: 1 worked example with numbers
• Diagrams: ≥ 2 SVG diagrams in Results tab
• Design tab: exactly 6 reverse-solve panels
• Chart tab: exactly 4 interactive charts in 2×2 grid
• Compare tab: searches CURRENT section type (not hardcoded)
• Auto-calc: no Calculate button, fires on every input change
• All inputs have unit dropdowns
• All outputs show both Imperial and SI
• Mobile: horizontal scroll wrapper on all diagrams (minWidth:720)
• TypeScript: npx tsc --noEmit passes clean
• Registry: slug added to registry.ts, NativeCalculatorLoader.tsx, calculators.ts

Step 7: Register

// components/calculators/native/registry.ts — add entry
// lib/calculators.ts — verify slug exists
// After completing: add to HAND_FINISHED set in scripts/bulk-port.mjs

NASA Quality Standard

• Never shortcut theory — walk the full textbook chapter
• Every formula: proper KaTeX fractions, subscripts, superscripts
• Include ALL failure modes, edge cases, limit conditions
• Verify all formulas against Shigley/Hibbeler before committing