@retiregolden/planner-ui 0.1.0

package/src/planner/PlanContext.tsx

@@ -0,0 +1,198 @@
+/**
+ * Plan workspace state: loads a plan by id, applies edits immutably (clone →
+ * mutate → Zod re-parse), and autosaves to IndexedDB on a debounce. Edits
+ * that fail validation still update the screen (so the user can finish
+ * typing) but are not persisted; the issues surface in the save indicator
+ * and section forms.
+ */
+
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import { Link } from 'react-router-dom'
+
+import { parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { loadPlan, savePlan } from '../data/planStore'
+import { EXAMPLE_PLAN_ID_PREFIX, isExamplePlanId } from '../data/planOrigin'
+import { getExampleById } from './examples/registry'
+import { saveFreshDemo } from './examples/loadExample'
+import { PlanCtx, type PlanContextValue, type SaveState } from './planContextCore'
+
+const AUTOSAVE_MS = 600
+
+/**
+ * Mount with key={planId}: a plan switch remounts the provider, so initial
+ * state is naturally "loading" and the load effect only sets state
+ * asynchronously.
+ */
+export function PlanProvider({ planId, children }: { planId: string; children: ReactNode }) {
+  const [plan, setPlan] = useState<Plan | null>(null)
+  const [loadError, setLoadError] = useState<string | null>(null)
+  const [saveState, setSaveState] = useState<SaveState>('loading')
+  const [issues, setIssues] = useState<string[]>([])
+  const timer = useRef<number | null>(null)
+  const latestValid = useRef<Plan | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    const adopt = (loaded: Plan) => {
+      setPlan(loaded)
+      latestValid.current = loaded
+      setSaveState('saved')
+    }
+    void (async () => {
+      const r = await loadPlan(planId)
+      if (cancelled) return
+      if (r.ok) {
+        adopt(r.plan)
+        return
+      }
+      // A shared or bookmarked example URL can reference a demo that was never
+      // seeded in this browser (plans are per-device). Seed a fresh copy from
+      // the registry instead of dead-ending the advertised on-ramp — but ONLY
+      // when the record is missing ('not_object'). Other reasons (bad_version,
+      // newer_than_app, …) mean a record EXISTS and failed to open; seeding
+      // over it would silently discard the on-device edits the product copy
+      // promises are kept.
+      if (isExamplePlanId(planId) && r.reason === 'not_object') {
+        const example = getExampleById(planId.slice(EXAMPLE_PLAN_ID_PREFIX.length))
+        if (example) {
+          const seeded = await saveFreshDemo(example)
+          if (cancelled) return
+          if (seeded.ok) {
+            adopt(seeded.plan)
+            return
+          }
+        }
+      }
+      setLoadError(r.reason)
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [planId])
+
+  // savePlan resolves { ok: false } on validation failure, but the IndexedDB
+  // write itself can still reject (quota, private mode) — degrade to 'error'
+  // instead of leaving 'saving' stuck plus an unhandled rejection.
+  const runSave = useCallback((toSave: Plan) => {
+    setSaveState('saving')
+    void savePlan(toSave)
+      .then((r) => {
+        setSaveState(r.ok ? 'saved' : 'error')
+      })
+      .catch(() => {
+        setSaveState('error')
+      })
+  }, [])
+
+  const scheduleSave = useCallback(() => {
+    if (timer.current !== null) window.clearTimeout(timer.current)
+    timer.current = window.setTimeout(() => {
+      timer.current = null
+      const toSave = latestValid.current
+      if (toSave) runSave(toSave)
+    }, AUTOSAVE_MS)
+  }, [runSave])
+
+  /** Runs a debounced save immediately; no-op when nothing is pending. */
+  const flushPendingSave = useCallback(() => {
+    if (timer.current === null) return
+    window.clearTimeout(timer.current)
+    timer.current = null
+    const toSave = latestValid.current
+    if (toSave) runSave(toSave)
+  }, [runSave])
+
+  const discardPendingSave = useCallback(() => {
+    if (timer.current !== null) {
+      window.clearTimeout(timer.current)
+      timer.current = null
+    }
+    latestValid.current = null
+  }, [])
+
+  const update = useCallback(
+    (mutator: (draft: Plan) => void) => {
+      setPlan((current) => {
+        if (!current) return current
+        const draft = structuredClone(current)
+        mutator(draft)
+        const parsed = parsePlan(draft)
+        if (parsed.ok) {
+          latestValid.current = parsed.plan
+          setIssues([])
+          setSaveState('dirty')
+          scheduleSave()
+          return parsed.plan
+        }
+        setIssues(parsed.issues)
+        setSaveState('invalid')
+        return draft
+      })
+    },
+    [scheduleSave],
+  )
+
+  // Flush pending saves when the page is hidden or torn down. The unmount
+  // cleanup alone is not enough: it never runs on tab close, and a mobile OS
+  // can kill a hidden PWA without any unmount — so `pagehide` and
+  // `visibilitychange → hidden` both flush too.
+  useEffect(() => {
+    const onPageHide = () => flushPendingSave()
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') flushPendingSave()
+    }
+    window.addEventListener('pagehide', onPageHide)
+    document.addEventListener('visibilitychange', onVisibilityChange)
+    return () => {
+      window.removeEventListener('pagehide', onPageHide)
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+      flushPendingSave()
+    }
+  }, [flushPendingSave])
+
+  if (loadError) {
+    // 'not_object' = no record in this browser (cross-device link, stale
+    // bookmark). Everything else = a stored plan that exists but failed to
+    // open (version/migration mismatch) — telling that user "not stored here"
+    // would be wrong and alarming.
+    const missing = loadError === 'not_object'
+    return (
+      <div className="card empty-state">
+        <h2>{missing ? 'Plan not found' : 'This plan could not be opened'}</h2>
+        <p className="muted">
+          {missing ? (
+            <>
+              This plan isn&apos;t stored in this browser. Plans live only on the device where they were created, so
+              a link from another device or an old bookmark won&apos;t open here. You can restore one from a backup
+              file via Data &amp; privacy on the planner home.
+            </>
+          ) : (
+            <>
+              The plan is stored on this device, but its data doesn&apos;t match what this version of the app can
+              read — usually a version mismatch (for example, a backup made by a newer version). Your data has not
+              been changed. Try reloading to pick up the latest app version, or restore a backup via Data &amp;
+              privacy on the planner home.
+            </>
+          )}
+        </p>
+        <div className="picker-actions">
+          <Link to="/" className="btn btn-primary">
+            Your plans
+          </Link>
+          <Link to="/examples" className="btn btn-secondary">
+            Browse examples
+          </Link>
+        </div>
+        <details className="ss-explainer">
+          <summary>Technical details</summary>
+          <p className="muted">Load failed with reason code: {loadError}</p>
+        </details>
+      </div>
+    )
+  }
+  if (!plan) {
+    return <div className="skeleton" style={{ height: '14rem', marginTop: '1rem' }} aria-label="Loading plan" />
+  }
+  const contextValue: PlanContextValue = { plan, update, discardPendingSave, saveState, issues }
+  return <PlanCtx.Provider value={contextValue}>{children}</PlanCtx.Provider>
+}

package/src/planner/PlanPickerPage.tsx

@@ -0,0 +1,124 @@
+/**
+ * Planner home: adaptive welcome for newcomers, plans-first for returning users.
+ * Composes section components from ./home/.
+ */
+
+import { Link, useNavigate } from 'react-router-dom'
+
+import { createEmptyPlan } from '@retiregolden/engine/model/plan'
+import { DataAndPrivacyCard } from './home/DataAndPrivacyCard'
+import { GettingStartedPaths } from './home/GettingStartedPaths'
+import { GettingStartedReopener } from './home/GettingStartedReopener'
+import { StartHereLinks } from './home/StartHereLinks'
+import { useHomeData } from './home/useHomeData'
+import { useHomeMode } from './home/useHomeMode'
+import { WelcomeHero } from './home/WelcomeHero'
+import { YourPlans } from './home/YourPlans'
+
+const GETTING_STARTED_PANEL_ID = 'home-getting-started-panel'
+
+export function PlanPickerPage() {
+  const navigate = useNavigate()
+  const {
+    plans,
+    notice,
+    undoPlan,
+    undoDelete,
+    dismissUndo,
+    fileInput,
+    createAndOpen,
+    handleExportAll,
+    handleImportFile,
+    handleDuplicate,
+    handleDelete,
+    handleClearAll,
+    openPlan,
+    dialogs,
+  } = useHomeData()
+
+  const { mode, welcomeExpanded, dismissWelcome, showWelcome } = useHomeMode(plans)
+  const isLoading = plans === null
+  const isFirstRun = !isLoading && mode === 'first-run'
+
+  const gettingStartedBlock = (
+    <>
+      <WelcomeHero
+        onTryExample={() => navigate('/examples')}
+        onDismiss={dismissWelcome}
+        showDismiss={mode === 'returning'}
+        headingLevel={mode === 'returning' ? 'h2' : 'h1'}
+      />
+      <GettingStartedPaths onCreatePlan={createAndOpen} />
+      <StartHereLinks />
+    </>
+  )
+
+  return (
+    <section className="page picker-page">
+      <div role="status" aria-live="polite">
+        {notice ? <div className="callout callout--info">{notice}</div> : null}
+        {undoPlan ? (
+          <div className="undo-toast">
+            <span>
+              Deleted “{undoPlan.name}”.
+            </span>
+            <div className="undo-toast-actions">
+              <button type="button" className="btn btn-secondary btn-small" onClick={() => void undoDelete()}>
+                Undo
+              </button>
+              <button type="button" className="btn btn-ghost btn-small" onClick={dismissUndo} aria-label="Dismiss">
+                Dismiss
+              </button>
+            </div>
+          </div>
+        ) : null}
+      </div>
+
+      {isLoading ? (
+        <>
+          <div className="skeleton" style={{ height: '2rem', marginBottom: '1rem' }} aria-hidden="true" />
+          <div className="skeleton" style={{ height: '8rem' }} aria-label="Loading plans" />
+        </>
+      ) : isFirstRun ? (
+        gettingStartedBlock
+      ) : (
+        <>
+          <GettingStartedReopener
+            expanded={welcomeExpanded}
+            onToggle={() => (welcomeExpanded ? dismissWelcome() : showWelcome())}
+            panelId={GETTING_STARTED_PANEL_ID}
+          >
+            {gettingStartedBlock}
+          </GettingStartedReopener>
+
+          <YourPlans
+            plans={plans}
+            headingLevel="h1"
+            actions={
+              <>
+                <button type="button" className="btn btn-primary" onClick={() => void createAndOpen(createEmptyPlan())}>
+                  New plan
+                </button>
+                <Link to="/compare" className="btn btn-secondary">
+                  Compare plans
+                </Link>
+              </>
+            }
+            onOpenPlan={openPlan}
+            onDuplicate={handleDuplicate}
+            onDelete={handleDelete}
+          />
+        </>
+      )}
+
+      <DataAndPrivacyCard
+        plans={plans}
+        fileInput={fileInput}
+        onExportAll={handleExportAll}
+        onImportFile={handleImportFile}
+        onClearAll={handleClearAll}
+      />
+      {dialogs}
+    </section>
+  )
+}

package/src/planner/PlanWorkspace.tsx

@@ -0,0 +1,290 @@
+/**
+ * Workspace shell: left rail (entry sections + results surfaces), editable
+ * plan name, autosave indicator, and a sticky KPI bar that re-simulates the
+ * deterministic projection live as the plan changes.
+ */
+
+import { useEffect } from 'react'
+import { Link, NavLink, Outlet, useLocation, useNavigate, useParams } from 'react-router-dom'
+
+import { duplicatePlan } from '../data/planStore'
+import { DEFAULT_PATH_COUNT } from '../mc/pool'
+import { useDialogs } from './dialogs'
+import { isPlanIncomplete } from './planCompleteness'
+import { ExamplePreviewBanner } from './examples/ExamplePreviewBanner'
+import { EXAMPLE_SAVE_INDICATOR } from './examples/exampleCopy'
+import { PlanProvider } from './PlanContext'
+import { usePlan } from './planContextCore'
+import { fmtMoneyCompact } from './format'
+import { successBand } from './successBand'
+import { useMcSuccessRate } from './useMcSuccessRate'
+import { useProjection } from './useProjection'
+
+const railClass = ({ isActive }: { isActive: boolean }) => (isActive ? 'rail-link rail-link--active' : 'rail-link')
+
+/** Section labels by route segment — drives the tab title and the page h1. */
+const SECTION_TITLES: Record<string, string> = {
+  household: 'Household',
+  'social-security': 'Social Security',
+  accounts: 'Accounts',
+  insurance: 'Insurance',
+  income: 'Income',
+  'income-floor': 'Income floor',
+  spending: 'Spending',
+  strategy: 'Strategy',
+  assumptions: 'Assumptions',
+  insights: 'Insights',
+  optimize: 'Roth & Tax Optimizer',
+  'spending-solver': 'How much can I spend?',
+  'social-security-analysis': 'Social Security Optimizer',
+  results: 'Results',
+  'monte-carlo': 'Monte Carlo',
+  scenarios: 'Scenarios',
+  survivor: 'Survivor transition',
+  relocation: 'Relocation Compare',
+  report: 'Report',
+  'assumptions-card': 'Assumptions card',
+}
+
+function sectionTitleOf(pathname: string): string | null {
+  // /plan/:planId/<section>[/...] — the segment after the plan id.
+  const segments = pathname.split('/').filter(Boolean)
+  const section = segments[2]
+  return section !== undefined ? (SECTION_TITLES[section] ?? null) : null
+}
+
+function SaveIndicator() {
+  const { plan, saveState, issues } = usePlan()
+  const isExample = plan.origin === 'example'
+  const text =
+    saveState === 'saved'
+      ? isExample
+        ? EXAMPLE_SAVE_INDICATOR
+        : 'Stored on this device'
+      : saveState === 'saving' || saveState === 'dirty'
+        ? 'Storing…'
+        : saveState === 'invalid'
+          ? `Fix ${issues.length} issue${issues.length === 1 ? '' : 's'} to store`
+          : saveState === 'error'
+            ? 'Could not store locally'
+            : ''
+  const title = isExample
+    ? "This example is saved on this device under its own slot — your edits stick across reloads, but it stays out of Your plans until you use 'Save to my plans'. 'Load a fresh copy' resets it."
+    : "Plans live only in this browser — nothing is sent to a server. Use 'Download plan backup' on the planner home to keep a copy."
+  return (
+    <span
+      className={saveState === 'invalid' || saveState === 'error' ? 'save-state save-state--error' : 'save-state'}
+      role="status"
+      aria-live="polite"
+      title={title}
+    >
+      {text}
+    </span>
+  )
+}
+
+function KpiBar() {
+  const { plan } = usePlan()
+  const { result, summary, deflate } = useProjection(plan)
+  const mcRate = useMcSuccessRate(plan, !isPlanIncomplete(plan))
+  const endYear = result.endYear
+  const depleted = summary.depletionYear !== null
+  const endingToday = deflate(endYear, result.endingNetWorth)
+
+  if (isPlanIncomplete(plan)) {
+    return (
+      <div className="kpi-bar kpi-bar--incomplete" aria-label="Plan headline results">
+        <div className="kpi">
+          <span className="kpi-label">Plan status</span>
+          <span className="kpi-value kpi-value--pending">Getting started</span>
+          <span className="kpi-sub kpi-sub--wrap">
+            Add income sources or account balances to complete the picture — results appear as you enter them.
+          </span>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="kpi-bar" aria-label="Plan headline results">
+      <div className="kpi">
+        <span className="kpi-label">Ending net worth</span>
+        <span className="kpi-value">{fmtMoneyCompact(result.endingNetWorth)}</span>
+        <span className="kpi-sub">{fmtMoneyCompact(endingToday)} today's $ · {endYear}</span>
+      </div>
+      <div className="kpi">
+        <span className="kpi-label">Money lasts</span>
+        {depleted ? (
+          <Link
+            className="kpi-value kpi-value--bad kpi-value-link"
+            to="insights"
+            title="See what would change this in Insights"
+          >
+            until {summary.depletionYear}
+          </Link>
+        ) : (
+          <span className="kpi-value kpi-value--good">full plan</span>
+        )}
+        <span className="kpi-sub">{depleted ? 'steady markets · depletes' : `steady markets · ${endYear}`}</span>
+      </div>
+      <div className="kpi">
+        <span className="kpi-label">Market success</span>
+        {mcRate !== null ? (
+          <Link
+            className="kpi-value kpi-value-link"
+            style={{ color: successBand(mcRate).color }}
+            to="monte-carlo"
+            title={`Share of ${DEFAULT_PATH_COUNT.toLocaleString()} varied-market simulations where the money lasts — open Monte Carlo for the full picture`}
+          >
+            {Math.round(mcRate * 100)}%
+          </Link>
+        ) : (
+          <span className="kpi-value kpi-value--pending" aria-label="Simulating markets">
+            …
+          </span>
+        )}
+        <span className="kpi-sub">of {DEFAULT_PATH_COUNT.toLocaleString()} varied markets</span>
+      </div>
+      <div className="kpi">
+        <span className="kpi-label">Lifetime tax</span>
+        <span className="kpi-value">{fmtMoneyCompact(summary.lifetimeTaxesAndPenalties)}</span>
+        <span className="kpi-sub">nominal $ · federal + state + penalties</span>
+      </div>
+      <div className="kpi">
+        <span className="kpi-label">Roth converted</span>
+        <span className="kpi-value">{fmtMoneyCompact(summary.lifetimeRothConversions)}</span>
+        <span className="kpi-sub">ending Roth {fmtMoneyCompact(summary.endingByCategory.roth)}</span>
+      </div>
+    </div>
+  )
+}
+
+function PlanName() {
+  const { plan, update } = usePlan()
+  return (
+    <input
+      className="plan-name-input"
+      value={plan.name}
+      aria-label="Plan name"
+      onChange={(e) =>
+        update((d) => {
+          d.name = e.target.value || 'My plan'
+        })
+      }
+    />
+  )
+}
+
+function WorkspaceInner() {
+  const { plan, discardPendingSave } = usePlan()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { prompt, alert, dialogs } = useDialogs()
+
+  // Page identity: retitle the tab per section so history and multi-tab
+  // comparison work, and give every plan page exactly one h1 (sr-only — the
+  // visual header is the plan name + KPI bar).
+  const sectionTitle = sectionTitleOf(location.pathname)
+  useEffect(() => {
+    document.title = sectionTitle ? `${sectionTitle} · ${plan.name} · RetireGolden` : `${plan.name} · RetireGolden`
+  }, [sectionTitle, plan.name])
+  // Reset only when leaving the workspace entirely — a per-change cleanup
+  // would churn the title through 'RetireGolden' between sections.
+  useEffect(
+    () => () => {
+      document.title = 'RetireGolden'
+    },
+    [],
+  )
+  const handleDuplicate = async () => {
+    const name = await prompt({
+      title: 'Duplicate plan',
+      label: 'Name for the duplicated plan',
+      defaultValue: `Copy of ${plan.name}`,
+      confirmLabel: 'Duplicate',
+    })
+    if (name === null) return
+    if (plan.origin === 'example') discardPendingSave()
+    const r = await duplicatePlan(plan.id, { name, source: plan })
+    if (r.ok) navigate(`/plan/${r.plan.id}/results`)
+    else await alert({ title: 'Duplicate plan', body: `Could not duplicate this plan: ${r.issues.join('; ')}` })
+  }
+
+  return (
+    <div className="planner-shell">
+      <ExamplePreviewBanner />
+      <div className="workspace-head">
+        <div className="workspace-head-main">
+          <nav className="workspace-breadcrumb" aria-label="Breadcrumb">
+            <ol>
+              <li>
+                <Link to="/">Your plans</Link>
+              </li>
+              <li aria-current="page">{plan.name}</li>
+            </ol>
+          </nav>
+          <PlanName />
+        </div>
+        <div className="workspace-head-actions">
+          <button type="button" className="btn btn-secondary btn-small" onClick={() => void handleDuplicate()}>
+            Duplicate plan
+          </button>
+          <SaveIndicator />
+        </div>
+      </div>
+      <KpiBar />
+      <div className="workspace">
+        {/* The global skip link lands on #main-content, which still puts the
+            19-link rail between keyboard users and the page content. This
+            second link lets them clear the rail in one stop. */}
+        <a className="skip-link" href="#plan-content">
+          Skip section navigation
+        </a>
+        <nav className="workspace-rail" aria-label="Plan sections">
+          <NavLink to="/" className="rail-link rail-link--back" end>
+            ← Your plans
+          </NavLink>
+          <span className="rail-group">Enter</span>
+          <NavLink to="household" className={railClass}>Household</NavLink>
+          <NavLink to="social-security" className={railClass}>Social Security</NavLink>
+          <NavLink to="accounts" className={railClass}>Accounts</NavLink>
+          <NavLink to="insurance" className={railClass}>Insurance</NavLink>
+          <NavLink to="income" className={railClass}>Income</NavLink>
+          <NavLink to="income-floor" className={railClass}>Income floor</NavLink>
+          <NavLink to="spending" className={railClass}>Spending</NavLink>
+          <NavLink to="strategy" className={railClass}>Strategy</NavLink>
+          <NavLink to="assumptions" className={railClass}>Assumptions</NavLink>
+          <span className="rail-group">Optimize</span>
+          <NavLink to="insights" className={railClass}>Insights</NavLink>
+          <NavLink to="optimize" className={railClass}>Roth & Tax Optimizer</NavLink>
+          <NavLink to="spending-solver" className={railClass}>How much can I spend?</NavLink>
+          <NavLink to="social-security-analysis" className={railClass}>Social Security Optimizer</NavLink>
+          <span className="rail-group">Explore</span>
+          <NavLink to="results" className={railClass}>Results</NavLink>
+          <NavLink to="monte-carlo" className={railClass}>Monte Carlo</NavLink>
+          <NavLink to="scenarios" className={railClass}>Scenarios</NavLink>
+          {plan.household.filingStatus === 'marriedFilingJointly' && plan.household.people.length === 2 ? (
+            <NavLink to="survivor" className={railClass}>Survivor transition</NavLink>
+          ) : null}
+          <NavLink to="relocation" className={railClass}>Relocation Compare</NavLink>
+          <NavLink to="/compare" className={railClass}>Compare plans</NavLink>
+        </nav>
+        <div id="plan-content" tabIndex={-1}>
+          <h1 className="sr-only">{sectionTitle ? `${sectionTitle} — ${plan.name}` : plan.name}</h1>
+          <Outlet />
+        </div>
+      </div>
+      {dialogs}
+    </div>
+  )
+}
+
+export function PlanWorkspace() {
+  const { planId } = useParams()
+  if (!planId) return null
+  return (
+    <PlanProvider planId={planId}>
+      <WorkspaceInner />
+    </PlanProvider>
+  )
+}

package/src/planner/ProvenancePanel.tsx

@@ -0,0 +1,45 @@
+/**
+ * Shows where the engine's tax/limit/benefit defaults come from — one row per
+ * assumption group with its key figures and a link to a citable source.
+ * Rendered on the Disclaimer page and pointed to from Assumptions.
+ */
+
+import {
+  LATEST_PACK_YEAR,
+  PARAMETER_DATA_AS_OF,
+  PARAMETER_PROVENANCE,
+} from '@retiregolden/engine/params'
+
+export function ProvenancePanel() {
+  return (
+    <div className="provenance">
+      <p className="muted small">
+        Applies to the {LATEST_PACK_YEAR} tax year · figures compiled {PARAMETER_DATA_AS_OF}.
+        Verify any number that matters against the official source.
+      </p>
+      <table className="provenance-table">
+        <thead>
+          <tr>
+            <th scope="col">Figures</th>
+            <th scope="col">Source</th>
+          </tr>
+        </thead>
+        <tbody>
+          {PARAMETER_PROVENANCE.map((s) => (
+            <tr key={s.id}>
+              <th scope="row">
+                <span className="provenance-label">{s.label}</span>
+                <span className="provenance-figures muted small">{s.figures}</span>
+              </th>
+              <td>
+                <a href={s.url} target="_blank" rel="noopener noreferrer">
+                  {s.publisher} ↗
+                </a>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}