@appinternalleads/ui 0.2.0

package/src/components/onboarding/brand-kit/runtime.ts

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useOperationRunner } from '../../../runtime/operations';
+import { checkFile, type PickedFile } from '../../../core';
+import type { OnboardingResult } from '../shared/contract';
+import {
+  ONBOARDING_TIMING, createMockOperation, createMockProgressOperation, type OnboardingOperation, type ProgressOperation,
+} from '../shared/mock';
+import { runOutcome } from '../shared/runtime';
+import type { BrandKitSettings } from './contract';
+import {
+  brandSeed, brandView, initialBrand, reduceBrand,
+  type BrandAction, type BrandSeed, type BrandState,
+} from './engine';
+
+export type BrandKitValue = { logo: PickedFile | null; colors: (string | null)[]; font: string };
+export type BrandKitOperations = {
+  /** The logo upload, with progress. */
+  upload: ProgressOperation<{ file: PickedFile }>;
+  save: OnboardingOperation<BrandKitValue>;
+};
+
+/**
+ * **The Brand Kit runtime** — two boundary operations: the logo upload (a progress stream; the
+ * prototype's +12% every 180ms by default) and the save (1400ms; `result` decides it).
+ */
+export function useBrandKit({
+  config, operations, result = 'success', initial, onChange, onSave,
+}: {
+  config: BrandKitSettings;
+  operations?: Partial<BrandKitOperations>;
+  result?: OnboardingResult;
+  initial?: BrandSeed;
+  onChange?: (value: BrandKitValue) => void;
+  onSave?: (value: BrandKitValue) => void;
+}) {
+  const seed = () => initialBrand(config, initial ?? (config.ship ? brandSeed(config, config.ship) : {}));
+  const [state, send] = useReducer((s: BrandState, a: BrandAction) => reduceBrand(config, s, a), undefined, seed);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const runner = useOperationRunner();
+  const upload = useMemo(
+    () => operations?.upload ?? createMockProgressOperation<{ file: PickedFile }>({ tickMs: 180, step: 0.12 }),
+    [operations?.upload],
+  );
+  const save = useMemo(
+    () => operations?.save ?? createMockOperation<BrandKitValue>({ latencyMs: ONBOARDING_TIMING.save, fail: () => result === 'error' }),
+    [operations?.save, result],
+  );
+  const valueOf = (s: BrandState): BrandKitValue => ({ logo: s.file.status === 'filled' ? s.file.file : null, colors: s.valid, font: s.font });
+
+  const key = JSON.stringify([config, initial ?? null]);
+  const seeded = useRef(key);
+  useEffect(() => {
+    if (seeded.current === key) return;
+    seeded.current = key;
+    runner.cancel('upload');
+    runner.cancel('save');
+    send({ type: 'reset', state: seed() });
+  });
+
+  const runUpload = useCallback((file: PickedFile, from: number) => {
+    runner.run('upload', ctx => upload({ file }, {
+      signal: ctx.signal,
+      onProgress: p => { if (ctx.isCurrent()) send({ type: 'progress', progress: Math.max(from, p) }); },
+    }), {
+      onOk: r => (r.ok ? send({ type: 'uploaded' }) : send({ type: 'removeFile' })),
+      onError: () => send({ type: 'removeFile' }),
+    });
+  }, [runner, upload]);
+
+  const runSave = useCallback(() => {
+    const v = valueOf(stateRef.current);
+    runOutcome(runner, 'save', save, v, {
+      ok: () => { send({ type: 'saved' }); onSave?.(v); },
+      fail: () => send({ type: 'failed' }),
+    });
+  }, [runner, save, onSave]);
+
+  /* A restored session resumes an upload or a save it was in (case 5 ships mid-upload). */
+  useEffect(() => {
+    const f = stateRef.current.file;
+    if (f.status === 'uploading') runUpload(f.file, f.progress);
+    if (stateRef.current.save === 'saving') runSave();
+  }, [key]);
+
+  const valueKey = JSON.stringify(valueOf(state));
+  const reported = useRef(valueKey);
+  useEffect(() => {
+    if (reported.current === valueKey) return;
+    reported.current = valueKey;
+    onChange?.(valueOf(state));
+  }, [valueKey]);
+
+  return {
+    state,
+    view: brandView(config, state),
+    dispatch: send,
+    file: (file: PickedFile) => {
+      send({ type: 'file', file });
+      /* The same rule the reducer applies: an accepted file starts uploading at once. */
+      const ext = file.ext === 'jpeg' ? 'jpg' : file.ext;
+      if (checkFile({ ...file, ext }, { accept: config.accept, maxSizeMB: config.maxSizeMB }).ok) runUpload(file, 0);
+    },
+    cancelUpload: () => { runner.cancel('upload'); send({ type: 'removeFile' }); },
+    save: () => {
+      if (!brandView(config, stateRef.current).canSave) return;
+      send({ type: 'save' });
+      runSave();
+    },
+  };
+}

package/src/components/onboarding/budget-allocation/BudgetAllocationView.tsx

@@ -0,0 +1,180 @@
+import { useEffect } from 'react';
+import { Box, Icon, Input, MotionView, Pressable, Text, useBlockMotion, usePresence } from '../../../core';
+import { AmountField, Button, Callout, ProgressBar, StatWell, TickNumber, TypeTile } from '../../../ds';
+import { useDs, type DensityName } from '../../../tokens';
+import { iconFor, 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 { BUDGET_PRESETS, formatAmount, validateBudget, type BudgetSettings } from './contract';
+import type { BudgetAction, BudgetRow, BudgetSeed } from './engine';
+import { useBudgetAllocation, type BudgetAllocationItem, type BudgetOperations } from './runtime';
+import { guarded } from '../shared/guard';
+
+export type BudgetAllocationProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<BudgetSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  operations?: BudgetOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: BudgetSeed;
+  onChange?: (items: BudgetAllocationItem[]) => void;
+  onSave?: (items: BudgetAllocationItem[]) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Budget Allocation** — a stat well (D4, B9: the allocated value cross-fading, an 8px bar ink /
+ * mint / apricot), then one row per category: tile, name, a 4px share bar with its percentage, a
+ * 150px amount field (grouped at rest, B7) and Remove. A share above `attentionAt` turns the bar
+ * and percentage apricot and says so. Rows add and remove with M14. The footer says what remains
+ * — or, in apricot, by how much it is over — and Save is gated on over, no rows, or a new row
+ * without a name.
+ */
+function BudgetAllocationView(props: BudgetAllocationProps) {
+  const config = resolveConfig(BUDGET_PRESETS, props.preset, props.config);
+  const issues = validateBudget(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, onChange, onSave, onScene, testID,
+}: Omit<BudgetAllocationProps, 'config'> & { config: BudgetSettings }) {
+  const { colors } = useDs();
+  const motion = useBlockMotion();
+  const pattern = usePatternStatus(status ?? (config.categories.length ? 'ready' : 'empty'), reload);
+  const rt = useBudgetAllocation({ config, operations, result, initial, onChange, onSave });
+  const v = rt.view;
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const fmt = (n: number) => formatAmount(config, n);
+  const over = v.mode === 'over';
+  const locked = rt.state.save === 'saving' || rt.state.save === 'saved';
+
+  const hint = (
+    <Box row align="center" gap="s1" wrap>
+      <Text variant="caption" style={{ fontSize: 12, color: over ? colors.status.needsUser : colors.textSecondary }}>{v.remCaption}</Text>
+      <TickNumber value={Math.abs(v.rem)} format={fmt} fontSize={12} tone={over ? 'apricot' : 'default'} label={v.remCaption} />
+    </Box>
+  );
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={() => {
+        /* "No categories yet" → Add category: the step starts from nothing and adds the first. */
+        pattern.set('ready');
+        rt.dispatch({ type: 'reset', state: { rows: [], save: 'idle', nextId: 100 } });
+        rt.dispatch({ type: 'add' });
+      }}
+      chip={v.chip}
+      hint={hint}
+      primary={{ label: v.primaryLabel, onPress: rt.save, disabled: !v.canSave, busy: rt.state.save === 'saving' }}>
+      <Box gap="s3">
+        <StatWell label="Allocated" hint={config.unitHint} value={v.alloc} total={config.total} format={fmt} />
+        <Box role="list" aria-label={`${config.title} categories`}>
+          {rt.state.rows.map(r => (
+            <CategoryRow
+              key={r.id}
+              row={r}
+              config={config}
+              share={v.share(r)}
+              hot={v.hot(r)}
+              locked={locked}
+              dispatch={rt.dispatch}
+              immediate={motion.reduced}
+            />
+          ))}
+        </Box>
+        {v.canAdd ? (
+          <Box alignSelf="flex-start">
+            <Button variant="secondary" size="small" leadingGlyph="plus" onPress={() => rt.dispatch({ type: 'add' })}>Add category</Button>
+          </Box>
+        ) : null}
+        {rt.state.save === 'failed' ? <Callout alert title={config.saveErrorTitle}>{config.saveErrorBody}</Callout> : null}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+function CategoryRow({
+  row, config, share, hot, locked, dispatch, immediate,
+}: {
+  row: BudgetRow;
+  config: BudgetSettings;
+  share: number;
+  hot: boolean;
+  locked: boolean;
+  dispatch: (a: BudgetAction) => void;
+  immediate: boolean;
+}) {
+  const { colors, density } = useDs();
+  /* M14: a new row fades and settles in; a removed one fades up, then leaves. */
+  const presence = usePresence(!row.leaving, { speed: 'list', appear: row.isNew });
+  useEffect(() => { if (row.leaving && !presence.mounted) dispatch({ type: 'drop', id: row.id }); }, [row.leaving, presence.mounted]);
+  if (!presence.mounted) return null;
+  const pct = Math.round(share * 100);
+  const label = row.name.trim() || 'New category';
+  const hotId = `budget-hot-${row.id}`;
+
+  return (
+    <MotionView
+      role="listitem"
+      aria-hidden={row.leaving || undefined}
+      style={{ opacity: presence.opacity, transform: [{ translateY: presence.translateY }] }}>
+      <Box
+        row
+        wrap
+        align="center"
+        gap="s3"
+        style={{ minHeight: density.rowH, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+        <TypeTile icon={iconFor(row.icon)} type={row.type} size={32} />
+        <Box flex={1} gap="s1" style={{ minWidth: 150 }}>
+          {row.isNew ? (
+            <Input value={row.name} onChangeText={name => dispatch({ type: 'name', id: row.id, name })} placeholder="Category name" aria-label="Category name" disabled={locked} />
+          ) : (
+            <Text variant="caption" color="textPrimary" style={{ fontWeight: '600', fontSize: 13 }}>{row.name}</Text>
+          )}
+          <Box row align="center" gap="s2">
+            <Box flex={1}>
+              <ProgressBar bare label={`${label} share`} value={Math.min(100, pct)} tone={hot ? 'attention' : 'neutral'} height={4} format={() => `${pct}% of the total`} />
+            </Box>
+            <Text variant="caption" numeric style={{ fontSize: 12, width: 36, textAlign: 'right', color: hot ? colors.status.needsUser : colors.textSecondary, fontWeight: hot ? '600' : '400' }}>{`${pct}%`}</Text>
+          </Box>
+          {hot ? (
+            <Text nativeID={hotId} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>
+              {`More than ${Math.round(config.attentionAt * 100)}% of the total`}
+            </Text>
+          ) : null}
+        </Box>
+        <AmountField
+          value={row.amount}
+          onChange={amount => dispatch({ type: 'amount', id: row.id, amount })}
+          label={`${label} amount`}
+          prefix={config.prefix || undefined}
+          suffix={config.fieldSuffix || undefined}
+          disabled={locked}
+          describedBy={hot ? hotId : undefined}
+          width={150}
+        />
+        {!locked ? (
+          <Pressable aria-label={`Remove ${row.name.trim() || 'new category'}`} onPress={() => dispatch({ type: 'remove', id: row.id, immediate })} width={32} height={32} radius="pill">
+            <Icon name="trash" size={15} color={colors.textSecondary} />
+          </Pressable>
+        ) : <Box width={32} />}
+      </Box>
+    </MotionView>
+  );
+}
+
+/** BudgetAllocation, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const BudgetAllocation = guarded(BudgetAllocationView, BUDGET_PRESETS, 'BudgetAllocation');

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

@@ -0,0 +1,62 @@
+import type { DataType } from '../../../tokens';
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Budget Allocation (handoff §3.2)** — split a fixed total across categories and see what is
+ * allocated against what remains.
+ */
+
+export type BudgetCategory = { name: string; type: DataType; icon: string; amount: number };
+
+export const BUDGET_SCENES = ['default', 'under', 'exact', 'over', 'saving', 'saved', 'failed', 'loading', 'empty', 'error'] as const;
+export type BudgetScene = (typeof BUDGET_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const BUDGET_IN_FLIGHT: readonly string[] = ['saving'];
+
+/** At most this many categories — "+ Add category" hides at seven. */
+export const MAX_CATEGORIES = 7;
+
+export type BudgetSettings = HeaderConfig & LoadCopy & {
+  total: number;
+  /** Before every figure — `$`. Empty for a unit without one (credits). */
+  prefix: string;
+  /** After every figure — ` / mo`, ` credits`. */
+  suffix: string;
+  /** The amount field's own suffix — `credits`. */
+  fieldSuffix: string;
+  /** Right of "Allocated" — "USD per month". */
+  unitHint: string;
+  categories: BudgetCategory[];
+  /** A category's share above this (0–1) is flagged apricot. Decision (PRD §5): a per-category share threshold. */
+  attentionAt: number;
+  allowAdd: boolean;
+  /** How far the demo's "over" scene over-allocates. Demo boards only. */
+  overBy?: number;
+  ship?: BudgetScene;
+  primaryLabel: string;
+  savingLabel: string;
+  savedLabel: string;
+  secondaryLabel?: string;
+  saveErrorTitle: string;
+  saveErrorBody: string;
+};
+
+export const BUDGET_PRESETS = presetsJson as unknown as PresetsFile<BudgetSettings>;
+
+export function validateBudget(c: BudgetSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.categories)) return [{ path: 'categories', message: 'categories must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  if (!(c.total > 0)) issues.push({ path: 'total', message: 'total must be more than 0.' });
+  if (!(c.attentionAt > 0 && c.attentionAt <= 1)) issues.push({ path: 'attentionAt', message: 'attentionAt is a share between 0 and 1.' });
+  if (c.categories.length > MAX_CATEGORIES) issues.push({ path: 'categories', message: `At most ${MAX_CATEGORIES} categories.` });
+  c.categories.forEach((k, i) => {
+    if (!(k.amount >= 0) || !Number.isInteger(k.amount)) issues.push({ path: `categories[${i}].amount`, message: 'Amounts are whole numbers, 0 or more.' });
+  });
+  return issues;
+}
+
+/** A figure in the budget's unit — `$25,000`, `1,000,000 credits`. */
+export function formatAmount(c: Pick<BudgetSettings, 'prefix' | 'suffix'>, n: number): string {
+  return `${c.prefix ?? ''}${n.toLocaleString('en-US')}${c.suffix ?? ''}`;
+}

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

@@ -0,0 +1,114 @@
+import type { StateChipTone } from '../../../ds';
+import type { SavePhase } from '../shared/contract';
+import { MAX_CATEGORIES, formatAmount, type BudgetScene, type BudgetSettings } from './contract';
+
+/** **The Budget Allocation engine** — pure: rows, amounts, the save, and every derived figure. */
+
+export type BudgetRow = {
+  id: string;
+  name: string;
+  type: BudgetSettings['categories'][number]['type'];
+  icon: string;
+  /** `null` while the field is empty — not 0. */
+  amount: number | null;
+  /** Added in this session: its name is an editable field. */
+  isNew: boolean;
+  /** Removed, playing its exit (M14); the engine drops it on `drop`. */
+  leaving: boolean;
+};
+export type BudgetState = { rows: BudgetRow[]; save: SavePhase; nextId: number };
+export type BudgetSeed = { amounts?: (number | null)[]; save?: SavePhase; rows?: BudgetRow[] };
+
+export type BudgetAction =
+  | { type: 'amount'; id: string; amount: number | null }
+  | { type: 'name'; id: string; name: string }
+  | { type: 'add' }
+  | { type: 'remove'; id: string; immediate?: boolean }
+  | { type: 'drop'; id: string }
+  | { type: 'save' }
+  | { type: 'saved' }
+  | { type: 'failed' }
+  | { type: 'reset'; state: BudgetState };
+
+export function initialBudget(c: BudgetSettings, seed: BudgetSeed = {}): BudgetState {
+  const rows = seed.rows ?? c.categories.map((k, i) => ({
+    id: `r${i}`, name: k.name, type: k.type, icon: k.icon, amount: seed.amounts?.[i] ?? k.amount, isNew: false, leaving: false,
+  }));
+  return { rows, save: seed.save ?? 'idle', nextId: 100 };
+}
+
+/**
+ * The demo scenes as seeds: `under` rescales to ~88% of the total, `over` to total + `overBy`,
+ * `exact` (and the save scenes) to the total — proportionally, rounded to 100, the last row
+ * taking the remainder. Verbatim from the prototype.
+ */
+export function budgetSeed(c: BudgetSettings, scene: BudgetScene): BudgetSeed {
+  const target = scene === 'under' ? Math.round((c.total * 0.88) / 100) * 100
+    : scene === 'over' ? c.total + (c.overBy ?? Math.round(c.total * 0.05))
+    : scene === 'exact' || scene === 'saving' || scene === 'saved' || scene === 'failed' ? c.total
+    : null;
+  const save = scene === 'saving' || scene === 'saved' || scene === 'failed' ? scene : undefined;
+  if (target === null || !c.categories.length) return save ? { save } : {};
+  const sum = c.categories.reduce((a, k) => a + k.amount, 0);
+  if (sum <= 0) return save ? { save } : {};
+  let acc = 0;
+  const amounts = c.categories.map((k, i) => {
+    const v = i === c.categories.length - 1 ? target - acc : Math.round((k.amount * target) / sum / 100) * 100;
+    acc += v;
+    return Math.max(0, v);
+  });
+  return { amounts, ...(save ? { save } : {}) };
+}
+
+export const liveRows = (s: BudgetState) => s.rows.filter(r => !r.leaving);
+export const isLocked = (s: BudgetState) => s.save === 'saving' || s.save === 'saved';
+
+export function reduceBudget(s: BudgetState, a: BudgetAction): BudgetState {
+  const idle = (next: BudgetState): BudgetState => ({ ...next, save: 'idle' });
+  switch (a.type) {
+    case 'amount': return isLocked(s) ? s : idle({ ...s, rows: s.rows.map(r => (r.id === a.id ? { ...r, amount: a.amount } : r)) });
+    case 'name': return isLocked(s) ? s : idle({ ...s, rows: s.rows.map(r => (r.id === a.id ? { ...r, name: a.name } : r)) });
+    case 'add': {
+      if (isLocked(s) || liveRows(s).length >= MAX_CATEGORIES) return s;
+      const row: BudgetRow = { id: `r${s.nextId}`, name: '', type: 'data', icon: 'tag', amount: 0, isNew: true, leaving: false };
+      return idle({ ...s, rows: [...s.rows, row], nextId: s.nextId + 1 });
+    }
+    case 'remove':
+      if (isLocked(s)) return s;
+      return idle({ ...s, rows: a.immediate ? s.rows.filter(r => r.id !== a.id) : s.rows.map(r => (r.id === a.id ? { ...r, leaving: true } : r)) });
+    case 'drop': return { ...s, rows: s.rows.filter(r => r.id !== a.id) };
+    case 'save': return { ...s, save: 'saving' };
+    case 'saved': return s.save === 'saving' ? { ...s, save: 'saved' } : s;
+    case 'failed': return s.save === 'saving' ? { ...s, save: 'failed' } : s;
+    case 'reset': return a.state;
+  }
+}
+
+export type Allocation = 'under' | 'exact' | 'over';
+
+export function budgetView(c: BudgetSettings, s: BudgetState) {
+  const live = liveRows(s);
+  const alloc = live.reduce((a, r) => a + (r.amount ?? 0), 0);
+  const rem = c.total - alloc;
+  const mode: Allocation = alloc > c.total ? 'over' : alloc === c.total ? 'exact' : 'under';
+  const fmt = (n: number) => formatAmount(c, n);
+  const unnamed = live.some(r => r.isNew && !r.name.trim());
+  const chip: { tone: StateChipTone; label: string } = s.save === 'saving' ? { tone: 'neutral', label: c.savingLabel }
+    : s.save === 'saved' ? { tone: 'success', label: c.savedLabel }
+    : mode === 'over' ? { tone: 'attention', label: `Over by ${fmt(-rem)}` }
+    : mode === 'exact' ? { tone: 'success', label: 'Fully allocated' }
+    : { tone: 'neutral', label: `${Math.round((alloc / c.total) * 100)}% allocated` };
+  return {
+    alloc,
+    rem,
+    mode,
+    chip,
+    scene: (s.save !== 'idle' ? s.save : mode === 'over' ? 'over' : mode === 'exact' ? 'exact' : 'default') as BudgetScene,
+    remCaption: mode === 'over' ? 'Over by' : 'Remaining',
+    canSave: mode !== 'over' && live.length > 0 && !unnamed && !isLocked(s),
+    canAdd: c.allowAdd && live.length < MAX_CATEGORIES && !isLocked(s),
+    primaryLabel: s.save === 'saving' ? c.savingLabel : s.save === 'saved' ? c.savedLabel : s.save === 'failed' ? c.retryLabel : c.primaryLabel,
+    share: (r: BudgetRow) => (c.total ? (r.amount ?? 0) / c.total : 0),
+    hot: (r: BudgetRow) => !r.leaving && (c.total ? (r.amount ?? 0) / c.total : 0) > c.attentionAt,
+  };
+}

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

@@ -0,0 +1,10 @@
+export {
+  BUDGET_PRESETS, BUDGET_SCENES, BUDGET_IN_FLIGHT, MAX_CATEGORIES, formatAmount, validateBudget,
+  type BudgetCategory, type BudgetScene, type BudgetSettings,
+} from './contract';
+export {
+  budgetSeed, budgetView, initialBudget, liveRows as liveBudgetRows, reduceBudget,
+  type BudgetAction, type BudgetRow, type BudgetSeed, type BudgetState,
+} from './engine';
+export { useBudgetAllocation, type BudgetAllocationItem, type BudgetOperations } from './runtime';
+export { BudgetAllocation, type BudgetAllocationProps } from './BudgetAllocationView';