@retiregolden/planner-ui 0.1.0

package/src/planner/home/DataAndPrivacyCard.tsx

@@ -0,0 +1,56 @@
+import type { RefObject } from 'react'
+
+import type { PlanSummary } from '../../data/planStore'
+
+type DataAndPrivacyCardProps = {
+  plans: PlanSummary[] | null
+  fileInput: RefObject<HTMLInputElement | null>
+  onExportAll: () => void
+  onImportFile: (file: File) => void
+  onClearAll: () => void
+}
+
+export function DataAndPrivacyCard({
+  plans,
+  fileInput,
+  onExportAll,
+  onImportFile,
+  onClearAll,
+}: DataAndPrivacyCardProps) {
+  return (
+    <div className="card home-privacy-card">
+      <h2>Your data stays on your device, not on our servers</h2>
+      <p className="card-hint">
+        RetireGolden has no accounts and no server storage. Everything you enter stays on this device, which means we
+        can never see it — and we can never recover it either. To keep a plan safe or move it to another device,
+        download a plan backup and take it with you.
+      </p>
+      <div className="picker-actions" style={{ margin: 0 }}>
+        <button type="button" className="btn btn-secondary" onClick={() => void onExportAll()} disabled={!plans || plans.length === 0}>
+          Download plan backup
+        </button>
+        <button type="button" className="btn btn-secondary" onClick={() => fileInput.current?.click()}>
+          Import previous backup
+        </button>
+        <button type="button" className="btn btn-secondary btn-danger" onClick={() => void onClearAll()}>
+          Clear all data
+        </button>
+      </div>
+      {/* Reached only through the visible "Import previous backup" button;
+          keeping it out of the tab order stops an invisible tab stop. */}
+      <input
+        ref={fileInput}
+        type="file"
+        accept="application/json"
+        className="sr-only"
+        tabIndex={-1}
+        aria-hidden="true"
+        onChange={(e) => {
+          const f = e.target.files?.[0]
+          if (f) void onImportFile(f)
+          e.target.value = ''
+        }}
+      />
+    </div>
+  )
+}

package/src/planner/home/GettingStartedPaths.tsx

@@ -0,0 +1,46 @@
+import { Link } from 'react-router-dom'
+
+import { createEmptyPlan } from '@retiregolden/engine/model/plan'
+
+type GettingStartedPathsProps = {
+  onCreatePlan: (plan: ReturnType<typeof createEmptyPlan>) => void
+}
+
+export function GettingStartedPaths({ onCreatePlan }: GettingStartedPathsProps) {
+  return (
+    <section className="home-paths" aria-labelledby="getting-started-paths-heading">
+      <h2 id="getting-started-paths-heading">Getting started</h2>
+      <div className="home-paths-grid plan-grid">
+        <Link to="/learn" className="home-path-card plan-card">
+          <span className="home-path-card-title">Learn the basics</span>
+          <span className="home-path-card-desc">
+            Read short guides on privacy, the planner sections, and what RetireGolden models.
+          </span>
+        </Link>
+        <Link to="/examples" className="home-path-card plan-card">
+          <span className="home-path-card-title">Try an example</span>
+          <span className="home-path-card-desc">
+            Open a curated household with realistic numbers — explore freely without saving anything yet.
+          </span>
+        </Link>
+        <button
+          type="button"
+          className="home-path-card plan-card"
+          onClick={() => void onCreatePlan(createEmptyPlan())}
+        >
+          <span className="home-path-card-title">Build your own plan</span>
+          <span className="home-path-card-desc">
+            Start from a blank slate and enter your household, accounts, and spending.
+          </span>
+        </button>
+        <Link to="/import" className="home-path-card plan-card">
+          <span className="home-path-card-title">Import from a file</span>
+          <span className="home-path-card-desc">
+            Seed a plan from a broker CSV, a ProjectionLab export, a spreadsheet, or last year&apos;s tax
+            return — parsed on this device, never uploaded.
+          </span>
+        </Link>
+      </div>
+    </section>
+  )
+}

package/src/planner/home/GettingStartedReopener.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+
+type GettingStartedReopenerProps = {
+  expanded: boolean
+  onToggle: () => void
+  panelId: string
+  children: ReactNode
+}
+
+export function GettingStartedReopener({ expanded, onToggle, panelId, children }: GettingStartedReopenerProps) {
+  return (
+    <div className="home-getting-started-reopener">
+      <button
+        type="button"
+        className="home-reopener-btn"
+        aria-expanded={expanded}
+        aria-controls={panelId}
+        onClick={onToggle}
+      >
+        <span className="home-reopener-icon" aria-hidden="true">
+          {expanded ? '▾' : '▸'}
+        </span>
+        New here? Getting started
+      </button>
+      {expanded ? (
+        <div id={panelId} className="home-getting-started-panel">
+          {children}
+        </div>
+      ) : null}
+    </div>
+  )
+}

package/src/planner/home/StartHereLinks.tsx

@@ -0,0 +1,22 @@
+import { LearnLink } from '../../learn/LearnLink'
+import { getArticle } from '../../learn/learningRegistry'
+import { START_HERE_SLUGS } from './startHereSlugs'
+
+export function StartHereLinks() {
+  return (
+    <section className="home-start-here" aria-labelledby="start-here-heading">
+      <h2 id="start-here-heading">Start here</h2>
+      <ul className="home-start-here-list">
+        {START_HERE_SLUGS.map((slug) => {
+          const article = getArticle(slug)
+          if (!article) return null
+          return (
+            <li key={slug}>
+              <LearnLink slug={slug} label={article.title} variant="inline" />
+            </li>
+          )
+        })}
+      </ul>
+    </section>
+  )
+}

package/src/planner/home/WelcomeHero.tsx

@@ -0,0 +1,39 @@
+type WelcomeHeroProps = {
+  onTryExample: () => void
+  onDismiss?: () => void
+  showDismiss?: boolean
+  headingLevel?: 'h1' | 'h2'
+}
+
+export function WelcomeHero({
+  onTryExample,
+  onDismiss,
+  showDismiss = false,
+  headingLevel = 'h1',
+}: WelcomeHeroProps) {
+  const Heading = headingLevel
+  return (
+    <section className="home-hero" aria-labelledby="home-hero-heading">
+      <Heading id="home-hero-heading">Plan your retirement — privately, in your browser</Heading>
+      <p className="home-hero-subhead lede">
+        Model your household, stress-test taxes and withdrawals, and explore scenarios — with no account and no data
+        leaving this device.
+      </p>
+      <ul className="trust-chips" aria-label="Why RetireGolden">
+        <li>No accounts</li>
+        <li>Nothing leaves your device</li>
+        <li>Educational, with sources</li>
+      </ul>
+      <div className="home-hero-cta">
+        <button type="button" className="btn btn-primary" onClick={onTryExample}>
+          Try an example
+        </button>
+        {showDismiss && onDismiss ? (
+          <button type="button" className="btn btn-ghost btn-small" onClick={onDismiss}>
+            Hide getting started
+          </button>
+        ) : null}
+      </div>
+    </section>
+  )
+}

package/src/planner/home/YourPlans.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react'
+
+import type { PlanSummary } from '../../data/planStore'
+
+function fmtUpdated(iso: string): string {
+  const d = new Date(iso)
+  return Number.isNaN(d.getTime()) ? '' : `Updated ${d.toLocaleDateString()} ${d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}`
+}
+
+type YourPlansProps = {
+  plans: PlanSummary[] | null
+  headingLevel?: 'h1' | 'h2'
+  actions?: ReactNode
+  onOpenPlan: (id: string) => void
+  onDuplicate: (s: PlanSummary) => void
+  onDelete: (s: PlanSummary) => void
+}
+
+export function YourPlans({ plans, headingLevel = 'h2', actions, onOpenPlan, onDuplicate, onDelete }: YourPlansProps) {
+  const Heading = headingLevel
+
+  if (plans === null) {
+    return <div className="skeleton" style={{ height: '8rem' }} aria-label="Loading plans" />
+  }
+
+  if (plans.length === 0) return null
+
+  return (
+    <section className="home-your-plans" aria-labelledby="your-plans-heading">
+      <div className="home-your-plans-head">
+        <Heading id="your-plans-heading">Your plans</Heading>
+        {actions ? <div className="picker-actions home-returning-actions">{actions}</div> : null}
+      </div>
+      <div className="plan-grid">
+        {plans.map((s) => (
+          /* The open action is a real button stretched over the card via CSS
+             (::after), so the whole card stays clickable without nesting the
+             Duplicate/Delete buttons inside another interactive element. */
+          <div key={s.id} className="plan-card">
+            <button
+              type="button"
+              className="plan-card-open"
+              aria-label={`Open plan ${s.name}`}
+              onClick={() => onOpenPlan(s.id)}
+            >
+              <span className="plan-card-name">{s.name}</span>
+            </button>
+            <span className="plan-card-meta">{fmtUpdated(s.updatedAtIso)}</span>
+            <span className="plan-card-actions">
+              <button
+                type="button"
+                className="btn-ghost"
+                aria-label={`Duplicate plan ${s.name}`}
+                onClick={() => void onDuplicate(s)}
+              >
+                Duplicate
+              </button>
+              <button
+                type="button"
+                className="btn-ghost btn-ghost-danger"
+                aria-label={`Delete plan ${s.name}`}
+                onClick={() => void onDelete(s)}
+              >
+                Delete
+              </button>
+            </span>
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/planner/home/importErrorMessage.ts

@@ -0,0 +1,22 @@
+import type { parseV2Backup } from '../../data/v2Backup'
+
+type ImportFailure = Extract<ReturnType<typeof parseV2Backup>, { ok: false }>['reason']
+
+/**
+ * Human import-failure copy with a next step (UI/UX round 2, Step 6) — never the
+ * raw enum reason with underscores, which leaked schema jargon at the user.
+ */
+export function importErrorMessage(reason: ImportFailure | string): string {
+  switch (reason) {
+    case 'too_large':
+      return 'That file is too large to be a RetireGolden backup. Pick the JSON file you downloaded from Data & privacy → Download backup.'
+    case 'unsupported_version':
+      return 'That backup was made by a different version of RetireGolden, so it can’t be imported here.'
+    case 'no_valid_plans':
+      return 'That backup didn’t contain any readable plans. Export a fresh one from Data & privacy → Download backup.'
+    case 'not_json':
+    case 'wrong_kind':
+    default:
+      return 'That file isn’t a RetireGolden backup. Export one from Data & privacy → Download backup, then import that file.'
+  }
+}

package/src/planner/home/startHereSlugs.ts

@@ -0,0 +1,7 @@
+/** Curated beginner articles surfaced on the planner home "Start here" row. */
+export const START_HERE_SLUGS = [
+  'about-retiregolden',
+  'privacy-what-stays-in-your-browser',
+  'planner-overview',
+  'what-retiregolden-models',
+] as const

package/src/planner/home/useHomeData.ts

@@ -0,0 +1,190 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+
+import {
+  clearAllPlans,
+  duplicatePlan,
+  listUserPlanSummaries,
+  loadPlan,
+  savePlan,
+  deletePlan,
+  type PlanSummary,
+} from '../../data/planStore'
+import { normalizePlansForImport, parseV2Backup, serializeV2Backup } from '../../data/v2Backup'
+import { type Plan } from '@retiregolden/engine/model/plan'
+import { useDialogs } from '../dialogs'
+import { importErrorMessage } from './importErrorMessage'
+
+export function useHomeData() {
+  const navigate = useNavigate()
+  const [plans, setPlans] = useState<PlanSummary[] | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+  // A just-deleted plan, held in memory for a brief undo window. The delete is
+  // already committed to storage, so an expired or navigated-away toast never
+  // leaves a plan half-deleted; Undo simply re-saves the in-memory copy.
+  const [undoPlan, setUndoPlan] = useState<Plan | null>(null)
+  const undoTimer = useRef<number | null>(null)
+  const fileInput = useRef<HTMLInputElement>(null)
+  const { confirm, prompt, dialogs } = useDialogs()
+
+  const refresh = useCallback(() => {
+    void listUserPlanSummaries().then(setPlans)
+  }, [])
+
+  const clearUndoTimer = () => {
+    if (undoTimer.current !== null) {
+      clearTimeout(undoTimer.current)
+      undoTimer.current = null
+    }
+  }
+
+  useEffect(() => {
+    refresh()
+  }, [refresh])
+
+  useEffect(() => () => clearUndoTimer(), [])
+
+  const openPlan = (id: string) => navigate(`/plan/${id}`)
+
+  const createAndOpen = async (plan: Plan) => {
+    const r = await savePlan(plan)
+    if (r.ok) openPlan(r.plan.id)
+    else setNotice(`Could not save the new plan: ${r.issues.join('; ')}`)
+  }
+
+  const handleExportAll = async () => {
+    const summaries = await listUserPlanSummaries()
+    const loaded: Plan[] = []
+    for (const s of summaries) {
+      const r = await loadPlan(s.id)
+      if (r.ok) loaded.push(r.plan)
+    }
+    const blob = new Blob([serializeV2Backup(loaded)], { type: 'application/json' })
+    const a = document.createElement('a')
+    a.href = URL.createObjectURL(blob)
+    a.download = `retiregolden-backup-${new Date().toISOString().slice(0, 10)}.json`
+    a.click()
+    URL.revokeObjectURL(a.href)
+  }
+
+  const handleImportFile = async (file: File) => {
+    const r = parseV2Backup(await file.text())
+    if (!r.ok) {
+      setNotice(importErrorMessage(r.reason))
+      return
+    }
+    const normalized = await normalizePlansForImport(r.plans)
+    for (const p of normalized) await savePlan(p)
+    setNotice(
+      `Imported ${normalized.length} plan${normalized.length === 1 ? '' : 's'}.` +
+        (r.warnings.length > 0 ? ` Skipped: ${r.warnings.join('; ')}` : ''),
+    )
+    refresh()
+  }
+
+  const handleDuplicate = async (s: PlanSummary) => {
+    const name = await prompt({
+      title: 'Duplicate plan',
+      label: 'Name for the duplicated plan',
+      defaultValue: `Copy of ${s.name}`,
+      confirmLabel: 'Duplicate',
+    })
+    if (name === null) return
+    const r = await duplicatePlan(s.id, { name })
+    if (r.ok) {
+      setNotice(`Duplicated "${s.name}" as "${r.plan.name}".`)
+      refresh()
+    } else {
+      setNotice(`Could not duplicate "${s.name}": ${r.issues.join('; ')}`)
+    }
+  }
+
+  const handleDelete = async (s: PlanSummary) => {
+    const ok = await confirm({
+      title: 'Delete plan',
+      body: `Delete "${s.name}"? You'll have a few seconds to undo.`,
+      confirmLabel: 'Delete plan',
+      danger: true,
+    })
+    if (!ok) return
+    const loaded = await loadPlan(s.id)
+    await deletePlan(s.id)
+    refresh()
+    if (loaded.ok) {
+      clearUndoTimer()
+      setUndoPlan(loaded.plan)
+      undoTimer.current = window.setTimeout(() => setUndoPlan(null), 5000)
+    }
+  }
+
+  const undoDelete = async () => {
+    if (!undoPlan) return
+    clearUndoTimer()
+    const restored = undoPlan
+    // Keep the in-memory plan (and the toast) until the restore actually
+    // lands — if the save fails, the user must not lose both the plan and
+    // the affordance at once.
+    try {
+      const r = await savePlan(restored)
+      if (r.ok) {
+        setUndoPlan(null)
+        refresh()
+      } else {
+        setNotice(`Could not restore "${restored.name}": ${r.issues.join('; ')}`)
+      }
+    } catch {
+      setNotice(`Could not restore "${restored.name}" — storage is unavailable in this browser right now.`)
+    }
+  }
+
+  const dismissUndo = () => {
+    clearUndoTimer()
+    setUndoPlan(null)
+  }
+
+  const handleClearAll = async () => {
+    const ok = await confirm({
+      title: 'Clear all data',
+      body:
+        'This erases ALL RetireGolden data from this browser — every plan, plus Social Security and ' +
+        'life-expectancy entries. It cannot be undone. Download a plan backup first if you want to keep anything.',
+      confirmLabel: 'Erase everything',
+      danger: true,
+      typedConfirmation: 'delete',
+      extraAction: { label: 'Download backup', onClick: () => void handleExportAll() },
+    })
+    if (!ok) return
+    // A pending delete-undo would let "Undo" resurrect a plan after the
+    // erasure — drop it before clearing so "erases ALL data" stays true.
+    dismissUndo()
+    await clearAllPlans()
+    try {
+      for (const key of Object.keys(localStorage)) {
+        if (key.startsWith('retiregolden.')) localStorage.removeItem(key)
+      }
+    } catch {
+      /* localStorage unavailable — IndexedDB is already cleared */
+    }
+    setNotice('All RetireGolden data has been erased from this browser.')
+    refresh()
+  }
+
+  return {
+    plans,
+    notice,
+    setNotice,
+    undoPlan,
+    undoDelete,
+    dismissUndo,
+    fileInput,
+    refresh,
+    createAndOpen,
+    handleExportAll,
+    handleImportFile,
+    handleDuplicate,
+    handleDelete,
+    handleClearAll,
+    openPlan,
+    dialogs,
+  }
+}

package/src/planner/home/useHomeMode.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from 'react'
+
+import { readLocal, STORAGE_KEYS, writeLocal } from '../../data/localStore'
+import type { PlanSummary } from '../../data/planStore'
+
+export const WELCOME_DISMISSED_KEY = STORAGE_KEYS.homeWelcomeDismissed
+
+export type HomeMode = 'first-run' | 'returning'
+
+function readWelcomeDismissed(): boolean {
+  if (typeof window === 'undefined') return true
+  return readLocal(WELCOME_DISMISSED_KEY) !== 'false'
+}
+
+function writeWelcomeDismissed(dismissed: boolean): void {
+  if (typeof window === 'undefined') return
+  writeLocal(WELCOME_DISMISSED_KEY, dismissed ? 'true' : 'false')
+}
+
+export function deriveHomeMode(plans: PlanSummary[] | null): HomeMode {
+  if (plans !== null && plans.length === 0) return 'first-run'
+  return 'returning'
+}
+
+export function isWelcomeExpanded(mode: HomeMode, welcomeDismissed: boolean): boolean {
+  if (mode === 'first-run') return true
+  return !welcomeDismissed
+}
+
+export function useHomeMode(plans: PlanSummary[] | null) {
+  const [welcomeDismissed, setWelcomeDismissed] = useState(readWelcomeDismissed)
+
+  const mode = deriveHomeMode(plans)
+  const welcomeExpanded = isWelcomeExpanded(mode, welcomeDismissed)
+
+  const dismissWelcome = useCallback(() => {
+    setWelcomeDismissed(true)
+    writeWelcomeDismissed(true)
+  }, [])
+
+  const showWelcome = useCallback(() => {
+    setWelcomeDismissed(false)
+    writeWelcomeDismissed(false)
+  }, [])
+
+  return { mode, welcomeExpanded, dismissWelcome, showWelcome }
+}

package/src/planner/householdActions.ts

@@ -0,0 +1,22 @@
+/** Pure plan mutations for household edits (kept out of the component file so
+ *  they're testable and don't trip react-refresh's only-export-components rule). */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+
+/**
+ * Remove a partner and re-home everything that referenced them so the plan stays
+ * valid: accounts move to the primary, the removed person's incomes and policies
+ * drop, and any permanent-life beneficiary pointing at them falls back to the
+ * estate. Pure mutator (works on an Immer draft or a plain Plan).
+ */
+export function removePartner(d: Plan, removedId: string) {
+  d.household.people = d.household.people.filter((p) => p.id !== removedId)
+  d.household.filingStatus = 'single'
+  const primaryId = d.household.people[0]!.id
+  d.accounts = d.accounts.map((a) => (a.ownerPersonId === removedId ? { ...a, ownerPersonId: primaryId } : a))
+  d.incomes = d.incomes.filter((s) => !('personId' in s) || s.personId !== removedId)
+  d.insurance = d.insurance
+    .filter((p) => (p.kind === 'ltc' ? p.owner : p.insured) !== removedId)
+    .map((p) => (p.kind === 'permanentLife' && p.beneficiary === removedId ? { ...p, beneficiary: 'estate' as const } : p))
+  d.careEvents = d.careEvents.filter((c) => c.personId !== removedId)
+}