@appinternalleads/ui 0.2.0

package/src/components/onboarding/data-view/contract.ts

@@ -0,0 +1,128 @@
+import type { HeaderConfig, LoadCopy } from '../shared/contract';
+
+/**
+ * **The data-view contract Table and Grid share (batch 4 PRD §4, with C14's changes).**
+ *
+ * Source: `design_handoff_data_components_batch4` README "Shared data-view contract". Table and Grid
+ * are two views of ONE behaviour: the same columns, the same server-side sort and cursor paging, the
+ * same selection and bulk actions. Grid's record card is also Table's stacked view below 640px.
+ *
+ * Rows come from the server. The component never generates, sorts or pages data itself — it asks
+ * the host's `page` operation for the next page under the current sort. The demo boards' rows come
+ * from `demoSource.ts`, a deterministic stand-in for that server (the prototype's `gen`).
+ */
+
+/** The column types (renderer registry, §1.9): nine seed types, plus batch 5's `bar` and `score`. An unknown type renders as `text`. */
+export const COLUMN_TYPES = ['text', 'number', 'currency', 'date', 'status', 'avatar', 'avatars', 'link', 'progress', 'bar', 'score'] as const;
+export type ColumnType = (typeof COLUMN_TYPES)[number];
+
+export type StatusTone = 'mint' | 'apricot' | 'plain';
+
+/**
+ * How the demo server generates a column — the prototype's `gen`, kept ONLY so the demo source can
+ * reproduce the prototype's rows. The views never read it; a real server supplies the rows.
+ */
+export type DemoGen = {
+  seq?: string; start?: number; hex?: boolean; pool?: string[]; num?: number;
+  days?: [number, number]; hours?: [number, number]; min?: number; max?: number; dec?: number;
+  /** Batch 5: `list` in order (row i takes `list[i % n]`); `desc` from `[hi, lo]`, geometric over the rows. */
+  list?: string[]; desc?: [number, number];
+} | null;
+
+export type ColumnDef = {
+  id: string;
+  label: string;
+  /** Unknown → `text`. */
+  type: ColumnType | string;
+  /** Default true. */
+  sortable?: boolean;
+  /** px, web only. Default 140. */
+  width?: number;
+  /** number, currency, date and progress default to `end`. */
+  align?: 'start' | 'end';
+  /** status only. */
+  tones?: Record<string, StatusTone>;
+  currency?: string;
+  suffix?: string;
+  href?: string;
+  external?: boolean;
+  withTime?: boolean;
+  /** `false`: left out of the stacked card (Grid, and Table below 640px). */
+  card?: false;
+  /** `bar`: scaled to the largest loaded value, re-scaling as pages raise it. */
+  scale?: 'loaded-max';
+  /** `score`: [good, fair] — at or above good is mint, at or above fair apricot, below muted. Default [85, 70]. */
+  thresholds?: [number, number];
+  /** Demo only — see `DemoGen`. */
+  gen?: DemoGen;
+};
+
+export type SortKey = { id: string; dir: 'asc' | 'desc' };
+export type DataRow = { id: string; [col: string]: unknown };
+
+/** A person C14 can pick. `meta` is their role, never an email (decided 2026-09-25). */
+export type Person = { id: string; name: string; avatarUrl?: string; meta?: string };
+
+export type BulkAction = 'export' | 'delete' | 'assign';
+
+/** The config both views take — the prototypes' `BASE` keys, verbatim. */
+export type DataViewSettings = HeaderConfig & LoadCopy & {
+  columns: ColumnDef[];
+  /** Demo row count (60 or more). A real host's first page carries `totalCount`. */
+  totalCount: number;
+  pageSize: number;
+  /** The initial sort. Mobile shows `sort[0]` plus a "+1 sort" chip. */
+  sort: SortKey[];
+  /** People C14 searches, by name — the demo's directory. */
+  assignees: string[];
+  /** C14 `meta`, cycled over `assignees`. */
+  assigneeRoles?: string[];
+  /** The `avatars` column Assign writes to. Null: Assign changes no cell. */
+  assignCol: string | null;
+  noun: string;
+  nouns: string;
+  /** Demo only: how many rows the "selected" scenes select. */
+  selCount: number;
+  idPrefix: string;
+  /** Demo only: the sort the `sorting` scene is waiting for. */
+  sortDemo?: SortKey[];
+  ship?: string;
+  /** Default true. `false`: no checkbox column, card checkboxes or select-all — so no bulk bar. */
+  selectable?: boolean;
+  /** M15 data reveal: rows stagger in (every page), bars fill and numbers count. */
+  m15?: boolean;
+};
+
+export const DATA_VIEW_SCENES = [
+  'default', 'loading', 'loadingMore', 'sorting', 'errorMore', 'end', 'someSelected', 'allSelected', 'notShown',
+  'deleteConfirm', 'deleting', 'deleteFailed', 'assignOpen', 'exportOpen', 'mobile', 'empty', 'error',
+] as const;
+export type DataViewScene = (typeof DATA_VIEW_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const DATA_VIEW_IN_FLIGHT: readonly string[] = ['loadingMore', 'sorting', 'deleting'];
+/**
+ * Scenes that open a layer. None of them moves focus when restored (only a person's click does), so
+ * a board may ship in one — Table case 5 ships with its delete confirm open.
+ */
+export const DATA_VIEW_LAYER_SCENES: readonly string[] = [];
+
+/** The handoff's demo timings (README "Demo simulation"). */
+export const DATA_VIEW_TIMING = {
+  sort: 800,
+  page: 800,
+  delete: 900,
+  /** C14: debounce, then the request. */
+  searchDebounce: 250,
+  search: 500,
+  /** C14: next page of results. */
+  searchMore: 600,
+  /** C14: suggestions. */
+  suggest: 500,
+  apply: 900,
+  /** Export modal closes this long after Export Format reports `exported`. */
+  exportClose: 700,
+  /** M14 removal. */
+  leave: 240,
+  copied: 1600,
+  toast: 6000,
+} as const;

package/src/components/onboarding/data-view/demoSource.ts

@@ -0,0 +1,201 @@
+import { abortableDelay } from '../../../runtime/operations';
+import type { OnboardingOutcome } from '../shared/mock';
+import { DATA_VIEW_TIMING, type BulkAction, type DataRow, type DataViewSettings, type Person, type SortKey } from './contract';
+
+/**
+ * **The demo server** — a deterministic stand-in for the host's data service, so the case-study
+ * boards have rows to show. The handoff says of `gen`: *"Don't port it. Your server supplies the
+ * rows."* The views don't port it: nothing in a view generates, sorts or pages. This file IS the
+ * server, for demos and tests only. It reproduces the prototype's rows exactly (same generator, same
+ * clock) and answers the same four calls a real host implements: `page`, `bulk`, `searchPeople`,
+ * `suggestPeople`.
+ *
+ * No `Math.random`, no `Date.now`: the demo clock is fixed, and the "random" numbers are the
+ * prototype's sine hash.
+ */
+
+/** The prototypes' clock — 25 Sep 2026, 12:00 UTC. Relative dates on the boards read from here. */
+export const DEMO_NOW = Date.UTC(2026, 8, 25, 12, 0);
+
+function rnd(i: number, k: number): number {
+  const x = Math.sin((i + 1) * 12.9898 + (k + 1) * 78.233) * 43758.5453;
+  return x - Math.floor(x);
+}
+
+/** The prototype's `genRows`, verbatim in behaviour. */
+export function generateRows(c: Pick<DataViewSettings, 'columns' | 'totalCount' | 'idPrefix'>): DataRow[] {
+  const out: DataRow[] = [];
+  for (let i = 0; i < c.totalCount; i++) {
+    const r: DataRow = { id: c.idPrefix + i };
+    c.columns.forEach((col, k) => {
+      const g = col.gen ?? {};
+      const u = rnd(i, k);
+      let v: unknown;
+      if (g.seq != null) v = g.seq + ((g.start ?? 0) + i);
+      else if (g.list) v = g.list[i % g.list.length];
+      else if (g.desc) v = Math.round(g.desc[0] * Math.pow(g.desc[1] / g.desc[0], i / Math.max(1, c.totalCount - 1)));
+      else if (g.hex) v = (Math.floor(rnd(i, 99) * 0xfffffff) + 0x1000000).toString(16).slice(0, 7);
+      else if (col.type === 'avatars' && g.pool) {
+        const n = Math.floor(u * 3);
+        const names: string[] = [];
+        for (let q = 0; q < n; q++) {
+          const nm = g.pool[Math.floor(rnd(i, k + 11 + q * 2) * g.pool.length)]!;
+          if (!names.includes(nm)) names.push(nm);
+        }
+        v = names;
+      } else if (g.pool) {
+        v = g.pool[Math.floor(u * g.pool.length)];
+        if (g.num) v = `${String(v)} #${g.num + i}`;
+      } else if (g.days) {
+        let t = DEMO_NOW + (g.days[0] + u * (g.days[1] - g.days[0])) * 864e5;
+        t = Math.round(t / 9e5) * 9e5;
+        if (g.hours) {
+          const dt = new Date(t);
+          const h = g.hours[0] + Math.floor(rnd(i, k + 7) * (g.hours[1] - g.hours[0]));
+          dt.setUTCHours(h, [0, 15, 30, 45][Math.floor(rnd(i, k + 3) * 4)]!, 0, 0);
+          t = dt.getTime();
+        }
+        v = t;
+      } else if (g.min != null && g.max != null) {
+        const p = Math.pow(10, g.dec ?? 0);
+        v = Math.round((g.min + u * (g.max - g.min)) * p) / p;
+      } else if (col.type === 'status') {
+        const ks = Object.keys(col.tones ?? {});
+        v = ks[Math.floor(u * ks.length)];
+      }
+      r[col.id] = v;
+    });
+    out.push(r);
+  }
+  return out;
+}
+
+/** Multi-key sort, as the prototype's server does it: numbers by value, everything else natural. */
+export function sortRows(rows: DataRow[], sort: SortKey[]): DataRow[] {
+  return rows.slice().sort((a, b) => {
+    for (const k of sort) {
+      const x = a[k.id];
+      const y = b[k.id];
+      const d = typeof x === 'number' && typeof y === 'number'
+        ? x - y
+        : String(x ?? '').localeCompare(String(y ?? ''), 'en', { numeric: true });
+      if (d) return k.dir === 'desc' ? -d : d;
+    }
+    return 0;
+  });
+}
+
+/** C14's directory for a data view: `assignees` by name, `assigneeRoles` cycled as `meta`. */
+export function peopleOf(c: Pick<DataViewSettings, 'assignees' | 'assigneeRoles'>): Person[] {
+  const roles = c.assigneeRoles?.length ? c.assigneeRoles : [''];
+  return (c.assignees ?? []).map((name, i) => ({ id: `a${i}`, name, meta: roles[i % roles.length] || undefined }));
+}
+
+/** Substring of the name or the meta, ignoring case — the C14 matching rule. */
+export function matchPeople(people: Person[], q: string): Person[] {
+  const s = q.trim().toLowerCase();
+  if (!s) return [];
+  return people.filter(p => p.name.toLowerCase().includes(s) || (p.meta ?? '').toLowerCase().includes(s));
+}
+
+export type PageRequest = { sort: SortKey[]; cursor: string | null; pageSize: number };
+export type PageResult = { ok: true; rows: DataRow[]; cursor: string | null; totalCount: number } | { ok: false; message?: string };
+export type PageOperation = (req: PageRequest, ctx: { signal: AbortSignal }) => Promise<PageResult>;
+export type BulkRequest = { action: BulkAction; ids: string[]; people?: Person[] };
+export type BulkOperation = (req: BulkRequest, ctx: { signal: AbortSignal }) => Promise<OnboardingOutcome>;
+export type SearchRequest = { q: string; cursor?: string | null };
+export type SearchResult = { ok: true; items: Person[]; cursor: string | null; total: number } | { ok: false; message?: string };
+export type SearchOperation = (req: SearchRequest, ctx: { signal: AbortSignal }) => Promise<SearchResult>;
+export type SuggestResult = { ok: true; items: Person[] } | { ok: false; message?: string };
+export type SuggestOperation = (req: void, ctx: { signal: AbortSignal }) => Promise<SuggestResult>;
+
+/**
+ * **One demo server per board.** It keeps what the board changed — deleted rows, reassigned cells —
+ * so the next page and the next sort reflect them, as a real server would. `result: 'error'` fails
+ * the first page load that has a cursor, the first delete, the first search and the first apply,
+ * once each; the retry succeeds (the README's demo contract).
+ */
+export function createDemoServer(c: DataViewSettings, opts: { result?: 'success' | 'error'; people?: Person[]; suggestions?: string[] } = {}) {
+  const fail = opts.result === 'error';
+  let rows = generateRows(c);
+  const tried = { more: false, delete: false, search: false, apply: false };
+  const people = opts.people ?? peopleOf(c);
+
+  const page: PageOperation = async (req, { signal }) => {
+    await abortableDelay(req.cursor === null ? DATA_VIEW_TIMING.sort : DATA_VIEW_TIMING.page, signal);
+    if (req.cursor !== null && fail && !tried.more) { tried.more = true; return { ok: false }; }
+    const from = req.cursor === null ? 0 : Number(req.cursor);
+    const sorted = sortRows(rows, req.sort);
+    const slice = sorted.slice(from, from + req.pageSize);
+    const next = from + slice.length;
+    return { ok: true, rows: slice, cursor: next < sorted.length ? String(next) : null, totalCount: sorted.length };
+  };
+
+  const bulk: BulkOperation = async (req, { signal }) => {
+    if (req.action === 'delete') {
+      await abortableDelay(DATA_VIEW_TIMING.delete, signal);
+      if (fail && !tried.delete) { tried.delete = true; return { ok: false }; }
+      rows = rows.filter(r => !req.ids.includes(r.id));
+    }
+    if (req.action === 'assign' && c.assignCol) {
+      const names = (req.people ?? []).map(p => p.name);
+      rows = rows.map(r => (req.ids.includes(r.id) ? { ...r, [c.assignCol!]: names } : r));
+    }
+    return { ok: true };
+  };
+
+  const searchPeople: SearchOperation = async (req, { signal }) => {
+    await abortableDelay(req.cursor ? DATA_VIEW_TIMING.searchMore : DATA_VIEW_TIMING.search, signal);
+    if (!req.cursor && fail && !tried.search) { tried.search = true; return { ok: false }; }
+    const m = matchPeople(people, req.q);
+    const from = req.cursor ? Number(req.cursor) : 0;
+    const items = m.slice(from, from + 20);
+    const next = from + items.length;
+    return { ok: true, items, cursor: next < m.length ? String(next) : null, total: m.length };
+  };
+
+  const suggestPeople: SuggestOperation = async (_req, { signal }) => {
+    await abortableDelay(DATA_VIEW_TIMING.suggest, signal);
+    const ids = opts.suggestions ?? people.slice(0, 5).map(p => p.id);
+    return { ok: true, items: ids.map(id => people.find(p => p.id === id)).filter((p): p is Person => Boolean(p)) };
+  };
+
+  const apply = async (_req: { people: Person[] }, { signal }: { signal: AbortSignal }): Promise<OnboardingOutcome> => {
+    await abortableDelay(DATA_VIEW_TIMING.apply, signal);
+    if (fail && !tried.apply) { tried.apply = true; return { ok: false }; }
+    return { ok: true };
+  };
+
+  return {
+    page, bulk, searchPeople, suggestPeople, apply, people,
+    /** The rows as they stand — a seed reads the first page and the ids beyond it synchronously. */
+    peek: (sort: SortKey[]) => sortRows(rows, sort),
+  };
+}
+
+export type DemoServer = ReturnType<typeof createDemoServer>;
+
+/**
+ * **Rows the host already has, served like a server would** — a sheet read into Table or Grid. The
+ * same `page` (sort, then slice at the cursor) and `bulk` (delete, assign) as the demo server, over
+ * the given rows instead of generated ones, with no latency.
+ */
+export function createRowServer(initial: DataRow[], opts: { assignCol?: string | null } = {}) {
+  let rows = initial.slice();
+  const page: PageOperation = async req => {
+    const from = req.cursor === null ? 0 : Number(req.cursor);
+    const sorted = sortRows(rows, req.sort);
+    const slice = sorted.slice(from, from + req.pageSize);
+    const next = from + slice.length;
+    return { ok: true, rows: slice, cursor: next < sorted.length ? String(next) : null, totalCount: sorted.length };
+  };
+  const bulk: BulkOperation = async req => {
+    if (req.action === 'delete') rows = rows.filter(r => !req.ids.includes(r.id));
+    if (req.action === 'assign' && opts.assignCol) {
+      const names = (req.people ?? []).map(p => p.name);
+      rows = rows.map(r => (req.ids.includes(r.id) ? { ...r, [opts.assignCol!]: names } : r));
+    }
+    return { ok: true };
+  };
+  return { page, bulk };
+}

package/src/components/onboarding/data-view/engine.ts

@@ -0,0 +1,232 @@
+import type { DataRow, DataViewScene, DataViewSettings, Person, SortKey } from './contract';
+import { countNoun } from './registry';
+import { generateRows, sortRows } from './demoSource';
+
+/**
+ * **The data-view engine** — pure: what is loaded, the sort (applied and requested), the selection,
+ * the bulk lifecycle, the overlays and the toast. Table and Grid run the same engine; only the
+ * drawing differs. Every async step is an action the runtime sends when the host's operation
+ * settles, so the engine never waits and never guesses.
+ */
+
+export type Overlay = null | 'delete' | 'sort' | 'export';
+export type ToastTone = 'neutral' | 'mint' | 'apricot';
+export type DataToast = { id: number; tone: ToastTone; text: string; retry?: 'delete' };
+
+export type DataViewState = {
+  /** Loaded rows, in the applied sort. */
+  rows: DataRow[];
+  /** Next page, or null at the end. */
+  cursor: string | null;
+  total: number;
+  sort: SortKey[];
+  /** A sort requested and not yet applied — the body dims until its first page lands. */
+  pend: SortKey[] | null;
+  /** Row ids — may include rows that are not loaded. */
+  sel: string[];
+  /** Rows fading out (M14) before they are removed. */
+  leaving: string[];
+  /** Optimistic cell overrides after Assign, by row id. */
+  over: Record<string, Record<string, unknown>>;
+  overlay: Overlay;
+  bulk: 'idle' | 'deleting';
+  more: 'idle' | 'loading' | 'error';
+  toast: DataToast | null;
+  copied: boolean;
+  /** The index of the first row appended by the last page — they fade in (opacity only). */
+  fresh: number | null;
+  /** C14 opens in the bulk bar (the `assignOpen` scene); bumped to reset the picker after Assign. */
+  assign: { open: boolean; nonce: number };
+  /** The `mobile` scene: stacked cards at any width. */
+  mobile: boolean;
+};
+
+export type DataViewSeed = Partial<DataViewState>;
+
+export type DataViewAction =
+  | { type: 'sortRequest'; sort: SortKey[] }
+  | { type: 'sorted'; sort: SortKey[]; rows: DataRow[]; cursor: string | null; total: number }
+  | { type: 'sortFailed' }
+  | { type: 'moreStart' }
+  | { type: 'moreDone'; rows: DataRow[]; cursor: string | null; total: number; fresh: boolean }
+  | { type: 'moreFailed' }
+  | { type: 'freshDone' }
+  | { type: 'toggle'; id: string }
+  | { type: 'toggleAll'; ids: string[] }
+  | { type: 'clearSel' }
+  | { type: 'overlay'; overlay: Overlay }
+  | { type: 'deleteStart' }
+  | { type: 'deleteDone'; ids: string[]; animate: boolean; toast: DataToast }
+  | { type: 'deleteGone'; ids: string[] }
+  | { type: 'deleteFailed'; toast: DataToast }
+  | { type: 'assigned'; ids: string[]; col: string | null; names: string[]; toast: DataToast }
+  | { type: 'toast'; toast: DataToast | null }
+  | { type: 'dropToast'; id: number }
+  | { type: 'copied'; on: boolean };
+
+export function initialDataView(
+  c: DataViewSettings,
+  page: { rows: DataRow[]; cursor: string | null; total: number },
+  seed: DataViewSeed = {},
+): DataViewState {
+  return {
+    rows: page.rows, cursor: page.cursor, total: page.total, sort: c.sort.slice(), pend: null, sel: [], leaving: [], over: {},
+    overlay: null, bulk: 'idle', more: 'idle', toast: null, copied: false, fresh: null, assign: { open: false, nonce: 0 }, mobile: false,
+    ...seed,
+  };
+}
+
+/** The first page of the demo server, synchronously — what a board shows before anything is clicked. */
+export function demoFirstPage(c: DataViewSettings, sort: SortKey[] = c.sort, loaded = c.pageSize) {
+  const all = sortRows(generateRows(c), sort);
+  const rows = all.slice(0, loaded);
+  return { rows, cursor: rows.length < all.length ? String(rows.length) : null, total: all.length, all };
+}
+
+/**
+ * **A demo-board scene as a seed** — the prototype's `sceneState`, on the demo server's rows.
+ * `loading` / `empty` / `error` are pattern status (see `sceneProps`), not seeds.
+ */
+export function dataViewSeed(c: DataViewSettings, scene: DataViewScene): DataViewSeed {
+  const first = demoFirstPage(c);
+  const page: DataViewSeed = { rows: first.rows, cursor: first.cursor, total: first.total };
+  const ids = first.all.map(r => r.id);
+  const n = c.selCount || 5;
+  const pick = (k: number) => ids.slice(0, k);
+  switch (scene) {
+    case 'loadingMore': return { ...page, more: 'loading' };
+    case 'sorting': return { ...page, pend: c.sortDemo ?? [{ id: c.columns[1]?.id ?? c.columns[0]!.id, dir: 'asc' }] };
+    case 'errorMore': return { ...page, more: 'error' };
+    case 'end': { const all = demoFirstPage(c, c.sort, first.total); return { rows: all.rows, cursor: null, total: all.total }; }
+    case 'someSelected': return { ...page, sel: pick(n) };
+    case 'allSelected': return { ...page, sel: pick(c.pageSize) };
+    case 'notShown': return { ...page, sel: pick(n - 2).concat(ids.slice(c.pageSize + 5, c.pageSize + 7)) };
+    case 'deleteConfirm': return { ...page, sel: pick(n), overlay: 'delete' };
+    case 'deleting': return { ...page, sel: pick(n), overlay: 'delete', bulk: 'deleting' };
+    case 'deleteFailed': return { ...page, sel: pick(n), toast: { id: 1, tone: 'apricot', text: `Couldn’t delete ${countNoun(n, c.noun, c.nouns)}`, retry: 'delete' } };
+    case 'assignOpen': return { ...page, sel: pick(n), assign: { open: true, nonce: 0 } };
+    case 'exportOpen': return { ...page, sel: pick(n), overlay: 'export' };
+    case 'mobile': return { ...page, mobile: true };
+    default: return page;
+  }
+}
+
+/** Click cycles asc → desc → none, replacing the sort. Shift adds the key, or cycles it in place. */
+export function cycleSort(current: SortKey[], id: string, add: boolean): SortKey[] {
+  const k = current.findIndex(s => s.id === id);
+  if (add) {
+    const next = current.slice();
+    if (k === -1) next.push({ id, dir: 'asc' });
+    else if (current[k]!.dir === 'asc') next[k] = { id, dir: 'desc' };
+    else next.splice(k, 1);
+    return next;
+  }
+  const d = k === -1 ? null : current[k]!.dir;
+  const nd = d === null ? 'asc' : d === 'asc' ? 'desc' : null;
+  return nd ? [{ id, dir: nd }] : [];
+}
+
+export function reduceDataView(s: DataViewState, a: DataViewAction): DataViewState {
+  switch (a.type) {
+    case 'sortRequest': return { ...s, pend: a.sort, more: 'idle', overlay: s.overlay === 'sort' ? 'sort' : null };
+    /* The new first page replaces what was loaded; the selection is kept by id (README "Selection"). */
+    case 'sorted': return { ...s, sort: a.sort, pend: null, rows: a.rows, cursor: a.cursor, total: a.total, fresh: null };
+    case 'sortFailed': return { ...s, pend: null };
+    case 'moreStart': return s.more === 'loading' || s.pend || !s.cursor ? s : { ...s, more: 'loading' };
+    case 'moreDone': return { ...s, more: 'idle', fresh: a.fresh ? s.rows.length : null, rows: s.rows.concat(a.rows), cursor: a.cursor, total: a.total };
+    case 'moreFailed': return { ...s, more: 'error' };
+    case 'freshDone': return { ...s, fresh: null };
+    case 'toggle': {
+      const sel = s.sel.includes(a.id) ? s.sel.filter(x => x !== a.id) : s.sel.concat(a.id);
+      return { ...s, sel, overlay: sel.length ? s.overlay : null };
+    }
+    /* The header box toggles LOADED rows only: all on → those off; otherwise → those on. */
+    case 'toggleAll': {
+      const allOn = a.ids.length > 0 && a.ids.every(id => s.sel.includes(id));
+      const sel = allOn ? s.sel.filter(id => !a.ids.includes(id)) : s.sel.concat(a.ids.filter(id => !s.sel.includes(id)));
+      return { ...s, sel, overlay: sel.length ? s.overlay : null };
+    }
+    case 'clearSel': return { ...s, sel: [], overlay: null };
+    case 'overlay': return { ...s, overlay: a.overlay };
+    case 'deleteStart': return s.bulk === 'deleting' ? s : { ...s, bulk: 'deleting', overlay: 'delete', toast: null };
+    case 'deleteDone':
+      return a.animate
+        ? { ...s, bulk: 'idle', overlay: null, leaving: a.ids, toast: a.toast }
+        : removeRows({ ...s, bulk: 'idle', overlay: null, toast: a.toast }, a.ids);
+    case 'deleteGone': return removeRows(s, a.ids);
+    case 'deleteFailed': return { ...s, bulk: 'idle', overlay: null, toast: a.toast };
+    case 'assigned': {
+      if (!a.col) return { ...s, toast: a.toast, assign: { open: false, nonce: s.assign.nonce + 1 } };
+      const over = { ...s.over };
+      a.ids.forEach(id => { over[id] = { ...over[id], [a.col!]: a.names.slice() }; });
+      return { ...s, over, toast: a.toast, assign: { open: false, nonce: s.assign.nonce + 1 } };
+    }
+    case 'toast': return { ...s, toast: a.toast };
+    case 'dropToast': return s.toast?.id === a.id ? { ...s, toast: null } : s;
+    case 'copied': return { ...s, copied: a.on };
+  }
+}
+
+function removeRows(s: DataViewState, ids: string[]): DataViewState {
+  const loaded = s.rows.filter(r => ids.includes(r.id)).length;
+  return {
+    ...s,
+    rows: s.rows.filter(r => !ids.includes(r.id)),
+    total: Math.max(0, s.total - ids.length),
+    /* A cursor is an offset into the server's list: the rows removed before it move it back. */
+    cursor: s.cursor === null ? null : String(Math.max(0, Number(s.cursor) - loaded)),
+    sel: [],
+    leaving: [],
+  };
+}
+
+/** A loaded row with its Assign overrides. */
+export function mergedRow(s: DataViewState, r: DataRow): DataRow {
+  const o = s.over[r.id];
+  return o ? { ...r, ...o } : r;
+}
+
+/** Everything the two views derive from the state — one place, so Table and Grid cannot disagree. */
+export function dataViewModel(c: DataViewSettings, s: DataViewState) {
+  const loadedIds = s.rows.map(r => r.id);
+  const onCount = loadedIds.filter(id => s.sel.includes(id)).length;
+  const allOn = loadedIds.length > 0 && onCount === loadedIds.length;
+  const shownSort = s.pend ?? s.sort;
+  const selN = s.sel.length;
+  const notShown = s.sel.filter(id => !loadedIds.includes(id)).length;
+  const count = (n: number) => countNoun(n, c.noun, c.nouns);
+  const atEnd = s.cursor === null;
+  /* "Replace assignees on 5 tickets" when any selected row already has a value in `assignCol`. */
+  const had = Boolean(c.assignCol) && s.sel.some(id => {
+    const row = s.rows.find(r => r.id === id);
+    const o = s.over[id];
+    const v = o && o[c.assignCol!] != null ? o[c.assignCol!] : row?.[c.assignCol!];
+    return Array.isArray(v) ? v.length > 0 : Boolean(v);
+  });
+  return {
+    loadedIds,
+    shownSort,
+    allOn,
+    mixed: onCount > 0 && !allOn,
+    selN,
+    notShown,
+    chipLabel: s.pend ? 'Sorting…' : count(s.total),
+    loadedLabel: atEnd ? `All ${count(s.total)} loaded` : `${Math.min(s.rows.length, s.total).toLocaleString('en-US')} of ${count(s.total)} loaded`,
+    endLabel: `All ${count(s.total)} loaded`,
+    selLabel: `${selN.toLocaleString('en-US')} selected`,
+    notShownLabel: notShown ? ` · ${notShown} not shown` : '',
+    selectAllLabel: `Select ${loadedIds.length.toLocaleString('en-US')} loaded`,
+    deleteTitle: `Delete ${count(selN)}?`,
+    exportTitle: `Export ${count(selN)}`,
+    applyLabel: had ? `Replace assignees on ${count(selN)}` : `Assign to ${count(selN)}`,
+    assignTitle: `Assign ${count(selN)}`,
+    sentinel: (s.more === 'loading' ? 'loading' : s.more === 'error' ? 'error' : atEnd ? (s.total > 0 ? 'end' : 'none') : 'idle') as 'loading' | 'error' | 'end' | 'idle' | 'none',
+    count,
+  };
+}
+
+/** "Assigned 5 tickets to Sam Ortiz" · "… to 3 people". */
+export function assignedText(c: DataViewSettings, n: number, people: Person[]): string {
+  const to = people.length === 1 ? people[0]!.name : `${people.length} people`;
+  return `Assigned ${countNoun(n, c.noun, c.nouns)} to ${to}`;
+}

package/src/components/onboarding/data-view/index.ts

@@ -0,0 +1,21 @@
+export {
+  COLUMN_TYPES, DATA_VIEW_IN_FLIGHT, DATA_VIEW_LAYER_SCENES, DATA_VIEW_SCENES, DATA_VIEW_TIMING,
+  type BulkAction, type ColumnDef, type ColumnType, type DataRow, type DataViewScene, type DataViewSettings, type DemoGen,
+  type Person as PickerPerson, type SortKey, type StatusTone,
+} from './contract';
+export {
+  absTime, cellModel, countNoun, dataViewToText, fmtN, initials, isEmptyValue, isEnd, money, relTime, toTextValue, typeOf,
+  type CellModel,
+} from './registry';
+export {
+  DEMO_NOW, createDemoServer, createRowServer, generateRows, matchPeople, peopleOf, sortRows,
+  type BulkOperation, type BulkRequest, type DemoServer, type PageOperation, type PageRequest, type PageResult,
+  type SearchOperation, type SearchRequest, type SearchResult, type SuggestOperation, type SuggestResult,
+} from './demoSource';
+export {
+  assignedText, cycleSort, dataViewModel, dataViewSeed, demoFirstPage, initialDataView, mergedRow, reduceDataView,
+  type DataToast, type DataViewAction, type DataViewSeed, type DataViewState, type Overlay,
+} from './engine';
+export { useDataView, type DataViewApi, type DataViewEvents, type DataViewOperations, type DataViewPage } from './runtime';
+export { validateDataView } from './validate';
+export { DataView, RecordCard, type DataViewProps } from './DataView';