@retiregolden/planner-ui 0.1.0

package/src/planner/dialogs.tsx

@@ -0,0 +1,133 @@
+/**
+ * In-app replacements for window.confirm / window.prompt / window.alert,
+ * built on the shared focus-managed Modal. `useDialogs()` returns
+ * promise-based openers so call sites keep their imperative shape:
+ *
+ *   const { confirm, dialogs } = useDialogs()
+ *   ...
+ *   if (!(await confirm({ title: 'Delete plan', body: '...' }))) return
+ *
+ * Render `dialogs` once in the owning component. Escape, backdrop click,
+ * and Cancel all resolve to the "did nothing" value (false / null).
+ */
+
+import { useCallback, useRef, useState, type ReactNode } from 'react'
+
+import {
+  AlertDialog,
+  ChoiceDialog,
+  ConfirmDialog,
+  PromptDialog,
+  type AlertOptions,
+  type ChoiceOptions,
+  type ConfirmOptions,
+  type PromptOptions,
+} from './dialogViews'
+
+export type { AlertOptions, ChoiceOption, ChoiceOptions, ConfirmOptions, PromptOptions } from './dialogViews'
+
+type ActiveDialog =
+  | { kind: 'confirm'; opts: ConfirmOptions; resolve: (ok: boolean) => void }
+  | { kind: 'prompt'; opts: PromptOptions; resolve: (value: string | null) => void }
+  | { kind: 'alert'; opts: AlertOptions; resolve: () => void }
+  | { kind: 'choice'; opts: ChoiceOptions<string>; resolve: (value: string | null) => void }
+
+export function useDialogs() {
+  const [active, setActive] = useState<ActiveDialog | null>(null)
+  // Synchronous mirror of `active`: a second dialog requested while one is
+  // open must not clobber it (that would strand the first Promise forever),
+  // so re-entrant calls resolve immediately to their "did nothing" value.
+  const activeRef = useRef<ActiveDialog | null>(null)
+
+  const open = useCallback((dialog: ActiveDialog): boolean => {
+    if (activeRef.current) return false
+    activeRef.current = dialog
+    setActive(dialog)
+    return true
+  }, [])
+
+  const confirm = useCallback(
+    (opts: ConfirmOptions) =>
+      new Promise<boolean>((resolve) => {
+        if (!open({ kind: 'confirm', opts, resolve })) resolve(false)
+      }),
+    [open],
+  )
+  const prompt = useCallback(
+    (opts: PromptOptions) =>
+      new Promise<string | null>((resolve) => {
+        if (!open({ kind: 'prompt', opts, resolve })) resolve(null)
+      }),
+    [open],
+  )
+  const alert = useCallback(
+    (opts: AlertOptions) =>
+      new Promise<void>((resolve) => {
+        if (!open({ kind: 'alert', opts, resolve })) resolve()
+      }),
+    [open],
+  )
+  const choice = useCallback(
+    <T extends string>(opts: ChoiceOptions<T>) =>
+      new Promise<T | null>((resolve) => {
+        const opened = open({
+          kind: 'choice',
+          opts: opts as ChoiceOptions<string>,
+          resolve: resolve as (value: string | null) => void,
+        })
+        if (!opened) resolve(null)
+      }),
+    [open],
+  )
+
+  let dialogs: ReactNode = null
+  if (active) {
+    const close = () => {
+      activeRef.current = null
+      setActive(null)
+    }
+    if (active.kind === 'confirm') {
+      dialogs = (
+        <ConfirmDialog
+          opts={active.opts}
+          onResult={(ok) => {
+            close()
+            active.resolve(ok)
+          }}
+        />
+      )
+    } else if (active.kind === 'prompt') {
+      dialogs = (
+        <PromptDialog
+          opts={active.opts}
+          onResult={(value) => {
+            close()
+            active.resolve(value)
+          }}
+        />
+      )
+    } else if (active.kind === 'alert') {
+      dialogs = (
+        <AlertDialog
+          opts={active.opts}
+          onResult={() => {
+            close()
+            active.resolve()
+          }}
+        />
+      )
+    } else {
+      dialogs = (
+        <ChoiceDialog
+          opts={active.opts}
+          onResult={(value) => {
+            close()
+            active.resolve(value)
+          }}
+        />
+      )
+    }
+  }
+
+  return { confirm, prompt, alert, choice, dialogs }
+}

package/src/planner/examples/ExampleLibrary.tsx

@@ -0,0 +1,189 @@
+/**
+ * Example library — browsable curated demos (rendered on `/examples`).
+ */
+
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+
+import { LearnLink } from '../../learn/LearnLink'
+import { useDialogs } from '../dialogs'
+import { EXAMPLE_PLANS, type ExamplePlan } from './registry'
+import { openExampleExisting, openExampleFresh, prepareExampleOpen, saveExampleToMyPlans } from './loadExample'
+import { EXAMPLE_LOAD_FRESH_DESC, EXAMPLE_OPEN_EXISTING_DESC } from './exampleCopy'
+import { loadPlan } from '../../data/planStore'
+import { readLocal, STORAGE_KEYS, writeLocal } from '../../data/localStore'
+
+/**
+ * Three curated starters shown first so a confused first-timer faces a handful
+ * of choices, not the whole 24-card wall (UI/UX round 2, Step 4): a mainstream
+ * couple, an approachable single just getting started, and an under-saved /
+ * late-start cautionary case. The full library is one click away.
+ */
+const FEATURED_EXAMPLE_IDS = ['example-couple', 'early-career-match', 'under-saved-single'] as const
+
+function householdFacts(example: ExamplePlan): string {
+  const plan = example.build()
+  const people = plan.household.people.length
+  const filing = plan.household.filingStatus === 'marriedFilingJointly' ? 'Couple' : 'Single'
+  return `${filing} · ${plan.household.state} · ${people} ${people === 1 ? 'person' : 'people'}`
+}
+
+function ExampleCard({ example, onNotice }: { example: ExamplePlan; onNotice: (msg: string) => void }) {
+  const navigate = useNavigate()
+  const [busy, setBusy] = useState(false)
+  const { choice, dialogs } = useDialogs()
+
+  const openDemo = async (chosen?: 'open-existing' | 'load-fresh') => {
+    setBusy(true)
+    try {
+      if (chosen === 'open-existing') {
+        const r = await openExampleExisting(example.id)
+        if (r.ok) navigate(`/plan/${r.planId}/results`)
+        else onNotice(r.reason)
+        return
+      }
+      if (chosen === 'load-fresh') {
+        const r = await openExampleFresh(example.id)
+        if (r.ok) navigate(`/plan/${r.planId}/results`)
+        else onNotice(r.reason)
+        return
+      }
+
+      const prepared = await prepareExampleOpen(example.id)
+      if (!prepared.ok) {
+        onNotice(prepared.reason)
+        return
+      }
+      if (prepared.needsChoice) {
+        const picked = await choice({
+          title: 'Open example',
+          body: `"${example.title}" was opened before. Which version would you like?`,
+          choices: [
+            { value: 'open-existing', label: 'Open my version', description: EXAMPLE_OPEN_EXISTING_DESC },
+            { value: 'load-fresh', label: 'Load a fresh copy', description: EXAMPLE_LOAD_FRESH_DESC },
+          ],
+        })
+        if (picked !== null) await openDemo(picked)
+        return
+      }
+      navigate(`/plan/${prepared.planId}/results`)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const handleSave = async () => {
+    setBusy(true)
+    try {
+      const prepared = await prepareExampleOpen(example.id)
+      if (!prepared.ok) {
+        onNotice(prepared.reason)
+        return
+      }
+      let planId = prepared.planId
+      if (prepared.needsChoice) {
+        const fresh = await openExampleFresh(example.id)
+        if (!fresh.ok) {
+          onNotice(fresh.reason)
+          return
+        }
+        planId = fresh.planId
+      }
+      const loaded = await loadPlan(planId)
+      if (!loaded.ok) {
+        onNotice('Could not load the example to save.')
+        return
+      }
+      const converted = await saveExampleToMyPlans(loaded.plan)
+      if (converted.ok) {
+        onNotice(`"${example.title}" saved to Your plans.`)
+        navigate(`/plan/${converted.plan.id}/results`)
+      } else {
+        onNotice(converted.issues.join('; '))
+      }
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const learnHook = { slug: example.learnSlug, label: 'Learn about this example' }
+
+  return (
+    <div className="plan-card example-card">
+      <span className="plan-card-name">{example.title}</span>
+      <span className="plan-card-meta">{householdFacts(example)}</span>
+      <p className="example-card-teaches">{example.teaches}</p>
+      <span className="plan-card-actions">
+        <button type="button" className="btn btn-primary btn-small" disabled={busy} onClick={() => void openDemo()}>
+          Open
+        </button>
+        <button type="button" className="btn btn-secondary btn-small" disabled={busy} onClick={() => void handleSave()}>
+          Save to my plans
+        </button>
+        <LearnLink {...learnHook} variant="button" className="btn btn-ghost btn-small" />
+      </span>
+      {dialogs}
+    </div>
+  )
+}
+
+const FEATURED = FEATURED_EXAMPLE_IDS.map((id) => EXAMPLE_PLANS.find((e) => e.id === id)).filter(
+  (e): e is ExamplePlan => e !== undefined,
+)
+const REST = EXAMPLE_PLANS.filter((e) => !FEATURED_EXAMPLE_IDS.includes(e.id as (typeof FEATURED_EXAMPLE_IDS)[number]))
+
+export function ExampleLibrary({
+  onNotice,
+  headingLevel = 'h2',
+}: {
+  onNotice: (msg: string) => void
+  headingLevel?: 'h1' | 'h2'
+}) {
+  const Heading = headingLevel
+  // First-time visitors see the three starters; anyone who expanded the full
+  // grid before keeps it open (stored per-device, cleared by "Clear all data").
+  const [expanded, setExpanded] = useState(() => readLocal(STORAGE_KEYS.examplesExpanded) === 'true')
+
+  const toggle = () => {
+    setExpanded((prev) => {
+      const next = !prev
+      writeLocal(STORAGE_KEYS.examplesExpanded, String(next))
+      return next
+    })
+  }
+
+  return (
+    <section className="example-library" aria-labelledby="example-library-heading">
+      <Heading id="example-library-heading">Example library</Heading>
+      <p className="lede">
+        Explore curated households in the full planner. Examples stay out of Your plans until you save one — edit freely
+        and refresh without cluttering your own list.
+      </p>
+      <div className="plan-grid">
+        {FEATURED.map((example) => (
+          <ExampleCard key={example.id} example={example} onNotice={onNotice} />
+        ))}
+      </div>
+
+      <div className="examples-browse-all">
+        <button
+          type="button"
+          className="btn btn-secondary"
+          aria-expanded={expanded}
+          aria-controls="examples-full-grid"
+          onClick={toggle}
+        >
+          {expanded ? 'Show fewer examples' : `Browse all ${EXAMPLE_PLANS.length} examples`}
+        </button>
+      </div>
+
+      {expanded ? (
+        <div className="plan-grid" id="examples-full-grid">
+          {REST.map((example) => (
+            <ExampleCard key={example.id} example={example} onNotice={onNotice} />
+          ))}
+        </div>
+      ) : null}
+    </section>
+  )
+}

package/src/planner/examples/ExamplePreviewBanner.tsx

@@ -0,0 +1,55 @@
+/**
+ * Persistent banner when viewing a library example in the workspace.
+ */
+
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+
+import { LearnLink } from '../../learn/LearnLink'
+import { useDialogs } from '../dialogs'
+import { usePlan } from '../planContextCore'
+import { getExampleById } from './registry'
+import { saveExampleToMyPlans } from './loadExample'
+import { EXAMPLE_BANNER_PERSISTENCE } from './exampleCopy'
+
+export function ExamplePreviewBanner() {
+  const { plan, discardPendingSave } = usePlan()
+  const navigate = useNavigate()
+  const [busy, setBusy] = useState(false)
+  const { alert, dialogs } = useDialogs()
+
+  if (plan.origin !== 'example') return null
+
+  const example = plan.exampleSourceId ? getExampleById(plan.exampleSourceId) : undefined
+  const learnHook = example
+    ? { slug: example.learnSlug, label: 'Learn about this example' }
+    : null
+
+  const handleSave = async () => {
+    setBusy(true)
+    try {
+      discardPendingSave()
+      const r = await saveExampleToMyPlans(plan)
+      if (r.ok) navigate(`/plan/${r.plan.id}/results`)
+      else await alert({ title: 'Save example', body: `Could not save: ${r.issues.join('; ')}` })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className="callout callout--info example-preview-banner" role="status">
+      <p>
+        <strong>You&apos;re viewing an example.</strong> {EXAMPLE_BANNER_PERSISTENCE}
+        {example?.lookFor ? ` ${example.lookFor}` : ''}
+      </p>
+      <div className="picker-actions" style={{ margin: 0 }}>
+        <button type="button" className="btn btn-primary btn-small" disabled={busy} onClick={() => void handleSave()}>
+          Save to my plans
+        </button>
+        {learnHook ? <LearnLink {...learnHook} variant="button" className="btn btn-secondary btn-small" /> : null}
+      </div>
+      {dialogs}
+    </div>
+  )
+}

package/src/planner/examples/ExamplesPage.tsx

@@ -0,0 +1,25 @@
+/**
+ * Dedicated example library route — browsable curated demos separate from the
+ * planner home so the home stays focused on the user's own plans.
+ */
+
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+
+import { ExampleLibrary } from './ExampleLibrary'
+
+export function ExamplesPage() {
+  const [notice, setNotice] = useState<string | null>(null)
+
+  return (
+    <section className="page examples-page">
+      <nav className="examples-back" aria-label="Back to planner home">
+        <Link to="/">← Your plans</Link>
+      </nav>
+
+      {notice ? <div className="callout callout--info">{notice}</div> : null}
+
+      <ExampleLibrary onNotice={setNotice} headingLevel="h1" />
+    </section>
+  )
+}

package/src/planner/examples/OpenExampleButton.tsx

@@ -0,0 +1,61 @@
+/**
+ * Open a library example from a Learning Center article.
+ */
+
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+
+import { useDialogs } from '../dialogs'
+import { getExampleById } from './registry'
+import { openExampleExisting, openExampleFresh, prepareExampleOpen } from './loadExample'
+import { EXAMPLE_LOAD_FRESH_DESC, EXAMPLE_OPEN_EXISTING_DESC } from './exampleCopy'
+
+export function OpenExampleButton({ exampleId }: { exampleId: string }) {
+  const navigate = useNavigate()
+  const [busy, setBusy] = useState(false)
+  const { choice, dialogs } = useDialogs()
+  const example = getExampleById(exampleId)
+  if (!example) return null
+
+  const open = async (chosen?: 'open-existing' | 'load-fresh') => {
+    setBusy(true)
+    try {
+      if (chosen === 'open-existing') {
+        const r = await openExampleExisting(exampleId)
+        if (r.ok) navigate(`/plan/${r.planId}/results`)
+        return
+      }
+      if (chosen === 'load-fresh') {
+        const r = await openExampleFresh(exampleId)
+        if (r.ok) navigate(`/plan/${r.planId}/results`)
+        return
+      }
+      const prepared = await prepareExampleOpen(exampleId)
+      if (!prepared.ok) return
+      if (prepared.needsChoice) {
+        const picked = await choice({
+          title: 'Open example',
+          body: `"${example.title}" was opened before. Which version would you like?`,
+          choices: [
+            { value: 'open-existing', label: 'Open my version', description: EXAMPLE_OPEN_EXISTING_DESC },
+            { value: 'load-fresh', label: 'Load a fresh copy', description: EXAMPLE_LOAD_FRESH_DESC },
+          ],
+        })
+        if (picked !== null) await open(picked)
+        return
+      }
+      navigate(`/plan/${prepared.planId}/results`)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <>
+      <button type="button" className="btn btn-primary" disabled={busy} onClick={() => void open()}>
+        Open this example in the planner
+      </button>
+      {dialogs}
+    </>
+  )
+}

package/src/planner/examples/buildAggressiveSaver.ts

@@ -0,0 +1,102 @@
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'aggressive-saver'
+
+export function buildAggressiveSaver(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Aggressive saver to early retirement', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'WA',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Taylor', dob: '1996-01-01', sex: 'average', retirementAge: 45, longevity: { planningAge: 95, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'pretax-401k'),
+      name: 'Pre-tax 401(k)',
+      ownerPersonId: p1,
+      annualReturnPct: 8,
+      kind: 'employer',
+      balance: 100_000,
+      annualContribution: 23_000,
+      employerMatch: {
+        matchPct: 100,
+        capPctOfPay: 5,
+      },
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth-ira'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 8,
+      kind: 'ira',
+      balance: 50_000,
+      annualContribution: 7_000,
+    },
+    {
+      type: 'taxable',
+      id: exampleEntityId(EXAMPLE_ID, 'taxable-brokerage'),
+      name: 'Taxable Brokerage',
+      ownerPersonId: null,
+      annualReturnPct: 8,
+      balance: 150_000,
+      costBasis: 120_000,
+      annualContribution: 0,
+      contributionSchedule: [
+        {
+          annualAmount: 30_000,
+          fromAge: 30,
+          toAge: 45,
+          escalationPct: 5,
+        },
+      ],
+    },
+  ]
+  plan.incomes = [
+    {
+      type: 'wages',
+      id: exampleEntityId(EXAMPLE_ID, 'wages'),
+      personId: p1,
+      annualGross: 120_000,
+      endAge: null,
+      realGrowthPct: 5,
+    },
+    {
+      type: 'socialSecurity',
+      id: exampleEntityId(EXAMPLE_ID, 'ss'),
+      personId: p1,
+      piaMonthly: 3_000,
+      earnings: null,
+      claimAge: { years: 67, months: 0 },
+    },
+  ]
+  plan.expenses = {
+    baseAnnual: 45_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 500, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 200 },
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 2,
+    defaultReturnPct: 6,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 120_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 3.5,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`aggressive-saver invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}