@appinternalleads/ui 0.2.0

package/src/runtime/query/queryEngine.ts

@@ -0,0 +1,470 @@
+import { useCallback, useEffect, useReducer, useRef } from 'react';
+
+/**
+ * **The shared query runtime.**
+ *
+ * Source: `Widget list.dc.html` + its README (`design_handoff_output_list`), "Build notes" §3–5:
+ * `errorModel` + `asyncOperation` + `epochGuard`, then a `DataAdapter` + `MockAdapter`, then a
+ * `queryMachine` "tested against the mock with no renderer attached". Each is a named section
+ * below; they live in one file for the same reason `fileUploadEngine.ts` does — one cohesive
+ * runtime, small, no framework.
+ *
+ * **The component owns the query *state and lifecycle*; the builder owns the *transport*.** The
+ * component composes a descriptor and hands it to an adapter; it never knows a URL, table or token.
+ *
+ * **Why it lives here rather than under `widgets/output/`.** It began as the Output `list`
+ * renderer's private engine, and was moved the day it acquired a real second consumer —
+ * `components/directory` — which is exactly the test
+ * `docs/architecture/COMPONENT-FAMILIES.md` §3 set for extraction. `src/widgets/output/queryEngine.ts`
+ * remains as a re-export, so `list`'s imports and the package's public surface are untouched.
+ */
+
+// ── errorModel ────────────────────────────────────────────────────────────────────────────────
+
+/** Minimal by design — the README names the type (`AppError | null`) but not its fields. */
+export type AppError = { message: string; retryable: boolean };
+
+export function toAppError(e: unknown): AppError {
+  return { message: e instanceof Error && e.message ? e.message : 'The request failed', retryable: true };
+}
+
+// ── asyncOperation — four statuses, not thirteen ───────────────────────────────────────────────
+
+/** `refreshing`, `stale`, `partial` are FLAGS on `ready`; `retrying` is `loading` + `reason:
+    'retry'`; empty/no-results are `ready` with zero records (README "Runtime state"). */
+export type AsyncStatus = 'idle' | 'loading' | 'ready' | 'error';
+export type QueryReason = 'initial' | 'refresh' | 'filter' | 'search' | 'sort' | 'page' | 'retry';
+export type QueryFlags = { refreshing: boolean; stale: boolean; partial: boolean };
+
+// ── epochGuard ────────────────────────────────────────────────────────────────────────────────
+
+/** A monotonic request token. A response whose epoch is not the CURRENT one is discarded whole —
+    never merged (the Async Combobox rule, generalised). */
+export function createEpochGuard() {
+  let current = 0;
+  return {
+    next: () => { current += 1; return current; },
+    isCurrent: (epoch: number) => epoch === current,
+    get current() { return current; },
+  };
+}
+
+// ── DataAdapter contract (README "Data fetching") ─────────────────────────────────────────────
+
+/**
+ * **The one filter primitive — N1/N5, decided 2026-09-18.** A filter is `{ column, op, value }`
+ * over a column of the data contract, whoever authored it. A USER's chip and an AGENT's dynamic
+ * addition are the same object, differing only in `author`; there is no second filter system. The
+ * shape is the handoff's own (`{ "column": "category", "op": "eq", "value": "Materials" }`).
+ */
+export const FILTER_OPS = [
+  /* text / any */ 'eq', 'neq', 'contains', 'startsWith',
+  /* ordered: numbers and dates alike, compared by the adapter in the column's own domain */
+  'gt', 'gte', 'lt', 'lte', 'between',
+  /* multi-value cells ("Paperback, Ebook") and set membership */ 'includes',
+  /* presence */ 'isEmpty', 'isNotEmpty',
+] as const;
+export type FilterOp = (typeof FILTER_OPS)[number];
+
+/**
+ * Operators that need no `value` — the rule is complete without one, so `validateFilter` must not
+ * reject them for an empty value.
+ */
+export const VALUELESS_FILTER_OPS: readonly FilterOp[] = ['isEmpty', 'isNotEmpty'];
+
+/** `between` carries two bounds in `value`, separated by this. Kept as one string so a filter stays
+    one flat `{ column, op, value }` — the shape both authors share and the descriptor already has. */
+export const RANGE_SEPARATOR = '..';
+export type FilterAuthor = 'user' | 'agent';
+/**
+ * `not` negates the match, and exists because a rule's consequence can be *exclude these* as
+ * easily as *show only these*. Negation belongs here rather than in a doubled operator list:
+ * `neq` would have needed a partner for each of the other eleven, and the two questions "does
+ * this cell match" and "do I want the ones that match" are genuinely separate. Absent or `false`
+ * means an ordinary filter, so every existing filter and fixture is unaffected.
+ */
+export type QueryFilter = { column: string; op: FilterOp; value: string; author?: FilterAuthor; not?: boolean };
+
+export type FilterRejection = 'unknown-column' | 'bad-operator' | 'empty-value' | 'filter-not-served';
+export type FilterCheck = { ok: true } | { ok: false; reason: FilterRejection };
+/** A filter request that did not become part of the query — kept so the rejection is visible, never silent. */
+export type RejectedFilter = { filter: { column: string; op?: string; value: string }; author: FilterAuthor; reason: FilterRejection };
+
+/**
+ * Structural validation, identical for both authors: the column must be one the data contract
+ * declares filterable, the operator must be a known one, the value non-empty. An agent therefore
+ * cannot invent a field — an unavailable column is rejected deterministically. `filterable`
+ * undefined means "unrestricted" (the generic engine, without a column contract).
+ */
+export function validateFilter(f: { column: string; op?: string; value: string }, filterable?: readonly string[]): FilterCheck {
+  if (filterable && !filterable.includes(f.column)) return { ok: false, reason: 'unknown-column' };
+  if (f.op !== undefined && !(FILTER_OPS as readonly string[]).includes(f.op)) return { ok: false, reason: 'bad-operator' };
+  if (f.value === '' && !(VALUELESS_FILTER_OPS as readonly string[]).includes(f.op ?? 'eq')) return { ok: false, reason: 'empty-value' };
+  return { ok: true };
+}
+export type QuerySort = { column: string; dir: 'asc' | 'desc' };
+export type QueryPage = { strategy: 'offset'; offset: number; size: number } | { strategy: 'cursor'; cursor: string | null; size: number };
+
+export type QueryDescriptor = {
+  resource: string;
+  filters: QueryFilter[];
+  search: { q: string; columns: string[] } | null;
+  sort: QuerySort | null;
+  page: QueryPage;
+  epoch: number;
+};
+
+/** A row still in flight is `status: 'pending'` — never an absent key. */
+export type QueryRecord = { id: string; status: 'ready' | 'pending'; data?: Record<string, string> };
+
+export type QueryResponse = {
+  records: QueryRecord[];
+  /** `total` is optional; absent → the counter degrades to "Showing n" and paging jumps dim. */
+  meta: { total?: number; nextCursor?: string | null; partial?: boolean; epoch: number };
+};
+
+export type AdapterCapabilities = {
+  serverSearch?: boolean;
+  serverFilter?: boolean;
+  serverSort?: boolean;
+  pagination?: 'offset' | 'cursor';
+};
+
+export type DataAdapter = {
+  capabilities: AdapterCapabilities;
+  /** Every call takes an `AbortSignal`; navigation and unmount abort. A cancelled call is never an error. */
+  fetch: (descriptor: QueryDescriptor, opts: { signal: AbortSignal }) => Promise<QueryResponse>;
+};
+
+// ── MockAdapter — deterministic latency / failure / reorder injection ─────────────────────────
+
+export type MockAdapterOptions = {
+  records: { id: string; data: Record<string, string> }[];
+  capabilities?: AdapterCapabilities;
+  /** Fixed latency, or a function of the descriptor + 0-based call index (lets a test make call 1
+      slower than call 2 — deterministic reordering, no randomness). Default 0. */
+  latencyMs?: number | ((d: QueryDescriptor, callIndex: number) => number);
+  /** Reject this call? Deterministic by call index / descriptor. */
+  failWhen?: (d: QueryDescriptor, callIndex: number) => boolean;
+  /** Mark the first `pendingCount` records of every response as still in flight. */
+  pendingCount?: number;
+  /** Omit `meta.total` (README "No total"). */
+  omitTotal?: boolean;
+  /** Times each call was made, for assertions. */
+  onCall?: (d: QueryDescriptor, callIndex: number) => void;
+};
+
+/**
+ * **The one place an operator's meaning is defined.** Exported so any adapter — the mock, a
+ * Google Sheets reader, a future SQL one — can execute the same vocabulary rather than inventing
+ * its own. An operator that cannot be executed here is not in `FILTER_OPS`.
+ *
+ * Comparison is domain-aware without a schema: two numeric strings compare numerically, two
+ * date-ish strings compare as dates, anything else compares as a case-insensitive string. That
+ * keeps `QueryFilter` flat (`{ column, op, value }`) while `gt`/`lt`/`between` still mean what a
+ * reader expects on a number or a date column.
+ */
+export function applyFilter(cell: string, f: { op?: FilterOp; value: string; not?: boolean }): boolean {
+  /* An operator this engine cannot execute matches nothing — and negating it must not turn that
+     into "matches everything", which would silently widen a filter instead of failing it. */
+  if (f.op !== undefined && !(FILTER_OPS as readonly string[]).includes(f.op)) return false;
+  return f.not === true ? !matches(cell, f) : matches(cell, f);
+}
+
+function matches(cell: string, f: { op?: FilterOp; value: string }): boolean {
+  const op = f.op ?? 'eq';
+  const a = cell.trim();
+  const b = f.value.trim();
+  const lower = a.toLowerCase();
+
+  switch (op) {
+    case 'isEmpty': return a === '';
+    case 'isNotEmpty': return a !== '';
+    case 'eq': return lower === b.toLowerCase();
+    case 'neq': return lower !== b.toLowerCase();
+    case 'contains': return lower.includes(b.toLowerCase());
+    case 'startsWith': return lower.startsWith(b.toLowerCase());
+    /* A multi-value cell is a delimited list; `includes` asks whether one member matches exactly,
+       which is what "Formats available contains Ebook" means to a reader — and is not the same
+       question as `contains`, a substring test over the whole cell. */
+    case 'includes': return a.split(/[,;|]/).map(p => p.trim().toLowerCase()).includes(b.toLowerCase());
+    case 'between': {
+      const [lo, hi] = b.split(RANGE_SEPARATOR).map(x => x.trim());
+      if (lo === undefined || hi === undefined || hi === '') return false;
+      return compareCell(a, lo) >= 0 && compareCell(a, hi) <= 0;
+    }
+    case 'gt': return compareCell(a, b) > 0;
+    case 'gte': return compareCell(a, b) >= 0;
+    case 'lt': return compareCell(a, b) < 0;
+    case 'lte': return compareCell(a, b) <= 0;
+    default: return false;
+  }
+}
+
+/** -1 / 0 / 1, numerically for two numbers, chronologically for two dates, else lexicographically. */
+export function compareCell(a: string, b: string): number {
+  const na = Number(a); const nb = Number(b);
+  if (a !== '' && b !== '' && !Number.isNaN(na) && !Number.isNaN(nb)) return na === nb ? 0 : na < nb ? -1 : 1;
+  const da = Date.parse(a); const db = Date.parse(b);
+  if (!Number.isNaN(da) && !Number.isNaN(db)) return da === db ? 0 : da < db ? -1 : 1;
+  return a.localeCompare(b, undefined, { sensitivity: 'base' });
+}
+
+const pageOf = (d: QueryDescriptor) => (d.page.strategy === 'offset' ? d.page.offset : Number(d.page.cursor ?? 0));
+
+export function createMockAdapter(opts: MockAdapterOptions): DataAdapter {
+  const capabilities: AdapterCapabilities = {
+    serverSearch: true, serverFilter: true, serverSort: true, pagination: 'offset', ...opts.capabilities,
+  };
+  let calls = 0;
+
+  const run = (d: QueryDescriptor): QueryResponse => {
+    let rows = opts.records.slice();
+    for (const f of d.filters) rows = rows.filter(r => applyFilter(r.data[f.column] ?? '', f));
+    if (d.search && d.search.q) {
+      const q = d.search.q.toLowerCase();
+      rows = rows.filter(r => d.search!.columns.some(c => (r.data[c] ?? '').toLowerCase().includes(q)));
+    }
+    if (d.sort) {
+      const { column, dir } = d.sort;
+      rows.sort((a, b) => compareCell(a.data[column] ?? '', b.data[column] ?? '') * (dir === 'asc' ? 1 : -1));
+    }
+    const total = rows.length;
+    const start = pageOf(d);
+    const slice = rows.slice(start, start + d.page.size);
+    const records: QueryRecord[] = slice.map((r, i) =>
+      opts.pendingCount && i < opts.pendingCount ? { id: r.id, status: 'pending' } : { id: r.id, status: 'ready', data: r.data });
+    const next = start + d.page.size;
+    return {
+      records,
+      meta: {
+        ...(opts.omitTotal ? {} : { total }),
+        nextCursor: d.page.strategy === 'cursor' ? (next < total ? String(next) : null) : undefined,
+        partial: !!opts.pendingCount && records.some(r => r.status === 'pending'),
+        epoch: d.epoch,
+      },
+    };
+  };
+
+  return {
+    capabilities,
+    fetch: (d, { signal }) => {
+      const callIndex = calls++;
+      opts.onCall?.(d, callIndex);
+      const latency = typeof opts.latencyMs === 'function' ? opts.latencyMs(d, callIndex) : (opts.latencyMs ?? 0);
+      return new Promise<QueryResponse>((resolve, reject) => {
+        const abort = () => reject(new DOMException('aborted', 'AbortError'));
+        if (signal.aborted) { abort(); return; }
+        const timer = setTimeout(() => {
+          signal.removeEventListener('abort', onAbort);
+          if (opts.failWhen?.(d, callIndex)) reject(new Error('The source did not answer'));
+          else resolve(run(d));
+        }, latency);
+        const onAbort = () => { clearTimeout(timer); abort(); };
+        signal.addEventListener('abort', onAbort, { once: true });
+      });
+    },
+  };
+}
+
+// ── queryMachine ──────────────────────────────────────────────────────────────────────────────
+
+export type QueryState = {
+  status: AsyncStatus;
+  reason: QueryReason;
+  flags: QueryFlags;
+  epoch: number;
+  query: { filters: QueryFilter[]; search: string; sort: QuerySort | null; page: QueryPage };
+  data: { records: QueryRecord[]; meta: QueryResponse['meta'] } | null;
+  /** Total of the last PRISTINE (no filter, no search) response — the "· 8 suppliers total" half of the counter. */
+  baselineTotal: number | undefined;
+  error: AppError | null;
+  /** Filter requests refused by `validateFilter` (or because the adapter cannot filter) — reported, not swallowed. */
+  rejectedFilters: RejectedFilter[];
+};
+
+export const isPristine = (q: QueryState['query']) => q.filters.length === 0 && q.search === '';
+
+type Action =
+  | { type: 'rejected'; rejected: RejectedFilter[] }
+  | { type: 'start'; reason: QueryReason; query: QueryState['query']; epoch: number }
+  | { type: 'success'; response: QueryResponse }
+  | { type: 'error'; error: AppError };
+
+function reduce(s: QueryState, a: Action): QueryState {
+  switch (a.type) {
+    case 'rejected':
+      return { ...s, rejectedFilters: a.rejected };
+    case 'start':
+      return {
+        ...s, query: a.query, epoch: a.epoch, reason: a.reason, error: null,
+        // A refresh keeps old rows at full opacity → `ready` + `refreshing`. Everything else is
+        // `loading`; rows already on screen are RETAINED until new ones land (never blanked).
+        status: a.reason === 'refresh' && s.data ? 'ready' : 'loading',
+        flags: { ...s.flags, refreshing: a.reason === 'refresh' && !!s.data, stale: false },
+      };
+    case 'success':
+      return {
+        ...s, status: 'ready', error: null,
+        data: { records: a.response.records, meta: a.response.meta },
+        flags: { refreshing: false, stale: false, partial: !!a.response.meta.partial },
+        baselineTotal: isPristine(s.query) ? a.response.meta.total : s.baselineTotal,
+      };
+    case 'error':
+      // An error never blanks rows already on screen; `stale` marks them as prior data.
+      return { ...s, status: 'error', error: a.error, flags: { refreshing: false, stale: !!s.data, partial: false } };
+  }
+}
+
+export type QueryConfig = {
+  resource: string;
+  searchColumns: string[];
+  pageSize: number;
+  initialSort?: QuerySort | null;
+  /** Seed for `query` — "seeded from config, then user-mutated". Seeds pass through `validateFilter` too. */
+  initial?: { filters: QueryFilter[]; search: string };
+  /** The columns the data contract declares filterable. Every filter, from either author, must name one. */
+  filterableColumns?: string[];
+};
+
+export type QueryMachine = {
+  state: QueryState;
+  capabilities: AdapterCapabilities;
+  setSearch: (q: string) => void;
+  /** A USER filter: toggle one column — the same value again clears it. One filter per column; the latest author wins. */
+  setFilter: (column: string, value: string | null, op?: FilterOp) => FilterCheck;
+  /** The AGENT's dynamic filters — the exact same primitive, `author: 'agent'`, validated by the same
+      rule. Replaces the agent-authored set in one query change; returns what was and was not accepted. */
+  /** Accepts whole filters, not just the three required fields — see the note at the call site. */
+  setAgentFilters: (requested: { column: string; op?: string; value: string; author?: FilterAuthor; not?: boolean }[]) => { accepted: QueryFilter[]; rejected: RejectedFilter[] };
+  clearFilters: () => void;
+  setSort: (sort: QuerySort | null) => void;
+  setPage: (offset: number) => void;
+  refresh: () => void;
+  /** Retries the LAST operation — never a blank reload; preserves UI, prior data and user changes. */
+  retry: () => void;
+};
+
+/**
+ * Owns the query lifecycle. Every query change resets page/cursor (page change touches page only;
+ * refresh keeps everything), aborts the in-flight request, bumps the epoch, and re-fetches. A
+ * response is applied only if it is the current epoch AND echoes it.
+ */
+export function useQueryMachine(config: QueryConfig, adapter: DataAdapter): QueryMachine {
+  const size = config.pageSize;
+  const firstPage: QueryPage = adapter.capabilities.pagination === 'cursor'
+    ? { strategy: 'cursor', cursor: null, size } : { strategy: 'offset', offset: 0, size };
+
+  /* N2 — decided A: query state does NOT survive a remount. The machine's whole state lives in this
+     hook, so a remount starts from `config` again: no URL, no storage, no run-record restore. Seeds
+     are filtered through the same rule as any other filter, and are not served if the adapter cannot filter. */
+  const canFilter = adapter.capabilities.serverFilter !== false;
+  const [state, dispatch] = useReducer(reduce, undefined, (): QueryState => {
+    const accepted: QueryFilter[] = []; const rejectedFilters: RejectedFilter[] = [];
+    for (const f of config.initial?.filters ?? []) {
+      const check = canFilter ? validateFilter(f, config.filterableColumns) : { ok: false as const, reason: 'filter-not-served' as const };
+      if (check.ok) accepted.push({ ...f, author: f.author ?? 'user' });
+      else rejectedFilters.push({ filter: f, author: f.author ?? 'user', reason: check.reason });
+    }
+    return {
+      status: 'idle', reason: 'initial', flags: { refreshing: false, stale: false, partial: false }, epoch: 0,
+      query: { filters: accepted, search: config.initial?.search ?? '', sort: config.initialSort ?? null, page: firstPage },
+      data: null, baselineTotal: undefined, error: null, rejectedFilters,
+    };
+  });
+
+  const guard = useRef(createEpochGuard());
+  const controller = useRef<AbortController | null>(null);
+  const mounted = useRef(true);
+  const stateRef = useRef(state);
+  const lastOp = useRef<{ reason: QueryReason; query: QueryState['query'] }>({ reason: 'initial', query: state.query });
+  const adapterRef = useRef(adapter);
+  adapterRef.current = adapter;
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const start = useCallback((reason: QueryReason, query: QueryState['query']) => {
+    controller.current?.abort();
+    const ctl = new AbortController();
+    controller.current = ctl;
+    const epoch = guard.current.next();
+    if (reason !== 'retry') lastOp.current = { reason, query };
+    stateRef.current = reduce(stateRef.current, { type: 'start', reason, query, epoch });
+    dispatch({ type: 'start', reason, query, epoch });
+    const c = configRef.current;
+    const descriptor: QueryDescriptor = {
+      resource: c.resource, filters: query.filters,
+      search: query.search ? { q: query.search, columns: c.searchColumns } : null,
+      sort: query.sort, page: query.page, epoch,
+    };
+    adapterRef.current.fetch(descriptor, { signal: ctl.signal }).then(
+      response => {
+        if (!mounted.current || !guard.current.isCurrent(epoch) || response.meta.epoch !== epoch) return; // discarded whole
+        stateRef.current = reduce(stateRef.current, { type: 'success', response });
+        dispatch({ type: 'success', response });
+      },
+      err => {
+        if (ctl.signal.aborted || !mounted.current || !guard.current.isCurrent(epoch)) return; // cancelled is never an error
+        const error = toAppError(err);
+        stateRef.current = reduce(stateRef.current, { type: 'error', error });
+        dispatch({ type: 'error', error });
+      },
+    );
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    start('initial', stateRef.current.query);
+    return () => { mounted.current = false; controller.current?.abort(); };
+  }, [start]);
+
+  const q = () => stateRef.current.query;
+  const reset = (p: QueryPage): QueryPage => (p.strategy === 'offset' ? { ...p, offset: 0 } : { ...p, cursor: null });
+
+  const refresh = useCallback(() => start('refresh', stateRef.current.query), [start]);
+
+  return {
+    state,
+    capabilities: adapter.capabilities,
+    setSearch: search => start('search', { ...q(), search, page: reset(q().page) }),
+    setFilter: (column, value, op = 'eq') => {
+      if (value !== null) {
+        const check = validateFilter({ column, op, value }, configRef.current.filterableColumns);
+        if (!check.ok) return check;
+      }
+      const rest = q().filters.filter(f => f.column !== column);
+      const filters = value === null || q().filters.some(f => f.column === column && f.value === value && f.op === op)
+        ? rest : [...rest, { column, op, value, author: 'user' as const }];
+      start('filter', { ...q(), filters, page: reset(q().page) });
+      return { ok: true };
+    },
+    setAgentFilters: requested => {
+      const accepted: QueryFilter[] = []; const rejected: RejectedFilter[] = [];
+      for (const r of requested) {
+        const check = adapterRef.current.capabilities.serverFilter === false
+          ? { ok: false as const, reason: 'filter-not-served' as const }
+          : validateFilter(r, configRef.current.filterableColumns);
+        /* Spread, never rebuild field by field: a filter carries more than the three fields this
+           used to copy (`not`, and an author the caller may already have set), and rebuilding
+           silently dropped them — the filter still validated, so nothing complained, and the query
+           quietly widened. Defaults are applied over the spread, not instead of it. */
+        if (check.ok) accepted.push({ ...r, op: (r.op ?? 'eq') as FilterOp, author: r.author ?? 'agent' });
+        else rejected.push({ filter: r, author: 'agent', reason: check.reason });
+      }
+      const sameRejected = JSON.stringify(stateRef.current.rejectedFilters) === JSON.stringify(rejected);
+      if (!sameRejected) { stateRef.current = reduce(stateRef.current, { type: 'rejected', rejected }); dispatch({ type: 'rejected', rejected }); }
+      const cols = new Set(accepted.map(a => a.column));
+      const next = [...q().filters.filter(f => f.author !== 'agent' && !cols.has(f.column)), ...accepted];
+      if (JSON.stringify(next) !== JSON.stringify(q().filters)) start('filter', { ...q(), filters: next, page: reset(q().page) });
+      return { accepted, rejected };
+    },
+    clearFilters: () => start('filter', { ...q(), filters: [], search: '', page: reset(q().page) }),
+    setSort: sort => start('sort', { ...q(), sort, page: reset(q().page) }),
+    setPage: offset => {
+      const p = q().page;
+      start('page', { ...q(), page: p.strategy === 'offset' ? { ...p, offset } : { ...p, cursor: String(offset) } });
+    },
+    refresh,
+    retry: () => start('retry', lastOp.current.reason === 'initial' ? q() : lastOp.current.query),
+  };
+}

package/src/sheets/adapter.ts

@@ -0,0 +1,25 @@
+import { createMockAdapter, type DataAdapter } from '../runtime/query/queryEngine';
+import type { SheetTable } from './csv';
+
+/**
+ * **A sheet as a `DataAdapter`** — for the components that query their rows through the shared
+ * query runtime (the output/1 `list`, Directory): search, filter, sort and paging run in memory over
+ * the sheet's rows, with the runtime's own semantics, and no latency.
+ *
+ * Each record's data is keyed by the sheet's headers. `columns` renames them to the keys your
+ * list document uses — `{ name: 'Supplier name' }` makes the list's `name` column read the sheet's
+ * "Supplier name". Record ids are the sheet row numbers.
+ */
+export function createSheetAdapter(table: SheetTable, opts: { columns?: Record<string, string> } = {}): DataAdapter {
+  const first = table.firstRow ?? 2;
+  const renamed = Object.entries(opts.columns ?? {});
+  const records = table.rows
+    .map((r, i) => ({ r, n: i + first }))
+    .filter(x => x.r.some(c => c.trim() !== ''))
+    .map(({ r, n }) => {
+      const data: Record<string, string> = Object.fromEntries(table.headers.map((h, j) => [h, (r[j] ?? '').trim()]));
+      for (const [key, header] of renamed) data[key] = data[header] ?? '';
+      return { id: String(n), data };
+    });
+  return createMockAdapter({ records, latencyMs: 0 });
+}