@retiregolden/planner-ui 0.1.0

package/src/planner/explainPanels.tsx

@@ -0,0 +1,233 @@
+/**
+ * "Why this number" panels (trust-and-transparency-layer, steps 2–3):
+ * expandable explainers that trace the two probabilistic headline outputs —
+ * the Monte Carlo success % and the optimizer recommendation — to their
+ * method, inputs, and the evidence already computed for them. Pure rendering
+ * over existing payloads; no engine work happens here.
+ */
+
+import { Link } from 'react-router-dom'
+
+import type { MonteCarloSummary } from '@retiregolden/engine/montecarlo/run'
+import type { ExactLedgerTournament } from '@retiregolden/engine/projection/optimizePlan'
+import { fmtMoney, fmtMoneyCompact } from './format'
+
+function fmtSignedMoney(v: number): string {
+  return `${v >= 0 ? '+' : '−'}${fmtMoney(Math.abs(v))}`
+}
+
+/**
+ * Decomposes the success gauge: what counts as success, how the markets were
+ * generated (model, paths, seed, precision), which ledger years the failing
+ * paths actually deplete in, and how wide the first decade's outcomes spread
+ * (sequence-of-returns sensitivity). Everything renders from the existing
+ * `MonteCarloSummary`.
+ */
+export function WhySuccessPanel({
+  summary,
+  modelLabel,
+  seed,
+  planId,
+}: {
+  summary: MonteCarloSummary
+  modelLabel: string
+  seed: number
+  planId: string
+}) {
+  const pct = Math.round(summary.successRate * 100)
+  const failing = summary.downsideRisk.failingPathCount
+  const depletions = summary.depletionYearCounts
+  const earliestDepletion = depletions.length > 0 ? depletions[0]!.year : null
+  const medianDepletion = (() => {
+    if (failing === 0) return null
+    let seen = 0
+    for (const row of depletions) {
+      seen += row.count
+      if (seen >= failing / 2) return row.year
+    }
+    return depletions[depletions.length - 1]?.year ?? null
+  })()
+  // "First decade" = the 10th projected year (or the last year on short plans).
+  const decade = summary.fan[Math.min(9, summary.fan.length - 1)]
+  const precision = summary.pathCount >= 10_000 ? '±0.5' : '±1.5'
+
+  return (
+    <details className="ss-explainer">
+      <summary>Why this number?</summary>
+      <p>
+        <strong>What it counts.</strong> {pct}% means investable assets lasted to the end of the plan in{' '}
+        {(summary.pathCount - failing).toLocaleString()} of the {summary.pathCount.toLocaleString()} simulated markets
+        ({failing.toLocaleString()} depleted early). It is a statistic about this model of your plan — not a
+        probability about your actual life.
+      </p>
+      <p>
+        <strong>How the markets were made.</strong> Each path re-runs your full year-by-year projection — taxes, RMDs,
+        IRMAA, withdrawals, everything — under markets generated by the <strong>{modelLabel}</strong> model
+        (seed {seed}, reproducible). Your expected returns and inflation from{' '}
+        <Link to={`/plan/${planId}/assumptions-card`}>your assumptions</Link> are the center of the distribution; the
+        model only shapes the variation around them. At {summary.pathCount.toLocaleString()} paths the success rate is
+        good to about {precision} points, so treat small differences between runs as noise.
+      </p>
+      {failing > 0 ? (
+        <p>
+          <strong>Which years drive it.</strong> Failing paths first run out between {earliestDepletion} and{' '}
+          {depletions[depletions.length - 1]!.year}
+          {medianDepletion !== null ? ` (median ${medianDepletion})` : ''} — see the depletion chart below for the full
+          curve. Early depletions usually trace to weak markets in the first retirement decade: by {decade?.year}, the
+          worst 10% of paths hold {fmtMoneyCompact(decade?.p10 ?? 0)} versus a median of{' '}
+          {fmtMoneyCompact(decade?.p50 ?? 0)} — the same spending drawn from that smaller base is what sinks those
+          paths (sequence-of-returns risk).
+        </p>
+      ) : (
+        <p>
+          <strong>Which years drive it.</strong> No simulated path depleted. The spread is still real: by{' '}
+          {decade?.year}, the worst 10% of paths hold {fmtMoneyCompact(decade?.p10 ?? 0)} versus a median of{' '}
+          {fmtMoneyCompact(decade?.p50 ?? 0)}.
+        </p>
+      )}
+      <p>
+        <strong>What would change it.</strong> The number moves with your assumptions, the model choice, spending, and
+        retirement timing — that's why identical plans score differently across tools. To see exactly what this run
+        assumed, open <Link to={`/plan/${planId}/assumptions-card`}>the assumptions card</Link>; to see how the engine
+        itself is checked, see <Link to="/how-tested">how RetireGolden is tested</Link>.
+      </p>
+    </details>
+  )
+}
+
+/**
+ * Surfaces the exact-ledger tournament behind an optimizer recommendation:
+ * the objective it was ranked by, every simple candidate it beat (with dollar
+ * margins on the full projection), and how the winner was refined. Acceptance
+ * (step 3): every recommendation shows its beaten alternatives and margins.
+ */
+export function WhyRecommendationPanel({
+  tournament,
+  objectiveLabel,
+}: {
+  tournament: ExactLedgerTournament
+  objectiveLabel: string
+}) {
+  const estateObjective = tournament.policyId === 'max-after-tax-estate'
+  const noWinner = tournament.winnerSource === 'none'
+  // Estate deltas are the ranking metric only under the estate objective; for
+  // other objectives keep the tournament's fixed generation order rather than
+  // presenting an estate sort as the hierarchy.
+  const candidates = estateObjective
+    ? [...tournament.candidates].sort((a, b) => b.afterTaxEstateDelta - a.afterTaxEstateDelta)
+    : tournament.candidates
+  const winnerDelta = tournament.winnerValidation?.afterTaxEstateDelta ?? 0
+  // Runner-up = best recommendation-eligible challenger. Candidates that
+  // shorten how long the money lasts are hard-rejected by every objective, so
+  // a higher estate delta on one of those is not a "next-best alternative".
+  const runnerUp = tournament.candidates
+    .filter((c) => c.id !== tournament.winnerCandidateId && c.moneyLastsYearsDelta >= 0)
+    .reduce<(typeof tournament.candidates)[number] | null>(
+      (best, c) => (best === null || c.afterTaxEstateDelta > best.afterTaxEstateDelta ? c : best),
+      null,
+    )
+  const marginOverRunnerUp =
+    runnerUp === null
+      ? null
+      : tournament.winnerSource === 'incumbent'
+        ? -runnerUp.afterTaxEstateDelta
+        : winnerDelta - runnerUp.afterTaxEstateDelta
+  // Only claim "ahead by $X" when it is true on the metric being quoted.
+  const showMargin = !noWinner && estateObjective && marginOverRunnerUp !== null && marginOverRunnerUp > 0
+
+  const winnerPhrase =
+    tournament.winnerSource === 'milp'
+      ? "the solver's schedule"
+      : (tournament.winnerLabel ?? 'the recommendation')
+
+  return (
+    <details className="ss-explainer">
+      <summary>Why this recommendation?</summary>
+      {noWinner ? (
+        <p>
+          Every candidate below was re-run through your full year-by-year projection and ranked by{' '}
+          <strong>{objectiveLabel}</strong>
+          {estateObjective ? '' : ' (the estate deltas shown are context, not the ranking metric)'}.{' '}
+          <strong>None cleared the recommendation threshold</strong>, so no schedule is recommended — the table shows
+          what was considered and why nothing won.
+        </p>
+      ) : (
+        <p>
+          Every candidate below was re-run through your full year-by-year projection and ranked by{' '}
+          <strong>{objectiveLabel}</strong>
+          {estateObjective ? '' : ' (the estate deltas shown are context, not the ranking metric)'} — no candidate is
+          recommended off the solver's simplified model alone. The winner is <strong>{winnerPhrase}</strong>
+          {showMargin ? (
+            <>
+              , ahead of the next-best eligible alternative by <strong>{fmtMoney(marginOverRunnerUp!)}</strong> of
+              projected after-tax estate
+            </>
+          ) : null}
+          {tournament.winnerSource === 'candidate' && tournament.marginOverMilpDollars > 0
+            ? `, and it beat the solver's own schedule by ${fmtMoney(tournament.marginOverMilpDollars)}`
+            : ''}
+          .{tournament.searchRefined ? ` A bounded local search (${tournament.searchSimulations} extra full-projection runs) then fine-tuned the winning schedule's per-year amounts.` : ''}
+        </p>
+      )}
+      <div className="year-table-wrap" style={{ border: 'none' }}>
+        <table className="compare-table">
+          <thead>
+            <tr>
+              <th>Alternative considered</th>
+              <th>Conversions executed</th>
+              <th>After-tax estate</th>
+              <th>Lifetime tax</th>
+              <th>Money lasts</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>
+                Your current plan (baseline)
+                {tournament.winnerSource === 'incumbent' ? <strong> — winner</strong> : ''}
+              </td>
+              <td>—</td>
+              <td>±$0</td>
+              <td>±$0</td>
+              <td>—</td>
+            </tr>
+            {tournament.winnerSource === 'milp' && tournament.winnerValidation ? (
+              <tr>
+                <td>
+                  Solver's schedule (post-processed)<strong> — winner</strong>
+                </td>
+                <td>{fmtMoneyCompact(tournament.winnerValidation.executedConversionTotal)}</td>
+                <td>{fmtSignedMoney(tournament.winnerValidation.afterTaxEstateDelta)}</td>
+                <td>{fmtSignedMoney(tournament.winnerValidation.lifetimeTaxDelta)}</td>
+                <td>
+                  {tournament.winnerValidation.moneyLastsYearsDelta === 0
+                    ? 'unchanged'
+                    : `${tournament.winnerValidation.moneyLastsYearsDelta > 0 ? '+' : ''}${tournament.winnerValidation.moneyLastsYearsDelta} yr`}
+                </td>
+              </tr>
+            ) : null}
+            {candidates.map((c) => (
+              <tr key={c.id}>
+                <td>
+                  {c.label}
+                  {c.id === tournament.winnerCandidateId ? <strong> — winner</strong> : ''}
+                </td>
+                <td>{fmtMoneyCompact(c.executedConversionTotal)}</td>
+                <td>{fmtSignedMoney(c.afterTaxEstateDelta)}</td>
+                <td>{fmtSignedMoney(c.lifetimeTaxDelta)}</td>
+                <td>{c.moneyLastsYearsDelta === 0 ? 'unchanged' : `${c.moneyLastsYearsDelta > 0 ? '+' : ''}${c.moneyLastsYearsDelta} yr`}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      <p className="field-hint" style={{ margin: '0.4rem 0 0' }}>
+        Deltas are versus your current plan, measured on the full projection (heir tax on pre-tax balances included).
+        Candidates that shorten how long the money lasts are rejected regardless of estate gain. The solver's own
+        schedule competes too; it only supplies the recommendation when nothing simpler beats it (and appears above
+        when it wins). See <Link to="/how-tested">how RetireGolden is tested</Link> for the harnesses behind this
+        pipeline.
+      </p>
+    </details>
+  )
+}

package/src/planner/fields.tsx

@@ -0,0 +1,381 @@
+/**
+ * Shared form fields. Numeric fields hold local text state while focused and
+ * commit parsed values on change, so partial input ("1,2") never fights the
+ * plan state; money fields accept "$450k"-style shorthand.
+ */
+
+import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
+
+import { LearnLink, type LearnHook } from '../learn/LearnLink'
+import { fmtMoney, parseAmount } from './format'
+
+/** External citation shown inside a ⓘ help bubble (cite-the-authority pattern). */
+export interface SourceLink {
+  /** Link text, e.g. the publisher ("IRS", "CMS"). */
+  label: string
+  url: string
+}
+
+interface BaseProps {
+  label: string
+  /** Short inline note shown below the field — only for things that change what you type. */
+  hint?: string
+  /** Longer explanation behind an ⓘ help button (hover/focus/click). Prefer this over hint for background detail. */
+  help?: string
+  /** Optional "Learn more" link to a Learning Center article, shown inside the ⓘ help bubble. */
+  learn?: LearnHook
+  /** Optional citation to the authority behind the parameter (Rev. Proc. / statute / agency figure). */
+  source?: SourceLink
+}
+
+/**
+ * The one help affordance on a label: a single ⓘ button that, on hover/focus,
+ * reveals a bubble holding the field's explanation, any short input note, and —
+ * when the concept has a durable article — a "Learn more" link. All field help
+ * lives in this bubble, so labels never carry separate sub-text under the input.
+ *
+ * It is an accessible disclosure, not a passive tooltip, because the bubble can
+ * hold an interactive link: hover or keyboard-focus reveals it, clicking pins it
+ * open (for touch and to reach the link), and Escape or an outside click closes
+ * a pinned bubble. The bubble is positioned with fixed coordinates clamped to
+ * the viewport, so it never clips at a screen edge or inside a scrolling panel.
+ */
+export function HelpTip({ text, hint, learn, source, id }: { text?: string; hint?: string; learn?: LearnHook; source?: SourceLink; id?: string }) {
+  const auto = useId()
+  const bubbleId = id ?? `${auto}-help`
+  const textId = `${bubbleId}-text`
+  const [hovered, setHovered] = useState(false)
+  const [focused, setFocused] = useState(false)
+  const [pinned, setPinned] = useState(false)
+  const wrapRef = useRef<HTMLSpanElement>(null)
+  const btnRef = useRef<HTMLButtonElement>(null)
+  const bubbleRef = useRef<HTMLSpanElement>(null)
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const open = hovered || focused || pinned
+
+  const cancelClose = () => {
+    if (closeTimer.current) clearTimeout(closeTimer.current)
+    closeTimer.current = undefined
+  }
+  // Brief delay so the pointer can cross the gap from the ⓘ into the bubble.
+  const scheduleClose = () => {
+    cancelClose()
+    closeTimer.current = setTimeout(() => setHovered(false), 120)
+  }
+
+  // Position the open bubble by the ⓘ, clamped to the viewport (flipping below
+  // when there's no room above), and keep it tracking on scroll/resize. Written
+  // imperatively (not via state) so it lands before paint with no extra render.
+  useLayoutEffect(() => {
+    if (!open) return
+    const bubble = bubbleRef.current
+    const button = btnRef.current
+    if (!bubble || !button) return
+    const place = () => {
+      const btn = button.getBoundingClientRect()
+      const bub = bubble.getBoundingClientRect()
+      const margin = 8
+      const left = Math.max(
+        margin,
+        Math.min(btn.left + btn.width / 2 - bub.width / 2, window.innerWidth - bub.width - margin),
+      )
+      const above = btn.top - bub.height - margin
+      bubble.style.left = `${left}px`
+      bubble.style.top = `${above >= margin ? above : btn.bottom + margin}px`
+    }
+    place()
+    window.addEventListener('scroll', place, true)
+    window.addEventListener('resize', place)
+    return () => {
+      window.removeEventListener('scroll', place, true)
+      window.removeEventListener('resize', place)
+    }
+  }, [open, text, hint])
+
+  // Close a pinned bubble on Escape or a click outside.
+  useEffect(() => {
+    if (!pinned) return
+    const onPointerDown = (e: PointerEvent) => {
+      const t = e.target as Node
+      if (!wrapRef.current?.contains(t) && !bubbleRef.current?.contains(t)) setPinned(false)
+    }
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setPinned(false)
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [pinned])
+
+  return (
+    <span
+      className={pinned ? 'help-tip help-tip--pinned' : 'help-tip'}
+      ref={wrapRef}
+      onMouseEnter={() => {
+        cancelClose()
+        setHovered(true)
+      }}
+      onMouseLeave={scheduleClose}
+      onFocus={() => setFocused(true)}
+      onBlur={(e) => {
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setFocused(false)
+      }}
+    >
+      <button
+        ref={btnRef}
+        type="button"
+        aria-label="More information"
+        aria-describedby={text || hint ? textId : undefined}
+        aria-expanded={pinned}
+        aria-controls={bubbleId}
+        // Prevent the surrounding <label> (e.g. CheckboxField) from toggling its control.
+        onClick={(e) => {
+          e.preventDefault()
+          e.stopPropagation()
+          setPinned((p) => !p)
+        }}
+      >
+        i
+      </button>
+      <span
+        ref={bubbleRef}
+        className={open ? 'help-tip-bubble help-tip-bubble--open' : 'help-tip-bubble'}
+        id={bubbleId}
+        onMouseEnter={cancelClose}
+        onMouseLeave={scheduleClose}
+      >
+        {text || hint ? (
+          <span id={textId} className="help-tip-text">
+            {text}
+            {text && hint ? <span className="help-tip-hint">{hint}</span> : hint}
+          </span>
+        ) : null}
+        {source ? (
+          <a className="help-tip-source" href={source.url} target="_blank" rel="noopener noreferrer">
+            Source: {source.label} ↗
+          </a>
+        ) : null}
+        {learn ? <LearnLink {...learn} variant="tip" /> : null}
+      </span>
+    </span>
+  )
+}
+
+export function ReadonlyField({ label, help, learn, value }: BaseProps & { value: ReactNode }) {
+  const id = useId()
+  return (
+    <div className="field">
+      <span className="field-label-row">
+        <span className="field-label" id={id}>
+          {label}
+        </span>
+        {help || learn ? <HelpTip text={help} learn={learn} id={`${id}-help`} /> : null}
+      </span>
+      <p className="field-readonly" aria-labelledby={id}>
+        {value}
+      </p>
+    </div>
+  )
+}
+
+function FieldShell({ label, hint, help, learn, source, id, children }: BaseProps & { id: string; children: ReactNode }) {
+  return (
+    <div className="field">
+      <span className="field-label-row">
+        <label className="field-label" htmlFor={id}>
+          {label}
+        </label>
+        {help || hint || learn || source ? <HelpTip text={help} hint={hint} learn={learn} source={source} id={`${id}-help`} /> : null}
+      </span>
+      {children}
+    </div>
+  )
+}
+
+interface NumericProps extends BaseProps {
+  value: number | null
+  onCommit: (value: number | null) => void
+  /** When false (default for most), clearing the field commits 0 instead of null. */
+  allowNull?: boolean
+}
+
+function useLocalText(formatted: string) {
+  const [text, setText] = useState(formatted)
+  const [focused, setFocused] = useState(false)
+  // Derived-state-during-render: adopt the external value unless the user is typing.
+  const [prevFormatted, setPrevFormatted] = useState(formatted)
+  if (formatted !== prevFormatted) {
+    setPrevFormatted(formatted)
+    if (!focused) setText(formatted)
+  }
+  return { text, setText, focused, setFocused }
+}
+
+export function MoneyField({ label, hint, help, learn, source, value, onCommit, allowNull }: NumericProps) {
+  const id = useId()
+  const { text, setText, setFocused } = useLocalText(value === null ? '' : fmtMoney(value))
+  return (
+    <FieldShell label={label} hint={hint} help={help} learn={learn} source={source} id={id}>
+      <div className="input-affix">
+        <span aria-hidden>$</span>
+        <input
+          id={id}
+          inputMode="decimal"
+          value={text.replace(/^\$/, '')}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          onChange={(e) => {
+            setText(e.target.value)
+            const parsed = parseAmount(e.target.value)
+            if (parsed !== null) onCommit(parsed)
+            else if (e.target.value.trim() === '') onCommit(allowNull ? null : 0)
+          }}
+        />
+      </div>
+    </FieldShell>
+  )
+}
+
+export function NumberField({
+  label,
+  hint,
+  help,
+  learn,
+  source,
+  value,
+  onCommit,
+  allowNull,
+  suffix,
+  step,
+  min,
+  max,
+}: NumericProps & { suffix?: string; step?: number; min?: number; max?: number }) {
+  const id = useId()
+  const { text, setText, setFocused } = useLocalText(value === null ? '' : String(value))
+  const input = (
+    <input
+      id={id}
+      type="number"
+      inputMode="decimal"
+      value={text}
+      step={step}
+      min={min}
+      max={max}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      onChange={(e) => {
+        setText(e.target.value)
+        const n = Number(e.target.value)
+        if (e.target.value.trim() === '') onCommit(allowNull ? null : 0)
+        else if (Number.isFinite(n)) onCommit(n)
+      }}
+    />
+  )
+  return (
+    <FieldShell label={label} hint={hint} help={help} learn={learn} source={source} id={id}>
+      {suffix ? (
+        <div className="input-affix">
+          {input}
+          <span aria-hidden>{suffix}</span>
+        </div>
+      ) : (
+        input
+      )}
+    </FieldShell>
+  )
+}
+
+export function PercentField(props: NumericProps & { step?: number; min?: number; max?: number }) {
+  return <NumberField {...props} suffix="%" step={props.step ?? 0.1} />
+}
+
+export function TextField({
+  label,
+  hint,
+  help,
+  learn,
+  source,
+  value,
+  onCommit,
+}: BaseProps & { value: string; onCommit: (v: string) => void }) {
+  const id = useId()
+  return (
+    <FieldShell label={label} hint={hint} help={help} learn={learn} source={source} id={id}>
+      <input id={id} type="text" value={value} onChange={(e) => onCommit(e.target.value)} />
+    </FieldShell>
+  )
+}
+
+export function DateField({
+  label,
+  hint,
+  help,
+  learn,
+  source,
+  value,
+  onCommit,
+}: BaseProps & { value: string; onCommit: (v: string) => void }) {
+  const id = useId()
+  return (
+    <FieldShell label={label} hint={hint} help={help} learn={learn} source={source} id={id}>
+      <input id={id} type="date" value={value} onChange={(e) => onCommit(e.target.value)} />
+    </FieldShell>
+  )
+}
+
+export function SelectField<T extends string>({
+  label,
+  hint,
+  help,
+  learn,
+  source,
+  value,
+  options,
+  onCommit,
+  describedBy,
+}: BaseProps & {
+  value: T
+  options: ReadonlyArray<{ value: T; label: string }>
+  onCommit: (v: T) => void
+  /** id of visible text outside the field (e.g. a card hint) that describes the current selection. */
+  describedBy?: string
+}) {
+  const id = useId()
+  return (
+    <FieldShell label={label} hint={hint} help={help} learn={learn} source={source} id={id}>
+      <select id={id} value={value} aria-describedby={describedBy} onChange={(e) => onCommit(e.target.value as T)}>
+        {options.map((o) => (
+          <option key={o.value} value={o.value}>
+            {o.label}
+          </option>
+        ))}
+      </select>
+    </FieldShell>
+  )
+}
+
+export function CheckboxField({
+  label,
+  hint,
+  help,
+  learn,
+  source,
+  value,
+  onCommit,
+}: BaseProps & { value: boolean; onCommit: (v: boolean) => void }) {
+  const id = useId()
+  return (
+    <div className="field field--checkbox">
+      <span className="field-label-row">
+        <label className="field-label" htmlFor={id}>
+          {label}
+        </label>
+        {help || hint || learn || source ? <HelpTip text={help} hint={hint} learn={learn} source={source} id={`${id}-help`} /> : null}
+      </span>
+      <input id={id} type="checkbox" checked={value} onChange={(e) => onCommit(e.target.checked)} />
+    </div>
+  )
+}

package/src/planner/format.ts

@@ -0,0 +1,33 @@
+/** Number formatting for the planner. All engine amounts are nominal dollars. */
+
+const money0 = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })
+
+export function fmtMoney(v: number): string {
+  if (!Number.isFinite(v)) return '—'
+  return money0.format(v)
+}
+
+/** Compact KPI form: $1.24M, $310k, −$8.2k. */
+export function fmtMoneyCompact(v: number): string {
+  if (!Number.isFinite(v)) return '—'
+  const sign = v < 0 ? '−' : ''
+  const a = Math.abs(v)
+  if (a >= 1e6) return `${sign}$${(a / 1e6).toFixed(2)}M`
+  if (a >= 10_000) return `${sign}$${Math.round(a / 1000)}k`
+  return `${sign}$${Math.round(a).toLocaleString('en-US')}`
+}
+
+export function fmtPct(v: number, digits = 0): string {
+  if (!Number.isFinite(v)) return '—'
+  return `${(v * 100).toFixed(digits)}%`
+}
+
+/** Parses a user-typed money/number string ("1,200,000", "$45k") to a number, or null. */
+export function parseAmount(text: string): number | null {
+  const cleaned = text.trim().replace(/[$,\s]/g, '').toLowerCase()
+  if (cleaned === '') return null
+  const mult = cleaned.endsWith('m') ? 1e6 : cleaned.endsWith('k') ? 1e3 : 1
+  const core = mult === 1 ? cleaned : cleaned.slice(0, -1)
+  const n = Number(core)
+  return Number.isFinite(n) ? n * mult : null
+}