@retiregolden/planner-ui 0.1.0

package/src/learn/ArticlePage.tsx

@@ -0,0 +1,57 @@
+/**
+ * Article page (/learn/:slug).
+ *
+ * Routes a slug to one of three states: a finished article (rendered through
+ * ArticleShell), an intentional "planned" placeholder for stubs, or a not-found
+ * state for unknown slugs. Stubs and unknown slugs never render an empty page.
+ */
+
+import { Link, useParams } from 'react-router-dom'
+import { getArticle, getCategory, isReadable, type LearningArticle } from './learningRegistry'
+import { ArticleShell, BackLink } from './components/ArticleShell'
+
+function ArticleNotFound() {
+  return (
+    <article className="page learn-article">
+      <BackLink />
+      <h1>Article not found</h1>
+      <p className="lede">We couldn’t find that article. It may have moved, or the link may be out of date.</p>
+      <p>
+        <Link to="/learn">Browse the Learning Center</Link> to find what you’re looking for.
+      </p>
+    </article>
+  )
+}
+
+function PlannedArticle({ article }: { article: LearningArticle }) {
+  const category = getCategory(article.category)
+  return (
+    <article className="page learn-article">
+      <BackLink />
+      <div className="learn-card-head">
+        {category && <span className="learn-card-cat">{category.label}</span>}
+        <span className="learn-badge learn-badge--planned">Planned</span>
+      </div>
+      <h1>{article.title}</h1>
+      <p className="lede">{article.description}</p>
+      <div className="learn-callout learn-callout--note">
+        <p>
+          This article is planned but not written yet — it’s on the V9 content roadmap. In the meantime, explore the
+          planner or browse other topics.
+        </p>
+      </div>
+      <p>
+        <Link to="/learn">Back to the Learning Center</Link>
+      </p>
+    </article>
+  )
+}
+
+export function ArticlePage() {
+  const { slug } = useParams()
+  const article = slug ? getArticle(slug) : undefined
+
+  if (!article) return <ArticleNotFound />
+  if (!isReadable(article)) return <PlannedArticle article={article} />
+  return <ArticleShell article={article} />
+}

package/src/learn/GlossaryPage.tsx

@@ -0,0 +1,33 @@
+/**
+ * Glossary index (/learn/glossary).
+ *
+ * A flat, alphabetized definition list. Each term has a stable anchor id so
+ * tooltips and articles can deep-link to a specific definition.
+ */
+
+import { Link } from 'react-router-dom'
+import { GLOSSARY_TERMS } from './glossary'
+
+export function GlossaryPage() {
+  return (
+    <article className="page learn-glossary">
+      <Link to="/learn" className="learn-back">
+        ← Learning Center
+      </Link>
+      <h1>Glossary</h1>
+      <p className="lede">Plain-language definitions of the terms and acronyms used across RetireGolden.</p>
+
+      <dl className="learn-glossary-list">
+        {GLOSSARY_TERMS.map((t) => (
+          <div key={t.id} className="learn-glossary-item" id={t.id}>
+            <dt className="learn-glossary-term">
+              {t.term}
+              {t.expansion && <span className="learn-glossary-expansion"> — {t.expansion}</span>}
+            </dt>
+            <dd className="learn-glossary-def">{t.definition}</dd>
+          </div>
+        ))}
+      </dl>
+    </article>
+  )
+}

package/src/learn/LearnAboutScreen.tsx

@@ -0,0 +1,41 @@
+/**
+ * LearnAboutScreen (V9 PR3) — the standard contextual learning cluster for a
+ * planner screen.
+ *
+ * Given a planner route pattern (e.g. `/plan/:planId/optimize`), it lists the
+ * readable Learning Center articles that relate to that screen, each via
+ * {@link LearnLink} so they carry a return path. The list is derived from
+ * article metadata, so it stays in sync with the registry and renders nothing
+ * when no ready article relates yet — every screen can host it safely.
+ */
+
+import { articlesForRoute, byListingOrder } from './learningRegistry'
+import { LearnLink } from './LearnLink'
+
+/** Keep the cluster focused — the doc's guidance is that 3-5 links is plenty. */
+const MAX_LINKS = 5
+
+export function LearnAboutScreen({
+  route,
+  title = 'Learn about this screen',
+  limit = MAX_LINKS,
+}: {
+  route: string
+  title?: string
+  limit?: number
+}) {
+  const articles = articlesForRoute(route).slice().sort(byListingOrder).slice(0, limit)
+  if (articles.length === 0) return null
+  return (
+    <aside className="learn-screen" aria-label={title}>
+      <span className="learn-screen-title">{title}</span>
+      <ul className="learn-screen-list">
+        {articles.map((a) => (
+          <li key={a.slug}>
+            <LearnLink slug={a.slug} label={a.title} />
+          </li>
+        ))}
+      </ul>
+    </aside>
+  )
+}

package/src/learn/LearnCards.tsx

@@ -0,0 +1,41 @@
+/**
+ * Shared presentational cards for the Learning Center.
+ *
+ * A readable article renders as a clickable card; a planned (stub) article
+ * renders as a non-interactive "Planned" card so users are never routed to an
+ * empty page (spec §7.3).
+ */
+
+import { Link } from 'react-router-dom'
+import { getCategory, isReadable, type LearningArticle } from './learningRegistry'
+
+export function ArticleCard({ article }: { article: LearningArticle }) {
+  const readable = isReadable(article)
+  const category = getCategory(article.category)
+
+  const inner = (
+    <>
+      <div className="learn-card-head">
+        {category && <span className="learn-card-cat">{category.label}</span>}
+        {readable ? null : <span className="learn-badge learn-badge--planned">Planned</span>}
+      </div>
+      <span className="learn-card-title">{article.title}</span>
+      <span className="learn-card-desc">{article.description}</span>
+    </>
+  )
+
+  if (readable) {
+    return (
+      <Link to={`/learn/${article.slug}`} className="learn-card learn-card--link">
+        {inner}
+      </Link>
+    )
+  }
+
+  return (
+    <div className="learn-card learn-card--planned">
+      {inner}
+      <span className="sr-only">Planned article, not yet available.</span>
+    </div>
+  )
+}

package/src/learn/LearnLink.tsx

@@ -0,0 +1,91 @@
+/**
+ * LearnLink (V9 PR3) — the single, consistent way the planner links out to the
+ * Learning Center.
+ *
+ * Every contextual "Learn more" in the app should go through this component so
+ * links behave the same everywhere: the slug is validated against the registry,
+ * an optional in-article anchor is supported, the look is consistent per
+ * variant, and the originating planner path is preserved so the article's back
+ * link can return the reader to the screen they came from instead of the
+ * Learning Center home.
+ *
+ * The slug is intentionally typed `string`: most call sites pass a hook from
+ * `planner/learnLinks.ts` (validated by a broken-slug test) or a registry slug
+ * (validated by the registry-integrity tests). An unknown slug renders nothing
+ * and logs in dev rather than producing a dead link.
+ */
+
+import { Link, useLocation } from 'react-router-dom'
+import { getArticle } from './learningRegistry'
+
+export type LearnHook = {
+  /** Article slug in the Learning Center registry. */
+  slug: string
+  /** Link text. Defaults to "Learn more". */
+  label?: string
+  /** Optional anchor (without `#`) to jump to within the article. */
+  anchor?: string
+}
+
+type LearnLinkProps = LearnHook & {
+  /**
+   * - `inline`: a quiet inline link (default), e.g. inside a screen cluster.
+   * - `tip`: sized and spaced to sit at the bottom of a help bubble.
+   * - `button`: a compact pill for page headers/callouts.
+   */
+  variant?: 'inline' | 'tip' | 'button'
+  className?: string
+}
+
+/** Title-case a single planner route segment into a human label for the back link. */
+const SEGMENT_LABELS: Record<string, string> = {
+  household: 'Household',
+  'social-security': 'Social Security',
+  accounts: 'Accounts',
+  insurance: 'Insurance',
+  income: 'Income',
+  spending: 'Spending',
+  strategy: 'Strategy',
+  assumptions: 'Assumptions',
+  'assumptions-card': 'Your assumptions',
+  insights: 'Insights',
+  'social-security-analysis': 'Social Security Optimizer',
+  results: 'Results',
+  'monte-carlo': 'Monte Carlo',
+  scenarios: 'Scenarios',
+  survivor: 'Survivor transition',
+  optimize: 'Roth & Tax Optimizer',
+  report: 'Report',
+}
+
+/** A short, human label for where a return path points (planner screen name). */
+function originLabel(pathname: string): string | undefined {
+  const segment = pathname.match(/\/plan\/[^/]+\/([^/]+)/)?.[1]
+  return segment ? SEGMENT_LABELS[segment] : undefined
+}
+
+export function LearnLink({ slug, label = 'Learn more', anchor, variant = 'inline', className }: LearnLinkProps) {
+  const location = useLocation()
+  const article = getArticle(slug)
+  if (!article) {
+    if (import.meta.env.DEV) console.error(`LearnLink: unknown article slug "${slug}"`)
+    return null
+  }
+
+  const to = anchor ? `/learn/${slug}#${anchor}` : `/learn/${slug}`
+  // Preserve an internal-only return path so the article can offer "← Back to …".
+  const from = location.pathname + location.search
+  const safeFrom = from.startsWith('/') && !from.startsWith('//') ? from : undefined
+  const classes = ['learn-link', `learn-link--${variant}`, className].filter(Boolean).join(' ')
+
+  return (
+    <Link
+      to={to}
+      className={classes}
+      state={safeFrom ? { learnFrom: safeFrom, learnFromLabel: originLabel(location.pathname) } : undefined}
+    >
+      {label}
+      <span aria-hidden="true"> →</span>
+    </Link>
+  )
+}

package/src/learn/LearningCenterPage.tsx

@@ -0,0 +1,114 @@
+/**
+ * Learning Center home (/learn): a fast index, not long copy.
+ *
+ * Search, featured high-value topics, a browse-by-category grid, and links to
+ * the glossary and sources.
+ */
+
+import { useId, useState } from 'react'
+import { Link } from 'react-router-dom'
+import {
+  articlesInCategory,
+  byListingOrder,
+  categorySummaries,
+  featuredArticles,
+  searchArticles,
+} from './learningRegistry'
+import { ArticleCard } from './LearnCards'
+
+export function LearningCenterPage() {
+  const [query, setQuery] = useState('')
+  const searchInputId = useId()
+  const trimmed = query.trim()
+  const results = trimmed ? searchArticles(trimmed) : null
+
+  const featured = featuredArticles()
+
+  return (
+    <article className="page learn-home">
+      <h1>Learning Center</h1>
+      <p className="lede">
+        Plain-language explanations of the ideas behind your plan — taxes, Social Security, withdrawals, risk, and
+        more. Read a topic, then come back to the planner with a clearer picture.
+      </p>
+
+      <div className="learn-search">
+        <label htmlFor={searchInputId} className="sr-only">
+          Search the Learning Center
+        </label>
+        <input
+          id={searchInputId}
+          type="search"
+          className="learn-search-input"
+          placeholder="Search topics, e.g. Roth, IRMAA, sequence risk"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+        />
+      </div>
+
+      {results ? (
+        <section className="learn-section" aria-label="Search results">
+          <h2 className="learn-section-title">
+            {results.length} result{results.length === 1 ? '' : 's'} for “{trimmed}”
+          </h2>
+          {results.length === 0 ? (
+            <p className="muted">No matching topics yet. Try a broader word, or browse the categories below.</p>
+          ) : (
+            <div className="learn-card-grid">
+              {results.map((a) => (
+                <ArticleCard key={a.slug} article={a} />
+              ))}
+            </div>
+          )}
+        </section>
+      ) : (
+        <>
+          {featured.length > 0 && (
+            <section className="learn-section" aria-label="Featured topics">
+              <h2 className="learn-section-title">Featured topics</h2>
+              <div className="learn-card-grid">
+                {featured.map((a) => (
+                  <ArticleCard key={a.slug} article={a} />
+                ))}
+              </div>
+            </section>
+          )}
+
+          <section className="learn-section" aria-label="Browse by category">
+            <h2 className="learn-section-title">Browse by category</h2>
+            {categorySummaries().map(({ category, count }) => (
+              <div key={category.id} className="learn-category">
+                <div className="learn-category-head">
+                  <h3 className="learn-category-title">{category.label}</h3>
+                  <span className="muted small">
+                    {count} article{count === 1 ? '' : 's'}
+                  </span>
+                </div>
+                <p className="learn-category-blurb muted">{category.blurb}</p>
+                <div className="learn-card-grid">
+                  {articlesInCategory(category.id)
+                    .slice()
+                    .sort(byListingOrder)
+                    .map((a) => (
+                      <ArticleCard key={a.slug} article={a} />
+                    ))}
+                </div>
+              </div>
+            ))}
+          </section>
+
+          <section className="learn-section learn-utility-links" aria-label="Reference">
+            <Link to="/learn/glossary" className="learn-utility-link">
+              <strong>Glossary</strong>
+              <span className="muted small">Plain definitions of the terms used across the app.</span>
+            </Link>
+            <Link to="/learn/sources" className="learn-utility-link">
+              <strong>Sources &amp; review methodology</strong>
+              <span className="muted small">Where the rules come from and how often they are reviewed.</span>
+            </Link>
+          </section>
+        </>
+      )}
+    </article>
+  )
+}

package/src/learn/SourcesPage.tsx

@@ -0,0 +1,98 @@
+/**
+ * Sources & review methodology (/learn/sources).
+ *
+ * Explains where rule statements come from, how current-year values are
+ * date-stamped, and how often content is reviewed. Each article also carries
+ * its own source list and last-reviewed date.
+ */
+
+import { Link } from 'react-router-dom'
+
+type PrimarySource = { name: string; scope: string; href: string }
+
+const PRIMARY_SOURCES: PrimarySource[] = [
+  {
+    name: 'IRS (irs.gov)',
+    scope: 'Tax brackets, deductions, retirement-account limits, RMD and QCD rules.',
+    href: 'https://www.irs.gov/',
+  },
+  {
+    name: 'Social Security Administration (ssa.gov)',
+    scope: 'Benefit formulas, claiming rules, and actuarial assumptions.',
+    href: 'https://www.ssa.gov/',
+  },
+  {
+    name: 'Medicare / CMS (medicare.gov)',
+    scope: 'Medicare premiums and IRMAA income brackets.',
+    href: 'https://www.medicare.gov/',
+  },
+  {
+    name: 'HealthCare.gov / CMS',
+    scope: 'ACA premium tax credit rules and marketplace eligibility.',
+    href: 'https://www.healthcare.gov/',
+  },
+]
+
+export function SourcesPage() {
+  return (
+    <article className="page learn-sources-page">
+      <Link to="/learn" className="learn-back">
+        ← Learning Center
+      </Link>
+      <h1>Sources &amp; review methodology</h1>
+      <p className="lede">How Learning Center articles stay accurate, and where their rule statements come from.</p>
+
+      <h2>Primary sources first</h2>
+      <p>
+        For anything involving tax, Medicare, Social Security, contribution limits, or ACA subsidies, articles cite
+        primary sources rather than secondary commentary. Secondary sources are used only for framing or examples,
+        never as the sole basis for a rule.
+      </p>
+      <table className="data-table">
+        <thead>
+          <tr>
+            <th>Source</th>
+            <th>What it covers</th>
+          </tr>
+        </thead>
+        <tbody>
+          {PRIMARY_SOURCES.map((s) => (
+            <tr key={s.href}>
+              <td>
+                <a href={s.href} target="_blank" rel="noreferrer">
+                  {s.name}
+                </a>
+              </td>
+              <td>{s.scope}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      <h2>Date-stamped, current-year values</h2>
+      <p>
+        Rules and dollar figures change — sometimes retroactively. Articles that depend on current-year numbers are
+        marked for annual review, carry a “last reviewed” date, and either pull live values from the app’s parameter
+        data or clearly stamp the year a figure applies to.
+      </p>
+
+      <h2>Simplifications are called out</h2>
+      <p>
+        RetireGolden models rules at planning precision, not return-filing precision. When an article describes something
+        the engine simplifies or omits, it says so, so you know where to verify a number that matters against the
+        official source.
+      </p>
+
+      <h2>Reviews</h2>
+      <p>
+        Each article declares a review cadence: <strong>annual</strong> for current-year-sensitive topics,{' '}
+        <strong>rule-change</strong> for topics that move only when a law changes, and <strong>stable</strong> for
+        evergreen concepts. The last-reviewed date on each article reflects its most recent check.
+      </p>
+
+      <p className="muted small">
+        See the full <Link to="/disclaimer">disclaimer</Link> for the authoritative legal terms.
+      </p>
+    </article>
+  )
+}

package/src/learn/components/ArticleFigure.tsx

@@ -0,0 +1,34 @@
+/**
+ * Renders a `figure` block: a registered chart or an image, wrapped in a
+ * semantic <figure>/<figcaption> with a screen-reader text equivalent and an
+ * optional source note. The visual never carries meaning by colour alone — the
+ * `alt` text equivalent always describes what the figure shows.
+ */
+
+import type { FigureBlockData } from '../learningRegistry'
+import { renderLearnChart } from './charts'
+
+export function ArticleFigure({ block }: { block: FigureBlockData }) {
+  const chart = block.chartId ? renderLearnChart(block.chartId) : null
+
+  return (
+    <figure className="learn-figure">
+      {chart ? (
+        <div className="learn-figure-media" role="img" aria-label={block.alt}>
+          {chart}
+        </div>
+      ) : block.image ? (
+        <img className="learn-figure-media" src={block.image.src} alt={block.alt} />
+      ) : (
+        // No renderable media: fall back to the text equivalent so nothing is lost.
+        <p className="learn-figure-fallback">{block.alt}</p>
+      )}
+      {/* Always expose the text equivalent to assistive tech, even for charts. */}
+      <span className="sr-only">{block.alt}</span>
+      <figcaption className="learn-figure-caption">
+        {block.caption}
+        {block.sourceNote && <span className="learn-figure-source"> {block.sourceNote}</span>}
+      </figcaption>
+    </figure>
+  )
+}

package/src/learn/components/ArticleShell.tsx

@@ -0,0 +1,86 @@
+/**
+ * The consistent layout for a finished article (spec §6.4): back link, category
+ * kicker, title, one-sentence promise, the structured body, related articles,
+ * sources, last-reviewed date, and a compact educational disclaimer.
+ *
+ * ArticlePage delegates the readable case here; the planned/not-found states
+ * stay in ArticlePage but share {@link BackLink}.
+ */
+
+import { Link, useLocation } from 'react-router-dom'
+import { OpenExampleButton } from '../../planner/examples/OpenExampleButton'
+import { getCategory, type LearningArticle } from '../learningRegistry'
+import { ArticleBody } from '../ArticleBody'
+import { RelatedArticles } from './RelatedArticles'
+import { SourceList } from './SourceList'
+
+function formatReviewed(iso: string): string {
+  const [y, m, d] = iso.split('-').map(Number)
+  if (!y || !m || !d) return iso
+  return new Date(Date.UTC(y, m - 1, d)).toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  })
+}
+
+/**
+ * Back link for any /learn page. When the reader arrived from a planner screen
+ * via {@link LearnLink}, returns them there ("← Back to Optimize"); otherwise
+ * falls back to the Learning Center home.
+ */
+export function BackLink() {
+  const { state } = useLocation()
+  const nav = state as { learnFrom?: unknown; learnFromLabel?: unknown } | null
+  const from = nav?.learnFrom
+  if (typeof from === 'string' && from.startsWith('/') && !from.startsWith('//')) {
+    const label = typeof nav?.learnFromLabel === 'string' ? `← Back to ${nav.learnFromLabel}` : '← Back'
+    return (
+      <Link to={from} className="learn-back">
+        {label}
+      </Link>
+    )
+  }
+  return (
+    <Link to="/learn" className="learn-back">
+      ← Learning Center
+    </Link>
+  )
+}
+
+export function ArticleShell({ article }: { article: LearningArticle }) {
+  const category = getCategory(article.category)
+
+  return (
+    <article className="page learn-article">
+      <BackLink />
+      {category && (
+        <div className="learn-article-kicker">
+          <span className="learn-card-cat">{category.label}</span>
+        </div>
+      )}
+      <h1>{article.title}</h1>
+      <p className="lede">{article.description}</p>
+
+      {article.exampleId ? (
+        <div className="learn-example-cta" style={{ marginBottom: '1.25rem' }}>
+          <OpenExampleButton exampleId={article.exampleId} />
+        </div>
+      ) : null}
+
+      <div className="learn-article-body">
+        <ArticleBody blocks={article.blocks ?? []} />
+      </div>
+
+      <RelatedArticles slugs={article.relatedArticles} />
+
+      {/* The persistent app footer directly below already carries the
+          educational disclaimer, so the article foot no longer repeats it. */}
+      <footer className="learn-article-foot">
+        <SourceList urls={article.sourceUrls} />
+        <p className="muted small">Last reviewed {formatReviewed(article.lastReviewed)}.</p>
+      </footer>
+    </article>
+  )
+}

package/src/learn/components/ComparisonTable.tsx

@@ -0,0 +1,42 @@
+/**
+ * Renders a `table` block: a small comparison table with a caption and proper
+ * header scopes. The first column is a row header; cells support inline markdown.
+ */
+
+import { renderInline } from '../inlineMarkdown'
+import type { TableBlockData } from '../learningRegistry'
+
+export function ComparisonTable({ block }: { block: TableBlockData }) {
+  const [rowHeader, ...colHeaders] = block.columns
+
+  return (
+    <div className="learn-table-wrap">
+      <table className="learn-table">
+        {block.caption && <caption className="learn-table-caption">{block.caption}</caption>}
+        <thead>
+          <tr>
+            <th scope="col">{rowHeader}</th>
+            {colHeaders.map((c, i) => (
+              <th key={i} scope="col">
+                {c}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {block.rows.map((row, r) => {
+            const [head, ...cells] = row
+            return (
+              <tr key={r}>
+                <th scope="row">{renderInline(head ?? '')}</th>
+                {cells.map((cell, c) => (
+                  <td key={c}>{renderInline(cell)}</td>
+                ))}
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/learn/components/FormulaBlock.tsx

@@ -0,0 +1,34 @@
+/**
+ * Renders a `formula` block: the expression, a "where" list defining each
+ * symbol, whether the dollars are nominal or in today's dollars, and a note on
+ * what the simple formula ignores (spec §8.5).
+ */
+
+import type { FormulaBlockData } from '../learningRegistry'
+
+const BASIS_LABEL: Record<NonNullable<FormulaBlockData['basis']>, string> = {
+  nominal: 'Amounts are in future (nominal) dollars.',
+  today: "Amounts are in today's dollars.",
+}
+
+export function FormulaBlock({ block }: { block: FormulaBlockData }) {
+  return (
+    <div className="learn-formula" role="group" aria-label="Formula">
+      <p className="learn-formula-expr">{block.expression}</p>
+
+      {block.where && block.where.length > 0 && (
+        <dl className="learn-formula-where">
+          {block.where.map((v) => (
+            <div key={v.symbol} className="learn-formula-row">
+              <dt>{v.symbol}</dt>
+              <dd>{v.meaning}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+
+      {block.basis && <p className="learn-formula-note muted small">{BASIS_LABEL[block.basis]}</p>}
+      {block.note && <p className="learn-formula-note muted small">{block.note}</p>}
+    </div>
+  )
+}