@appinternalleads/ui 0.2.0

package/src/components/onboarding/shared/runtime.ts

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { useOperationRunner, type OperationRunner } from '../../../runtime/operations';
+import type { PatternStatus } from './contract';
+import { createMockOperation, mockReload, type OnboardingOperation, type OnboardingOutcome } from './mock';
+
+/**
+ * **The pattern status (S1) as runtime state.** The host says where the step starts — `ready`,
+ * `loading`, `empty`, `error` — and the component owns what happens next: Retry from `error` goes
+ * to `loading`, runs the host's `reload`, and lands on `ready` (or back on `error`). The same for
+ * the empty state's action when it is a refresh. A new `status` from the host always wins.
+ */
+export function usePatternStatus(status: PatternStatus, reload: OnboardingOperation<void> = mockReload) {
+  const [current, setCurrent] = useState<PatternStatus>(status);
+  useEffect(() => setCurrent(status), [status]);
+  const runner = useOperationRunner();
+  const retry = useCallback(() => {
+    setCurrent('loading');
+    runner.run('reload', ctx => reload(undefined, { signal: ctx.signal }), {
+      onOk: r => setCurrent(r.ok ? 'ready' : 'error'),
+      onError: () => setCurrent('error'),
+    });
+  }, [runner, reload]);
+  return { status: current, retry, set: setCurrent };
+}
+
+/**
+ * Run one boundary operation and route its outcome — a business refusal (`{ ok: false }`) and a
+ * thrown transport error both land in `fail`, with the message when there is one. An abort (an
+ * unmount, a superseded attempt) lands nowhere.
+ */
+export function runOutcome<Req>(
+  runner: OperationRunner,
+  id: string,
+  op: OnboardingOperation<Req>,
+  req: Req,
+  on: { ok: () => void; fail: (message?: string) => void },
+) {
+  runner.run(id, ctx => op(req, { signal: ctx.signal }), {
+    onOk: (r: OnboardingOutcome) => (r.ok ? on.ok() : on.fail(r.message)),
+    onError: e => on.fail(e.message),
+  });
+}
+
+/**
+ * Report the component's scene whenever it changes — the README's optional `onScene` (analytics,
+ * a demo board following along). Never drives anything.
+ */
+export function useSceneReport(scene: string, onScene?: (scene: string) => void) {
+  const last = useRef<string | null>(null);
+  useEffect(() => {
+    if (last.current === scene) return;
+    last.current = scene;
+    onScene?.(scene);
+  }, [scene, onScene]);
+}
+
+/**
+ * **A reducer seeded from the config, reseeded when the config (or seed) genuinely changes** — the
+ * rule every onboarding runtime follows: a parent re-rendering with an equal config must not wipe
+ * the person's work, and a preset switch must start over. Returns the state, a dispatch, and a
+ * ref that always holds the latest state (for operation callbacks).
+ */
+export function useSeededReducer<S, A>(
+  reduce: (s: S, a: A) => S,
+  seed: () => S,
+  key: string,
+  onReseed?: () => void,
+): [S, (a: A) => void, { current: S }] {
+  type Internal = A | { type: '__reset'; state: S };
+  const [state, send] = useReducer(
+    (s: S, a: Internal) => ((a as { type?: string }).type === '__reset' ? (a as { state: S }).state : reduce(s, a as A)),
+    undefined,
+    seed,
+  );
+  const ref = useRef(state);
+  ref.current = state;
+  const seeded = useRef(key);
+  useEffect(() => {
+    if (seeded.current === key) return;
+    seeded.current = key;
+    onReseed?.();
+    send({ type: '__reset', state: seed() });
+  });
+  return [state, send as (a: A) => void, ref];
+}
+
+/**
+ * The host's operation, or — without one — the prototype's placeholder: `latencyMs`, then success,
+ * or failure when `fail` says so (the README's `result` contract).
+ */
+export function useDefaultOperation<Req>(
+  op: OnboardingOperation<Req> | undefined,
+  latencyMs: number,
+  fail: (req: Req, callIndex: number) => boolean,
+): OnboardingOperation<Req> {
+  const failRef = useRef(fail);
+  failRef.current = fail;
+  return useMemo(
+    () => op ?? createMockOperation<Req>({ latencyMs, fail: (r, i) => failRef.current(r, i) }),
+    [op, latencyMs],
+  );
+}

package/src/components/onboarding/shared/shape.ts

@@ -0,0 +1,75 @@
+import { presetsOf, resolveConfig, type OnboardingIssue, type PresetsFile } from './contract';
+
+/**
+ * **A config's shape, learned from the component's own presets.** Every value a component ships
+ * with — the base and each case, resolved — is a sample; a field may take the kinds its samples
+ * take (text, a number, yes/no, a list, an object, null), and a list's items the kinds its items
+ * take. `shapeIssues` holds a host's config to that before anything renders, so `{}` where a title
+ * belongs, `null` where a list belongs or `NaN` where a number belongs is refused out loud (the
+ * component's "This step can't be shown" card, naming the field) rather than crashing the page.
+ *
+ * Only kinds are checked, and only where the presets say something: a field no preset sets, and the
+ * keys of an object the presets fill differently (tones by status, say), are left to the component's
+ * own validator. What that validator checks — ranges, ids, counts — it still checks.
+ */
+
+type Kind = 'string' | 'number' | 'boolean' | 'null' | 'array' | 'object';
+type Shape = { kinds: Set<Kind>; item?: Shape; fields?: Map<string, Shape> };
+
+const kindOf = (v: unknown): Kind =>
+  v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v === 'object' ? 'object'
+    : typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string';
+
+const NAMES: Record<Kind, string> = { string: 'text', number: 'a number', boolean: 'true or false', null: 'null', array: 'a list', object: 'an object' };
+
+function learn(samples: unknown[]): Shape {
+  const defined = samples.filter(s => s !== undefined && (typeof s !== 'function'));
+  const shape: Shape = { kinds: new Set(defined.map(kindOf)) };
+  const items = defined.filter(Array.isArray).flat();
+  if (items.length) shape.item = learn(items);
+  const objects = defined.filter((s): s is Record<string, unknown> => kindOf(s) === 'object');
+  if (objects.length) {
+    const keys = [...new Set(objects.flatMap(o => Object.keys(o)))];
+    shape.fields = new Map(keys.map(k => [k, learn(objects.map(o => o[k]))]));
+  }
+  return shape;
+}
+
+const learned = new WeakMap<object, Shape>();
+function shapeOf(presets: PresetsFile<object>): Shape {
+  let s = learned.get(presets);
+  if (!s) {
+    s = learn([resolveConfig(presets), ...presetsOf(presets).map(p => resolveConfig(presets, p))]);
+    learned.set(presets, s);
+  }
+  return s;
+}
+
+const MAX = 8;
+
+function check(value: unknown, shape: Shape, path: string, out: OnboardingIssue[]) {
+  if (out.length >= MAX || value === undefined || shape.kinds.size === 0) return;
+  const k = typeof value === 'function' ? null : kindOf(value);
+  if (k === null || !shape.kinds.has(k)) {
+    const want = [...shape.kinds].map(x => NAMES[x]).join(' or ');
+    out.push({ path, message: `must be ${want} (got ${k ? NAMES[k] : 'a function'}).` });
+    return;
+  }
+  if (k === 'number' && !Number.isFinite(value)) { out.push({ path, message: 'must be a finite number.' }); return; }
+  if (k === 'array' && shape.item) (value as unknown[]).forEach((v, i) => check(v, shape.item!, `${path}[${i}]`, out));
+  if (k === 'object' && shape.fields) {
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      const f = shape.fields.get(key);
+      if (f) check(v, f, path ? `${path}.${key}` : key, out);
+    }
+  }
+}
+
+/** Problems with the kinds of `config`'s values, against what `presets` use — empty when it is fine. */
+export function shapeIssues(presets: PresetsFile<object>, config: object | undefined): OnboardingIssue[] {
+  const out: OnboardingIssue[] = [];
+  if (config === undefined || config === null) return out;
+  if (kindOf(config) !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  check(config, shapeOf(presets), '', out);
+  return out;
+}

package/src/components/onboarding/shared/viz.tsx

@@ -0,0 +1,271 @@
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { Animated, Platform, Pressable as RNPressable, View } from 'react-native';
+import { Box, MotionView, Text, useReduceMotion } from '../../../core';
+import { blockRadii, useDs } from '../../../tokens';
+import { M15, ease } from './m15';
+
+/**
+ * **M15, running** — the hooks and parts the batch 5 data-viz views share. The timing is `./m15`
+ * (pure); this holds the clock, the in-view trigger, the tweens and the drawn pieces. Only
+ * `opacity` and `transform` ever animate (never width or height), and reduced motion — the OS
+ * setting or the board's `forceReduced` — drops every stagger, fill and count for one 160ms fade.
+ */
+
+/* ── When: 30% in view, once per mount ─────────────────────────────────────────────────── */
+
+/**
+ * The first time the card is 30% in view. On the web: an `IntersectionObserver` at 0.3, plus a
+ * 400ms `getBoundingClientRect` poll (iframes can throttle the observer) — the prototype's pair.
+ * Where there is no layout to measure (native, a test DOM), it counts as in view.
+ */
+export function useInView(): [React.RefObject<View | null>, boolean] {
+  const ref = useRef<View | null>(null);
+  const [seen, setSeen] = useState(Platform.OS !== 'web');
+  useEffect(() => {
+    if (seen || Platform.OS !== 'web') return;
+    const el = ref.current as unknown as HTMLElement | null;
+    const w = globalThis as { innerHeight?: number; IntersectionObserver?: typeof IntersectionObserver };
+    if (!el || typeof el.getBoundingClientRect !== 'function') { setSeen(true); return; }
+    const check = () => {
+      const r = el.getBoundingClientRect();
+      if (r.height === 0 && r.width === 0) return true;          // nothing measured: a test DOM
+      const vh = w.innerHeight ?? 0;
+      const visible = Math.max(0, Math.min(r.bottom, vh) - Math.max(r.top, 0));
+      return visible / Math.max(1, r.height) >= 0.3;
+    };
+    if (check()) { setSeen(true); return; }
+    let io: IntersectionObserver | undefined;
+    if (w.IntersectionObserver) {
+      io = new w.IntersectionObserver(es => { if (es.some(e => e.intersectionRatio >= 0.3)) setSeen(true); }, { threshold: 0.3 });
+      io.observe(el);
+    }
+    const poll = setInterval(() => { if (check()) setSeen(true); }, 400);
+    return () => { io?.disconnect(); clearInterval(poll); };
+  }, [seen]);
+  return [ref, seen];
+}
+
+/* ── The clock ──────────────────────────────────────────────────────────────────────────── */
+
+export type RevealClock = { t: number; fade: number; done: boolean; reduced: boolean };
+
+/**
+ * **Milliseconds since the reveal began** — a 16ms timer, as the prototype drives it, stopping at
+ * `total`. It starts when `active` (in view and ready) and starts over when `replay` changes.
+ * Reduced motion: `t` is at the end at once, and `fade` runs 0→1 over 160ms.
+ */
+export function useRevealClock(active: boolean, total: number, replay: unknown, forceReduced?: boolean): RevealClock {
+  const osReduced = useReduceMotion();
+  const reduced = Boolean(forceReduced) || osReduced;
+  const [t, setT] = useState(0);
+  const [fade, setFade] = useState(0);
+  const started = useRef<number | null>(null);
+  useEffect(() => { started.current = null; setT(0); setFade(0); }, [replay, reduced]);
+  useEffect(() => {
+    if (!active || started.current !== null) return;
+    started.current = Date.now();
+    const span = reduced ? M15.reducedFadeMs : total;
+    const iv = setInterval(() => {
+      const e = Date.now() - (started.current ?? Date.now());
+      if (reduced) setFade(Math.min(1, e / span)); else setT(Math.min(e, total));
+      if (e >= span) clearInterval(iv);
+    }, 16);
+    return () => clearInterval(iv);
+  }, [active, replay, reduced, total]);
+  /* Reduced: the final values at once — only the opacity fades in, once the card is in view. */
+  if (reduced) return { t: Number.MAX_SAFE_INTEGER, fade: active ? Math.max(fade, 0.001) : 0, done: true, reduced };
+  return { t, fade: 1, done: started.current !== null && t >= total, reduced };
+}
+
+/**
+ * **Values that tween on a data change** (a period switch, a live update) — from where they are
+ * now to the new targets over `ms`, never re-staggering. Before `settled` (the reveal still
+ * running) the targets pass through untouched; the reveal draws them.
+ */
+export function useTweenedValues(targets: number[], ms: number, settled: boolean, reduced: boolean): number[] {
+  const [shown, setShown] = useState(targets);
+  const from = useRef(targets);
+  const key = targets.join('|');
+  const last = useRef(key);
+  useEffect(() => {
+    if (key === last.current) return;
+    last.current = key;
+    if (!settled || reduced) { from.current = targets; setShown(targets); return; }
+    const start = Date.now();
+    const a = from.current;
+    const iv = setInterval(() => {
+      const p = ease(Math.min(1, (Date.now() - start) / ms));
+      const next = targets.map((to, i) => (a[i] ?? 0) + (to - (a[i] ?? 0)) * p);
+      from.current = next;
+      setShown(next);
+      if (p >= 1) clearInterval(iv);
+    }, 16);
+    return () => clearInterval(iv);
+  }, [key, settled, reduced]);
+  return settled ? shown : targets;
+}
+
+/* ── Drawn pieces ───────────────────────────────────────────────────────────────────────── */
+
+/** A row that drops 6px into place and fades in (M15), or only fades under reduced motion. */
+export function RevealRow({ opacity, y, children, style }: { opacity: number; y: number; children: ReactNode; style?: object }) {
+  return <View style={[{ opacity, transform: [{ translateY: y }] }, style]}>{children}</View>;
+}
+
+/**
+ * **A bar: a track and a fill scaled on X** — never a width — from the left, or the centre (Funnel).
+ * `overlay` is a tone layer (apricot) at the same scale that fades in on its own opacity.
+ */
+export function VizBar({
+  scale, height = 6, color, track, radius = 999, origin = 'left', overlay, dim = 1, a11y,
+}: {
+  scale: number;
+  height?: number;
+  color: string;
+  /** Omit for no track (Funnel). */
+  track?: string;
+  radius?: number;
+  origin?: 'left' | 'center';
+  overlay?: { color: string; opacity: number };
+  /** 0.6 for a paused test. */
+  dim?: number;
+  a11y?: { role: 'progressbar' | 'meter'; label: string; now: number; min?: number; max?: number; text: string };
+}) {
+  const s = Math.max(0, Math.min(1, scale));
+  const fill = (bg: string, opacity = 1) => (
+    <View style={{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0, borderRadius: radius, backgroundColor: bg, opacity, transform: [{ scaleX: s }], transformOrigin: origin === 'left' ? 'left' : 'center' } as object} />
+  );
+  return (
+    <Box
+      role={a11y?.role as never}
+      aria-label={a11y?.label}
+      aria-valuemin={a11y ? a11y.min ?? 0 : undefined}
+      aria-valuemax={a11y ? a11y.max ?? 100 : undefined}
+      aria-valuenow={a11y?.now}
+      aria-valuetext={a11y?.text}
+      style={{ height, borderRadius: radius, backgroundColor: track, overflow: 'hidden', opacity: dim, position: 'relative' }}>
+      {s > 0 ? fill(color) : null}
+      {s > 0 && overlay ? fill(overlay.color, overlay.opacity) : null}
+    </Box>
+  );
+}
+
+/**
+ * **Two stacked layers that cross-fade (M9)** — the muted figure, then its toned twin once the count
+ * has ended. The text is the same in both, so nothing moves; only colour arrives.
+ */
+export function ToneText({ children, color, tone, toneOpacity, weight = '400', size = 12, align = 'left', minWidth }: {
+  children: ReactNode;
+  color: string;
+  /** No tone: only the muted layer. */
+  tone?: string;
+  toneOpacity: number;
+  weight?: '400' | '600';
+  size?: number;
+  align?: 'left' | 'right';
+  minWidth?: number;
+}) {
+  const base = { fontSize: size, fontWeight: weight, textAlign: align } as const;
+  return (
+    <View style={{ position: 'relative', minWidth }}>
+      <Text numeric style={{ ...base, color, opacity: tone ? 1 - toneOpacity : 1 }}>{children}</Text>
+      {tone ? <Text numeric aria-hidden style={{ ...base, color: tone, opacity: toneOpacity, position: 'absolute', left: 0, right: 0, top: 0 }}>{children}</Text> : null}
+    </View>
+  );
+}
+
+/**
+ * **O4 · the data tooltip** — ink, white 12px tabular text, radius 8, padding 6/10, above the row.
+ * Shows on hover and on focus, fades 160ms (opacity only), Esc hides it; linked by
+ * `aria-describedby`. The row is focusable to reach it, and pressable only with `onPress`.
+ */
+export function DataTip({ label, children, onPress, style, testID, onHover }: {
+  label: string;
+  children: ReactNode;
+  onPress?: () => void;
+  style?: object;
+  testID?: string;
+  /** Hover or focus on (true) and off — Spider highlights the row's axis. */
+  onHover?: (on: boolean) => void;
+}) {
+  const { colors, lift2 } = useDs();
+  const id = `dt-${useId().replace(/:/g, '')}`;
+  const [shown, setShown] = useState(false);
+  const [hover, setHover] = useState(false);
+  const op = useRef(new Animated.Value(0)).current;
+  useEffect(() => { Animated.timing(op, { toValue: shown ? 1 : 0, duration: 160, useNativeDriver: false }).start(); onHover?.(shown); }, [shown, op]);
+  return (
+    <View style={{ position: 'relative' }}>
+      {/* React Native's own Pressable: the row must be focusable to reach its tooltip, even when it does nothing on press. */}
+      <RNPressable
+        {...({ focusable: true, 'aria-describedby': id, onKeyDown: (e: { key: string }) => { if (e.key === 'Escape') setShown(false); } } as object)}
+        testID={testID}
+        onPress={onPress}
+        onHoverIn={() => { setHover(true); setShown(true); }}
+        onHoverOut={() => { setHover(false); setShown(false); }}
+        onFocus={() => setShown(true)}
+        onBlur={() => setShown(false)}
+        style={[{ borderRadius: blockRadii.inset, backgroundColor: hover ? colors.surfaceSunken : 'transparent' }, style]}>
+        {children}
+      </RNPressable>
+      <MotionView
+        nativeID={id}
+        role="tooltip"
+        aria-hidden={!shown}
+        pointerEvents="none"
+        style={{
+          position: 'absolute', bottom: '100%', left: 0, marginBottom: 4, zIndex: 5,
+          paddingHorizontal: 10, paddingVertical: 6, borderRadius: blockRadii.inset,
+          backgroundColor: colors.textPrimary, opacity: op, maxWidth: 320,
+          boxShadow: lift2,
+        } as object}>
+        <Text numeric style={{ fontSize: 12, color: colors.surface1 }}>{label}</Text>
+      </MotionView>
+    </View>
+  );
+}
+
+/**
+ * **A centred bar whose rounded ends stay round** — the Funnel's. Scaling a rounded rectangle on X
+ * squashes its corners, so a narrow stage read as square-ended (the prototype's own scaling does the
+ * same; decided 2026-09-26 to fix it). Here two fixed caps (radius r) ride outward on `translateX`
+ * and a square middle scales between them — still only `transform`, never a width. Below 2r wide
+ * (the 2px floor) one cap scales down, as a bar that small has no visible corners.
+ */
+export function CapsuleBar({ scale, height, radius, color, opacity = 1, a11y }: {
+  scale: number;
+  height: number;
+  radius: number;
+  /** A solid colour; the whole bar takes `opacity`, so the overlapping caps never double up. */
+  color: string;
+  opacity?: number;
+  a11y?: { label: string; now: number; max?: number; text: string };
+}) {
+  /* The bar measures its own track, so the caps and the middle are placed against one width. */
+  const [width, setWidth] = useState(0);
+  const s = Math.max(0, Math.min(1, scale));
+  const w = s * width;
+  const r = Math.min(radius, height / 2);
+  const cap = (x: number, sx = 1) => (
+    <View style={{ position: 'absolute', top: 0, bottom: 0, left: width / 2 - r, width: 2 * r, borderRadius: r, backgroundColor: color, transform: [{ translateX: x }, { scaleX: sx }] }} />
+  );
+  return (
+    <Box
+      role={a11y ? ('meter' as never) : undefined}
+      aria-label={a11y?.label}
+      aria-valuemin={a11y ? 0 : undefined}
+      aria-valuemax={a11y ? a11y.max ?? 100 : undefined}
+      aria-valuenow={a11y?.now}
+      aria-valuetext={a11y?.text}
+      onLayout={e => setWidth(e.nativeEvent.layout.width)}
+      style={{ height, width: '100%', position: 'relative', overflow: 'hidden', opacity }}>
+      {w <= 0 || width === 0 ? null : w < 2 * r ? cap(0, w / (2 * r)) : (
+        <>
+          <View style={{ position: 'absolute', top: 0, bottom: 0, left: 0, right: 0, backgroundColor: color, transform: [{ scaleX: Math.max(0, (w - 2 * r) / width) }] }} />
+          {cap(-(w / 2 - r))}
+          {cap(w / 2 - r)}
+        </>
+      )}
+    </Box>
+  );
+}

package/src/components/onboarding/shipping-update/ShippingUpdateView.tsx

@@ -0,0 +1,93 @@
+import { useMemo } from 'react';
+import { Box, Icon, Text } from '../../../core';
+import { Callout, Timeline } from '../../../ds';
+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 { CopyField } from '../shared/parts';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { SHIPPING_PRESETS, validateShippingUpdate, type ShippingUpdateSettings } from './contract';
+import { initialShippingUpdate, shippingSeed, shippingView, type ShippingUpdateSeed } from './engine';
+import { guarded } from '../shared/guard';
+
+export type ShippingUpdateProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<ShippingUpdateSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Tracking is read-only; accepted for the shared shape. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  initial?: ShippingUpdateSeed;
+  onHelp?: () => void;
+  /** The primary — "View order", "View refund". */
+  onPrimary?: () => void;
+  onCopyTracking?: (trackingNo: string) => void | Promise<void>;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Shipping Update** — the tracking number, read-only in mono with Copy; a Q2 timeline (an ordered
+ * list, columns at least 120px, scrolling in its own container on a narrow screen; the current
+ * node `aria-current="step"`, a delay a 3px apricot ring and "Delayed"); then the ETA — or, delayed,
+ * a bold apricot alert. Footer: Get help and one coral primary.
+ */
+function ShippingUpdateView(props: ShippingUpdateProps) {
+  const config = resolveConfig(SHIPPING_PRESETS, props.preset, props.config);
+  const issues = validateShippingUpdate(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, onHelp, onPrimary, onCopyTracking, onScene, testID,
+}: Omit<ShippingUpdateProps, 'config'> & { config: ShippingUpdateSettings }) {
+  const { colors } = useDs();
+  const key = JSON.stringify([config, initial ?? null]);
+  /* Read-only: the state is the config (or a restored seed), never changed here. */
+  const state = useMemo(() => initialShippingUpdate(config, initial ?? (config.ship ? shippingSeed(config, config.ship) : {})), [key]);
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const v = shippingView(config, state);
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}
+      hint={v.footerHint}
+      secondary={{ label: 'Get help', onPress: () => onHelp?.() }}
+      primary={{ label: config.primaryLabel, onPress: () => onPrimary?.() }}>
+      <Box gap="s4">
+        <CopyField
+          nativeID={`su-no-${config.trackingNo.replace(/\W/g, '')}`}
+          label={config.trackLabel}
+          value={config.trackingNo}
+          copyLabel={`Copy ${config.trackLabel.toLowerCase()}`}
+          mono
+          onCopy={onCopyTracking}
+        />
+        <Timeline variant="track" label={config.timelineLabel} steps={v.steps} />
+        {v.delayed ? (
+          <Callout alert strong title={config.delayTitle}>{config.delayBody}</Callout>
+        ) : (
+          <Box row align="center" gap="s2" style={{ paddingVertical: 10, paddingHorizontal: 12, borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken }}>
+            <Icon name="clock" size={16} color={colors.textSecondary} />
+            <Text variant="caption" color="textPrimary" numeric style={{ fontSize: 13, flexShrink: 1 }}>{v.etaLine}</Text>
+          </Box>
+        )}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** ShippingUpdate, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const ShippingUpdate = guarded(ShippingUpdateView, SHIPPING_PRESETS, 'ShippingUpdate');

package/src/components/onboarding/shipping-update/contract.ts

@@ -0,0 +1,53 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Shipping Update (batch 3 §3.11)** — order tracking with a delivery timeline; the same component
+ * tracks a return, a lab sample or a courier. A delay is a 3px apricot-deep ring and bold words.
+ */
+
+export type ShipmentStatus = 'transit' | 'delivered' | 'delayed';
+export type ShipmentNode = { label: string; date: string };
+
+export const SHIPPING_SCENES = ['default', 'inTransit', 'delivered', 'delayed', 'loading', 'empty', 'error'] as const;
+export type ShippingScene = (typeof SHIPPING_SCENES)[number];
+/** Scenes that are an operation in flight — none: tracking is read-only. */
+export const SHIPPING_IN_FLIGHT: readonly string[] = [];
+
+export type ShippingUpdateSettings = HeaderConfig & LoadCopy & {
+  /** "Tracking number", "Sample ID". */
+  trackLabel: string;
+  trackingNo: string;
+  status: ShipmentStatus;
+  nodes: ShipmentNode[];
+  /** 0-based: where the shipment is now. */
+  currentIdx: number;
+  /** The node that is held up, when delayed. */
+  delayedIdx?: number;
+  /** The chip while in transit — "In transit", "In lab". */
+  transitLabel: string;
+  /** The chip once delivered — "Delivered", "Refunded", "Returned". */
+  deliveredLabel: string;
+  timelineLabel: string;
+  etaLine: string;
+  deliveredLine: string;
+  deliveredHint: string;
+  /** "12 min ago". */
+  updated: string;
+  delayTitle: string;
+  delayBody: string;
+  primaryLabel: string;
+  /** Demo-only: the scene this case ships in (B2-9). */
+  ship?: ShippingScene;
+};
+
+export const SHIPPING_PRESETS = presetsJson as unknown as PresetsFile<ShippingUpdateSettings>;
+
+export function validateShippingUpdate(c: ShippingUpdateSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.nodes) || c.nodes.length < 2) return [{ path: 'nodes', message: 'nodes must list at least two steps.' }];
+  const issues: OnboardingIssue[] = [];
+  if (!['transit', 'delivered', 'delayed'].includes(c.status)) issues.push({ path: 'status', message: 'status is transit, delivered or delayed.' });
+  if (!(Number.isInteger(c.currentIdx) && c.currentIdx >= 0 && c.currentIdx < c.nodes.length)) issues.push({ path: 'currentIdx', message: `currentIdx is a node index from 0 to ${c.nodes.length - 1}.` });
+  if (c.delayedIdx !== undefined && !(Number.isInteger(c.delayedIdx) && c.delayedIdx >= 0 && c.delayedIdx < c.nodes.length)) issues.push({ path: 'delayedIdx', message: 'delayedIdx is a node index.' });
+  return issues;
+}

package/src/components/onboarding/shipping-update/engine.ts

@@ -0,0 +1,43 @@
+import type { BlockStep, StateChipTone } from '../../../ds';
+import type { ShipmentStatus, ShippingScene, ShippingUpdateSettings } from './contract';
+
+/** **The Shipping Update engine** — pure: where the shipment is, and whether it is late. */
+
+export type ShippingUpdateState = { phase: ShipmentStatus; cur: number };
+export type ShippingUpdateSeed = Partial<ShippingUpdateState>;
+
+export function initialShippingUpdate(c: ShippingUpdateSettings, seed: ShippingUpdateSeed = {}): ShippingUpdateState {
+  return { phase: seed.phase ?? c.status, cur: seed.cur ?? c.currentIdx };
+}
+
+export function shippingSeed(c: ShippingUpdateSettings, scene: ShippingScene): ShippingUpdateSeed {
+  if (scene === 'inTransit') return { phase: 'transit', cur: c.currentIdx < c.nodes.length - 1 ? c.currentIdx : 1 };
+  if (scene === 'delivered') return { phase: 'delivered', cur: c.nodes.length - 1 };
+  if (scene === 'delayed') return { phase: 'delayed', cur: c.delayedIdx ?? Math.max(1, c.currentIdx) };
+  return {};
+}
+
+export function shippingView(c: ShippingUpdateSettings, s: ShippingUpdateState) {
+  const delivered = s.phase === 'delivered';
+  const delayed = s.phase === 'delayed';
+  const steps: BlockStep[] = c.nodes.map((n, i) => {
+    const done = delivered || i < s.cur;
+    const current = !delivered && i === s.cur;
+    return {
+      id: `n${i}`,
+      label: n.label,
+      detail: n.date,
+      state: done ? 'done' : current ? (delayed ? 'attention' : 'current') : 'pending',
+      note: current && delayed ? 'Delayed' : undefined,
+    };
+  });
+  const chip: { tone: StateChipTone; label: string; dot: boolean } = delivered ? { tone: 'success', label: c.deliveredLabel, dot: true }
+    : delayed ? { tone: 'attention', label: 'Delayed', dot: true }
+    : { tone: 'neutral', label: c.transitLabel, dot: false };
+  return {
+    delivered, delayed, steps, chip,
+    etaLine: delivered ? c.deliveredLine : c.etaLine,
+    footerHint: delivered ? c.deliveredHint : delayed ? 'We’ll update you within 24 hours' : `Updated ${c.updated}`,
+    scene: (delivered ? 'delivered' : delayed ? 'delayed' : 'inTransit') as ShippingScene,
+  };
+}

package/src/components/onboarding/shipping-update/index.ts

@@ -0,0 +1,6 @@
+export {
+  SHIPPING_IN_FLIGHT, SHIPPING_PRESETS, SHIPPING_SCENES, validateShippingUpdate,
+  type ShipmentNode, type ShipmentStatus, type ShippingScene, type ShippingUpdateSettings,
+} from './contract';
+export { initialShippingUpdate, shippingSeed, shippingView, type ShippingUpdateSeed, type ShippingUpdateState } from './engine';
+export { ShippingUpdate, type ShippingUpdateProps } from './ShippingUpdateView';