@x12i/data 1.0.0 → 1.1.0

package/README.md

@@ -1,38 +1,213 @@
 # @x12i/data
 
-Data grid contracts for the Unified UI Kit.
+An accessible, virtualized data grid for the Unified UI Kit, and the headless
+engine it is built on.
 
-> **Status: foundation.** This package ships the types that apps, reports and
-> charts will depend on. The `Table` and `DataGrid` components are not built yet.
+- **`DataGrid`**: sort, filter, quick search, group and aggregate, resize,
+  reorder, hide and pin columns, row selection, row detail panels, inline
+  editing with rollback, totals, pagination, saved views, CSV export and copy.
+  Rows and columns are virtualized. Server mode loads rows in blocks.
+- **Headless engine**: the same sorting, filtering, grouping, selection,
+  keyboard model, CSV, saved views and server block store as plain functions.
+  No React, no DOM, safe on the server.
 
-```ts
-import { defineColumns, type ServerDataSource } from "@x12i/data";
+It is styled by kit tokens only (`--kit-*`), uses logical CSS properties, and
+adapts to density, right-to-left text, high contrast and reduced motion.
+
+## Install
+
+```sh
+pnpm add @x12i/data @x12i/ui @x12i/themes react react-dom
+```
+
+```css
+@import "@x12i/themes/themes.css";
+@import "@x12i/ui/styles.css";
+@import "@x12i/data/styles.css";
+```
+
+`@x12i/ui` is a peer dependency of the React entry only (the grid uses its
+`Button`, `IconButton`, `Badge`, `Spinner` and `VisuallyHidden`). If you only
+use the headless entry you do not need React or `@x12i/ui`. The package's own
+dependencies (`@x12i/icons`, `@x12i/tokens`, `@tanstack/react-virtual`) install
+with it.
+
+## Two entry points
+
+| Import | What it is | Needs |
+| --- | --- | --- |
+| `@x12i/data` | The headless engine and all the types. | Nothing. No React, no DOM. |
+| `@x12i/data/react` | `DataGrid`, `Pagination`, `useGridState`, `useSavedViews`. | React 19, `@x12i/ui`. |
+| `@x12i/data/styles.css` | The grid's stylesheet. | The kit's theme CSS for the token values. |
+
+`@x12i/data/react` starts with a `"use client"` directive, so a Next.js server
+component can import it and the grid becomes a client component. The root entry
+has no directive and imports on the server as it is.
 
-type Order = { id: string; customer: string; total: number };
+**Server rendering.** `DataGrid` renders on the server: the first paint holds a
+window of rows and columns (about two dozen rows at the default height), not an
+empty box, and the client takes over from there. Browser-only work (measuring
+the row height, observing the size, clipboard, downloads) runs in effects or on
+user action. `pnpm --filter @x12i/data run smoke:ssr` renders the built package
+with a 500-row grid in Node, without a DOM, and checks that only a window of the
+rows ended up in the markup.
 
-export const columns = defineColumns<Order>([
-  { id: "customer", header: "Customer", field: "customer", sortable: true },
-  { id: "total", header: "Total", field: "total", cellType: "currency" },
-]);
+## Examples
 
-export const orders: ServerDataSource<Order> = {
-  async getRows({ startRow, endRow, sort, filter }, { signal } = {}) {
-    // Call your API and return { rows, total }.
-    return { rows: [], total: 0 };
+### A grid with client-side data
+
+```tsx
+import { DataGrid, type DataGridColumn } from "@x12i/data/react";
+
+type Order = { id: string; customer: string; status: "open" | "paid" | "late"; total: number; placed: string };
+
+const columns: DataGridColumn<Order>[] = [
+  { id: "id", header: "Order", field: "id", width: 120, pinned: "start" },
+  { id: "customer", header: "Customer", field: "customer", filterable: true },
+  {
+    id: "status",
+    header: "Status",
+    field: "status",
+    cellType: "status",
+    options: [
+      { value: "open", label: "Open", tone: "info" },
+      { value: "paid", label: "Paid", tone: "success" },
+      { value: "late", label: "Late", tone: "danger" },
+    ],
+  },
+  { id: "total", header: "Total", field: "total", cellType: "currency", currency: "EUR", aggregate: "sum", editable: true },
+  { id: "placed", header: "Placed", field: "placed", cellType: "date", filterable: true },
+];
+
+export function Orders({ rows }: { rows: Order[] }) {
+  return (
+    <DataGrid
+      columns={columns}
+      rows={rows}
+      getRowId={(row) => row.id}
+      aria-label="Orders"
+      selectionMode="multiple"
+      showTotals
+      height={480}
+      locale="de-DE"
+      onCellEdit={async ({ rowId, column, value }) => {
+        await saveOrderField(rowId, column.id, value); // your API call; throw to roll the edit back
+      }}
+    />
+  );
+}
+```
+
+The grid sorts, filters, groups and pages `rows` itself. It never changes
+`rows`: an edit is shown at once, `onCellEdit` persists it, and when it throws
+the cell goes back to the old value and says so. Give the grid new `rows` (for
+example after a refetch) and the pending edits are dropped.
+
+Every piece of state works uncontrolled (`defaultSort`, `defaultFilter`, ...) or
+controlled (`sort` + `onSortChange`, ...). `useGridState({ columns })` holds all
+of it in one hook when you want to read it, put it in the URL or reset it:
+
+```tsx
+const state = useGridState({ columns });
+<DataGrid columns={columns} rows={rows} getRowId={getRowId} aria-label="Orders" {...state.props} />;
+state.reset();
+```
+
+### A server-side grid
+
+Pass a `dataSource` instead of `rows`. The grid asks for blocks of rows as the
+user scrolls, sends the sort, filters and quick search to the server, and shows
+placeholder rows while a block loads.
+
+```tsx
+import { DataGrid } from "@x12i/data/react";
+import type { ServerDataSource } from "@x12i/data";
+
+// Create it once (module level or useMemo): a new data source throws the loaded rows away.
+const orders: ServerDataSource<Order> = {
+  async getRows({ startRow, endRow, sort, filter, quickFilter }, { signal } = {}) {
+    const query = new URLSearchParams({
+      start: String(startRow),
+      end: String(endRow),
+      sort: JSON.stringify(sort), // [{ field: "total", direction: "desc" }]
+      filter: JSON.stringify(filter), // [{ field: "status", operator: "in", value: ["late"] }]
+      q: quickFilter ?? "",
+    });
+    const response = await fetch(`/api/orders?${query}`, { signal });
+    if (!response.ok) throw new Error(`Orders failed: ${response.status}`);
+    const { rows, total } = await response.json();
+    return { rows, total }; // `total` sizes the scrollbar
   },
 };
+
+<DataGrid columns={columns} dataSource={orders} getRowId={(row) => row.id} aria-label="Orders" blockSize={100} />;
 ```
 
-## Saved views
+What the grid does for you in server mode:
 
-`SavedView` is versioned JSON. `parseSavedView(value)` reads one from untrusted
-storage (local storage, a URL, a server) and returns `null` for anything this
-version does not understand, so a bad or newer record is ignored instead of
-crashing the grid. `SavedViewStore` is the small interface an app implements to
-keep views: `list`, `load`, `save`, `delete`.
+- **Blocks.** One request per `blockSize` rows, only for blocks near the visible
+  window, never twice for the same block. Rows that have not arrived show a
+  skeleton row (`aria-busy`).
+- **Abort.** Every request gets an `AbortSignal`. A new sort or filter, a reload
+  and unmounting abort what is in flight. Pass `signal` to `fetch`; an aborted
+  request is ignored, not shown as an error.
+- **Stale while revalidating.** After a sort or filter change the rows on screen
+  stay (dimmed, `data-stale`) until the new blocks arrive, instead of flashing empty.
+- **Errors.** A failed block shows an alert with a retry button; blocks that did
+  load stay visible. The rows of a failed block say "Row could not be loaded"
+  and stop claiming to be busy.
+- **Pagination.** `paginated` makes each page one block and shows the footer.
+- **Cursor APIs.** Return `nextCursor` with an answer and the following block is
+  requested with `request.cursor` set to it (`null` for the first block). Blocks
+  then load in order, so jumping far ahead loads the blocks in between.
+- **Totals, selection, export.** `showTotals` plus `totals` (keyed by column id)
+  shows totals you computed on the server. Select all selects "everything except
+  these" without loading every row. Export reads every row the query matches,
+  block after block.
+- **Column names.** Requests name columns by `column.field ?? column.id`.
+- `ref.current.reload()` drops the loaded rows and fetches again.
 
-`@x12i/flowix-ui` has one that keeps views as Flowix facts, so they follow the
-user across devices and keep a revision history:
+`createClientDataSource(rows, columns, { latency, fail })` is a data source over
+an array that behaves like a server (it honors the abort signal), for demos and
+tests.
+
+### Saved views
+
+A saved view is versioned JSON: column order, widths, visibility and pinning,
+plus sort, filters and grouping. `useSavedViews` saves, lists and applies them
+against any `SavedViewStore`.
+
+```tsx
+import { createLocalStorageSavedViewStore } from "@x12i/data";
+import { DataGrid, useGridState, useSavedViews } from "@x12i/data/react";
+
+const store = createLocalStorageSavedViewStore({ key: "orders-views" }); // memory-only where there is no localStorage
+
+function Orders({ rows }: { rows: Order[] }) {
+  const state = useGridState({ columns });
+  const views = useSavedViews({ store, columns, grid: state });
+  return (
+    <>
+      <button onClick={() => void views.save("mine", "My view")}>Save view</button>
+      <select value={views.activeId ?? ""} onChange={(event) => void views.apply(event.target.value)}>
+        <option value="" disabled>Views</option>
+        {views.views.map((view) => (
+          <option key={view.id} value={view.id}>{view.name ?? view.id}</option>
+        ))}
+      </select>
+      <DataGrid columns={columns} rows={rows} getRowId={(row) => row.id} aria-label="Orders" {...state.props} />
+    </>
+  );
+}
+```
+
+`parseSavedView(value)` reads a view from untrusted storage and returns `null`
+for anything this version does not understand, so a bad or newer record is
+skipped instead of crashing the grid. A view saved against other columns still
+applies: ids the grid does not have are ignored. Implement `SavedViewStore`
+(`list`, `load`, `save`, `delete`) to keep views in your API.
+`@x12i/flowix-ui` has one that keeps each view as a Flowix fact, with every save
+kept as an immutable revision:
 
 ```ts
 import { createFlowixSavedViewStore } from "@x12i/flowix-ui/stores";
@@ -40,13 +215,335 @@ import { createFlowixSavedViewStore } from "@x12i/flowix-ui/stores";
 const views = createFlowixSavedViewStore(flowix, { namespace: "grid-views" });
 ```
 
+### CSV export and copy
+
+The toolbar has an Export CSV button (it downloads `export.csv`, or calls
+`onExport(csv)` with the text if you pass it; the file starts with a byte order
+mark so Excel reads non-ASCII text) and, while rows are selected, a Copy button.
+`toolbar={{ export: false }}` removes one of them, `toolbar={false}` all of them.
+The same things are available in code:
+
+```tsx
+const ref = useRef<DataGridHandle<Order>>(null);
+
+<DataGrid ref={ref} columns={columns} rows={rows} getRowId={getRowId} aria-label="Orders" exportFileName="orders.csv" />;
+
+// The current view: every filtered row (all pages), in sort order, visible columns only.
+const csv = await ref.current?.exportCsv({ values: "raw", bom: true });
+await ref.current?.copySelection(); // selected rows (or the focused cell) as tab-separated text
+```
+
+Headless, for any rows and columns, on the server too:
+
+```ts
+import { gridToCsv, gridToTsv } from "@x12i/data";
+
+const csv = gridToCsv(rows, columns, { locale: "en-US", bom: true });
+```
+
+CSV follows RFC 4180 (CRLF, quoted fields, doubled quotes). Cells a spreadsheet
+would run as a formula (a leading `=`, `@`, tab, or a `+`/`-` that is not a plain
+number) get an apostrophe prefix, so an exported cell cannot execute. Values are
+written as the grid shows them; `values: "raw"` writes the stored values instead.
+`bom: true` adds the byte order mark Excel needs for non-ASCII text.
+
+## Column definition reference
+
+`ColumnDef<Row>` (headless) is the base; `DataGridColumn<Row>` adds the React
+renderers. Only `id` and `header` are required.
+
+| Property | Type | Meaning |
+| --- | --- | --- |
+| `id` | `string` | Stable identifier. Used by state, saved views and `columnVisibility` and friends. |
+| `header` | `string` | Header text. Pass a translated string. |
+| `field` | `keyof Row` | Property to read. Also what server requests call the column. |
+| `accessor` | `(row) => unknown` | Reads the value when `field` is not enough (a nested property). |
+| `cellType` | `text` `number` `currency` `percent` `date` `datetime` `boolean` `status` `avatar` `progress` `sparkline` `link` `tags` `actions` `custom` | How the cell renders, formats, aligns, sorts, filters and exports. |
+| `format` | `string` | Intl-based format name by type: number `integer` `compact` `decimal:2` `unit:kilobyte`; currency an ISO code; percent `whole`; date `short` `medium` `long` `full` `iso`. |
+| `currency` / `numberFormat` / `dateFormat` | `string` / `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` | Direct `Intl` control. `currency` defaults to `USD`. |
+| `formatter` | `(value, row) => string` | Text for a value. Used by the cell, CSV, copy, quick search and screen readers. |
+| `comparator` | `(a, b, rowA, rowB) => number` | Replaces the default comparison (numbers numerically, dates by time, text with `Intl.Collator`). |
+| `width` / `minWidth` / `maxWidth` | `number` | Pixels. |
+| `align` | `start` `center` `end` | Defaults to `end` for `number`, `currency` and `percent`, `center` for `boolean`, `start` otherwise. |
+| `pinned` | `start` `end` | Start state. Logical sides, so it follows `dir`. |
+| `hidden` | `boolean` | Hidden until the user shows it. |
+| `hideable` / `groupable` / `searchable` | `boolean` | `false` removes the column from the visibility menu, grouping, quick search. |
+| `sortable` / `filterable` / `resizable` | `boolean` | Sortable (except `actions` and `custom` cells) and resizable by default; filterable only when set. |
+| `filterType` | `text` `number` `date` `enum` `boolean` | The filter UI and operators. Derived from `cellType` when absent. |
+| `options` | `{ value, label, tone? }[]` | Choices for `status` cells, enum filters and select editors. |
+| `aggregate` | `sum` `avg` `min` `max` `count` or `(values, rows) => unknown` | Shown in group rows and the totals row. |
+| `editable` / `canEdit` | `boolean` / `(row) => boolean` | Inline editing, and per-row editability on top of it. |
+| `editor` | `text` `number` `select` `boolean` `date` | Defaults from `cellType`. Boolean cells toggle in place. |
+| `validate` | `(value, row) => string \| null` | Return a message to reject an edit. |
+| `parseValue` | `(input, row) => unknown` | Turns the editor's text into a value. |
+| `group` | `string` | Adjacent columns with the same `group` share a header above them. |
+| `progressMax` | `number` | Maximum of `progress` cells. Default 100. |
+| `meta` | `Record<string, unknown>` | Yours. The grid never reads it. |
+| `cell` | `(context) => ReactNode` | Replaces the cell. Runs for every rendered cell, so keep it cheap. |
+| `headerCell` | `(context) => ReactNode` | Replaces the header label. The sort, filter and menu buttons stay. |
+| `footerCell` | `(context) => ReactNode` | Replaces the totals-row content. |
+| `actions` | `(row) => RowAction[]` | Menu entries for `actions` cells. |
+| `href` | `(row) => string \| undefined` | Target of `link` cells. Without it the cell's string value is the target. A value becomes an anchor only when it is `http`, `https`, `mailto`, `tel` or a relative path; a target from `href` may be anything except `javascript:`, `data:` and `vbscript:`. Otherwise the text is not linked. |
+
+### `DataGrid` props
+
+| Group | Props |
+| --- | --- |
+| Data | `columns`, `rows` (client) or `dataSource` (server), `getRowId` (required), `blockSize` (server, default 100), `totals` (server), `loading`, `error`, `onRetry` (client) |
+| Naming | `aria-label` or `aria-labelledby` (give one), `className`, `ref` |
+| Layout | `height`, `maxHeight` (default 640 px), `density`, `dir`, `estimateRowHeight`, `virtualize` (`"auto"`), `overscan`, `columnOverscan` |
+| Language | `locale`, `timeZone`, `messages` |
+| Sort, filter, group | `sort`, `filter`, `quickFilter`, `group`, `groupExpansion`, `groupsExpandedByDefault`, `multiSort`, `quickFilterDelay`; each with `default…` and `on…Change` |
+| Columns | `columnOrder`, `columnVisibility`, `columnSizing`, `columnPinning`; each with `default…` and `on…Change` |
+| Selection, detail | `selectionMode` (`none` `single` `multiple`), `selection`, `isRowSelectable`, `renderDetail`, `detailHeight`, `isRowExpandable`, `expanded`, `onRowClick`; with `default…` and `on…Change` for `selection` and `expanded` |
+| Paging | `paginated`, `pagination`, `pageSizeOptions`; with `default…` and `on…Change` for `pagination` |
+| Editing | `onCellEdit` |
+| Chrome | `toolbar` (`false`, or `{ search, columns, export, copy }` with each defaulting to `true`), `toolbarStart`, `toolbarEnd`, `showTotals`, `slots` (`empty`, `loading`, `error`), `onExport`, `exportFileName` |
+
+`DataGridHandle` (the `ref`): `scrollToIndex`, `scrollToRow`, `focusCell`,
+`exportCsv`, `copySelection`, `getSelectedRows`, `reload`, `getViewState`.
+
+`Pagination` is also exported on its own, for any list: `page` (zero-based),
+`pageSize`, `total` (or `null` while unknown), `onPageChange`, and optionally
+`pageSizeOptions` with `onPageSizeChange`, `messages`, `locale`, `disabled`.
+
+```tsx
+<Pagination page={page} pageSize={25} total={rows.length} onPageChange={setPage} locale="en-US" />
+```
+
+## Keyboard map
+
+The grid is one tab stop (roving tabindex): Tab moves into it at the last cell
+you were on, and the next Tab leaves it. Row 0 is the header row.
+
+| Key | Where | What it does |
+| --- | --- | --- |
+| Arrow keys | Any cell | Move one cell. They stop at the edges. Left and Right swap in right-to-left. |
+| Home / End | Any cell | First / last cell of the row. |
+| Ctrl+Home / Ctrl+End | Any cell | First / last cell of the grid. |
+| Page Up / Page Down | Any cell | Move by the number of visible rows. |
+| Enter or Space | Header | Sort by the column. With Shift, add it to the sort (multi-sort). |
+| Alt+Down, Menu key, Shift+F10 | Header | Open the column menu: sort, filter, group, pin, move, hide. Arrows, Home, End move; Enter selects; Escape closes and returns focus. |
+| Ctrl+Shift+Left / Right | Header | Move the column earlier / later (in reading order). |
+| Shift+Left / Right | Header | Make the column narrower / wider by 16 px. |
+| Enter or F2 | Editable cell | Start editing. |
+| Enter / Escape | Editor | Commit / cancel. Leaving the field commits. A value the column rejects keeps the editor open with the message on Enter; on leaving the field the edit is dropped and the message is announced. |
+| Space | Body cell | Toggle the row's selection (Shift+Space extends the range from the last toggled row). In a selection checkbox, expander or editable boolean cell it activates that control. |
+| Enter | Cell with a control | Activates the link, expander, checkbox or row-actions menu in the cell. |
+| Shift+Up / Down | Body cell, `multiple` | Extend the selection by one row. |
+| Ctrl+A (Cmd+A) | Body cell, `multiple` | Select every row. |
+| Ctrl+C (Cmd+C) | Body cell | Copy the selected rows, or the focused cell, as tab-separated text. |
+| Enter or Space | Group row | Expand or collapse the group. |
+| Right / Left | Group row, first column | Expand / collapse the group (swapped in right-to-left). |
+| Escape | Quick search | Clears the text. |
+
+Column reordering also works by dragging a header with the pointer; the dragged
+column lands before or after the one you drop on, inside its own pinned zone.
+
+## Accessibility
+
+- **Roles and counts.** `role="grid"` (a `treegrid` with `aria-level` and
+  `aria-expanded` while grouped), `aria-rowcount` and `aria-rowindex` that count
+  all rows even though only a window is in the DOM, `aria-colcount` and
+  `aria-colindex`. Column groups use `aria-colspan`. A server grid reports
+  `aria-rowcount="-1"` until the server has said how many rows there are.
+- **Sorting.** `aria-sort` on the sorted header; a multi-sort shows each
+  column's priority number, with a text alternative ("Sort priority 2") for
+  screen readers.
+- **Selection.** `aria-multiselectable` on the grid and `aria-selected` on rows;
+  native checkboxes with names; the select-all box is indeterminate for a
+  partial selection.
+- **Live region.** A polite `role="status"` region announces sorting ("Sorted
+  by Total, descending. 120 rows."), filtering ("31 rows match the filters."),
+  grouping, selection counts, column moves, hides, pins and resizes, copies,
+  saved or failed edits, and edit validation messages. In server mode the
+  filter count waits for the new answer, so it never reports the old total.
+- **Busy states.** `aria-busy` on the grid while loading and on placeholder
+  rows; the empty state, the loading state and the error (`role="alert"`) are
+  all text, not just pictures.
+- **Focus.** Visible focus rings from tokens. Closing a menu or popover with
+  Escape or by choosing something returns focus to the header cell. A moved or
+  pinned column keeps the cursor.
+- **Popups.** The column menu is `role="menu"` with `menuitem` and
+  `menuitemcheckbox`; the filter editor is a `role="dialog"` with labelled
+  fields. Both sit in the browser's top layer where it exists, so the grid's
+  scroll area never clips them, and close on Escape, on a press outside and
+  when focus leaves.
+- **Resize and reorder.** The resize handle is a `role="separator"` with
+  `aria-valuenow`, `-min` and `-max`; its keys (arrows, Shift for larger steps,
+  Home and End) work once it has focus, and the header cell has Shift+Arrow.
+  Double-click resets the width. Reordering by drag has a keyboard shortcut and
+  menu items as alternatives.
+- **Forced colors and reduced motion.** Selection, focus, pinned edges, the
+  progress bars and the drop marker use system colors under `forced-colors`;
+  skeleton pulses, the loading bar and transitions stop under
+  `prefers-reduced-motion`.
+
+The test suite runs `vitest-axe` over the grid in its main states (plain,
+selection with toolbar, totals and filter chips, loading, empty, error, grouped,
+every cell type, paginated, inside a `ThemeProvider`, with a filter popover or a
+column menu open, and in server mode while loading, loaded, with placeholder rows
+and failed) and expects zero violations. Color contrast is not checked there
+(jsdom has no layout or computed colors); it rests on the kit's token pairs.
+Automated checks catch a lot, not everything: test with a screen reader in your
+own context.
+
+## Theming and density
+
+The stylesheet reads kit tokens only: surface, text, border, accent, selection
+and danger colors, spacing, radii, type sizes, motion durations, z-indexes. It
+declares no colors or lengths of its own, wraps every selector in `:where()` (so
+your CSS wins at any specificity) and uses logical properties
+(`inset-inline-start`, `padding-inline`, `border-block-end`). Pinned columns are
+`position: sticky` with `inset-inline-start` / `-end`, so they flip in RTL.
+
+- **Theme.** Wrap the app in `ThemeProvider` from `@x12i/ui`; the grid follows
+  light, dark and high contrast.
+- **Density.** The row height is the `--kit-grid-row-height` token, which follows
+  the kit's `data-density`. Use `DensityProvider` above the grid, or the
+  `density` prop for one grid.
+- **Hooks for your CSS.** Everything has a `data-kit` name and state attributes:
+
+| Attribute | On | Meaning |
+| --- | --- | --- |
+| `data-kit="data-grid"` | root | `data-density`, `data-loading`, `data-stale`, `data-server` |
+| `data-kit="data-grid-scroller"` | the `role="grid"` element | `data-virtual-rows`, `data-virtual-columns` |
+| `data-kit="data-grid-header-cell"` | header cell | `data-column` (the id), `data-align`, `data-sorted` (`asc` `desc`), `data-filtered`, `data-pinned` (`start` `end`), `data-pinned-edge`, `data-resizing`, `data-dragging`, `data-drop` (`before` `after`) |
+| `data-kit="data-grid-row"` | row | `data-kind` (`data` `group` `detail` `placeholder`), `data-index`, `data-row-id`, `data-selected`, `data-expanded`, `data-failed` |
+| `data-kit="data-grid-cell"` | cell | `data-type`, `data-align`, `data-pinned`, `data-pinned-edge`, `data-editable`, `data-editing`, `data-dirty`, `data-pending`, `data-error` |
+| `data-kit="data-grid-overlay"` | loading, empty and error layers | `data-state` (`loading` `empty` `error`) |
+| `data-grid-toolbar`, `-chips`, `-pagination`, `-header`, `-body`, `-footer`, `-live` | the other parts | |
+
+Other `data-kit` names include `-sort`, `-resizer`, `-menu`, `-popover`,
+`-filter`, `-progress`, `-tags`, `-skeleton` and `-detail`.
+
+## Languages and formats
+
+There is no English in the code that is not in `defaultMessages`. Pass `messages`
+with only the strings you change; the rest keep their defaults.
+
+```tsx
+<DataGrid
+  locale="fr-FR"
+  messages={{
+    loading: "Chargement des lignes",
+    empty: "Aucune ligne",
+    announceFiltered: "{count, plural, =0 {Aucune ligne ne correspond} one {# ligne correspond} other {# lignes correspondent}}.",
+  }}
+  /* ... */
+/>
+```
+
+Messages use a small ICU subset: `{name}`, `{n, plural, =0 {...} one {...} other {...}}`
+with `#`, and `{x, select, ...}`, with the plural rules of `locale`. Numbers,
+currency, percent, dates and times go through `Intl` with `locale` (and
+`timeZone` for date-times); `YYYY-MM-DD` strings are calendar days and do not
+shift with the time zone. Text sorts and searches with `Intl.Collator`, ignoring
+case and accents, with numbers compared as numbers. `dir` (or the document's
+direction) mirrors the layout; no code path uses left or right.
+
+`Pagination` takes the same `messages` and `locale`. `resolveMessages(overrides)`
+and `defaultMessages` are exported from both entries.
+
+## Performance
+
+- **Virtualization.** `virtualize="auto"` windows rows above 100 and center
+  columns above 24 (`@tanstack/react-virtual`). The rows in the DOM are the
+  visible ones plus `overscan` (8) either side, whatever the data size. The cell
+  with the cursor stays mounted so the grid keeps its tab stop. Pinned columns
+  are always rendered; column virtualization is off when column groups are used.
+  Below the thresholds nothing is windowed, so a short grid is plain markup.
+- **Stable rendering.** Rows and header cells are memoized. Keep `columns`,
+  `messages` and `dataSource` stable (module level or `useMemo`), because a new
+  `columns` array recomputes the layout and a new `dataSource` reloads. Inline
+  `cell` renderers run per rendered cell, so keep them cheap.
+- **The engine.** Sorting, filtering and grouping work on arrays of row indexes
+  and compile each column's comparison and predicate once. Measured on one
+  developer machine (Node, 100,000 rows, 6 columns): filter on three columns
+  38 ms; sort by one column 40 ms, by three columns 322 ms; filter then sort
+  61 ms; build the search index 384 ms (once per `rows`), then a quick search
+  13 ms; group by two columns 19 ms; CSV of the full set 392 ms. The test suite
+  guards these with generous bounds to catch accidental quadratic work.
+- **Client mode keeps every row in memory** and recomputes the view when `rows`
+  or the sort, filters or grouping change. Past a few hundred thousand rows, or
+  whenever the rows live on a server anyway, use server mode: the grid then only
+  holds the blocks it has been asked to show.
+- **Quick search** in client mode builds its index lazily, on the first search
+  after `rows` changes.
+- **Row height is fixed** (from the density token), which is what makes the
+  window cheap. Only detail panels are measured.
+
+## Headless engine
+
+Everything the grid computes is a plain function of the root entry:
+
+| Area | Exports |
+| --- | --- |
+| Columns | `defineColumns`, `getColumnValue`, `indexColumns`, `isSortable`, `isFilterable`, `isEditable`, `isResizable`, `resolveColumnAlign`, `resolveFilterType`, `resolveEditor` |
+| Sorting | `sortRows`, `sortIndexes`, `compareValues`, `createCollator` |
+| Filtering | `filterIndexes`, `matchesFilter`, `createValuePredicate`, `createSearchIndex`, `parseQuickFilter`, `operatorsFor`, `distinctValues` |
+| Grouping, aggregates | `buildGroupTree`, `buildDisplayRows`, `computeViewIndexes`, `aggregateValues`, `computeAggregate`, `computeAggregates` |
+| Formatting | `createCellFormatter`, `formatCellValue`, `formatMessage`, `defaultMessages`, `resolveMessages` |
+| Selection | `createSelection`, `toggleRow`, `selectRange`, `selectAll`, `selectAllExceptNone`, `isSelected`, `countSelected`, `serializeSelection`, `deserializeSelection` |
+| Keyboard | `navigate`, `clampNav`, `isNavigationKey` |
+| View state | `createViewState`, `layoutColumns`, `moveColumn`, `moveColumnTo`, `resizeColumn`, `setPinning`, `toggleSort`, `setSort`, `setColumnFilter`, `toggleGroup` |
+| Saved views | `captureView`, `applySavedView`, `parseSavedView`, `createMemorySavedViewStore`, `createLocalStorageSavedViewStore` |
+| Server | `createServerRowStore`, `createClientDataSource`, `toServerQuery`, `fromServerQuery`, `createAbortError`, `isAbortError` |
+| Export | `gridToCsv`, `gridToTsv`, `parseDelimited`, `escapeCsvField` |
+
 `@x12i/records` turns the same column definitions into a Fieldkit `FieldMap`
 (`fieldMapFromColumns`), so the detail view of a row uses the grid's headers.
 
-## Planned engine
+## Design decisions
+
+- **A small engine of our own, plus TanStack Virtual.** Sorting, filtering,
+  grouping and the row pipeline are plain functions over arrays of row indexes,
+  so they run unchanged on the server, in tests and in the component, and so the
+  keyboard model and server cache are testable without a DOM. Windowing is
+  `@tanstack/react-virtual` (MIT). TanStack Table is not used.
+- **Controls are private.** The grid's checkbox, select, text input, menu and
+  popover are small internal components over native elements. The kit's `ui`
+  components it uses are `Button`, `IconButton`, `Badge`, `Spinner`,
+  `VisuallyHidden`, and icons come from `@x12i/icons`.
+- **The grid does not own your rows.** Edits are optimistic overrides until your
+  `onCellEdit` settles, and they do not re-run sort or filter until you hand over
+  new `rows`; editing a value does not make the row jump away under the cursor.
+- **Server rows are keyed by place, not id.** While stale blocks wait for fresh
+  ones the same id can be on screen twice, and the cursor follows a place anyway.
+- **Selection is "these" or "all except these".** That is what lets select all
+  work on a server grid without loading every row. `getSelectedRows()` returns the
+  selected rows that are loaded.
+- **Prefetch.** Server mode requests `overscan` rows beyond the rendered window,
+  so the next block usually arrives before you scroll to it.
+
+## Limitations
 
-Headless: TanStack Table and TanStack Virtual (both MIT). Grouping, pivot, editing
-UX, saved views and cell types are built on top, so no feature depends on a
-commercial license.
+Honest list of what this grid does not do:
 
-`SavedView` is already versioned JSON, so views saved today stay readable.
+- **Server mode has no grouping, no row detail panels and no value lists.** Group
+  and detail props are ignored there, and enum filters need `options` (the grid
+  cannot list distinct values it has not loaded). Server totals come from you.
+- **Grouping with pagination groups the current page only.** Groups are built from
+  the rows on the page, not from the whole result.
+- **Fixed row height.** Cells truncate with an ellipsis; text does not wrap, and
+  there is no auto-height. Detail panels may have any height.
+- **No pivoting, no tree data** (rows with children from the data itself; grouping
+  by columns is supported), **no merged cells, no frozen rows, no cell-range
+  selection, no fill handle, no paste into cells, no row drag-and-drop.**
+- **Editing is one cell at a time** with a text, number, select, date or boolean
+  editor; there is no row editor, and custom editors are not pluggable yet.
+- **Export is CSV and TSV.** No Excel, PDF or print layout. Copy goes through
+  the async clipboard API where it is allowed and falls back to `execCommand`.
+- **Column drag has no autoscroll** beyond what the browser does, and you can only
+  drop on a header that is rendered (with many columns, move far with the menu or
+  the keyboard).
+- **Quick search** splits the text at spaces and keeps the rows where every term
+  appears, case- and accent-insensitively, somewhere in the formatted text of the
+  searchable columns (not the `actions`, `sparkline` and `custom` ones, nor any
+  with `searchable: false`). There are no quoted phrases, no fuzzy matching and
+  no ranking. In server mode the text goes to your data source as `quickFilter`
+  (after `quickFilterDelay`) and what it means is up to you.
+- **Screen-reader behavior is tested through the DOM, not with real assistive
+  technology.** Grids are hard to make perfect: tell us what your readers hit.
+- **Browser testing is jsdom only.** The layout code reads sizes from the DOM and
+  has been exercised against stubs, not in real browsers.