feat(react): CSV export on the surface, with docs and browser proof (#368)

* feat(react): CSV export on the surface, with docs

Slice 3. Three props mirroring clipboard — `csvOptions`, `onExport`, `saveFile`
— and `exportCsv(options?)` on the grid handle. This grid has no toolbar, so an
imperative method the consumer calls from their own button is the trigger.

`exportCsv` takes columns from the DRAWN order (never the `columns` prop),
passes the scope `resolveDataScope` computed rather than assuming "all", builds
`rowIds` from the selection when asked, and announces — saying so when the file
is partial.

Two things came out of review of the wiring and are worth naming:

- `onlySelected` and `rowIds` together used to merge `rowIds` last, so the
  caller's explicit set vanished with nothing said. That is the silent
  narrowing `serializeCsv` refuses for an unknown `columnIds`; it now throws
  rather than picking a winner.
- A SYMBOLIC all-selection (header checkbox, Cmd+A) leaves `selectedRowIds`
  empty, so it lands on the empty-selection branch and exports everything. That
  is the right answer, but it arrived by accident rather than by a rule — now
  stated in-source so a later change to either side is a decision.

Docs: `grid/export.mdx`, registered in `_nav.ts` and in the guard roster — the
options table bound to `PretableCsvOptions`, the omissions table bound to
`PretableCsvOmission` through the discriminant-union check. All four
registration mutations fail. Its `serializeCsv` fences are transcribed into a
compile-time fixture; the `<PretableSurface>` fence is registered as
untranscribed with a written reason, because the surface's generic inference
needs a row type that does NOT extend `Record<string, unknown>` while
`serializeCsv` needs exactly that, and one shared preamble cannot be both. That
API is covered by `csv-export-surface.test.tsx` instead.

1001 react tests, 369 website tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(website): prove CSV export downloads a real file in a real browser

jsdom can assert that `saveFile` got the right `PretableCsvFile`, and
`csv.test.ts` does so exhaustively. It cannot answer whether a browser accepts
the synthetic `<a download>` click as a download at all, whether it honours the
name we computed, or whether the bytes survive the Blob URL round trip. Each of
those is somewhere a green unit suite still ships a broken button.

The fixture leaves `saveFile` unset so `defaultSaveFile` itself is what runs.
Four assertions, all mutation-proven by breaking the fixture and watching the
matching test go red:

- Filename arrives exactly as built. Confirms the compact `20260813T202142Z`
  stamp is the right call: Chromium rewrites `:` to `_` on every OS, so a raw
  `toISOString()` would have been mangled here. (`name: "wrong"` → red.)
- Byte 0 is 0xEF. Without the BOM Excel reads UTF-8 in the OS legacy codepage
  and `Größe` becomes mojibake. (`bom: false` → byte 0 is 83 → red.)
- `=1+1` reaches disk apostrophe-prefixed while `-450` reaches it intact — both
  halves of the value-vouched rule in one file. (`escapeFormulas: false` → red.)
- `onlySelected` exports the two checked rows, and an empty selection exports
  everything rather than a zero-row file. (Dropping `onlySelected` → red.)

8 passed across chromium and webkit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(react): close four export defects review found, and a false guard excuse

Adversarial review of #368. Every item below was proven by a test that fails
first; the four behavioural ones are in `csv-export-surface.test.tsx`.

**The conflict refusal was watching one of two doors.** `onlySelected` +
`rowIds` threw only for a call-site `rowIds`; a `rowIds` on the surface's
`csvOptions` was overwritten silently — the exact silent narrowing the throw
exists to refuse. It now reads the merged value. This also fixes the second
half: with a surface `rowIds` set, an empty selection exported that other
subset rather than everything, so the button quietly downloaded someone else's
rows.

**A synchronous throw from `saveFile` bypassed the failure path.**
`Promise.resolve(saveFile(file))` evaluates the call before wrapping it, so a
sync throw escaped `exportCsv` with nothing warned, nothing announced, and the
rest of the click handler dead. `defaultSaveFile` is entirely synchronous DOM
work, so this is the shape a real failure takes. Caught around the call rather
than moved into a `.then` — the first attempt did exactly that and the suite
caught it: deferring delivery a microtask is wrong for `<a download>` (which is
chosen BECAUSE it survives an await, a property worth spending deliberately not
accidentally) and dangerous for the identical clipboard path, where `writeText`
IS activation-gated.

**`.then(ok).catch(err)` reported a delivered file as failed.** A consumer's
`exportAnnouncement` that throws was caught by the export's own failure branch:
file on disk, screen-reader user told otherwise. Split into `.then(ok, err)` —
which leaves the success branch to handle its own throw or it escapes as an
unhandled rejection, so it warns under its own distinct message.

The clipboard path had both bugs verbatim, being where the shape was copied
from. Fixed there too.

**A documented snippet that did not compile, behind an excuse that was false.**
The `<PretableSurface>` fence was exempt from transcription on the recorded
grounds that its row type could not extend `Record<string, unknown>`.
Transcribing it showed the constraint was never the problem: the snippet was
missing its explicit type argument and referenced an undeclared global. Both
fixed, the fence transcribed, `UNTRANSCRIBED_FENCES` now empty. Two mutations
kill it — a fixture that diverges from the page, and a fixture that stops
naming the fence at all.

That is the second time a guard escape hatch has been the thing that failed
rather than the guard, and the first where the written reason was itself wrong.

Also, smaller: `columnCount`'s TSDoc claimed to be the columns actually written
and is the columns requested, which an `onExport` returning a hand-built file
can contradict — stated, along with which fields ARE exact. `exportCsv` now
documents both throws and says a save failure is not one of them. Two e2e
comments asserted things the file disproves (the escaped field is not quoted;
the buttons are `disabled` pre-hydration), and the escaping assertion is now
the whole line, since `toContain` passed under both readings and so tested
neither. `csvOptions`/`onExport`/`saveFile` are now documented in prose and
listed beside their clipboard twins in the grid API reference.

Not fixed here, filed instead: `rowIds` is typed `ReadonlySet<PretableRowId>`
rather than the grid's `TRowId`, so a `Set<number>` on a string-id grid is
accepted and yields an empty selection. Making `PretableCsvOptions` generic is
a wider change than this PR should carry.

1023 react tests, 369 website tests, 8 e2e across chromium and webkit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changeset): record the clipboard half of the delivery fix

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: blove

.changeset/csv-export-surface.md

@@ -0,0 +1,27 @@
+---
+"@pretable/react": minor
+---
+
+Wire CSV export into `<PretableSurface>`.
+
+Three props mirroring the clipboard trio — `csvOptions`, `onExport` (return
+`null` to cancel) and `saveFile` — plus `exportCsv(options?)` on the grid handle
+`onGridReady` hands you, since this grid has no toolbar and the trigger belongs
+to the consumer's own button.
+
+`exportCsv` resolves columns from the DRAWN order, passes the scope
+`resolveDataScope` computed, and announces through the live region — including
+when the file is partial, which the announcement says out loud rather than
+leaving to `omissions`.
+
+`onlySelected` and `rowIds` are refused together. They are two ways to name the
+same row set, and merging one over the other made the caller's explicit set
+vanish with nothing said.
+
+Also fixes two defects on the **clipboard** path, which is where this code's
+shape was copied from and carried both faults verbatim: a `copyToClipboard`
+that threw synchronously escaped the failure branch entirely, and a
+`copyAnnouncement` that threw was reported as a failed copy. The clipboard
+write stays in the keystroke's own task — `writeText` is transient-activation
+gated, so deferring it even one microtask would put it outside the gesture that
+earned the permission.

apps/website/app/docs/__tests__/csv-export.types.tsx

@@ -0,0 +1,90 @@
+/**
+ * The code fences on `grid/export.mdx`, transcribed so `tsc --noEmit` compiles
+ * them. A documented snippet that does not compile is a documented lie, and
+ * MDX is not typechecked.
+ *
+ * Each `// docs-fence:` marker binds everything up to the next marker to the
+ * fence under that heading. The preamble above the first marker is prepended to
+ * every region, which is what lets several snippets share one import.
+ *
+ * The page's `<PretableSurface>` fence used to be exempt from this file, on
+ * the recorded grounds that its row type could not extend
+ * `Record<string, unknown>` while the `serializeCsv` fences require exactly
+ * that. Transcribing it proved the reason false: the constraint was never what
+ * broke it — the snippet was missing its explicit type argument and referenced
+ * an undeclared global. Both are fixed on the page, and the exemption is gone.
+ */
+import {
+  defaultSaveFile,
+  PretableSurface,
+  resolveDataScope,
+  serializeCsv,
+  type PretableColumn,
+  type PretableRowModelSnapshot,
+  type PretableSurfaceGrid,
+} from "@pretable/react";
+import { useRef } from "react";
+
+interface Position extends Record<string, unknown> {
+  id: string;
+  symbol: string;
+}
+
+declare const rowModelSnapshot: PretableRowModelSnapshot<
+  Position,
+  string,
+  readonly { readonly id: string }[]
+>;
+declare const grid: { getColumns: () => readonly PretableColumn<Position>[] };
+declare const dataHonesty: Parameters<typeof resolveDataScope>[0];
+declare const processing: Parameters<typeof resolveDataScope>[1];
+
+// docs-fence: grid/export.mdx#Getting a file
+const file = serializeCsv({
+  rowModelSnapshot,
+  columns: grid.getColumns(),
+  scope: resolveDataScope(dataHonesty, processing),
+});
+
+if (file) defaultSaveFile(file, { name: "positions" });
+
+// docs-fence: grid/export.mdx#Formula escaping
+serializeCsv({
+  rowModelSnapshot,
+  columns: grid.getColumns(),
+  scope: "all",
+  options: { escapeFormulas: (value) => value.startsWith("=") },
+});
+
+declare const columns: readonly PretableColumn<Position>[];
+
+// docs-fence: grid/export.mdx#Getting a file (fence 2)
+export function PositionGrid({ positions }: { positions: Position[] }) {
+  const grid = useRef<PretableSurfaceGrid<
+    Position,
+    string,
+    readonly PretableColumn<Position>[]
+  > | null>(null);
+
+  return (
+    <>
+      <button
+        onClick={() => grid.current?.exportCsv({ onlySelected: true })}
+        type="button"
+      >
+        Export selected
+      </button>
+      <PretableSurface<Position>
+        ariaLabel="Positions"
+        columns={columns}
+        getRowId={(row) => row.id}
+        onGridReady={(ready) => {
+          grid.current = ready;
+        }}
+        rowSelectionColumn={{ enabled: true }}
+        rows={positions}
+        viewportHeight={520}
+      />
+    </>
+  );
+}

apps/website/app/docs/_nav.ts

@@ -51,6 +51,7 @@ export const docsNav: DocsNavSection[] = [
         href: "/docs/grid/custom-rendering",
       },
       { title: "Density helpers", href: "/docs/grid/density-helpers" },
+      { title: "CSV export", href: "/docs/grid/export" },
       { title: "API reference", href: "/docs/grid/api-reference" },
     ],
   },

apps/website/app/fixtures/csv-export/page.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import {
+  PretableSurface,
+  type PretableColumn,
+  type PretableSurfaceGrid,
+} from "@pretable/react";
+import { useMemo, useRef, useState } from "react";
+
+/**
+ * Test fixture for `apps/website/e2e/csv-export.spec.ts`.
+ *
+ * The serializer and the filename builder are covered exhaustively by unit
+ * tests, and jsdom can assert that `saveFile` was called with the right bytes.
+ * What jsdom cannot do is the part users actually experience: whether a real
+ * browser accepts the synthetic `<a download>` click as a download at all,
+ * whether it honours the filename we computed, and whether the bytes that
+ * reach disk still carry the UTF-8 BOM and CRLF line endings once a `Blob`
+ * URL has round-tripped through the download machinery.
+ *
+ * So this route deliberately leaves `saveFile` unset — `defaultSaveFile` is
+ * the thing under test — and the spec reads the file Chromium wrote.
+ *
+ * Deliberately not part of the product surface; `app/fixtures/layout.tsx`
+ * keeps it out of search engines.
+ */
+
+interface PositionRow {
+  id: string;
+  symbol: string;
+  desk: string;
+  note: string;
+  qty: number;
+}
+
+const ROWS: PositionRow[] = [
+  { id: "p1", symbol: "AAPL", desk: "Equity", note: "core", qty: 1200 },
+  // A leading `=` is the formula vector; escaping must reach disk, not just
+  // the serializer's return value.
+  { id: "p2", symbol: "MSFT", desk: "Equity", note: "=1+1", qty: 800 },
+  // A negative number must NOT be escaped — the Jira/MUI bug this design
+  // exists to avoid. It is a real `number`, so it is exempt by JS type.
+  { id: "p3", symbol: "NVDA", desk: "Equity", note: "hedge", qty: -450 },
+  // A comma and a quote force RFC 4180 quoting; a non-ASCII character proves
+  // the BOM and the encoding survive the Blob round trip.
+  {
+    id: "p4",
+    symbol: "SAP",
+    desk: "Macro",
+    note: 'Frankfurt, "Größe"',
+    qty: 300,
+  },
+];
+
+const COLUMNS: PretableColumn<PositionRow>[] = [
+  { id: "symbol", header: "Symbol", widthPx: 120 },
+  { id: "desk", header: "Desk", widthPx: 140 },
+  { id: "note", header: "Note", widthPx: 220 },
+  { id: "qty", header: "Qty", type: "number", widthPx: 120 },
+];
+
+export default function CsvExportFixturePage() {
+  const rows = useMemo(() => ROWS, []);
+  const columns = useMemo(() => COLUMNS, []);
+  const gridRef = useRef<PretableSurfaceGrid<
+    PositionRow,
+    string,
+    readonly PretableColumn<PositionRow>[]
+  > | null>(null);
+  const [ready, setReady] = useState(false);
+
+  return (
+    <main style={{ padding: 24 }}>
+      <h1 style={{ marginBottom: 12 }}>CSV export fixture</h1>
+      <p>
+        <button
+          data-testid="export-all"
+          disabled={!ready}
+          onClick={() => gridRef.current?.exportCsv()}
+          type="button"
+        >
+          Export
+        </button>{" "}
+        <button
+          data-testid="export-selected"
+          disabled={!ready}
+          onClick={() => gridRef.current?.exportCsv({ onlySelected: true })}
+          type="button"
+        >
+          Export selected
+        </button>
+      </p>
+      <PretableSurface<PositionRow>
+        ariaLabel="Positions"
+        columns={columns}
+        getRowId={(row) => row.id}
+        onGridReady={(grid) => {
+          gridRef.current = grid;
+          setReady(true);
+        }}
+        rowSelectionColumn={{ enabled: true, headerCheckbox: true }}
+        rows={rows}
+        viewportHeight={300}
+      />
+    </main>
+  );
+}

apps/website/content/docs/grid/api-reference.mdx

@@ -59,7 +59,7 @@ Both helpers return native `Intl.NumberFormatOptions` and are exported from `@pr
 
 Rows with a conventional string or number `id` do not require `getRowId`. Otherwise pass a stable explicit accessor. Identity survives row-array replacements and is used by selection, focus, editing, expansion, and transactions.
 
-Important shared props include `ariaLabel`, `viewportHeight`, `overscan`, `locale`, `state`, `onSelectionChange`, `onFocusChange`, `onPaste`, `onCopy`, `copyToClipboard`, `groupPanel`, `groupColumn`, `hideGroupedColumns`, and cell/header/row render hooks. Rows mode alone accepts the exact controlled `query`/`onQueryChange` pair, `onRowChange`, `initialExpansion`, and `aggregateFilteredRows`. Explicit-model mode alone accepts `beforeRowChange`.
+Important shared props include `ariaLabel`, `viewportHeight`, `overscan`, `locale`, `state`, `onSelectionChange`, `onFocusChange`, `onPaste`, `onCopy`, `copyToClipboard`, `csvOptions`, `onExport`, `saveFile`, `groupPanel`, `groupColumn`, `hideGroupedColumns`, and cell/header/row render hooks. Rows mode alone accepts the exact controlled `query`/`onQueryChange` pair, `onRowChange`, `initialExpansion`, and `aggregateFilteredRows`. Explicit-model mode alone accepts `beforeRowChange`.
 
 The experimental `processing`, `resultMeta`, `dataState`, and `renderBodyState` props describe external filter/sort authority, total and dataset identity, and consumer-owned loading/error presentation. They do not move row or query ownership into the UI grid.