@appinternalleads/ui 0.2.0

package/src/components/onboarding/fallback/FallbackView.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useRef, useState } from 'react';
+import { View } from 'react-native';
+import { Box, Icon, Text } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, 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 { Ghost } from '../data-view/parts';
+import { DATA_VIEW_TIMING } from '../data-view/contract';
+import { FALLBACK_PRESETS, validateFallback, type FallbackSettings } from './contract';
+import { flatten, flatToText, noteBody, typeLabel, type Flat, type FallbackSeed } from './engine';
+import { guarded } from '../shared/guard';
+
+export type FallbackProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<FallbackSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  reload?: OnboardingOperation<void>;
+  /** A scene's data (shallow, nested, array, null) — see `fallbackSeed`. */
+  initial?: FallbackSeed;
+  /** The host's clipboard. Omitted on the web, the browser's is used. */
+  onCopy?: (text: string) => void | Promise<void>;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Fallback** — the D9 note, then the data as label/value rows in groups (a `<dl>` per group, a
+ * 150px label column), or the "No data" well. Footer: "Declared as stats · a value is missing" and a
+ * small ghost "Copy as text" that reads "Copied" for 1600ms. Chip: "Simplified view".
+ */
+function FallbackView(props: FallbackProps) {
+  const config = resolveConfig(FALLBACK_PRESETS, props.preset, props.config);
+  const issues = validateFallback(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, onCopy, onScene, testID }: Omit<FallbackProps, 'config'> & { config: FallbackSettings }) {
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const data = initial && 'data' in initial ? initial.data : config.data;
+  const flat = flatten(data);
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+  useSceneReport(pattern.status === 'ready' ? (copied ? 'copied' : 'default') : pattern.status, onScene);
+  const copy = async () => {
+    const text = flatToText(flat);
+    const clip = (globalThis as { navigator?: { clipboard?: { writeText: (t: string) => Promise<void> } } }).navigator?.clipboard;
+    try {
+      if (onCopy) await onCopy(text);
+      else await clip?.writeText(text);
+    } catch {
+      return;
+    }
+    setCopied(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setCopied(false), DATA_VIEW_TIMING.copied);
+  };
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={{ tone: 'neutral', label: 'Simplified view' }}
+      hint={`Declared as ${typeLabel(config.declared)} · ${config.failure}`}
+      actions={<Ghost label={copied ? 'Copied' : 'Copy as text'} onPress={() => { void copy(); }} height={28} />}>
+      <FlatView flat={flat} declared={config.declared} showNote={config.showNote !== false} />
+    </OnboardingCard>
+  );
+}
+
+/** The D9 note — "Showing a simplified view" on the well, with a 15px info glyph. */
+export function SimplifiedNote({ declared }: { declared: string }) {
+  const { colors } = useDs();
+  return (
+    <View {...({ role: 'note' } as object)} style={{ flexDirection: 'row', alignItems: 'flex-start', gap: 10, paddingVertical: 10, paddingHorizontal: 12, borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken }}>
+      <View style={{ marginTop: 1 }}><Icon name="info" size={15} color={colors.textSecondary} /></View>
+      <Box flex={1} gap="s1">
+        <Text style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>Showing a simplified view</Text>
+        <Text style={{ fontSize: 12, color: colors.textSecondary }}>{noteBody(declared)}</Text>
+      </Box>
+    </View>
+  );
+}
+
+/** Flattened data as groups of label/value rows — Fallback's body, and Tabbed's keyvalue panel. */
+export function FlatGroups({ flat }: { flat: Flat }) {
+  const { colors } = useDs();
+  return (
+    <Box style={{ gap: 14 }}>
+      {flat.groups.map((g, gi) => (
+        <Box key={`${g.title}-${gi}`}>
+          {g.title ? <Text numeric role="heading" aria-level={3} style={{ paddingBottom: 2, fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{g.title}</Text> : null}
+          <View role="list">
+            {g.rows.map((r, ri) => (
+              <View key={`${r.label}-${ri}`} role="listitem" style={{ flexDirection: 'row', gap: 12, paddingVertical: 8, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+                <Text style={{ width: 150, maxWidth: '40%', flexShrink: 0, paddingTop: 1, fontSize: 12, color: colors.textSecondary }}>{r.label}</Text>
+                <Text numeric style={{ flex: 1, minWidth: 0, fontSize: 13, color: r.muted ? colors.textSecondary : colors.textPrimary, wordBreak: 'break-word' } as object}>{r.text}</Text>
+              </View>
+            ))}
+          </View>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+export function FlatView({ flat, declared, showNote = true }: { flat: Flat; declared: string; showNote?: boolean }) {
+  const { colors } = useDs();
+  return (
+    <Box style={{ gap: 14 }}>
+      {showNote && !flat.empty ? <SimplifiedNote declared={declared} /> : null}
+      {flat.empty ? (
+        <Box align="center" gap="s1" style={{ paddingVertical: 28, paddingHorizontal: 16, borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken }}>
+          <Text style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>No data</Text>
+          <Text style={{ fontSize: 12, color: colors.textSecondary }}>{`This ${typeLabel(declared)} came back empty.`}</Text>
+        </Box>
+      ) : <FlatGroups flat={flat} />}
+    </Box>
+  );
+}
+
+/** Fallback, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const Fallback = guarded(FallbackView, FALLBACK_PRESETS, 'Fallback');

package/src/components/onboarding/fallback/contract.ts

@@ -0,0 +1,33 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Fallback (batch 4 PRD §6.2) — error recovery, not an output type.** It renders ONLY when data
+ * fails its declared type's schema, and shows it as label/value rows (`keyvalue`) — never as raw
+ * text or JSON. A muted D9 note says so ("Showing a simplified view"; `showNote: false` hides it).
+ */
+export type FallbackSettings = HeaderConfig & LoadCopy & {
+  /** The type the data was declared as — "stats", "table", "comparison". */
+  declared: string;
+  /** Why it failed — "a value is missing". */
+  failure: string;
+  /** Default true. */
+  showNote?: boolean;
+  data: unknown;
+  /** Demo only: the data the shallow / nested / array scenes show. */
+  samples?: { shallow?: unknown; nested?: unknown; array?: unknown };
+  ship?: string;
+};
+
+export const FALLBACK_SCENES = ['default', 'shallow', 'nested', 'array', 'nullData', 'loading', 'empty', 'error'] as const;
+export type FallbackScene = (typeof FALLBACK_SCENES)[number];
+export const FALLBACK_IN_FLIGHT: readonly string[] = [];
+
+export const FALLBACK_PRESETS = presetsJson as unknown as PresetsFile<FallbackSettings>;
+
+export function validateFallback(c: FallbackSettings): OnboardingIssue[] {
+  const issues: OnboardingIssue[] = [];
+  if (!c.declared) issues.push({ path: 'declared', message: 'Say which type the data was declared as.' });
+  if (!c.failure) issues.push({ path: 'failure', message: 'Say why it did not match.' });
+  return issues;
+}

package/src/components/onboarding/fallback/engine.ts

@@ -0,0 +1,117 @@
+import type { FallbackScene, FallbackSettings } from './contract';
+
+/**
+ * **`flatten(data)` — any value as label/value rows (batch 4 PRD §6.2).** Pure, and shared with
+ * Tabbed, whose invalid panel is this Fallback. The rules, verbatim:
+ * - primitives are one row each; keys are humanised (`averageOrder` → "Average order"); `null` or
+ *   `""` is a muted "No data"; booleans are Yes/No; numbers are grouped (`1,284`);
+ * - arrays of primitives are one comma-separated row; arrays of `{label, value}` one row per item;
+ * - objects are a group titled with the key, ONE level deep; record maps (every value an object) are
+ *   one group per key ("Rows · #1042"); top-level arrays of objects one group per item ("Items · 1");
+ * - anything deeper is summarised, muted: "3 fields", "2 items";
+ * - `null`, `{}` or `[]` is the "No data" state.
+ */
+
+export type FlatCell = { label: string; text: string; muted: boolean };
+export type FlatGroup = { title: string; rows: FlatCell[] };
+export type Flat = { empty: boolean; groups: FlatGroup[] };
+
+const prim = (v: unknown) => v === null || v === undefined || typeof v !== 'object';
+
+export function humanise(k: string): string {
+  const s = String(k).replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2');
+  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+
+function fmt(v: unknown): { text: string; muted: boolean } {
+  if (v === null || v === undefined || v === '') return { text: 'No data', muted: true };
+  if (typeof v === 'number') return { text: v.toLocaleString('en-US'), muted: false };
+  if (typeof v === 'boolean') return { text: v ? 'Yes' : 'No', muted: false };
+  return { text: String(v), muted: false };
+}
+
+function summary(v: object): { text: string; muted: boolean } {
+  if (Array.isArray(v)) {
+    if (v.every(prim)) return v.length ? { text: v.map(x => fmt(x).text).join(', '), muted: false } : { text: 'No data', muted: true };
+    return { text: `${v.length} ${v.length === 1 ? 'item' : 'items'}`, muted: true };
+  }
+  const n = Object.keys(v).length;
+  return { text: `${n} ${n === 1 ? 'field' : 'fields'}`, muted: true };
+}
+
+const cell = (label: string, v: unknown): FlatCell => ({ label, ...(prim(v) ? fmt(v) : summary(v as object)) });
+const isLabelled = (x: unknown) => Boolean(x) && !prim(x) && 'label' in (x as object);
+
+function rowsOf(o: unknown): FlatCell[] {
+  if (prim(o)) return [cell('Value', o)];
+  if (Array.isArray(o)) {
+    if (o.length && o.every(isLabelled)) return o.map(x => cell(String((x as { label: unknown }).label), (x as { value: unknown }).value));
+    return o.map((x, i) => cell(`Item ${i + 1}`, x));
+  }
+  return Object.keys(o as object).map(k => cell(humanise(k), (o as Record<string, unknown>)[k]));
+}
+
+function isRecordMap(v: unknown): boolean {
+  if (prim(v) || Array.isArray(v)) return false;
+  const ks = Object.keys(v as object);
+  return ks.length > 0 && ks.every(k => { const x = (v as Record<string, unknown>)[k]; return Boolean(x) && !prim(x) && !Array.isArray(x); });
+}
+
+export function isNoData(d: unknown): boolean {
+  return d === null || d === undefined || (typeof d === 'string' && !d.trim()) || (Array.isArray(d) && !d.length)
+    || (!prim(d) && !Array.isArray(d) && !Object.keys(d as object).length);
+}
+
+export function flatten(d: unknown): Flat {
+  if (isNoData(d)) return { empty: true, groups: [] };
+  if (prim(d)) return { empty: false, groups: [{ title: '', rows: [cell('Value', d)] }] };
+  if (Array.isArray(d)) {
+    if (d.every(prim)) return { empty: false, groups: [{ title: '', rows: [cell('Values', d)] }] };
+    if (d.every(isLabelled)) return { empty: false, groups: [{ title: '', rows: rowsOf(d) }] };
+    return { empty: false, groups: d.map((x, i) => ({ title: `Item ${i + 1}`, rows: rowsOf(x) })) };
+  }
+  const top: FlatCell[] = [];
+  const groups: FlatGroup[] = [];
+  Object.keys(d as object).forEach(k => {
+    const v = (d as Record<string, unknown>)[k];
+    if (prim(v) || (Array.isArray(v) && v.every(prim))) top.push(cell(humanise(k), v));
+    else if (Array.isArray(v)) v.forEach((x, i) => groups.push({ title: `${humanise(k)} · ${i + 1}`, rows: rowsOf(x) }));
+    else if (isRecordMap(v)) Object.keys(v as object).forEach(sk => groups.push({ title: `${humanise(k)} · ${sk}`, rows: rowsOf((v as Record<string, unknown>)[sk]) }));
+    else groups.push({ title: humanise(k), rows: rowsOf(v) });
+  });
+  if (top.length) groups.unshift({ title: '', rows: top });
+  return { empty: false, groups };
+}
+
+/** **Fallback `toText()`** — each group title, then `Label: value` lines, indented 2 spaces under a titled group. */
+export function flatToText(f: Flat): string {
+  const out: string[] = [];
+  f.groups.forEach(g => {
+    if (g.title) out.push(g.title);
+    g.rows.forEach(r => out.push(`${g.title ? '  ' : ''}${r.label}: ${r.text}`));
+  });
+  return out.length ? out.join('\n') : 'No data';
+}
+
+/** How a declared type is named in copy — "This key-value didn’t match…". */
+export const TYPE_LABEL: Record<string, string> = {
+  stats: 'stats', table: 'table', Table: 'table', comparison: 'comparison', keyvalue: 'key-value', sequence: 'sequence',
+  artifact: 'files', collection: 'collection', text: 'text',
+};
+export const typeLabel = (t: string) => TYPE_LABEL[t] ?? t;
+
+export const noteBody = (declared: string) => `This ${typeLabel(declared)} didn’t match its expected format, so its fields are listed instead.`;
+
+/** A demo-board scene → the data it shows. */
+export function fallbackData(c: FallbackSettings, scene: FallbackScene): unknown {
+  if (scene === 'shallow') return c.samples?.shallow;
+  if (scene === 'nested') return c.samples?.nested;
+  if (scene === 'array') return c.samples?.array;
+  if (scene === 'nullData') return null;
+  return c.data;
+}
+
+export type FallbackSeed = { data?: unknown };
+export function fallbackSeed(c: FallbackSettings, scene: FallbackScene): FallbackSeed {
+  return scene === 'default' ? {} : { data: fallbackData(c, scene) };
+}

package/src/components/onboarding/fallback/index.ts

@@ -0,0 +1,6 @@
+export { FALLBACK_PRESETS, FALLBACK_SCENES, FALLBACK_IN_FLIGHT, validateFallback, type FallbackSettings, type FallbackScene } from './contract';
+export {
+  fallbackData, fallbackSeed, flatten, flatToText, humanise, isNoData, noteBody, typeLabel, TYPE_LABEL,
+  type Flat, type FlatCell, type FlatGroup, type FallbackSeed,
+} from './engine';
+export { Fallback, FlatGroups, FlatView, SimplifiedNote, type FallbackProps } from './FallbackView';

package/src/components/onboarding/fallback/presets.json

@@ -0,0 +1,136 @@
+{
+  "component": "fallback",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "data",
+    "icon": "layers",
+    "title": "Revenue this month",
+    "subtitle": "Stats output",
+    "declared": "stats",
+    "failure": "a value is missing",
+    "showNote": true,
+    "data": {
+      "revenue": "$48,200",
+      "orders": 1284,
+      "averageOrder": null,
+      "period": "September 2026"
+    },
+    "samples": {
+      "shallow": {
+        "status": "Active",
+        "owner": "Sam Ortiz",
+        "seats": 12,
+        "renews": "1 Oct 2026"
+      },
+      "nested": {
+        "customer": {
+          "name": "Ana Ruiz",
+          "company": "Harbor Legal",
+          "address": {
+            "city": "Leeds",
+            "postcode": "LS1 4AP",
+            "country": "UK"
+          }
+        },
+        "plan": "Team",
+        "seats": 12
+      },
+      "array": [
+        "SSO",
+        "Audit log",
+        "Priority support",
+        "Custom roles"
+      ]
+    },
+    "emptyTitle": "Nothing to show",
+    "emptyBody": "This step didn’t return any output.",
+    "emptyCta": "Run again"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "type": "data",
+      "icon": "cart",
+      "title": "Orders this week",
+      "subtitle": "Table output",
+      "declared": "table",
+      "failure": "rows isn’t a list",
+      "data": {
+        "columns": [
+          "Order",
+          "Customer",
+          "Total"
+        ],
+        "rows": {
+          "#1042": {
+            "customer": "Ana Ruiz",
+            "total": "$86.00",
+            "items": 2
+          },
+          "#1043": {
+            "customer": "Ken Ito",
+            "total": "$42.00",
+            "items": 1
+          },
+          "#1044": {
+            "customer": "Mia Lopez",
+            "total": "$128.50",
+            "items": 3,
+            "shipping": {
+              "carrier": "DHL",
+              "eta": "Thu 26 Sep",
+              "address": {
+                "city": "Leeds",
+                "postcode": "LS1 4AP"
+              }
+            }
+          }
+        }
+      }
+    },
+    "case3": {
+      "type": "action",
+      "icon": "card",
+      "title": "Compare plans",
+      "subtitle": "Comparison output",
+      "declared": "comparison",
+      "failure": "only 1 item",
+      "data": {
+        "items": [
+          {
+            "name": "Team",
+            "price": "$12 / user / month",
+            "seats": "Unlimited",
+            "features": [
+              "Shared projects",
+              "Priority support",
+              "SSO"
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · Stats",
+      "title": "Revenue stats",
+      "scenario": "A stats output arrives with one value missing, so it’s shown as rows and the missing value reads “No data”."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · Table",
+      "title": "Order table",
+      "scenario": "“rows” came back as an object keyed by order, not a list. Each order becomes its own group of rows."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Comparison",
+      "title": "Plan comparison",
+      "scenario": "A comparison needs two or more items and got one. Its fields are listed, with features as a comma list."
+    }
+  }
+}

package/src/components/onboarding/file-shared/FileSharedView.tsx

@@ -0,0 +1,150 @@
+import { useEffect, useRef } from 'react';
+import { Box, Icon, Text } from '../../../core';
+import { Button, IconButton } from '../../../ds';
+import { useDs, type DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, type OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { Hidden, HueTile, PlainChip, Slot, Spinner, StatusMark } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport, useSeededReducer } from '../shared/runtime';
+import { useOperationRunner } from '../../../runtime/operations';
+import { FILE_SHARED_PRESETS, validateFileShared, type FileSharedSettings, type SharedFile } from './contract';
+import {
+  fileSharedSeed, fileSharedView, initialFileShared, reduceFileShared,
+  type FileRow, type FileSharedSeed,
+} from './engine';
+import { guarded } from '../shared/guard';
+
+export type FileSharedOperations = { download: OnboardingOperation<{ index: number; name: string; attempt: number }> };
+
+export type FileSharedProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<FileSharedSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  operations?: FileSharedOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: FileSharedSeed;
+  onOpen?: (file: SharedFile) => void;
+  onDownloaded?: (file: SharedFile) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **File Shared** — one row per file: a sky tile, the name (700 and an ink dot while new), a plain
+ * type chip, who · when · size, a ghost Open (clears "new"), and a download slot whose four layers
+ * cross-fade (M8): the icon button, a named spinner, a mint check, a small Retry with a bold apricot
+ * line under the meta. With `result="error"` the file at `failIndex` fails once; Retry succeeds.
+ */
+function FileSharedView(props: FileSharedProps) {
+  const config = resolveConfig(FILE_SHARED_PRESETS, props.preset, props.config);
+  const issues = validateFileShared(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, onOpen, onDownloaded, onScene, testID,
+}: Omit<FileSharedProps, 'config'> & { config: FileSharedSettings }) {
+  const runner = useOperationRunner();
+  const started = useRef(new Set<string>());
+  const key = JSON.stringify([config, initial ?? null]);
+  const [state, send, ref] = useSeededReducer(
+    reduceFileShared,
+    () => initialFileShared(config, initial ?? (config.ship ? fileSharedSeed(config, config.ship) : {})),
+    key,
+    () => { started.current.forEach(id => runner.cancel(id)); started.current.clear(); },
+  );
+  const pattern = usePatternStatus(status ?? (config.ship === 'empty' || !config.files.length ? 'empty' : 'ready'), reload);
+  const v = fileSharedView(state);
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const download = useDefaultOperation(operations?.download, ONBOARDING_TIMING.download, r => result === 'error' && r.index === config.failIndex && r.attempt === 0);
+  const run = (row: FileRow) => {
+    const index = ref.current.rows.findIndex(r => r.id === row.id);
+    const file = config.files[index]!;
+    started.current.add(`download-${row.id}`);
+    runOutcome(runner, `download-${row.id}`, download, { index, name: file.name, attempt: row.attempts }, {
+      ok: () => { send({ type: 'downloaded', id: row.id }); onDownloaded?.(file); },
+      fail: () => send({ type: 'failed', id: row.id }),
+    });
+  };
+  useEffect(() => { ref.current.rows.forEach(r => { if (r.phase === 'busy') run(r); }); }, [key]);
+  const start = (row: FileRow) => {
+    const cur = ref.current.rows.find(r => r.id === row.id);
+    if (!cur || cur.phase === 'busy') return;
+    send({ type: 'download', id: row.id });
+    run(cur);
+  };
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}>
+      <Box role="list" aria-label={config.title}>
+        {state.rows.map((row, i) => (
+          <FileRowView
+            key={row.id}
+            row={row}
+            file={config.files[i]!}
+            last={i === state.rows.length - 1}
+            type={config.type}
+            onOpen={() => { send({ type: 'open', id: row.id }); onOpen?.(config.files[i]!); }}
+            onDownload={() => start(row)}
+          />
+        ))}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+function FileRowView({ row, file, last, onOpen, onDownload }: {
+  row: FileRow; file: SharedFile; last: boolean; type: FileSharedSettings['type']; onOpen: () => void; onDownload: () => void;
+}) {
+  const { colors, density } = useDs();
+  const failed = row.phase === 'failed';
+  return (
+    <Box
+      role="listitem"
+      row
+      align="center"
+      gap="s3"
+      style={{ minHeight: density.rowH, paddingVertical: 10, borderBottomWidth: last ? 0 : 1, borderBottomColor: colors.hairline }}>
+      <HueTile icon={iconFor(file.icon || 'file')} type="file" />
+      <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+        <Box row align="center" gap="s2" style={{ minWidth: 0 }}>
+          <Text variant="caption" color="textPrimary" numberOfLines={1} style={{ fontSize: 13, fontWeight: row.isNew ? '700' : '600', flexShrink: 1 }}>{file.name}</Text>
+          <PlainChip height={20}>{file.type}</PlainChip>
+          {row.isNew ? <><Box width={8} height={8} radius="pill" aria-hidden style={{ backgroundColor: colors.textPrimary, flexShrink: 0 }} /><Hidden>New</Hidden></> : null}
+        </Box>
+        <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 12 }}>{`${file.sharedBy} · ${file.when} · ${file.size}`}</Text>
+        {failed ? (
+          <Box row align="center" gap="s1" role="alert">
+            <Icon name="alert" size={13} color={colors.status.needsUser} />
+            <Text variant="caption" style={{ fontSize: 12, fontWeight: '700', color: colors.status.needsUser, flexShrink: 1 }}>Download failed · check your connection</Text>
+          </Box>
+        ) : null}
+      </Box>
+      <Button variant="secondary" size="small" aria-label={`Open ${file.name}`} onPress={onOpen} style={{ minHeight: density.controlH }}>Open</Button>
+      <Box style={{ minWidth: 72, alignItems: 'flex-end' }}>
+        <Slot slotKey={row.phase}>
+          {row.phase === 'idle' ? <IconButton icon="download" label={`Download ${file.name}`} onPress={onDownload} /> : null}
+          {row.phase === 'busy' ? <Box width={32} height={32} align="center" justify="center"><Spinner label={`Downloading ${file.name}`} /></Box> : null}
+          {row.phase === 'done' ? <Box width={32} height={32} align="center" justify="center" role="img" aria-label={`Downloaded ${file.name}`}><StatusMark tone="mint" /></Box> : null}
+          {failed ? <Button variant="secondary" size="xsmall" aria-label={`Retry download of ${file.name}`} onPress={onDownload}>Retry</Button> : null}
+        </Slot>
+      </Box>
+    </Box>
+  );
+}
+
+/** FileShared, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const FileShared = guarded(FileSharedView, FILE_SHARED_PRESETS, 'FileShared');

package/src/components/onboarding/file-shared/contract.ts

@@ -0,0 +1,29 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/** **File Shared (batch 3 §3.3)** — files other people shared, with Open and Download. */
+
+export type SharedFile = { name: string; type: string; sharedBy: string; when: string; size: string; isNew: boolean; icon: string };
+
+export const FILE_SHARED_SCENES = ['default', 'newItem', 'downloading', 'downloaded', 'failed', 'loading', 'empty', 'error'] as const;
+export type FileSharedScene = (typeof FILE_SHARED_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const FILE_SHARED_IN_FLIGHT: readonly string[] = ['downloading'];
+
+export type FileSharedSettings = HeaderConfig & LoadCopy & {
+  files: SharedFile[];
+  /** With `result="error"`, the file at this index fails its first download; Retry succeeds. */
+  failIndex: number;
+  /** Demo-only: the scene this case ships in (B2-9) — `empty` ships the empty state. */
+  ship?: FileSharedScene;
+};
+
+export const FILE_SHARED_PRESETS = presetsJson as unknown as PresetsFile<FileSharedSettings>;
+
+export function validateFileShared(c: FileSharedSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.files)) return [{ path: 'files', message: 'files must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  c.files.forEach((f, i) => { if (!f || !f.name) issues.push({ path: `files[${i}].name`, message: 'Every file needs a name.' }); });
+  if (!(Number.isInteger(c.failIndex) && c.failIndex >= 0)) issues.push({ path: 'failIndex', message: 'failIndex is a whole number from 0.' });
+  return issues;
+}

package/src/components/onboarding/file-shared/engine.ts

@@ -0,0 +1,47 @@
+import type { StateChipTone } from '../../../ds';
+import type { FileSharedScene, FileSharedSettings } from './contract';
+
+/** **The File Shared engine** — pure: each file's new flag and its download. */
+
+export type DownloadPhase = 'idle' | 'busy' | 'done' | 'failed';
+export type FileRow = { id: string; phase: DownloadPhase; isNew: boolean; attempts: number };
+export type FileSharedState = { rows: FileRow[] };
+export type FileSharedSeed = Partial<FileSharedState>;
+export type FileSharedAction =
+  | { type: 'open'; id: string } | { type: 'download'; id: string } | { type: 'downloaded'; id: string } | { type: 'failed'; id: string };
+
+export function initialFileShared(c: FileSharedSettings, seed: FileSharedSeed = {}): FileSharedState {
+  return { rows: seed.rows ?? c.files.map((f, i) => ({ id: `f${i}`, phase: 'idle', isNew: Boolean(f.isNew), attempts: 0 })) };
+}
+
+export function fileSharedSeed(c: FileSharedSettings, scene: FileSharedScene): FileSharedSeed {
+  const rows = initialFileShared(c).rows;
+  if (!rows.length) return {};
+  const k = Math.min(c.failIndex, rows.length - 1);
+  if (scene === 'newItem') return { rows: rows.map((r, i) => (i === 0 ? { ...r, isNew: true } : r)) };
+  if (scene === 'downloading') return { rows: rows.map((r, i) => (i === 0 ? { ...r, phase: 'busy' } : r)) };
+  if (scene === 'downloaded') return { rows: rows.map((r, i) => (i === 0 ? { ...r, phase: 'done', attempts: 1 } : r)) };
+  if (scene === 'failed') return { rows: rows.map((r, i) => (i === k ? { ...r, phase: 'failed', attempts: 1 } : r)) };
+  return {};
+}
+
+const patch = (s: FileSharedState, id: string, f: (r: FileRow) => FileRow): FileSharedState => ({ rows: s.rows.map(r => (r.id === id ? f(r) : r)) });
+
+export function reduceFileShared(s: FileSharedState, a: FileSharedAction): FileSharedState {
+  switch (a.type) {
+    case 'open': return patch(s, a.id, r => ({ ...r, isNew: false }));
+    case 'download': return patch(s, a.id, r => (r.phase === 'busy' ? r : { ...r, phase: 'busy' }));
+    case 'downloaded': return patch(s, a.id, r => (r.phase === 'busy' ? { ...r, phase: 'done', attempts: r.attempts + 1 } : r));
+    case 'failed': return patch(s, a.id, r => (r.phase === 'busy' ? { ...r, phase: 'failed', attempts: r.attempts + 1 } : r));
+  }
+}
+
+export function fileSharedView(s: FileSharedState) {
+  const fresh = s.rows.filter(r => r.isNew).length;
+  const bad = s.rows.some(r => r.phase === 'failed');
+  const chip: { tone: StateChipTone; label: string } = bad ? { tone: 'attention', label: 'Download failed' }
+    : fresh ? { tone: 'neutral', label: `${fresh} new` }
+    : { tone: 'neutral', label: `${s.rows.length} ${s.rows.length === 1 ? 'file' : 'files'}` };
+  const scene = bad ? 'failed' : s.rows.some(r => r.phase === 'busy') ? 'downloading' : s.rows.some(r => r.phase === 'done') ? 'downloaded' : fresh ? 'newItem' : 'default';
+  return { chip, scene };
+}