@appinternalleads/ui 0.2.0

package/src/sheets/apply.ts

@@ -0,0 +1,196 @@
+import { configFromSheet, fieldsOf, humanHeader, sheetTargets, typeOfKinds, typeOfValue, type SheetFieldType, type SheetMapping, type SheetReport, type SheetTarget } from './bind';
+import type { SheetTable } from './csv';
+import { checklistFromSheet, dataRowsFromSheet } from './records';
+import type { Checklist } from '../components/checklist/contract';
+
+/**
+ * **A sheet, applied only if it works.** `configFromSheet` reads; `applySheet` decides. A sheet is
+ * used when every check passes, and otherwise not at all: the component keeps its config, and the
+ * person is told — in the sheet's own terms, rows and columns — what to change.
+ *
+ * 1. **Read.** Columns match fields by name, then loosely (see `configFromSheet`). A cell that
+ *    cannot be read as its field's type is a problem at that row and column.
+ * 2. **Required columns.** A text or number field every item of the case fills is one the
+ *    component cannot do without; a sheet that has no column for it is not used. Ids are made up
+ *    from the row when missing; yes/no fields and lists default to no and empty.
+ * 3. **References.** Fields that point into the list — a default plan, preselected widgets, a sort
+ *    by column — are moved to what the sheet has, and the change is noted.
+ * 4. **The component's validator.** Whatever it refuses is a problem, pointed at the sheet row.
+ *
+ * The result never makes a component refuse to render: a config it would refuse is never returned.
+ */
+
+export type SheetIssue = { path: string; message: string };
+
+export type SheetApplyResult =
+  | { usable: true; patch: Record<string, unknown>; report: SheetReport; notes: string[] }
+  | { usable: false; report: SheetReport; problems: string[]; needs: string[] };
+
+const ID = /^(id|value|key)$/;
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const idOf = (item: unknown) => {
+  if (!isObj(item)) return undefined;
+  const v = item.id ?? item.value ?? item.key;
+  return typeof v === 'string' ? v : undefined;
+};
+
+/** The columns a list reads, required first — what a person's sheet needs. */
+export function sheetNeeds(base: Record<string, unknown>, target: SheetTarget): { required: string[]; optional: string[]; types: Record<string, SheetFieldType> } {
+  if (target.kind === 'settings') {
+    const lists = new Set(sheetTargets(base).flatMap(t => (t.kind === 'list' ? [t.key] : [])));
+    const optional = Object.keys(base).filter(k => !lists.has(k));
+    return { required: ['key', 'value'], optional, types: { key: 'text', value: 'text', ...Object.fromEntries(optional.map(k => [k, typeOfValue(base[k])])) } };
+  }
+  const items = (Array.isArray(base[target.key]) ? base[target.key] : []) as unknown[];
+  const objs = items.filter(isObj);
+  const required: string[] = [];
+  const optional: string[] = [];
+  const types: Record<string, SheetFieldType> = {};
+  for (const f of fieldsOf(objs)) {
+    const single = f.kinds.size === 1 ? [...f.kinds][0] : null;
+    const alwaysFilled = !f.optional && objs.every(o => o[f.key] !== '' && o[f.key] !== null && o[f.key] !== undefined);
+    (!ID.test(f.key) && alwaysFilled && (single === 'string' || single === 'number') ? required : optional).push(f.key);
+    types[f.key] = typeOfKinds(f.kinds);
+  }
+  return { required, optional, types };
+}
+
+/** "Price (number, required)" — a column as a person needs to know it. */
+export function describeNeed(field: string, type: SheetFieldType | undefined, required: boolean): string {
+  return `${humanHeader(field)} (${[type, required ? 'required' : null].filter(Boolean).join(', ')})`;
+}
+
+/** Move fields that point at the old list's ids to what the new list has. */
+function repairReferences(base: Record<string, unknown>, key: string, next: unknown[]): { patch: Record<string, unknown>; notes: string[] } {
+  const oldIds = new Set((Array.isArray(base[key]) ? base[key] as unknown[] : []).map(idOf).filter((x): x is string => Boolean(x)));
+  const newIds = next.map(idOf).filter((x): x is string => Boolean(x));
+  const have = new Set(newIds);
+  const patch: Record<string, unknown> = {};
+  const notes: string[] = [];
+  if (!oldIds.size) return { patch, notes };
+  for (const [k, v] of Object.entries(base)) {
+    if (k === key) continue;
+    if (typeof v === 'string' && oldIds.has(v) && !have.has(v)) {
+      patch[k] = newIds[0] ?? '';
+      notes.push(`${humanHeader(k)} was “${v}”, which the sheet does not have — now the sheet’s first (“${newIds[0] ?? ''}”).`);
+    } else if (Array.isArray(v) && v.length && v.every(x => typeof x === 'string' && oldIds.has(x))) {
+      const kept = (v as string[]).filter(x => have.has(x));
+      if (kept.length !== v.length) { patch[k] = kept; notes.push(`${humanHeader(k)} pointed at items the sheet does not have — ${kept.length ? `kept ${kept.join(', ')}` : 'cleared'}.`); }
+    } else if (Array.isArray(v) && v.length && v.every(x => isObj(x) && typeof x.id === 'string' && oldIds.has(x.id))) {
+      const kept = (v as Record<string, unknown>[]).filter(x => have.has(x.id as string));
+      if (kept.length !== v.length) { patch[k] = kept; notes.push(`${humanHeader(k)} pointed at items the sheet does not have — ${kept.length ? 'kept the rest' : 'cleared'}.`); }
+    }
+  }
+  return { patch, notes };
+}
+
+/** A validator's path, in the sheet's terms: `plans[3].price` → "Row 5 · Price". */
+function explain(issue: SheetIssue, key: string | null, report: SheetReport): string {
+  const headerOf = (field: string) => report.matched.find(m => m.field === field && !m.fixed)?.header ?? humanHeader(field);
+  const m = key ? new RegExp(`^${key}\\[(\\d+)\\](?:\\.([\\w]+))?`).exec(issue.path) : null;
+  const text = issue.message.replace(/\s+$/, '');
+  if (m) {
+    const row = report.rowNumbers?.[Number(m[1])] ?? Number(m[1]) + 2;
+    return `Row ${row}${m[2] ? ` · ${headerOf(m[2])}` : ''}: ${text}`;
+  }
+  if (key && issue.path === key) return `${text} The sheet gives ${report.count} row${report.count === 1 ? '' : 's'}.`;
+  if (!issue.path) return text;
+  const root = issue.path.split(/[.[]/)[0] ?? issue.path;
+  return `${humanHeader(root)}: ${text}`;
+}
+
+/**
+ * **Apply a sheet to a component's config — or say why not.** `base` is the config the sheet
+ * changes (the case, resolved); `validate` is the component's own validator, given the whole
+ * config the sheet would produce.
+ */
+export function applySheet(
+  base: Record<string, unknown>,
+  table: SheetTable,
+  target: SheetTarget,
+  opts: { validate?: (config: Record<string, unknown>) => SheetIssue[]; maxItems?: number; label?: string; mapping?: SheetMapping } = {},
+): SheetApplyResult {
+  const { patch, report } = configFromSheet(base, table, target, { maxItems: opts.maxItems, mapping: opts.mapping });
+  const needs = sheetNeeds(base, target);
+  const key = target.kind === 'list' ? target.key : null;
+  const needList = key
+    ? [...needs.required.map(f => describeNeed(f, needs.types[f], true)), ...needs.optional.map(f => describeNeed(f, needs.types[f], false))]
+    : ['Key (text, required)', 'Value (the setting’s type, required)'];
+  const fail = (problems: string[]): SheetApplyResult => ({ usable: false, report, problems, needs: needList });
+  const what = opts.label ?? humanHeader(target.kind === 'list' ? target.key : 'settings');
+
+  if (!table.rows.some(r => r.some(c => c.trim() !== ''))) return fail(['The sheet has a header row but no rows under it.']);
+  if (report.mappingErrors?.length) return fail(report.mappingErrors);
+  if (!report.applied) {
+    return fail([target.kind === 'settings'
+      ? `No row names a setting this component has. A settings sheet has two columns — key, value — with keys such as ${needs.optional.slice(0, 4).join(', ')}.`
+      : `None of the sheet’s columns match what ${what} reads (${needList.join(', ')}). The sheet has: ${table.headers.filter(Boolean).join(', ')}.`]);
+  }
+  const missing = key ? needs.required.filter(f => !report.matched.some(m => m.field === f)) : [];
+  if (missing.length) {
+    return fail([`The sheet has no column for ${missing.map(f => `${humanHeader(f)} (${needs.types[f] ?? 'text'})`).join(', ')} — ${what} needs ${missing.length === 1 ? 'it' : 'them'}. Matched so far: ${report.matched.map(m => (m.header === m.field ? m.header : `${m.header} → ${humanHeader(m.field)}`)).join(', ')}. Assign ${missing.length === 1 ? 'it a column, or one value for every row' : 'them columns, or one value for every row'}.`]);
+  }
+  if (report.errors.length) {
+    return fail(report.errors.slice(0, 8).map(e => `Row ${e.row} · ${e.column}: ${e.message}.`).concat(report.errors.length > 8 ? [`…and ${report.errors.length - 8} more cells like these.`] : []));
+  }
+  const notes: string[] = [];
+  let full = { ...patch };
+  if (key) {
+    const fix = repairReferences(base, key, (patch[key] ?? []) as unknown[]);
+    full = { ...full, ...fix.patch };
+    notes.push(...fix.notes);
+  }
+  const issues = opts.validate?.({ ...base, ...full }) ?? [];
+  if (issues.length) return fail(issues.slice(0, 8).map(i => explain(i, key, report)).concat(issues.length > 8 ? [`…and ${issues.length - 8} more.`] : []));
+  return { usable: true, patch: full, report, notes };
+}
+
+/**
+ * **A sheet as Table / Grid data** — every row a record, every column a column. Used when there are
+ * rows under the header and the component accepts the columns; the card is named after `title`.
+ */
+export function applyRowsSheet(
+  base: Record<string, unknown>,
+  table: SheetTable,
+  opts: { validate?: (config: Record<string, unknown>) => SheetIssue[]; title?: string; subtitle?: string } = {},
+) {
+  const { columns, rows } = dataRowsFromSheet(table);
+  const report: SheetReport = {
+    matched: columns.map((c, i) => ({ header: table.headers[i] ?? c.label, field: `${c.id} (${c.type})` })),
+    unused: [], missing: [], errors: [], count: rows.length, total: rows.length, applied: rows.length > 0,
+  };
+  const needs = ['one column per field', 'one row per record'];
+  if (!rows.length) return { usable: false as const, report, problems: ['The sheet has a header row but no rows under it.'], needs };
+  if (!columns.length) return { usable: false as const, report, problems: ['The sheet has no named columns.'], needs };
+  const patch: Record<string, unknown> = {
+    columns, totalCount: rows.length, sort: [], assignCol: null, noun: 'row', nouns: 'rows', selCount: Math.min(5, rows.length),
+    ...(opts.title ? { title: opts.title } : {}), ...(opts.subtitle !== undefined ? { subtitle: opts.subtitle } : {}),
+  };
+  const issues = opts.validate?.({ ...base, ...patch }) ?? [];
+  if (issues.length) return { usable: false as const, report, problems: issues.slice(0, 8).map(i => `${i.path}: ${i.message}`), needs };
+  return { usable: true as const, patch, report, notes: [] as string[], rows };
+}
+
+const CHECKLIST_NEEDS = ['Task or Title (text, required)', 'Section (text)', 'Description (text)', 'Required (yes/no)', 'Assignee (text — a person id)', 'Done (yes/no)'];
+
+/** **A sheet as a checklist** — used when it has a Task column with tasks in it; otherwise, why not. */
+export function applyChecklistSheet(
+  table: SheetTable,
+  base: { id: string; title: string; description?: string },
+  opts: { mapping?: SheetMapping; maxTasks?: number } = {},
+): { usable: true; checklist: Checklist; report: SheetReport; notes: string[] } | { usable: false; problems: string[]; needs: string[]; report?: SheetReport } {
+  const read = checklistFromSheet(table, base, { mapping: opts.mapping, maxTasks: opts.maxTasks });
+  const found: SheetReport = { matched: read.columns, unused: [], missing: [], errors: [], count: 0, total: read.total, applied: false };
+  if (read.mappingErrors.length) return { usable: false, problems: read.mappingErrors, needs: CHECKLIST_NEEDS, report: found };
+  const needs = CHECKLIST_NEEDS;
+  if (!read.total) return { usable: false, problems: ['The sheet has a header row but no rows under it.'], needs, report: found };
+  if (read.missing.length) {
+    return { usable: false, problems: [`The sheet has no Task column (a column named Task or Title, or ending with it — “Book title” works). It has: ${table.headers.filter(Boolean).join(', ')}. Assign the Task column by hand.`], needs, report: found };
+  }
+  const tasks = read.checklist.sections.flatMap(x => x.tasks);
+  if (!tasks.length) return { usable: false, problems: ['The Task column is empty in every row, so there are no tasks to make.'], needs, report: found };
+  const notes: string[] = [];
+  if (read.used > tasks.length) notes.push(`${read.used - tasks.length} row${read.used - tasks.length === 1 ? '' : 's'} with an empty Task ${read.used - tasks.length === 1 ? 'was' : 'were'} skipped.`);
+  const report: SheetReport = { matched: read.columns, unused: table.headers.filter(h => h && !read.columns.some(c => c.header === h)), missing: [], errors: [], count: tasks.length, total: read.total, applied: true };
+  return { usable: true, checklist: read.checklist, report, notes };
+}

package/src/sheets/bind.ts

@@ -0,0 +1,369 @@
+import type { SheetTable } from './csv';
+
+/**
+ * **A sheet → a component's config, and back.** Generic: nothing here knows a component. The shape
+ * of the config the component already ships (its preset) is the schema:
+ *
+ * - **A list** (`plans`, `categories`, `tasks`…: any config field that is a list of objects) takes one
+ *   sheet row per item, up to `LIST_MAX_ITEMS` (these lists are a handful of cards, not a table —
+ *   a list the case itself fills beyond that, like Combobox's people, is a directory and takes all).
+ *   A column matches a field by name — `monthlyPrice`, "Monthly price" and `monthly_price` are the
+ *   same column. Failing that, loosely: a header that ends with the field's name ("Book title" →
+ *   `title`), then one that ends with a near word ("Author" → `name`) — a loose match is taken only
+ *   when the column's cells read as the field's type. Each cell is read as the type the preset
+ *   uses for that field: a number, yes/no, a `;`-separated list, or JSON for anything nested.
+ *   A sheet whose columns match none of the list's fields is not applied: the case stays as it is,
+ *   and the report says so.
+ * - **Settings** take a two-column sheet — `key`, `value` — one row per config field.
+ *
+ * The reverse, `sheetFromConfig`, writes any case study as a sheet in exactly that shape, so a
+ * person can download it, edit it in Google Sheets and read it back: the round trip is lossless
+ * (`tests/sheets.test.ts` checks it for every list and every settings field of every component).
+ *
+ * The component still validates what comes back, as it validates any config: a sheet cannot make a
+ * component render something its own validator refuses.
+ */
+
+export type SheetTarget = { kind: 'list'; key: string } | { kind: 'settings' };
+
+/**
+ * **Columns assigned by hand** — by a person in a mapping panel, or by an agent or host code. For a
+ * list, field → a sheet column's name, `{ value }` (the same value in every row), or `null` (not from
+ * the sheet: the component's default). For settings, `key` and `value` name the two columns.
+ * An assignment always wins over automatic matching.
+ */
+export type SheetMapping = Record<string, string | { value: string } | null>;
+
+/** At most this many sheet rows fill a list — a Plans or Tasks list is a few cards, not 5,000. A list
+ *  whose case already holds more (a searchable directory) is not limited. */
+export const LIST_MAX_ITEMS = 50;
+
+type Json = unknown;
+type Kind = 'string' | 'number' | 'boolean' | 'null' | 'strings' | 'numbers' | 'json';
+
+const isObj = (v: Json): v is Record<string, Json> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** "monthlyPrice" → "Monthly price" — the header a template writes. */
+export function humanHeader(field: string): string {
+  const s = field.replace(/[_-]+/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2').trim();
+  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+
+/** A field's type in a person's words — what a sheet column for it must hold. */
+export type SheetFieldType = 'text' | 'number' | 'yes/no' | 'list' | 'list of numbers' | 'JSON' | 'text or empty';
+
+export function typeOfKinds(kinds: Set<string>): SheetFieldType {
+  const k = [...kinds].filter(x => x !== 'null');
+  if (k.length === 0) return 'text or empty';
+  if (k.length === 1) {
+    return ({ string: 'text', number: 'number', boolean: 'yes/no', strings: 'list', numbers: 'list of numbers', json: 'JSON' } as Record<string, SheetFieldType>)[k[0]!] ?? 'text';
+  }
+  if (k.every(x => x === 'strings' || x === 'numbers')) return 'list';
+  return k.includes('json') ? 'JSON' : 'text';
+}
+
+/** The type a value has, as `typeOfKinds` names it. */
+export function typeOfValue(v: unknown): SheetFieldType {
+  return typeOfKinds(new Set([kindOf(v)]));
+}
+
+function kindOf(v: Json): Kind {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'string') return 'string';
+  if (typeof v === 'number') return 'number';
+  if (typeof v === 'boolean') return 'boolean';
+  if (Array.isArray(v)) {
+    if (v.every(x => typeof x === 'number')) return v.length ? 'numbers' : 'strings';
+    if (v.every(x => typeof x === 'string' && !x.includes(';') && !x.includes('\n') && x.trim() === x && x !== '')) return 'strings';
+  }
+  return 'json';
+}
+
+/** The fields a list's items use, in first-seen order, with every kind each field takes and whether some item omits it. */
+export function fieldsOf(items: Record<string, Json>[]) {
+  const order: string[] = [];
+  const kinds = new Map<string, Set<Kind>>();
+  for (const it of items) {
+    for (const [k, v] of Object.entries(it)) {
+      if (!kinds.has(k)) { kinds.set(k, new Set()); order.push(k); }
+      kinds.get(k)!.add(kindOf(v));
+    }
+  }
+  return order.map(key => ({ key, kinds: kinds.get(key)!, optional: items.some(it => !(key in it)) }));
+}
+
+/** Every target a config offers: each list of objects, then its settings. */
+export function sheetTargets(config: Record<string, Json>): SheetTarget[] {
+  const lists = Object.entries(config)
+    .filter(([, v]) => Array.isArray(v) && v.length > 0 && v.every(isObj))
+    .map(([key]) => ({ kind: 'list' as const, key }));
+  return [...lists, { kind: 'settings' }];
+}
+
+export function targetLabel(t: SheetTarget): string {
+  return t.kind === 'settings' ? 'Settings (key, value)' : `${humanHeader(t.key)} — one row each`;
+}
+
+/* ── Cells ──────────────────────────────────────────────────────────────────────────────── */
+
+function toCell(v: Json): string {
+  switch (kindOf(v)) {
+    case 'null': return '';
+    case 'string': return v as string;
+    case 'number': return String(v);
+    case 'boolean': return v ? 'yes' : 'no';
+    case 'strings': case 'numbers': return (v as Json[]).join('; ');
+    default: return JSON.stringify(v);
+  }
+}
+
+const YES = /^(y|yes|true|1|x|✓|✔|on)$/i;
+const NO = /^(n|no|false|0|off|-)$/i;
+
+/** One cell read as the kind(s) the preset uses for the field. `undefined` means "leave the field out". */
+function fromCell(raw: string, kinds: Set<Kind>, optional: boolean): { ok: true; value: Json } | { ok: false } {
+  const s = raw.trim();
+  if (s === '') {
+    if (optional) return { ok: true, value: undefined };
+    if (kinds.has('null')) return { ok: true, value: null };
+    if (kinds.has('string')) return { ok: true, value: '' };
+    if (kinds.has('strings') || kinds.has('numbers')) return { ok: true, value: [] };
+    if (kinds.has('boolean')) return { ok: true, value: false };
+    if (kinds.has('number')) return { ok: true, value: 0 };
+    return { ok: true, value: undefined };
+  }
+  if ((kinds.has('json') || kinds.has('strings') || kinds.has('numbers')) && /^[[{]/.test(s)) {
+    try { return { ok: true, value: JSON.parse(s) as Json }; } catch { /* fall through */ }
+  }
+  if (kinds.has('number') && !kinds.has('string')) {
+    const n = Number(s.replace(/[\s,$£€%]/g, ''));
+    return Number.isFinite(n) ? { ok: true, value: n } : { ok: false };
+  }
+  if (kinds.has('boolean') && !kinds.has('string')) {
+    if (YES.test(s)) return { ok: true, value: true };
+    if (NO.test(s)) return { ok: true, value: false };
+    return { ok: false };
+  }
+  if (kinds.has('numbers')) {
+    const parts = s.split(/;|\n/).map(x => x.trim()).filter(Boolean).map(Number);
+    return parts.every(Number.isFinite) ? { ok: true, value: parts } : { ok: false };
+  }
+  if (kinds.has('strings')) return { ok: true, value: s.split(/;|\n/).map(x => x.trim()).filter(Boolean) };
+  if (kinds.has('json') && !kinds.has('string')) return { ok: false };
+  /* A field the preset writes as text, or a mix: text. A number-only preset field that a sheet
+     wrote as a number stays a string here only if the preset ever used a string for it. */
+  if (kinds.has('number') && /^-?\d+(\.\d+)?$/.test(s) && !kinds.has('string')) return { ok: true, value: Number(s) };
+  return { ok: true, value: raw };
+}
+
+/* ── Reading ────────────────────────────────────────────────────────────────────────────── */
+
+export type SheetReport = {
+  /** Sheet columns (or setting keys) that were used, and the field each filled. `fixed` is a value
+   *  assigned by hand for every row; `manual` means the column was assigned by hand. */
+  matched: { header: string; field: string; fixed?: boolean; manual?: boolean }[];
+  /** Assignments that could not be followed — a column the sheet does not have, a fixed value of the wrong type. */
+  mappingErrors?: string[];
+  /** Sheet columns (or setting keys) that match nothing in this config — ignored. */
+  unused: string[];
+  /** Fields the sheet did not provide — left out, or empty. */
+  missing: string[];
+  /** Cells that could not be read as their field's type — row is 1-based, as in the sheet (header = 1). */
+  errors: { row: number; column: string; message: string }[];
+  /** Items (list) or settings read. */
+  count: number;
+  /** Non-empty rows in the sheet (list) — more than `count` when the list's limit cut it short. */
+  total: number;
+  /** False when nothing in the sheet matched: the patch is empty and the case is left as it is. */
+  applied: boolean;
+  /** The sheet row (1-based, header = 1) each list item came from, in order. */
+  rowNumbers?: number[];
+};
+
+/**
+ * **A sheet → a config patch** for `target`, shaped like `base` (the component's resolved config).
+ * Merge the patch over the preset — `{ ...preset, ...patch }` — or pass it as the `config` prop.
+ */
+export function configFromSheet(
+  base: Record<string, Json>,
+  table: SheetTable,
+  target: SheetTarget,
+  opts: { maxItems?: number; mapping?: SheetMapping } = {},
+): { patch: Record<string, Json>; report: SheetReport } {
+  return target.kind === 'settings'
+    ? readSettings(base, table, opts.mapping)
+    : readList(base, table, target.key, opts.maxItems, opts.mapping);
+}
+
+/* Near words, by a field's last word — tried in order, after the field's own name. */
+const NEAR: Record<string, string[]> = {
+  title: ['name', 'label', 'heading', 'subject'],
+  name: ['title', 'label', 'author', 'owner', 'person'],
+  label: ['title', 'name'],
+  description: ['details', 'detail', 'notes', 'summary', 'about', 'body'],
+  subtitle: ['description', 'summary'],
+  body: ['description', 'details', 'text'],
+  detail: ['description', 'details', 'notes'],
+  price: ['cost', 'amount'],
+  url: ['link', 'href', 'website'],
+  href: ['url', 'link', 'website'],
+  link: ['url', 'href', 'website'],
+  email: ['mail'],
+};
+const wordsOf = (s: string) => humanHeader(s).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const endsWith = (hw: string[], fw: string[]) => fw.length > 0 && hw.length >= fw.length && fw.every((w, i) => hw[hw.length - fw.length + i] === w);
+
+/** A header by name, ignoring case and surrounding spaces. */
+const headerIndex = (table: SheetTable, name: string) => table.headers.findIndex(h => h.trim().toLowerCase() === name.trim().toLowerCase());
+
+function readList(base: Record<string, Json>, table: SheetTable, key: string, maxItems: number | undefined, mapping: SheetMapping = {}) {
+  const items = (Array.isArray(base[key]) ? base[key] : []) as Record<string, Json>[];
+  const fields = fieldsOf(items.filter(isObj));
+  const numbered = table.rows.map((r, i) => ({ r, n: i + (table.firstRow ?? 2) })).filter(x => x.r.some(c => c.trim() !== ''));
+  const all = numbered.map(x => x.r);
+  const colOf = new Map<string, number>();
+  const taken = new Set<number>();
+  const take = (field: string, i: number) => { colOf.set(field, i); taken.add(i); };
+  /* 0 · by hand — a column, a fixed value, or nothing; never second-guessed below. */
+  const fixed = new Map<string, Json>();
+  const manual = new Set<string>();
+  const mappingErrors: string[] = [];
+  for (const [field, to] of Object.entries(mapping)) {
+    const f = fields.find(x => x.key === field);
+    if (!f) { mappingErrors.push(`${humanHeader(field)} is not something this list reads.`); continue; }
+    manual.add(field);
+    if (to === null) continue;
+    if (typeof to === 'string') {
+      const i = headerIndex(table, to);
+      if (i < 0) mappingErrors.push(`${humanHeader(field)} is assigned the column “${to}”, which the sheet does not have.`);
+      else { colOf.set(field, i); taken.add(i); }
+    } else {
+      const v = fromCell(to.value, f.kinds, false);
+      if (!v.ok) mappingErrors.push(`${humanHeader(field)} is set to “${to.value}” for every row, but it must be ${describe(f.kinds)}.`);
+      else fixed.set(field, v.value);
+    }
+  }
+  /* 1 · by name. */
+  const byNorm = new Map<string, number>();
+  table.headers.forEach((h, i) => { if (!byNorm.has(norm(h))) byNorm.set(norm(h), i); });
+  for (const f of fields) {
+    if (manual.has(f.key)) continue;
+    const i = byNorm.get(norm(f.key)) ?? byNorm.get(norm(humanHeader(f.key)));
+    if (i !== undefined && !taken.has(i)) take(f.key, i);
+  }
+  /* 2 · loosely — a header ending with the field's name, then with a near word — if the cells fit. */
+  const fits = (i: number, f: (typeof fields)[number]) =>
+    all.slice(0, 50).map(r => r[i] ?? '').filter(c => c.trim() !== '').every(c => fromCell(c, f.kinds, f.optional).ok);
+  const loose = (wordsFor: (f: (typeof fields)[number]) => string[][]) => {
+    for (const f of fields) {
+      if (colOf.has(f.key) || manual.has(f.key) || /^(id|key)$/.test(f.key)) continue;
+      for (const fw of wordsFor(f)) {
+        const i = table.headers.findIndex((h, j) => !taken.has(j) && endsWith(wordsOf(h), fw) && fits(j, f));
+        if (i >= 0) { take(f.key, i); break; }
+      }
+    }
+  };
+  loose(f => [wordsOf(f.key)]);
+  loose(f => (NEAR[wordsOf(f.key).at(-1) ?? ''] ?? []).map(w => [w]));
+  const matched: SheetReport['matched'] = [
+    ...[...colOf].sort((a, b) => a[1] - b[1]).map(([field, i]) => ({ header: table.headers[i]!, field, ...(manual.has(field) ? { manual: true } : {}) })),
+    ...[...fixed].map(([field, v]) => ({ header: `“${Array.isArray(v) ? v.join('; ') : String(v)}” in every row`, field, fixed: true, manual: true })),
+  ];
+  const unused = table.headers.filter((_, i) => !taken.has(i));
+  const missing = fields.filter(f => !colOf.has(f.key) && !fixed.has(f.key)).map(f => f.key);
+  /* Nothing matched (and nothing assigned): filling the list with empty items would only show blanks. Leave the case alone. */
+  if (!colOf.size && !fixed.size) return { patch: {}, report: { matched, unused, missing, errors: [], count: 0, total: all.length, applied: false, mappingErrors } };
+  const errors: SheetReport['errors'] = [];
+  /* A limit asked for is kept; the default spares a list the case already holds more of (a directory). */
+  const kept = maxItems !== undefined ? numbered.slice(0, Math.max(1, maxItems)) : items.length > LIST_MAX_ITEMS ? numbered : numbered.slice(0, LIST_MAX_ITEMS);
+  const rows = kept.map(x => x.r);
+  const out = rows.map((r, ri) => {
+    const item: Record<string, Json> = {};
+    for (const f of fields) {
+      if (fixed.has(f.key)) { if (fixed.get(f.key) !== undefined) item[f.key] = fixed.get(f.key)!; continue; }
+      const i = colOf.get(f.key);
+      if (i === undefined) {
+        /* Not in the sheet. An identity field is made up from the row; anything else is left to the
+           component's own default, or — when every item has it — taken as empty of its kind. */
+        if (/^(id|value|key)$/.test(f.key) && f.kinds.has('string')) {
+          const label = String(r[colOf.get('label') ?? colOf.get('title') ?? colOf.get('name') ?? 0] ?? '');
+          item[f.key] = `${label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item'}-${ri + 1}`;
+        } else if (!f.optional) {
+          const v = fromCell('', f.kinds, false);
+          if (v.ok && v.value !== undefined) item[f.key] = v.value;
+        }
+        continue;
+      }
+      const v = fromCell(r[i] ?? '', f.kinds, f.optional);
+      if (!v.ok) { errors.push({ row: kept[ri]!.n, column: table.headers[i]!, message: `“${r[i]}” is not ${describe(f.kinds)}` }); continue; }
+      if (v.value !== undefined) item[f.key] = v.value;
+    }
+    return item;
+  });
+  return { patch: { [key]: out }, report: { matched, unused, missing, errors, count: out.length, total: all.length, applied: true, rowNumbers: kept.map(x => x.n), mappingErrors } };
+}
+
+function readSettings(base: Record<string, Json>, table: SheetTable, mapping: SheetMapping = {}) {
+  const lists = new Set(sheetTargets(base).flatMap(t => (t.kind === 'list' ? [t.key] : [])));
+  const fields = Object.keys(base).filter(k => !lists.has(k));
+  const byNorm = new Map(fields.flatMap(f => [[norm(f), f], [norm(humanHeader(f)), f]] as [string, string][]));
+  /* Headers "key, value" (either order, any case) — or none: then the header row is itself a pair. */
+  const mappingErrors: string[] = [];
+  const byHand = (which: 'key' | 'value') => {
+    const to = mapping[which];
+    if (typeof to !== 'string') return -1;
+    const i = headerIndex(table, to);
+    if (i < 0) mappingErrors.push(`The ${which} column is assigned “${to}”, which the sheet does not have.`);
+    return i;
+  };
+  const hk = byHand('key');
+  const hv = byHand('value');
+  const ki = hk >= 0 ? hk : table.headers.findIndex(h => /^(key|setting|field|name)$/i.test(h.trim()));
+  const vi = hv >= 0 ? hv : table.headers.findIndex(h => /^value$/i.test(h.trim()));
+  const named = ki >= 0 && vi >= 0;
+  /* A row-shaped sheet (at least two columns named after settings, no key/value columns): each such
+     column sets its setting from the first row — so a list-style sheet can still set a title. */
+  const wide = !named && table.rows.length > 0 && table.headers.filter(h => byNorm.has(norm(h))).length >= 2;
+  const pairs = wide
+    ? table.headers.map((h, i) => [h, table.rows[0]![i] ?? ''])
+    : (named ? table.rows : [table.headers, ...table.rows]).map(r => (named ? [r[ki] ?? '', r[vi] ?? ''] : r));
+  const all = pairs;
+  const patch: Record<string, Json> = {};
+  const matched: SheetReport['matched'] = [];
+  const unused: string[] = [];
+  const errors: SheetReport['errors'] = [];
+  all.forEach((r, ri) => {
+    const k = (r[0] ?? '').trim();
+    if (!k) return;
+    const f = byNorm.get(norm(k));
+    if (!f) { unused.push(k); return; }
+    const kinds = new Set([kindOf(base[f])]);
+    const v = fromCell(r[1] ?? '', kinds, false);
+    if (!v.ok) { errors.push({ row: wide ? 2 : ri + (named ? 2 : 1), column: k, message: `“${r[1]}” is not ${describe(kinds)}` }); return; }
+    patch[f] = v.value;
+    matched.push({ header: k, field: f });
+  });
+  const got = new Set(matched.map(m => m.field));
+  return { patch, report: { matched, unused, missing: fields.filter(f => !got.has(f)), errors, count: matched.length, total: matched.length, applied: matched.length > 0, mappingErrors } };
+}
+
+function describe(kinds: Set<Kind>): string {
+  if (kinds.has('number')) return 'a number';
+  if (kinds.has('boolean')) return 'yes or no';
+  if (kinds.has('numbers')) return 'a ;-separated list of numbers';
+  return 'valid JSON';
+}
+
+/* ── Writing ────────────────────────────────────────────────────────────────────────────── */
+
+/** **A config → a sheet** for `target` — the template a person edits and reads back. */
+export function sheetFromConfig(config: Record<string, Json>, target: SheetTarget): SheetTable {
+  if (target.kind === 'settings') {
+    const lists = new Set(sheetTargets(config).flatMap(t => (t.kind === 'list' ? [t.key] : [])));
+    return { headers: ['key', 'value'], rows: Object.keys(config).filter(k => !lists.has(k)).map(k => [k, toCell(config[k])]) };
+  }
+  const items = ((config[target.key] ?? []) as Json[]).filter(isObj);
+  const fields = fieldsOf(items);
+  return { headers: fields.map(f => f.key), rows: items.map(it => fields.map(f => (f.key in it ? toCell(it[f.key]) : ''))) };
+}

package/src/sheets/csv.ts

@@ -0,0 +1,80 @@
+/**
+ * **Sheets, as data — the pure half.** A sheet here is a header row and data rows of strings
+ * (`SheetTable`): what Google's CSV export, a CSV file or a paste all reduce to. This module parses
+ * and writes that shape and names a public Google Sheet's CSV address; it performs no request.
+ *
+ * Reading is the host's job, and on the web it must happen on a server: Google's CSV endpoint sends
+ * no CORS header. A link-shared sheet ("anyone with the link can view") needs no credentials.
+ */
+
+/** A sheet's header and rows. `firstRow` is the sheet row `rows[0]` came from (2 unless a row under the header was dropped). */
+export type SheetTable = { headers: string[]; rows: string[][]; firstRow?: number };
+export type SheetRef = { spreadsheetId: string; gid?: string };
+
+/** Accepts a full edit/view URL (with or without `#gid=`) or a bare spreadsheet id. */
+export function parseSheetUrl(input: string): SheetRef | null {
+  const raw = input.trim();
+  if (!raw) return null;
+  /* The host is part of the check: `https://example.test/spreadsheets/d/x` is not a Google Sheet,
+     and accepting it would mean silently reading a *different* id from docs.google.com. */
+  const byUrl = raw.match(/^(?:https?:\/\/)?docs\.google\.com\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/);
+  const id = byUrl?.[1] ?? (/^[a-zA-Z0-9-_]{20,}$/.test(raw) ? raw : undefined);
+  if (!id) return null;
+  const gid = raw.match(/[#&?]gid=([0-9]+)/)?.[1];
+  return { spreadsheetId: id, gid };
+}
+
+/** The CSV export address of one tab of a link-shared Google Sheet. */
+export function sheetCsvUrl(ref: SheetRef, gid = ref.gid): string {
+  return `https://docs.google.com/spreadsheets/d/${ref.spreadsheetId}/export?format=csv${gid ? `&gid=${gid}` : ''}`;
+}
+
+/** RFC 4180, including quoted fields with embedded commas and newlines — both occur in real sheets. */
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cur = '';
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quoted) {
+      if (c === '"') { if (text[i + 1] === '"') { cur += '"'; i++; } else quoted = false; }
+      else cur += c;
+    } else if (c === '"') quoted = true;
+    else if (c === ',') { row.push(cur); cur = ''; }
+    else if (c === '\n') { row.push(cur); rows.push(row); row = []; cur = ''; }
+    else if (c !== '\r') cur += c;
+  }
+  if (cur !== '' || row.length) { row.push(cur); rows.push(row); }
+  return rows;
+}
+
+/** CSV text → a table: the first non-blank row is the header; blank rows are dropped. */
+export function tableFromCsv(text: string): SheetTable | null {
+  const all = parseCsv(text).filter(r => r.some(c => c.trim() !== ''));
+  const [headers, ...rows] = all;
+  if (!headers || headers.every(h => h.trim() === '')) return null;
+  return dropControlRow({ headers: headers.map(h => h.trim()), rows });
+}
+
+/* Awesome Table's second row: a filter setting per column ("DateFilter - Hidden", "CategoryFilter",
+   "Hidden", "NoFilter"…), not data. */
+const CONTROL = /^(hidden|nofilter|[a-z]*filter( - hidden)?)$/i;
+
+/**
+ * **A sheet without its control row.** A sheet built for Awesome Table (Directory's base sheet is
+ * one) keeps a row of filter settings under the header. It is dropped when every filled cell in it is
+ * such a setting — a real row never is.
+ */
+export function dropControlRow(table: SheetTable): SheetTable {
+  const first = table.rows[0];
+  const filled = first?.map(c => c.trim()).filter(Boolean) ?? [];
+  return filled.length && filled.every(c => CONTROL.test(c)) ? { ...table, rows: table.rows.slice(1), firstRow: (table.firstRow ?? 2) + 1 } : table;
+}
+
+const needsQuotes = /[",\n\r]/;
+/** A table → CSV text that a spreadsheet opens as-is (and `tableFromCsv` reads back unchanged). */
+export function toCsv(table: SheetTable): string {
+  const cell = (v: string) => (needsQuotes.test(v) ? `"${v.replace(/"/g, '""')}"` : v);
+  return [table.headers, ...table.rows].map(r => r.map(cell).join(',')).join('\n');
+}

package/src/sheets/index.ts

@@ -0,0 +1,10 @@
+/**
+ * **Sheets as input** — a Google Sheet (or any CSV) read into any New component: its lists, its
+ * settings, Table and Grid's rows, Checklist's tasks. Pure; the read itself is the host's (see
+ * `csv.ts`).
+ */
+export { dropControlRow, parseCsv, parseSheetUrl, sheetCsvUrl, tableFromCsv, toCsv, type SheetRef, type SheetTable } from './csv';
+export { LIST_MAX_ITEMS, configFromSheet, humanHeader, typeOfKinds, typeOfValue, type SheetFieldType, sheetFromConfig, sheetTargets, targetLabel, type SheetMapping, type SheetReport, type SheetTarget } from './bind';
+export { CHECKLIST_LABELS, CHECKLIST_TYPES, checklistFromSheet, dataRowsFromSheet, sheetFromChecklist } from './records';
+export { applyChecklistSheet, applyRowsSheet, applySheet, describeNeed, sheetNeeds, type SheetApplyResult, type SheetIssue } from './apply';
+export { createSheetAdapter } from './adapter';