@appinternalleads/ui 0.2.0

package/src/components/onboarding/budget-allocation/presets.json

@@ -0,0 +1,231 @@
+{
+  "component": "budget-allocation",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "data",
+    "icon": "wallet",
+    "title": "Split the marketing budget",
+    "subtitle": "Allocate this month’s spend across channels.",
+    "total": 25000,
+    "prefix": "$",
+    "suffix": "",
+    "fieldSuffix": "",
+    "unitHint": "USD per month",
+    "categories": [
+      {
+        "name": "Paid search",
+        "type": "action",
+        "icon": "search",
+        "amount": 9000
+      },
+      {
+        "name": "Social",
+        "type": "agent",
+        "icon": "megaphone",
+        "amount": 6000
+      },
+      {
+        "name": "Events",
+        "type": "schedule",
+        "icon": "ticket",
+        "amount": 5000
+      },
+      {
+        "name": "Content",
+        "type": "file",
+        "icon": "doc",
+        "amount": 3000
+      }
+    ],
+    "attentionAt": 0.6,
+    "allowAdd": true,
+    "overBy": 1200,
+    "primaryLabel": "Save budget",
+    "savingLabel": "Saving…",
+    "savedLabel": "Saved",
+    "secondaryLabel": "",
+    "saveErrorTitle": "Couldn’t save the budget",
+    "saveErrorBody": "Nothing was changed. Retry when you’re ready.",
+    "emptyTitle": "No categories yet",
+    "emptyBody": "Add a category to start splitting the budget.",
+    "emptyCta": "Add category"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "title": "Plan cloud spend",
+      "subtitle": "Set a monthly cap for each service.",
+      "total": 12000,
+      "suffix": " / mo",
+      "unitHint": "USD per month",
+      "attentionAt": 0.4,
+      "overBy": 600,
+      "categories": [
+        {
+          "name": "Compute",
+          "type": "action",
+          "icon": "bolt",
+          "amount": 5200
+        },
+        {
+          "name": "Storage",
+          "type": "file",
+          "icon": "server",
+          "amount": 1800
+        },
+        {
+          "name": "Database",
+          "type": "data",
+          "icon": "db",
+          "amount": 2600
+        },
+        {
+          "name": "Networking",
+          "type": "schedule",
+          "icon": "globe",
+          "amount": 900
+        },
+        {
+          "name": "Observability",
+          "type": "agent",
+          "icon": "eye",
+          "amount": 800
+        }
+      ],
+      "primaryLabel": "Save caps"
+    },
+    "case3": {
+      "title": "Offsite budget",
+      "subtitle": "Three days in Lisbon for 24 people.",
+      "total": 8500,
+      "unitHint": "USD total",
+      "allowAdd": false,
+      "categories": [
+        {
+          "name": "Venue",
+          "type": "data",
+          "icon": "building",
+          "amount": 3800
+        },
+        {
+          "name": "Travel",
+          "type": "schedule",
+          "icon": "plane",
+          "amount": 3200
+        },
+        {
+          "name": "Catering",
+          "type": "action",
+          "icon": "utensils",
+          "amount": 1900
+        },
+        {
+          "name": "Activities",
+          "type": "agent",
+          "icon": "sparkle",
+          "amount": 800
+        }
+      ],
+      "primaryLabel": "Save offsite budget"
+    },
+    "case4": {
+      "title": "Training budget by team",
+      "subtitle": "Courses, conferences and books for the year.",
+      "total": 40000,
+      "suffix": " / yr",
+      "unitHint": "USD per year",
+      "overBy": 2000,
+      "categories": [
+        {
+          "name": "Design",
+          "type": "action",
+          "icon": "pen",
+          "amount": 8000
+        },
+        {
+          "name": "Engineering",
+          "type": "data",
+          "icon": "code",
+          "amount": 14000
+        },
+        {
+          "name": "Sales",
+          "type": "schedule",
+          "icon": "briefcase",
+          "amount": 9000
+        },
+        {
+          "name": "Support",
+          "type": "agent",
+          "icon": "headset",
+          "amount": 6000
+        }
+      ],
+      "primaryLabel": "Save training budget"
+    },
+    "case5": {
+      "title": "Split API credits",
+      "subtitle": "Share this cycle’s credits across projects.",
+      "total": 1000000,
+      "prefix": "",
+      "suffix": " credits",
+      "fieldSuffix": "credits",
+      "unitHint": "Credits per billing cycle",
+      "overBy": 50000,
+      "attentionAt": 0.7,
+      "categories": [
+        {
+          "name": "Prod",
+          "type": "action",
+          "icon": "bolt",
+          "amount": 600000
+        },
+        {
+          "name": "Staging",
+          "type": "file",
+          "icon": "layers",
+          "amount": 150000
+        },
+        {
+          "name": "Research",
+          "type": "agent",
+          "icon": "flask",
+          "amount": 250000
+        }
+      ],
+      "primaryLabel": "Save allocation"
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · Marketing",
+      "title": "Monthly marketing budget",
+      "scenario": "A marketing lead splits $25,000 across four channels. The board opens under-allocated, with $2,000 left to place."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · Engineering",
+      "title": "Cloud spend by service",
+      "scenario": "A platform team sets monthly caps for five services. Compute is above the 40% attention line, so it shows a warning."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Operations",
+      "title": "Offsite budget",
+      "scenario": "An ops manager plans a team offsite. The categories add up to more than the budget, so the board ships over-allocated and Save is disabled."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · People",
+      "title": "Training budget by team",
+      "scenario": "People ops gives each team a yearly training allowance and keeps $3,000 in reserve."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · Platform",
+      "title": "API credits across projects",
+      "scenario": "A developer splits one million credits across three projects. It uses a suffix, no currency, and ships exactly allocated."
+    }
+  }
+}

package/src/components/onboarding/budget-allocation/runtime.ts

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useOperationRunner } from '../../../runtime/operations';
+import type { OnboardingResult } from '../shared/contract';
+import { ONBOARDING_TIMING, createMockOperation, type OnboardingOperation } from '../shared/mock';
+import { runOutcome } from '../shared/runtime';
+import type { BudgetSettings } from './contract';
+import {
+  budgetSeed, budgetView, initialBudget, liveRows, reduceBudget,
+  type BudgetAction, type BudgetSeed, type BudgetState,
+} from './engine';
+
+export type BudgetAllocationItem = { name: string; amount: number };
+export type BudgetOperations = { save: OnboardingOperation<{ allocations: BudgetAllocationItem[] }> };
+
+const itemsOf = (s: BudgetState): BudgetAllocationItem[] => liveRows(s).map(r => ({ name: r.name, amount: r.amount ?? 0 }));
+
+/** **The Budget Allocation runtime** — the reducer and its one boundary operation, save. */
+export function useBudgetAllocation({
+  config, operations, result = 'success', initial, onChange, onSave,
+}: {
+  config: BudgetSettings;
+  operations?: BudgetOperations;
+  result?: OnboardingResult;
+  initial?: BudgetSeed;
+  onChange?: (items: BudgetAllocationItem[]) => void;
+  onSave?: (items: BudgetAllocationItem[]) => void;
+}) {
+  const seed = () => initialBudget(config, initial ?? (config.ship ? budgetSeed(config, config.ship) : {}));
+  const [state, send] = useReducer((s: BudgetState, a: BudgetAction) => reduceBudget(s, a), undefined, seed);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const runner = useOperationRunner();
+  const save = useMemo(
+    () => operations?.save ?? createMockOperation<{ allocations: BudgetAllocationItem[] }>({ latencyMs: ONBOARDING_TIMING.save, fail: () => result === 'error' }),
+    [operations, result],
+  );
+
+  const key = JSON.stringify([config, initial ?? null]);
+  const seeded = useRef(key);
+  useEffect(() => {
+    if (seeded.current === key) return;
+    seeded.current = key;
+    runner.cancel('save');
+    send({ type: 'reset', state: seed() });
+  });
+
+  const run = useCallback(() => {
+    const items = itemsOf(stateRef.current);
+    runOutcome(runner, 'save', save, { allocations: items }, {
+      ok: () => { send({ type: 'saved' }); onSave?.(items); },
+      fail: () => send({ type: 'failed' }),
+    });
+  }, [runner, save, onSave]);
+
+  useEffect(() => { if (stateRef.current.save === 'saving') run(); }, [key]);
+
+  const itemsKey = JSON.stringify(itemsOf(state));
+  const reported = useRef(itemsKey);
+  useEffect(() => {
+    if (reported.current === itemsKey) return;
+    reported.current = itemsKey;
+    onChange?.(itemsOf(state));
+  }, [itemsKey]);
+
+  return {
+    state,
+    view: budgetView(config, state),
+    dispatch: send,
+    save: () => {
+      if (!budgetView(config, stateRef.current).canSave) return;
+      send({ type: 'save' });
+      run();
+    },
+  };
+}

package/src/components/onboarding/budget-tracker/BudgetTrackerView.tsx

@@ -0,0 +1,147 @@
+import { useEffect, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import { Box, Select, Text } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { guarded } from '../shared/guard';
+import { M15, barFill, barStart, compactCurrency, progress, revealEnd, rowReveal, toneIn } from '../shared/m15';
+import { DataTip, RevealRow, ToneText, VizBar, useInView, useRevealClock, useTweenedValues } from '../shared/viz';
+import { BUDGET_TRACKER_PRESETS, validateBudgetTracker, type BudgetTrackerSettings } from './contract';
+import { budgetRows, budgetScene, budgetTotals, budgetTrackerSeed, initialBudgetTracker, type BudgetTrackerSeed } from './engine';
+
+export type BudgetTrackerProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<BudgetTrackerSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Read-only; accepted for the shared shape. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  initial?: BudgetTrackerSeed;
+  /** A row is pressable only with this; without it, a row is focusable only (to reach its tooltip). */
+  onOpen?: (id: string) => void;
+  onPeriodChange?: (period: string) => void;
+  /** Increment to play M15 again (the board's Replay). */
+  replay?: number;
+  /** The board's Reduced motion toggle — as if the OS asked. */
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Budget Tracker** — header (tile, title, subtitle; the period as a C6 select when there are
+ * several, muted text when one), a `<dl>` of three wells (Allocated, Spent, Utilization — count up
+ * from 0 at 160ms over 600ms), then one row per category: name, spent / allocated (spent counts),
+ * the variance (mint left, apricot over or near, muted $0 — after the bar), and a 6px
+ * `progressbar` whose apricot layer fades in once the fill ends. M15 plays the first time the card
+ * is 30% in view; a period change tweens the values without re-staggering.
+ */
+function BudgetTrackerView(props: BudgetTrackerProps) {
+  const config = resolveConfig(BUDGET_TRACKER_PRESETS, props.preset, props.config);
+  const issues = validateBudgetTracker(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, reload, initial, onOpen, onPeriodChange, replay, forceReduced, onScene, testID,
+}: Omit<BudgetTrackerProps, 'config'> & { config: BudgetTrackerSettings }) {
+  const { colors } = useDs();
+  const key = JSON.stringify([config, initial ?? null]);
+  const seed = useMemo(() => initialBudgetTracker(config, initial ?? (config.ship ? budgetTrackerSeed(config, config.ship) : {})), [key]);
+  const [period, setPeriod] = useState(seed.period);
+  useEffect(() => setPeriod(seed.period), [seed]);
+  const state = { ...seed, period };
+  const rows = budgetRows(config, state);
+  const totals = budgetTotals(rows);
+
+  /* Loading → ready: the case that ships loading turns ready after a beat, then M15 plays. */
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : rows.length ? 'ready' : 'empty'), reload);
+  useEffect(() => {
+    if (!seed.loadReady || status) return;
+    const t = setTimeout(() => pattern.set('ready'), 1200);
+    return () => clearTimeout(t);
+  }, [seed, status, replay]);
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : budgetScene(rows, state, config)) : pattern.status, onScene);
+
+  const [ref, inView] = useInView();
+  const clock = useRevealClock(inView && pattern.status === 'ready', revealEnd(rows.length), `${replay ?? 0}|${pattern.status}`, forceReduced);
+  const t = clock.t;
+  const shown = useTweenedValues([...rows.map(r => r.spent), ...rows.map(r => Math.min(1, r.ratio)), totals.allocated, totals.spent, totals.utilization], M15.fillMs, clock.done, clock.reduced);
+  const n = rows.length;
+  const spentOf = (i: number) => (clock.done ? shown[i]! : rows[i]!.spent * barFill(i, t));
+  const scaleOf = (i: number) => (clock.done ? shown[n + i]! : Math.min(1, rows[i]!.ratio) * barFill(i, t));
+  const sum = progress(t, 160, M15.fillMs);
+  const stat = (k: number, target: number) => (clock.done ? shown[2 * n + k]! : target * sum);
+
+  const tones = { mint: colors.status.executed, apricot: colors.status.needsUser, muted: colors.textSecondary };
+  const meta = config.periods.length > 1 ? (
+    <Box style={{ minWidth: 132 }}>
+      <Select
+        aria-label="Period"
+        value={period}
+        options={config.periods.map(p => ({ value: p, label: p }))}
+        onChange={p => { setPeriod(p); onPeriodChange?.(p); }}
+      />
+    </Box>
+  ) : <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{config.period}</Text>;
+
+  return (
+    <OnboardingCard testID={testID} header={config} copy={config} density={density} status={pattern.status} onRetry={pattern.retry} onEmptyAction={pattern.retry} meta={meta}>
+      <View ref={ref} style={{ opacity: clock.reduced ? clock.fade : 1, gap: 14 }}>
+        <Box row gap="s2" role={'list' as never} aria-label="Summary" style={{ flexWrap: 'wrap' }}>
+          {[
+            ['Allocated', compactCurrency(stat(0, totals.allocated), config.currency)],
+            ['Spent', compactCurrency(stat(1, totals.spent), config.currency)],
+            ['Utilization', `${Math.round(stat(2, totals.utilization))}%`],
+          ].map(([dt, dd], k) => (
+            <Box key={dt} role={'listitem' as never} style={{ flexGrow: 1, flexBasis: 96, padding: 12, borderRadius: blockRadii.inset + 4, backgroundColor: colors.surfaceSunken }}>
+              <Text style={{ fontSize: 12, color: colors.textSecondary }}>{dt}</Text>
+              <Text numeric style={{ fontSize: 20, fontWeight: '600', letterSpacing: -0.3, color: colors.textPrimary, textAlign: k === 2 ? 'right' : 'left' }}>{dd}</Text>
+            </Box>
+          ))}
+        </Box>
+        <Box role={'list' as never} aria-label="Categories" gap="s1">
+          {rows.map((r, i) => {
+            const rv = clock.reduced ? { opacity: 1, y: 0 } : rowReveal(i, t);
+            const toneP = clock.done ? 1 : toneIn(barStart(i) + M15.fillMs, t);
+            return (
+              <RevealRow key={r.id} opacity={rv.opacity} y={rv.y}>
+                <View role={'listitem' as never}>
+                  <DataTip label={r.tooltip} onPress={onOpen ? () => onOpen(r.id) : undefined} style={{ paddingHorizontal: 8, paddingVertical: 8 }}>
+                    <Box gap="s2">
+                      <Box row align="center" gap="s2">
+                        <Text numberOfLines={1} style={{ flex: 1, fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{r.name}</Text>
+                        <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>
+                          {`${compactCurrency(spentOf(i), config.currency)} / ${compactCurrency(r.allocated, config.currency)}`}
+                        </Text>
+                        <View style={{ opacity: toneP, minWidth: 104 }}>
+                          <ToneText color={colors.textSecondary} tone={tones[r.varianceTone]} toneOpacity={1} weight="600" align="right">{r.variance}</ToneText>
+                        </View>
+                      </Box>
+                      <VizBar
+                        scale={scaleOf(i)}
+                        color={colors.textSecondary}
+                        track={colors.band}
+                        overlay={r.overlay ? { color: r.overlay === 'over' ? colors.status.needsUser : colors.statusBg.needsUser, opacity: toneP } : undefined}
+                        a11y={{ role: 'progressbar', label: r.name, now: Math.round((Number.isFinite(r.ratio) ? r.ratio : 1) * 100), max: 100, text: r.valueText }}
+                      />
+                    </Box>
+                  </DataTip>
+                </View>
+              </RevealRow>
+            );
+          })}
+        </Box>
+      </View>
+    </OnboardingCard>
+  );
+}
+
+/** BudgetTracker, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const BudgetTracker = guarded(BudgetTrackerView, BUDGET_TRACKER_PRESETS, 'BudgetTracker');

package/src/components/onboarding/budget-tracker/contract.ts

@@ -0,0 +1,60 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Budget Tracker (batch 5 §4.1)** — spend against allocation, by category. Read-only; the only
+ * entrance animation is M15 (`../shared/m15`). Over budget is always said in words, never only in
+ * colour; totals and utilisation are computed from `categories`, never configured.
+ */
+
+/** `period`: the period this row belongs to, when there are several — one row per category per period, so a sheet can hold them all. */
+export type BudgetTrackerCategory = { id?: string; name: string; allocated: number; spent: number; period?: string };
+
+export const BUDGET_TRACKER_SCENES = ['default', 'someOver', 'allUnder', 'allOver', 'switchPeriod', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type BudgetTrackerScene = (typeof BUDGET_TRACKER_SCENES)[number];
+/** Nothing is in flight: the view only reads. */
+export const BUDGET_TRACKER_IN_FLIGHT: readonly string[] = [];
+
+export type BudgetTrackerSettings = HeaderConfig & LoadCopy & {
+  /** ISO 4217 — every figure is formatted in it. */
+  currency: string;
+  period: string;
+  /** More than one: a period select in the header (C6); changing it tweens the values. */
+  periods: string[];
+  /** The categories. With several periods, each row names its `period`; rows without one apply to every period. */
+  categories: BudgetTrackerCategory[];
+  /** Deprecated: per-period categories by name. Prefer `period` on each category — a sheet can fill that. */
+  data?: Record<string, BudgetTrackerCategory[]>;
+  /** A ratio (0.9): a category at or past it is near its limit (apricot soft). `null`: off. */
+  attentionAt: number | null;
+  /** Demo-only: the scene this case ships in. */
+  ship: BudgetTrackerScene | null;
+};
+
+export const BUDGET_TRACKER_PRESETS = presetsJson as unknown as PresetsFile<BudgetTrackerSettings>;
+
+const num = (v: unknown) => typeof v === 'number' && Number.isFinite(v);
+
+function categoryIssues(list: unknown, path: string): OnboardingIssue[] {
+  if (!Array.isArray(list)) return [{ path, message: `${path} must be a list.` }];
+  const out: OnboardingIssue[] = [];
+  list.forEach((c: Partial<BudgetTrackerCategory> | null, i) => {
+    if (!c || typeof c !== 'object') { out.push({ path: `${path}[${i}]`, message: 'Each category is { name, allocated, spent }.' }); return; }
+    if (typeof c.name !== 'string' || !c.name.trim()) out.push({ path: `${path}[${i}].name`, message: 'Every category needs a name.' });
+    if (!num(c.allocated) || (c.allocated as number) < 0) out.push({ path: `${path}[${i}].allocated`, message: 'allocated is a number, 0 or more.' });
+    if (!num(c.spent) || (c.spent as number) < 0) out.push({ path: `${path}[${i}].spent`, message: 'spent is a number, 0 or more.' });
+  });
+  return out;
+}
+
+export function validateBudgetTracker(c: BudgetTrackerSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  const issues = categoryIssues(c.categories, 'categories');
+  if (c.data && typeof c.data === 'object') for (const [p, list] of Object.entries(c.data)) issues.push(...categoryIssues(list, `data.${p}`));
+  if (!Array.isArray(c.periods) || c.periods.some(p => typeof p !== 'string')) issues.push({ path: 'periods', message: 'periods is a list of period names.' });
+  else if (c.periods.length > 1 && !c.periods.includes(c.period)) issues.push({ path: 'period', message: `“${c.period}” is not one of the periods.` });
+  if (c.attentionAt !== null && c.attentionAt !== undefined && !(num(c.attentionAt) && c.attentionAt > 0 && c.attentionAt <= 1)) {
+    issues.push({ path: 'attentionAt', message: 'attentionAt is a ratio above 0 and at most 1 — or null for off.' });
+  }
+  return issues;
+}

package/src/components/onboarding/budget-tracker/engine.ts

@@ -0,0 +1,87 @@
+import { compactCurrency, money } from '../shared/m15';
+import type { BudgetTrackerCategory, BudgetTrackerScene, BudgetTrackerSettings } from './contract';
+
+/** **The Budget Tracker engine** — pure: which categories, their figures, tones and words. */
+
+/** `mod` reshapes the spend for the demo scenes, as the prototype's `cats` does. */
+export type BudgetTrackerState = { period: string; mod: 'none' | 'under' | 'over' | 'some'; loadReady: boolean };
+export type BudgetTrackerSeed = Partial<BudgetTrackerState>;
+
+export function initialBudgetTracker(c: BudgetTrackerSettings, seed: BudgetTrackerSeed = {}): BudgetTrackerState {
+  return { period: seed.period ?? c.period, mod: seed.mod ?? 'none', loadReady: seed.loadReady ?? false };
+}
+
+const nextPeriod = (c: BudgetTrackerSettings) => {
+  const i = c.periods.indexOf(c.period);
+  return c.periods.length > 1 ? c.periods[(i + 1) % c.periods.length]! : c.period;
+};
+
+export function budgetTrackerSeed(c: BudgetTrackerSettings, scene: BudgetTrackerScene): BudgetTrackerSeed {
+  if (scene === 'someOver') return { mod: 'some' };
+  if (scene === 'allUnder') return { mod: 'under' };
+  if (scene === 'allOver') return { mod: 'over' };
+  if (scene === 'switchPeriod') return { period: nextPeriod(c) };
+  if (scene === 'loadReady') return { loadReady: true };
+  return {};
+}
+
+export function categoriesOf(c: BudgetTrackerSettings, s: BudgetTrackerState): (BudgetTrackerCategory & { id: string })[] {
+  /* Rows for this period: those naming it, plus those naming none. (`data` still works for hosts that used it.) */
+  const list = (c.data && c.data[s.period]) || c.categories.filter(x => !x.period || x.period === s.period);
+  return list.map((x, i) => {
+    let spent = x.spent;
+    const a = x.allocated;
+    if (s.mod === 'under') spent = Math.min(spent, Math.round(a * 0.86));
+    if (s.mod === 'over') spent = Math.max(spent, Math.round(a * 1.07));
+    if (s.mod === 'some') spent = i % 3 === 1 ? Math.max(spent, Math.round(a * 1.07)) : Math.min(spent, Math.round(a * 0.9));
+    return { id: x.id ?? `c${i}`, name: x.name, allocated: a, spent };
+  });
+}
+
+export type BudgetTrackerRow = {
+  id: string; name: string; allocated: number; spent: number;
+  /** spent ÷ allocated (0 when nothing is allocated). */
+  ratio: number;
+  over: boolean; near: boolean;
+  /** "+$35K left", "−$16.4K over", "$0", "+$1.2K left · 95% used". */
+  variance: string;
+  varianceTone: 'mint' | 'apricot' | 'muted';
+  /** The bar's tone layer, after the fill: apricot deep (over), apricot soft (near), none. */
+  overlay: 'over' | 'near' | null;
+  valueText: string;
+  tooltip: string;
+};
+
+export function budgetRows(c: BudgetTrackerSettings, s: BudgetTrackerState): BudgetTrackerRow[] {
+  return categoriesOf(c, s).map(x => {
+    const ratio = x.allocated > 0 ? x.spent / x.allocated : x.spent > 0 ? Infinity : 0;
+    const d = x.allocated - x.spent;
+    const over = d < 0;
+    /* Near the limit: money left, but past `attentionAt`. Exactly on budget is a muted $0, never near. */
+    const near = d > 0 && c.attentionAt !== null && c.attentionAt !== undefined && ratio >= c.attentionAt;
+    const pctUsed = Number.isFinite(ratio) ? Math.round(ratio * 100) : 100;
+    const variance = over ? `−${compactCurrency(-d, c.currency)} over`
+      : d === 0 ? compactCurrency(0, c.currency)
+      : `+${compactCurrency(d, c.currency)} left${near ? ` · ${pctUsed}% used` : ''}`;
+    return {
+      ...x, ratio, over, near, variance,
+      varianceTone: over || near ? 'apricot' : d === 0 ? 'muted' : 'mint',
+      overlay: over ? 'over' : near ? 'near' : null,
+      valueText: `${pctUsed}% — ${over ? `${compactCurrency(-d, c.currency)} over` : d === 0 ? 'exactly on budget' : `${compactCurrency(d, c.currency)} left`}`,
+      tooltip: `Spent ${money(x.spent, c.currency)} of ${money(x.allocated, c.currency)} · ${pctUsed}%`,
+    };
+  });
+}
+
+export function budgetTotals(rows: BudgetTrackerRow[]) {
+  const allocated = rows.reduce((a, r) => a + r.allocated, 0);
+  const spent = rows.reduce((a, r) => a + r.spent, 0);
+  return { allocated, spent, utilization: allocated ? (spent / allocated) * 100 : 0 };
+}
+
+/** The scene the view is in — for `onScene`. */
+export function budgetScene(rows: BudgetTrackerRow[], s: BudgetTrackerState, c: BudgetTrackerSettings): BudgetTrackerScene {
+  if (s.period !== c.period) return 'switchPeriod';
+  const over = rows.filter(r => r.over).length;
+  return over === 0 ? 'allUnder' : over === rows.length ? 'allOver' : over ? 'someOver' : 'default';
+}

package/src/components/onboarding/budget-tracker/index.ts

@@ -0,0 +1,9 @@
+export {
+  BUDGET_TRACKER_IN_FLIGHT, BUDGET_TRACKER_PRESETS, BUDGET_TRACKER_SCENES, validateBudgetTracker,
+  type BudgetTrackerCategory, type BudgetTrackerScene, type BudgetTrackerSettings,
+} from './contract';
+export {
+  budgetRows, budgetScene, budgetTotals, budgetTrackerSeed, categoriesOf, initialBudgetTracker,
+  type BudgetTrackerRow, type BudgetTrackerSeed, type BudgetTrackerState,
+} from './engine';
+export { BudgetTracker, type BudgetTrackerProps } from './BudgetTrackerView';