@startsimpli/ui 0.4.170 → 0.4.172

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.170",
+  "version": "0.4.172",
   "description": "Shared UI components package for StartSimpli applications",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -22,6 +22,7 @@
     "./gantt": "./src/components/gantt/index.ts",
     "./gantt/styles": "./src/components/gantt/gantt.css",
     "./charts": "./src/components/charts/index.ts",
+    "./payoff": "./src/components/payoff/index.ts",
     "./components": "./src/components/index.ts",
     "./error": "./src/components/error/index.ts",
     "./i18n": "./src/components/i18n/index.ts",
@@ -67,9 +68,9 @@
     "@codemirror/language": "^6.0.0",
     "@codemirror/state": "^6.0.0",
     "@codemirror/view": "^6.0.0",
-    "@startsimpli/auth": "^0.4.49",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.69"
+    "@startsimpli/api": "^0.5.69",
+    "@startsimpli/auth": "^0.4.50",
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/payoff/CategoryBreakdown.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react'
+import { DonutChart } from '../dashboard/DonutChart'
+import { moneyWhole } from './format'
+import { totalsByTag, type CategoryItem } from './category'
+
+export interface CategoryBreakdownProps {
+  items: CategoryItem[]
+  /** Tags shown before the rest roll into "Other" (default 6). */
+  topN?: number
+  centerLabel?: string
+}
+
+/** Palette cycles brand + muted tones from the theme contract. */
+const COLORS = [
+  'hsl(var(--primary))',
+  'hsl(var(--primary) / 0.7)',
+  'hsl(var(--primary) / 0.5)',
+  'hsl(var(--muted-foreground))',
+  'hsl(var(--muted-foreground) / 0.7)',
+  'hsl(var(--muted-foreground) / 0.5)',
+  'hsl(var(--border))',
+]
+
+/** Donut of totals per generic tag, with a legend of amounts. */
+export function CategoryBreakdown({ items, topN = 6, centerLabel = 'Total' }: CategoryBreakdownProps) {
+  const totals = React.useMemo(() => totalsByTag(items, topN), [items, topN])
+  const sum = totals.reduce((s, t) => s + t.total, 0)
+  return (
+    <DonutChart
+      segments={totals.map((t, i) => ({ label: t.tag, value: Math.max(t.total, 0), color: COLORS[i % COLORS.length] }))}
+      centerValue={moneyWhole(sum)}
+      centerLabel={centerLabel}
+      showLegend
+      formatLegendValue={(s) => moneyWhole(s.value)}
+      ariaLabel="Spending by category"
+    />
+  )
+}

package/src/components/payoff/CategoryTrend.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import * as React from 'react'
+import { TimeSeriesChart } from '../charts/TimeSeriesChart'
+import { monthlyByTag, type CategoryItem } from './category'
+
+export interface CategoryTrendProps {
+  items: CategoryItem[]
+  topN?: number
+  height?: number
+}
+
+/** Monthly total per tag as one line each. */
+export function CategoryTrend({ items, topN = 6, height = 280 }: CategoryTrendProps) {
+  const series = React.useMemo(() => {
+    const { tags, months, values } = monthlyByTag(items, topN)
+    return tags.map((tag) => ({
+      name: tag,
+      points: months.map((mk) => ({ t: `${mk}-01`, v: values[tag][mk] ?? 0 })),
+    }))
+  }, [items, topN])
+  return <TimeSeriesChart series={series} unit="$" height={height} ariaLabel="Monthly spending by category" />
+}

package/src/components/payoff/PayoffBalanceChart.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import * as React from 'react'
+import { TimeSeriesChart } from '../charts/TimeSeriesChart'
+import type { TimeSeries } from '../charts/lib/series'
+import type { PayoffDebtLabel, PayoffScheduleLike } from './types'
+
+export interface PayoffBalanceChartProps {
+  schedule: PayoffScheduleLike
+  debts: PayoffDebtLabel[]
+  /** Draw the combined-balance line (default true). */
+  showTotal?: boolean
+  height?: number
+}
+
+/** Remaining balance per debt over the plan, plus an optional Total line. */
+export function PayoffBalanceChart({ schedule, debts, showTotal = true, height = 320 }: PayoffBalanceChartProps) {
+  const series = React.useMemo(() => {
+    // Without a start date the x axis is a count of months from an arbitrary epoch.
+    const at = (m: { month: number; date?: string }) => m.date ?? Date.UTC(2000, m.month - 1, 1)
+    const out: TimeSeries[] = debts.map((d) => ({
+      name: d.name,
+      points: schedule.months.map((m) => ({
+        t: at(m),
+        v: m.payments.find((p) => p.debtId === d.id)?.endBalance ?? 0,
+      })),
+    }))
+    if (showTotal) {
+      out.push({ name: 'Total', points: schedule.months.map((m) => ({ t: at(m), v: m.totalBalance })) })
+    }
+    return out
+  }, [schedule, debts, showTotal])
+
+  return (
+    <TimeSeriesChart
+      series={series}
+      unit="$"
+      height={height}
+      ariaLabel="Remaining balance by debt over time"
+    />
+  )
+}

package/src/components/payoff/PayoffScheduleTable.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+import * as React from 'react'
+import { Button } from '../ui/button'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table'
+import { money, monthYear } from './format'
+import type { PayoffDebtLabel, PayoffScheduleLike } from './types'
+
+export interface PayoffScheduleTableProps {
+  schedule: PayoffScheduleLike
+  debts: PayoffDebtLabel[]
+  /** Months per page (default 12). */
+  pageSize?: number
+}
+
+/** Month x debt: payment, interest and ending balance, one page of months at a time. */
+export function PayoffScheduleTable({ schedule, debts, pageSize = 12 }: PayoffScheduleTableProps) {
+  const [page, setPage] = React.useState(0)
+  const pages = Math.max(1, Math.ceil(schedule.months.length / pageSize))
+  const safePage = Math.min(page, pages - 1)
+  const slice = schedule.months.slice(safePage * pageSize, safePage * pageSize + pageSize)
+  const name = (id: string) => debts.find((d) => d.id === id)?.name ?? id
+
+  return (
+    <div className="space-y-3">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Month</TableHead>
+            <TableHead>Debt</TableHead>
+            <TableHead className="text-right">Payment</TableHead>
+            <TableHead className="text-right">Interest</TableHead>
+            <TableHead className="text-right">Balance</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {slice.flatMap((m) => [
+            ...m.payments.map((p, i) => (
+              <TableRow key={`${m.month}-${p.debtId}`}>
+                <TableCell>{i === 0 ? (m.date ? monthYear(m.date) : `Month ${m.month}`) : ''}</TableCell>
+                <TableCell>{name(p.debtId)}</TableCell>
+                <TableCell className="text-right tabular-nums">{money(p.payment)}</TableCell>
+                <TableCell className="text-right tabular-nums">{money(p.interest)}</TableCell>
+                <TableCell className="text-right tabular-nums">{money(p.endBalance)}</TableCell>
+              </TableRow>
+            )),
+            <TableRow key={`${m.month}-total`} className="bg-muted/40 font-medium">
+              <TableCell />
+              <TableCell>Total</TableCell>
+              <TableCell className="text-right tabular-nums">{money(m.totalPayment)}</TableCell>
+              <TableCell className="text-right tabular-nums">{money(m.totalInterest)}</TableCell>
+              <TableCell className="text-right tabular-nums">{money(m.totalBalance)}</TableCell>
+            </TableRow>,
+          ])}
+        </TableBody>
+      </Table>
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>
+          Page {safePage + 1} of {pages}
+        </span>
+        <div className="flex gap-2">
+          <Button variant="outline" size="sm" disabled={safePage === 0} onClick={() => setPage(safePage - 1)}>
+            Previous
+          </Button>
+          <Button variant="outline" size="sm" disabled={safePage >= pages - 1} onClick={() => setPage(safePage + 1)}>
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/payoff/PayoffSummaryCards.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react'
+import { Card, CardContent } from '../ui/card'
+import { Progress } from '../ui/progress'
+import { duration, monthYear, moneyWhole } from './format'
+import type { PayoffScheduleLike } from './types'
+
+export interface PayoffSummaryCardsProps {
+  schedule: PayoffScheduleLike
+  /** Total owed when the plan began; enables the progress card. */
+  startingBalance?: number
+  /** Total owed today; defaults to the starting balance (no progress yet). */
+  currentBalance?: number
+}
+
+function Stat({ label, value, hint }: { label: string; value: React.ReactNode; hint?: React.ReactNode }) {
+  return (
+    <Card>
+      <CardContent className="p-5">
+        <p className="text-sm text-muted-foreground">{label}</p>
+        <p className="mt-1 text-2xl font-semibold tabular-nums">{value}</p>
+        {hint ? <p className="mt-1 text-sm text-muted-foreground">{hint}</p> : null}
+      </CardContent>
+    </Card>
+  )
+}
+
+/** Debt-free date, interest cost, total paid and (optionally) progress. */
+export function PayoffSummaryCards({ schedule, startingBalance, currentBalance }: PayoffSummaryCardsProps) {
+  const free = schedule.paidOff && schedule.debtFreeMonth !== null
+  const progress =
+    startingBalance && startingBalance > 0
+      ? Math.max(0, Math.min(100, (1 - (currentBalance ?? startingBalance) / startingBalance) * 100))
+      : null
+  return (
+    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4" data-testid="payoff-summary">
+      <Stat
+        label="Debt-free"
+        value={free ? (schedule.debtFreeDate ? monthYear(schedule.debtFreeDate) : `Month ${schedule.debtFreeMonth}`) : 'Not within forecast'}
+        hint={free ? `in ${duration(schedule.debtFreeMonth!)}` : 'Raise the monthly payment to pay these off'}
+      />
+      <Stat label="Total interest" value={moneyWhole(schedule.totalInterest)} />
+      <Stat label="Total paid" value={moneyWhole(schedule.totalPaid)} />
+      {progress !== null ? (
+        <Card>
+          <CardContent className="p-5">
+            <p className="text-sm text-muted-foreground">Progress</p>
+            <p className="mt-1 text-2xl font-semibold tabular-nums">{Math.round(progress)}%</p>
+            <Progress value={progress} className="mt-3 h-2" aria-label="Paid off so far" />
+          </CardContent>
+        </Card>
+      ) : null}
+    </div>
+  )
+}

package/src/components/payoff/PayoffTimeline.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react'
+import { ActivityTimeline, type ActivityTimelineItem } from '../ActivityTimeline'
+import { duration, monthYear, moneyWhole } from './format'
+import type { PayoffDebtLabel, PayoffScheduleLike } from './types'
+
+export interface PayoffTimelineProps {
+  schedule: PayoffScheduleLike
+  debts: PayoffDebtLabel[]
+  /** Month each debt reached zero, from the schedule result. */
+  payoffMonthByDebt: Record<string, number>
+}
+
+/** Milestones in payoff order: each debt cleared, then debt-free. */
+export function payoffMilestones(
+  schedule: PayoffScheduleLike,
+  debts: PayoffDebtLabel[],
+  payoffMonthByDebt: Record<string, number>,
+): ActivityTimelineItem[] {
+  const dateOf = (month: number) =>
+    schedule.months.find((m) => m.month === month)?.date ?? new Date(Date.UTC(2000, month - 1, 1)).toISOString()
+  const items: ActivityTimelineItem[] = debts
+    .filter((d) => (payoffMonthByDebt[d.id] ?? 0) > 0)
+    .map((d) => {
+      const month = payoffMonthByDebt[d.id]
+      const interest = schedule.months
+        .flatMap((m) => m.payments)
+        .filter((p) => p.debtId === d.id)
+        .reduce((s, p) => s + p.interest, 0)
+      return {
+        id: d.id,
+        type: 'debt_cleared',
+        title: `${d.name} paid off`,
+        description: `Month ${month} · ${moneyWhole(interest)} interest`,
+        occurredAt: dateOf(month),
+        tone: 'ok' as const,
+      }
+    })
+    .sort((a, b) => a.occurredAt.localeCompare(b.occurredAt))
+  if (schedule.paidOff && schedule.debtFreeMonth) {
+    items.push({
+      id: 'debt-free',
+      type: 'debt_free',
+      title: 'Debt-free',
+      description: `After ${duration(schedule.debtFreeMonth)} · ${moneyWhole(schedule.totalInterest)} total interest`,
+      occurredAt: dateOf(schedule.debtFreeMonth),
+      tone: 'ok',
+    })
+  }
+  return items
+}
+
+/** Future-facing timeline of payoff milestones, oldest first. */
+export function PayoffTimeline({ schedule, debts, payoffMonthByDebt }: PayoffTimelineProps) {
+  const activities = React.useMemo(
+    () => payoffMilestones(schedule, debts, payoffMonthByDebt),
+    [schedule, debts, payoffMonthByDebt],
+  )
+  return (
+    <ActivityTimeline
+      activities={activities}
+      emptyTitle="No payoff milestones"
+      emptyDescription="Raise the monthly payment so these debts clear within the forecast."
+      formatTime={monthYear}
+    />
+  )
+}

package/src/components/payoff/RangeSlider.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface RangeSliderProps {
+  label: string
+  value: number
+  min: number
+  max: number
+  step?: number
+  onChange: (value: number) => void
+  /** How the current value reads next to the label. */
+  format?: (value: number) => string
+  className?: string
+}
+
+/** A labelled range input with the current value shown. Native input: keyboard and a11y for free. */
+export function RangeSlider({ label, value, min, max, step = 1, onChange, format, className }: RangeSliderProps) {
+  const id = React.useId()
+  return (
+    <div className={cn('space-y-2', className)}>
+      <div className="flex items-baseline justify-between text-sm">
+        <label htmlFor={id} className="font-medium">
+          {label}
+        </label>
+        <span className="tabular-nums text-muted-foreground">{format ? format(value) : value}</span>
+      </div>
+      <input
+        id={id}
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(e) => onChange(Number(e.target.value))}
+        className="h-2 w-full cursor-pointer accent-primary"
+      />
+    </div>
+  )
+}

package/src/components/payoff/ScenarioCompare.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react'
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table'
+import { duration, monthYear, moneyWhole } from './format'
+import type { PayoffScheduleLike } from './types'
+
+export interface PayoffScenario {
+  id: string
+  label: string
+  schedule: PayoffScheduleLike
+}
+
+export interface ScenarioCompareProps {
+  /** The first scenario is the baseline the others are compared with. */
+  scenarios: PayoffScenario[]
+}
+
+function delta(value: number, unit: 'money' | 'months'): { text: string; good: boolean } | null {
+  if (value === 0) return null
+  const abs = Math.abs(value)
+  const text = unit === 'money' ? moneyWhole(abs) : duration(abs)
+  return { text: value > 0 ? `${text} less` : `${text} more`, good: value > 0 }
+}
+
+/** Debt-free date, months and interest per scenario, with savings vs the baseline. */
+export function ScenarioCompare({ scenarios }: ScenarioCompareProps) {
+  const base = scenarios[0]?.schedule
+  return (
+    <Table data-testid="scenario-compare">
+      <TableHeader>
+        <TableRow>
+          <TableHead>Scenario</TableHead>
+          <TableHead>Debt-free</TableHead>
+          <TableHead className="text-right">Time</TableHead>
+          <TableHead className="text-right">Interest</TableHead>
+          <TableHead className="text-right">Total paid</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {scenarios.map((s, i) => {
+          const sch = s.schedule
+          const bothFree = i > 0 && base && base.paidOff && sch.paidOff
+          const time = bothFree ? delta(base!.debtFreeMonth! - sch.debtFreeMonth!, 'months') : null
+          const interest = i > 0 && base ? delta(base.totalInterest - sch.totalInterest, 'money') : null
+          const tone = (g: boolean) => (g ? 'text-green-600 dark:text-green-400' : 'text-red-600 dark:text-red-400')
+          return (
+            <TableRow key={s.id}>
+              <TableCell className="font-medium">{s.label}</TableCell>
+              <TableCell>
+                {sch.paidOff ? (sch.debtFreeDate ? monthYear(sch.debtFreeDate) : `Month ${sch.debtFreeMonth}`) : 'Not within forecast'}
+              </TableCell>
+              <TableCell className="text-right tabular-nums">
+                {sch.paidOff ? duration(sch.debtFreeMonth!) : '—'}
+                {time ? <div className={`text-xs ${tone(time.good)}`}>{time.text}</div> : null}
+              </TableCell>
+              <TableCell className="text-right tabular-nums">
+                {moneyWhole(sch.totalInterest)}
+                {interest ? <div className={`text-xs ${tone(interest.good)}`}>{interest.text}</div> : null}
+              </TableCell>
+              <TableCell className="text-right tabular-nums">{moneyWhole(sch.totalPaid)}</TableCell>
+            </TableRow>
+          )
+        })}
+      </TableBody>
+    </Table>
+  )
+}

package/src/components/payoff/__tests__/category.test.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react'
+import { totalsByTag, monthlyByTag, monthKey } from '../category'
+import { payoffMilestones, PayoffTimeline } from '../PayoffTimeline'
+import type { PayoffScheduleLike } from '../types'
+
+const items = [
+  { date: '2027-01-05', amount: 100, tag: 'food' },
+  { date: '2027-01-20', amount: 50, tag: 'food' },
+  { date: '2027-03-02', amount: 30, tag: 'fun' },
+  { date: '2027-03-09', amount: 10, tag: null },
+  { date: '2027-03-10', amount: 5, tag: 'tiny' },
+]
+
+describe('category helpers', () => {
+  it('totals by tag, largest first, with Other rollup', () => {
+    expect(totalsByTag(items, 10).map((t) => [t.tag, t.total])).toEqual([
+      ['food', 150], ['fun', 30], ['Uncategorized', 10], ['tiny', 5],
+    ])
+    const r = totalsByTag(items, 2)
+    expect(r.map((t) => t.tag)).toEqual(['food', 'fun', 'Other'])
+    expect(r[2].total).toBe(15)
+  })
+  it('monthly series fill empty months with 0', () => {
+    const r = monthlyByTag(items, 10)
+    expect(r.months).toEqual(['2027-01', '2027-02', '2027-03'])
+    expect(r.values.food).toEqual({ '2027-01': 150, '2027-02': 0, '2027-03': 0 })
+  })
+  it('ignores bad dates and amounts', () => {
+    expect(monthKey('nope')).toBeNull()
+    expect(totalsByTag([{ date: 'x', amount: NaN, tag: 'a' }])).toEqual([])
+  })
+})
+
+const sched: PayoffScheduleLike = {
+  months: [1, 2, 3].map((m) => ({ month: m, date: `2027-0${m}-01`, payments: [
+    { debtId: 'a', month: m, startBalance: 1, interest: 2, payment: 1, endBalance: 0 },
+  ], totalPayment: 1, totalInterest: 2, totalBalance: 0 })),
+  debtFreeMonth: 3, debtFreeDate: '2027-03-01', totalInterest: 6, totalPaid: 3, paidOff: true,
+}
+
+describe('PayoffTimeline', () => {
+  it('lists debts in payoff order then debt-free', () => {
+    const m = payoffMilestones(sched, [{ id: 'a', name: 'Visa' }, { id: 'b', name: 'Auto' }], { a: 1, b: 3 })
+    expect(m.map((i) => i.title)).toEqual(['Visa paid off', 'Auto paid off', 'Debt-free'])
+  })
+  it('renders', () => {
+    render(<PayoffTimeline schedule={sched} debts={[{ id: 'a', name: 'Visa' }]} payoffMonthByDebt={{ a: 2 }} />)
+    expect(screen.getByText('Visa paid off')).toBeTruthy()
+    expect(screen.getByText('Debt-free')).toBeTruthy()
+  })
+})

package/src/components/payoff/__tests__/payoff.test.tsx

@@ -0,0 +1,86 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { PayoffSummaryCards } from '../PayoffSummaryCards'
+import { PayoffScheduleTable } from '../PayoffScheduleTable'
+import { ScenarioCompare } from '../ScenarioCompare'
+import { RangeSlider } from '../RangeSlider'
+import { duration, monthYear } from '../format'
+import type { PayoffScheduleLike } from '../types'
+
+function schedule(over: Partial<PayoffScheduleLike> = {}, months = 3): PayoffScheduleLike {
+  return {
+    months: Array.from({ length: months }, (_, i) => ({
+      month: i + 1,
+      date: `2027-0${i + 1}-01`,
+      payments: [
+        { debtId: 'a', month: i + 1, startBalance: 100, interest: 1, payment: 50, endBalance: 51 },
+        { debtId: 'b', month: i + 1, startBalance: 10, interest: 0, payment: 10, endBalance: 0 },
+      ],
+      totalPayment: 60,
+      totalInterest: 1,
+      totalBalance: 51,
+    })),
+    debtFreeMonth: months,
+    debtFreeDate: '2027-03-01',
+    totalInterest: 300,
+    totalPaid: 1300,
+    paidOff: true,
+    ...over,
+  }
+}
+
+describe('format', () => {
+  it('formats durations and month/year', () => {
+    expect(duration(14)).toBe('1 year 2 months')
+    expect(duration(5)).toBe('5 months')
+    expect(duration(24)).toBe('2 years')
+    expect(monthYear('2028-03-01')).toBe('Mar 2028')
+  })
+})
+
+describe('PayoffSummaryCards', () => {
+  it('shows debt-free date, interest and progress', () => {
+    render(<PayoffSummaryCards schedule={schedule()} startingBalance={1000} currentBalance={750} />)
+    expect(screen.getByText('Mar 2027')).toBeTruthy()
+    expect(screen.getByText('$300')).toBeTruthy()
+    expect(screen.getByText('25%')).toBeTruthy()
+  })
+  it('says so when the plan never clears', () => {
+    render(<PayoffSummaryCards schedule={schedule({ paidOff: false, debtFreeMonth: null, debtFreeDate: null })} />)
+    expect(screen.getByText('Not within forecast')).toBeTruthy()
+  })
+})
+
+describe('PayoffScheduleTable', () => {
+  it('pages by month and names debts', () => {
+    render(<PayoffScheduleTable schedule={schedule({}, 5)} debts={[{ id: 'a', name: 'Visa' }, { id: 'b', name: 'Auto' }]} pageSize={2} />)
+    expect(screen.getAllByText('Visa')).toHaveLength(2)
+    expect(screen.getByText('Page 1 of 3')).toBeTruthy()
+    fireEvent.click(screen.getByText('Next'))
+    expect(screen.getByText('Page 2 of 3')).toBeTruthy()
+  })
+})
+
+describe('ScenarioCompare', () => {
+  it('reports savings against the first scenario', () => {
+    render(
+      <ScenarioCompare
+        scenarios={[
+          { id: 'base', label: 'Base', schedule: schedule({ debtFreeMonth: 24, totalInterest: 1000 }) },
+          { id: 'fast', label: 'Fast', schedule: schedule({ debtFreeMonth: 12, totalInterest: 400 }) },
+        ]}
+      />,
+    )
+    expect(screen.getByText('1 year less')).toBeTruthy()
+    expect(screen.getByText('$600 less')).toBeTruthy()
+  })
+})
+
+describe('RangeSlider', () => {
+  it('reports changes as numbers', () => {
+    const onChange = jest.fn()
+    render(<RangeSlider label="Payment" min={0} max={100} value={10} onChange={onChange} format={(v) => `$${v}`} />)
+    expect(screen.getByText('$10')).toBeTruthy()
+    fireEvent.change(screen.getByLabelText('Payment'), { target: { value: '40' } })
+    expect(onChange).toHaveBeenCalledWith(40)
+  })
+})

package/src/components/payoff/category.ts

@@ -0,0 +1,71 @@
+/** One spend (or income) record, segmented by a generic tag. */
+export interface CategoryItem {
+  /** ISO date (YYYY-MM-DD or full timestamp). */
+  date: string
+  amount: number
+  /** Generic tag/category; empty or missing groups under "Uncategorized". */
+  tag?: string | null
+}
+
+export const UNCATEGORIZED = 'Uncategorized'
+export const OTHER = 'Other'
+
+const tagOf = (i: CategoryItem) => (i.tag && i.tag.trim() ? i.tag.trim() : UNCATEGORIZED)
+
+/** Totals per tag, largest first; everything past `topN` rolls up into "Other". */
+export function totalsByTag(items: CategoryItem[], topN = 6): { tag: string; total: number }[] {
+  const sums = new Map<string, number>()
+  for (const i of items) {
+    if (!Number.isFinite(i.amount)) continue
+    sums.set(tagOf(i), (sums.get(tagOf(i)) ?? 0) + i.amount)
+  }
+  const sorted = [...sums.entries()].map(([tag, total]) => ({ tag, total })).sort((a, b) => b.total - a.total)
+  if (sorted.length <= topN) return sorted
+  const head = sorted.slice(0, topN)
+  const rest = sorted.slice(topN).reduce((s, r) => s + r.total, 0)
+  return [...head, { tag: OTHER, total: rest }]
+}
+
+/** "YYYY-MM" bucket of an ISO date, or null if unreadable. */
+export function monthKey(date: string): string | null {
+  const m = /^(\d{4})-(\d{2})/.exec(date)
+  return m ? `${m[1]}-${m[2]}` : null
+}
+
+/**
+ * Monthly totals for each of the top tags (same top-N/"Other" rule as
+ * `totalsByTag`). Months with no spend for a tag are 0, not gaps, so lines
+ * stay continuous across the whole range.
+ */
+export function monthlyByTag(
+  items: CategoryItem[],
+  topN = 6,
+): { tags: string[]; months: string[]; values: Record<string, Record<string, number>> } {
+  const keep = new Set(totalsByTag(items, topN).map((t) => t.tag))
+  const named = new Set([...keep].filter((t) => t !== OTHER))
+  const values: Record<string, Record<string, number>> = {}
+  const monthSet = new Set<string>()
+  for (const i of items) {
+    const mk = monthKey(i.date)
+    if (!mk || !Number.isFinite(i.amount)) continue
+    const t = named.has(tagOf(i)) ? tagOf(i) : OTHER
+    monthSet.add(mk)
+    values[t] ??= {}
+    values[t][mk] = (values[t][mk] ?? 0) + i.amount
+  }
+  const months = [...monthSet].sort()
+  // Fill every month between first and last.
+  const filled: string[] = []
+  if (months.length) {
+    let [y, m] = months[0].split('-').map(Number)
+    const [ey, em] = months[months.length - 1].split('-').map(Number)
+    while (y < ey || (y === ey && m <= em)) {
+      filled.push(`${y}-${String(m).padStart(2, '0')}`)
+      m++
+      if (m > 12) { m = 1; y++ }
+    }
+  }
+  const tags = [...keep].filter((t) => values[t])
+  for (const t of tags) for (const mk of filled) values[t][mk] ??= 0
+  return { tags, months: filled, values }
+}

package/src/components/payoff/format.ts

@@ -0,0 +1,23 @@
+const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
+const usd0 = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })
+
+export const money = (n: number) => usd.format(n)
+export const moneyWhole = (n: number) => usd0.format(n)
+
+/** "Mar 2028" from an ISO date, in UTC so the day never shifts. */
+export function monthYear(iso: string): string {
+  const d = new Date(`${iso.slice(0, 10)}T00:00:00Z`)
+  return Number.isNaN(d.getTime())
+    ? iso
+    : d.toLocaleDateString('en-US', { month: 'short', year: 'numeric', timeZone: 'UTC' })
+}
+
+/** "3 years 2 months" / "5 months". */
+export function duration(months: number): string {
+  const y = Math.floor(months / 12)
+  const m = months % 12
+  const parts: string[] = []
+  if (y) parts.push(`${y} ${y === 1 ? 'year' : 'years'}`)
+  if (m || !y) parts.push(`${m} ${m === 1 ? 'month' : 'months'}`)
+  return parts.join(' ')
+}

package/src/components/payoff/index.ts

@@ -0,0 +1,26 @@
+// Payoff UI lives behind its own subpath (`@startsimpli/ui/payoff`) because it pulls in recharts.
+export { PayoffBalanceChart } from './PayoffBalanceChart'
+export type { PayoffBalanceChartProps } from './PayoffBalanceChart'
+export { PayoffSummaryCards } from './PayoffSummaryCards'
+export type { PayoffSummaryCardsProps } from './PayoffSummaryCards'
+export { PayoffScheduleTable } from './PayoffScheduleTable'
+export type { PayoffScheduleTableProps } from './PayoffScheduleTable'
+export { ScenarioCompare } from './ScenarioCompare'
+export type { ScenarioCompareProps, PayoffScenario } from './ScenarioCompare'
+export { RangeSlider } from './RangeSlider'
+export type { RangeSliderProps } from './RangeSlider'
+export { money, moneyWhole, monthYear, duration } from './format'
+export type {
+  PayoffDebtLabel,
+  PayoffMonthLike,
+  PayoffPaymentLike,
+  PayoffScheduleLike,
+} from './types'
+export { CategoryBreakdown } from './CategoryBreakdown'
+export type { CategoryBreakdownProps } from './CategoryBreakdown'
+export { CategoryTrend } from './CategoryTrend'
+export type { CategoryTrendProps } from './CategoryTrend'
+export { PayoffTimeline, payoffMilestones } from './PayoffTimeline'
+export type { PayoffTimelineProps } from './PayoffTimeline'
+export { totalsByTag, monthlyByTag, monthKey, UNCATEGORIZED, OTHER } from './category'
+export type { CategoryItem } from './category'

package/src/components/payoff/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Structural shapes the payoff components read. They match what
+ * `buildPayoffSchedule` (@startsimpli/utils) returns, but are declared here so
+ * @startsimpli/ui does not depend on @startsimpli/utils.
+ */
+export interface PayoffPaymentLike {
+  debtId: string
+  month: number
+  date?: string
+  startBalance: number
+  interest: number
+  payment: number
+  endBalance: number
+}
+
+export interface PayoffMonthLike {
+  month: number
+  date?: string
+  payments: PayoffPaymentLike[]
+  totalPayment: number
+  totalInterest: number
+  totalBalance: number
+}
+
+export interface PayoffScheduleLike {
+  months: PayoffMonthLike[]
+  debtFreeMonth: number | null
+  debtFreeDate: string | null
+  totalInterest: number
+  totalPaid: number
+  paidOff: boolean
+}
+
+export interface PayoffDebtLabel {
+  id: string
+  name: string
+}