@jielga/tmdatagrid 2.0.0-beta.13 → 2.0.0-beta.15

package/docs/editors.md

@@ -0,0 +1,248 @@
+# Editors and validation
+
+Which control a cell opens when editing starts, what the value becomes on the
+way in, and what prevents a bad one being committed. All three follow from the
+column: `meta.type` picks the editor, and `meta.edit` holds the rest.
+
+```demo
+file: editing/EditorsAndValidation.tsx
+hint: Type a single letter into String, or 5 into Number, to see validation reject it.
+height: 440
+```
+
+## The built-in editors
+
+`meta.type` picks one, and `meta.options` feeds the select editors from the same
+source the filter panel reads. Neither lives under `meta.edit`.
+
+| `meta.type` | Editor | Writes |
+| --- | --- | --- |
+| `string` (default) | Text input | `string` |
+| `number` | Number input | `number`, or `null` while the cell is empty or the text is not yet a number |
+| `boolean` | Checkbox | `boolean` |
+| `date` | Native `<input type="date">` | A `Date`, or the `"YYYY-MM-DD"` string; `null` when cleared |
+| `select` | Searchable select from `meta.options`. Commits on pick under `"cell"` | `string \| null` |
+| `multiSelect` | Multi-select, same source | `string[]` |
+
+**Writes** is the value the editor puts into the draft: what `meta.edit.mapValue` is handed, what `meta.edit.validate` checks, and what a commit carries in `value` and in `changes[].next`.
+
+The number editor writes `null` rather than `NaN` while the text does not parse, so a half-typed number leaves the field empty instead of committing a number no rule can describe.
+The date editor picks between its two types once, when it opens, from what the cell held: a `Date` cell keeps receiving `Date`s and a string cell keeps receiving `"YYYY-MM-DD"` strings, so clearing and retyping cannot flip the type.
+
+Each is a named export (`TMDataGridStringEditor`, `TMDataGridNumberEditor`,
+`TMDataGridBooleanEditor`, `TMDataGridDateEditor`, `TMDataGridSelectEditor`,
+`TMDataGridMultiSelectEditor`), so a custom editor can wrap one instead of
+starting from scratch.
+
+## Writing your own
+
+`meta.edit.editor` fills the same slot as the built-ins. It is a **component**,
+rendered as JSX, so hooks may be used inside, and it receives the live TanStack
+Form `field` API. Bind any control to it as you would inside a form:
+
+```tsx
+const SalaryEditor: TMDataGridEditorComponent = ({ field, commit }) => (
+  <Slider
+    value={field.state.value}
+    onChange={field.handleChange}
+    onChangeEnd={() => void commit()}
+  />
+);
+
+meta: { edit: { editor: SalaryEditor } }
+```
+
+**Define editors at module scope.** An inline arrow function gets a new identity
+on every render, which remounts the editor mid-edit and discards what was typed.
+
+The field's validation message is shown by the host, in a tooltip on the
+editor: open while the input is focused, and on hover. A custom editor gets the
+same tooltip, so it renders no message of its own.
+
+The built-in editors mark the input invalid and add no inline text, since the
+message would be clipped by the width of the cell. A custom editor does the
+same by binding a boolean to the control's `error` prop:
+
+```tsx
+const hasError = field.state.meta.errors.length > 0;
+
+<Slider value={field.state.value} onChange={field.handleChange} error={hasError} />;
+```
+
+## Mapping the value as it is typed
+
+A column can rewrite every value on its way into the draft: uppercase a code,
+strip spaces out of an IBAN, clamp a number into range. `meta.edit.mapValue`
+runs on each write an editor makes, which is each keystroke for a text input and
+each pick for a select.
+
+```demo
+file: editing/MappedInput.tsx
+hint: Type into either column. Code uppercases, Reference keeps digits only.
+height: 420
+```
+
+```tsx
+meta: {
+  edit: {
+    mapValue: ({ value }) =>
+      typeof value === "string" ? value.toUpperCase() : value,
+  },
+}
+```
+
+What it returns is what the cell shows, what the validators check and what is
+committed.
+
+The map is applied inside the editor host, around the field every editor writes
+through, so one declaration covers all six built-in editors, your own
+`meta.edit.editor`, and the character that opened the editor when typing started
+the edit.
+
+Some writes are not mapped: the value the editor opens with, and the writes that go through the form rather than through an editor - `edit.clearCell()`, the Delete key, `edit.setCellValue()` and `edit.setRowValues()`.
+An editor calling `field.setValue` instead of `field.handleChange` also bypasses the map.
+`handleChange` is the mapped path.
+
+The map receives the row and column as well, so it can depend on the record
+being edited:
+
+```tsx
+meta: {
+  edit: {
+    mapValue: ({ value, row }) =>
+      row.original.country === "SE" && typeof value === "string"
+        ? value.replace(/ /g, "")
+        : value,
+  },
+}
+```
+
+`previous` is the value the field held before this write, which a mask needs in
+order to tell an insertion from a deletion.
+
+### Keeping the caret
+
+A mapped value differs from the one the input holds, so React writes the new
+value into the DOM node and the browser collapses the selection to the end of
+the field.
+
+The built-in string and number editors restore the caret to where it was typed,
+shifted by however much the map changed the length, so a mask that inserts or
+strips characters keeps the caret beside the same text.
+
+A custom editor rendering its own input has the same problem, and solves it the
+same way: record `selectionStart` as the value is handed over, and restore it in
+a layout effect once the mapped value has rendered.
+
+## Validation
+
+The validators are TanStack Form's own: a Standard Schema (Zod, Valibot,
+ArkType) or a plain function returning an error message or nothing.
+
+```tsx
+// Per column: field-level validators. A bare schema or function means { onChange: it }.
+meta: { edit: { validate: z.string().min(2, "Too short") } }
+
+// The same rule without a schema library:
+meta: {
+  edit: {
+    validate: ({ value }: { value: unknown }) =>
+      typeof value === "string" && value.length < 2 ? "Too short" : undefined,
+  },
+}
+
+// Per row: form-level validators - cross-field rules live here.
+useTMDataGrid({
+  editing: {
+    mode: "cell",
+    rowValidators: {
+      onSubmit: z.object({ salary: z.number().positive() })
+        .refine((r) => r.status !== "Terminated" || r.salary === 0, {
+          message: "A terminated employee has no salary",
+        }),
+    },
+  },
+});
+```
+
+A plain function is typed `TMDataGridValidator`, whose `value` is `never`, so annotate the parameter - `{ value: unknown }`, or the type the column's editor writes - rather than leaving it to be inferred.
+
+Pathed issues land on the matching cells; pathless ones on the row, where the
+message shows in the edit lane's tooltip - on the open row's ✓, and on the
+parked row's marker. To show a pathless message somewhere of your own, read it
+from `edit.getForm(rowId)?.state.errors`; `edit.store` carries the flag
+(`hasRowError`) and the field messages (`errorMessages`), not the row text.
+
+A commit blocked by validation keeps the editor open, invalid, with the message
+in its tooltip. A rejected `editing.onCommit` keeps the draft too, with the
+error on the row. Server-side field errors can be returned natively through
+`editing.rowValidators.onSubmitAsync`'s `{ form, fields }` shape.
+
+Cross-field rules need a mode that commits the whole row at once. Under
+`"cell"` each cell commits alone, so a rule spanning two columns cannot be
+satisfied by either one. Use `editing.rowValidators.onSubmit` with `"row"`. See
+[Editing](/docs/editing#row-editing).
+
+A rule about the whole collection, such as "no duplicates" or "shares sum to
+100", is neither a field rule nor a row rule. It takes
+`editing.tableValidators` - see [Cross-row rules](#cross-row-rules).
+
+## Cross-row rules
+
+`editing.tableValidators` holds the rules that need the other rows: no
+duplicate keys, no overlapping ranges, allocations summing to a total. Its
+validators receive the committing row and `rows`, the collection as it would
+stand if the commit landed - every draft overlaid, entry rows appended,
+deletion-marked rows removed:
+
+```tsx
+editing: {
+  mode: "cell",
+  draft: true,
+  tableValidators: {
+    onSubmit: ({ value, rowId, rows }) =>
+      rows.some((r) => r.rowId !== rowId && r.value.code === value.code)
+        ? { fields: { code: "Codes must be unique" } }
+        : undefined,
+  },
+}
+```
+
+The result is the `rowValidators` vocabulary: nothing passes, a string is a
+row-level message, and `{ form, fields }` lands pathed issues on the
+committing row's cells. `onSubmit` runs first, and its failure stands without
+`onSubmitAsync` running.
+
+The rules run at every commit, after the row's own validators, and again for
+every parked row during `saveDrafts` - a draft that a later edit has
+invalidated fails there, keeps its markers, and the save resolves `false`.
+Errors land on the committing row only; the row it clashes with is not
+marked.
+
+`rows` is unfiltered, so a rule sees the whole collection whatever the view
+shows, and it never contains group rows.
+
+```demo
+file: editing/TableValidation.tsx
+hint: Give two teams the same code, or push the shares past 100, and the commit is refused. Drafts count - a clash with a pending edit is caught too.
+height: 380
+```
+
+A grid inside an outer form can put collection rules in the form's own field
+validator instead. See [A query builder form](/docs/query-builder).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `meta.edit.editor` | Column meta | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. |
+| `meta.edit.validate` | Column meta | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema or function means `onChange`. |
+| `meta.edit.mapValue` | Column meta | `TMDataGridEditValueMap` | – | Maps each value an editor writes, before it reaches the draft. |
+| `editing.rowValidators` | Option | `TMDataGridRowValidators` | – | Form-level validation, for cross-field rules. |
+| `editing.tableValidators` | Option | `TMDataGridTableValidators` | – | Cross-row rules, handed the collection with every draft overlaid. See [Cross-row rules](#cross-row-rules). |
+| `TMDataGridTableValidateArgs` | Export | type | – | What a table validator receives: `value`, `rowId`, `isNew`, `rows`. |
+| `TMDataGridEditorArgs` | Export | type | – | What an editor component receives: `field`, `commit`, `cancel`, `row`, `column`. |
+| `TMDataGridEditValueMapArgs` | Export | type | – | What `mapValue` receives: `value`, `previous`, `row`, `column`, `table`. |
+| `TMDataGridStringEditor` · `NumberEditor` · `BooleanEditor` · `DateEditor` · `SelectEditor` · `MultiSelectEditor` | Exports | components | – | The six built-ins, for wrapping. |
+| `normalizeFieldValidate` | Export | `(validate) => validators` | – | Turns a bare schema into TanStack Form's validator shape. |
+| `getEditFieldName` | Export | `(column) => string` | – | The data path a column's edits write to. |

package/docs/export.md

@@ -0,0 +1,326 @@
+# Export
+
+Downloads the grid as a file: every filtered and sorted row across every page, or the selected rows, in the format the grid is configured with.
+`TMDataGrid.Menu.Export` and `TMDataGrid.Menu.ExportSelected` are the built-in entry points; `useTMDataGridExport` is the same export as click handlers for a control of your own.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Export />
+    <TMDataGrid.Menu.ExportSelected />
+    <Menu.Divider />
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+</TMDataGrid.Toolbar>
+```
+
+```demo
+file: data/Export.tsx
+hint: Tick a few rows, then open the menu. The Excel CSV opens straight into columns.
+```
+
+## What is written
+
+By default the columns are the visible data columns in render order, so a hidden column is not exported and a pinned one keeps its place.
+`columns` on `exportOptions`, on the menu items and on the functions picks another set:
+
+- `"visible"` - the data columns on screen. The default.
+- `"all"` - every exportable column, hidden ones in the place they would take if shown.
+- a list of column ids - those columns, in render order.
+
+The generated lanes (checkbox, details, edit, row numbers) are never exported, whichever is asked for.
+Set `meta.enableExport: false` to leave a column of your own out the same way:
+
+```tsx
+columnHelper.display({
+  id: "actions",
+  cell: ActionsCell,
+  meta: { enableExport: false },
+});
+```
+
+The rows are every row after filtering and sorting, across every page.
+On a grouped grid the records under every group are written, whether the group is open or not, and the group rows are not.
+
+Each cell is written as its **value**, `row.getValue(column.id)`, not as what the cell renders.
+A cell showing `32 000 kr` exports `32000`; a select column exports the option's `value`.
+Set `meta.exportValue` to write something else:
+
+```tsx
+columnHelper.accessor("status", {
+  meta: {
+    type: "select",
+    options: STATUS_OPTIONS,
+    exportValue: ({ value }) => STATUS_LABELS[value as EmployeeStatus],
+  },
+});
+```
+
+`exportValue` receives `{ value, row, column }` and returns the value the format writes.
+Both meta fields also apply to Ctrl+C under [cell selection](/docs/cell-selection#copy-and-export).
+
+## The exportOptions option
+
+`exportOptions` on `useTMDataGrid` sets the format, the file name and whether the column labels go in as the first row:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: csvFormat(), fileName: "employees" },
+});
+```
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `TMDataGridExportFormat` | `csvExcelFormat()` | The file format. See [Formats](#formats). |
+| `fileName` | `string` | `"export"` | The file name without extension; the format adds its own. |
+| `includeHeaders` | `boolean` | `true` | Determines whether the column labels are written as the first row. |
+| `columns` | `"visible" \| "all" \| Array<string>` | `"visible"` | Which columns are written. See [What is written](#what-is-written). |
+
+The option is read field by field, so a literal is fine.
+Every export of the grid reads it: the menu items, the hook, and the export item of the cell-range menu.
+
+## Formats
+
+A format is a `TMDataGridExportFormat`, and the package ships four factories:
+
+| Factory | File | Writes |
+| --- | --- | --- |
+| `csvExcelFormat()` | `.csv` | A CSV Excel opens straight into columns: UTF-8 BOM, a `sep=;` first line, CRLF endings, `;` between fields, `,` as the decimal mark. |
+| `csvFormat()` | `.csv` | CSV as RFC 4180 has it: `,` between fields, `.` as the decimal mark, CRLF, a UTF-8 BOM, no `sep=` line. |
+| `tsvFormat()` | `.tsv` | Tab-separated text, the clipboard shape as a file. |
+| `jsonFormat()` | `.json` | An array with one object per row, keyed by column label, values as the data holds them. |
+
+Excel xlsx is a separate package, since it needs a spreadsheet library the grid should not carry: see [Excel export (xlsx)](/docs/xlsx).
+
+By default the grid writes `csvExcelFormat()` with the Nordic conventions, because an Excel running a Swedish, Norwegian, Danish or Finnish locale reads `;` as its list separator and `,` as its decimal mark, and a file written the other way opens as one column of text.
+To write for an English-locale Excel, set the separator and the decimal mark on the format:
+
+```tsx
+exportOptions: { format: csvExcelFormat({ separator: ",", decimalComma: false }) }
+```
+
+The `sep=` line is Excel's alone; Google Sheets and Numbers show it as a first row.
+Use `csvFormat()` for a file that goes there.
+
+`csvExcelFormat`, `csvFormat` and `tsvFormat` write values through `formatExportValue`: numbers with the format's decimal mark, dates in the `sv-SE` form (`2026-07-31 14:05:00`, which Excel reads as a date), booleans as `true` / `false`, arrays joined with `, `, and any other object as JSON.
+`jsonFormat` writes numbers as numbers, dates as ISO strings, and `undefined` as `null`.
+
+| Option | Formats | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `separator` | csvExcel, csv | `string` | `";"` for csvExcel, `","` for csv | The character between fields. |
+| `decimalComma` | csvExcel, csv, tsv | `boolean` | `true` for csvExcel and tsv, `false` for csv | Determines whether numbers are written as `1,5` rather than `1.5`. |
+| `escapeFormulas` | csvExcel, csv, tsv | `boolean` | `true` | Determines whether text a spreadsheet would run as a formula is prefixed. See [Formula guard](#formula-guard). |
+| `space` | json | `number` | `2` | Indentation passed to `JSON.stringify`. |
+
+### Formula guard
+
+Excel and Google Sheets run a cell that starts with `=`, `+`, `-` or `@` as a formula, so text one user typed into the grid would run in another user's spreadsheet when the file is opened.
+By default the text formats prefix such a value with an apostrophe, which every spreadsheet reads as "text follows" and shows.
+Text that parses as a number (`-5`, `+4670123456`) is not prefixed; a phone number written with spaces (`+46 70 123 45 67`) is.
+To write every value as it is, set `escapeFormulas: false` on the format:
+
+```tsx
+exportOptions: { format: csvExcelFormat({ escapeFormulas: false }) }
+```
+
+`guardFormula(text)` is the rule as a function, for a format of your own.
+
+## TMDataGrid.Menu.Export
+
+A menu item that downloads every filtered and sorted row, all pages, in the grid's format.
+It needs a Mantine `Menu` around it and reads the grid from context, so it works in `TMDataGrid.Menu` and in any Mantine menu rendered inside `TMDataGrid`.
+Its props override `exportOptions` for this item alone, which is how one menu offers two formats:
+
+```tsx
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.Export
+    format={csvFormat()}
+    fileName="employees-plain"
+    label="Export all rows as plain CSV"
+  />
+</TMDataGrid.Menu>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `TMDataGridExportFormat` | `exportOptions.format` | The file format for this item. |
+| `fileName` | `string` | `exportOptions.fileName` | The file name for this item. |
+| `includeHeaders` | `boolean` | `exportOptions.includeHeaders` | Determines whether this item writes the header row. |
+| `columns` | `"visible" \| "all" \| Array<string> \| "custom"` | `exportOptions.columns` | Which columns the item writes. `"custom"` opens the column picker. |
+| `label` | `ReactNode` | `labels.exportAll` | The item's text. |
+
+### The column picker
+
+`columns="custom"` opens a dialog instead of downloading, titled with the format ("Export as CSV"): every exportable column as a checkbox, the visible ones ticked and the hidden ones marked **Hidden**, and an Export button that downloads the ticked columns in render order.
+The line under the title names the selected rows when the item is `ExportSelected`.
+A select-all row heads the list with a count of the ticked columns, a search box appears once there are six columns, and the list scrolls inside the dialog past half the viewport.
+Under a search, select all ticks the matches and leaves the rest as they are.
+Cancel closes it with no download.
+The dialog follows the grid's `size`: its width, title and controls step with the toolbar's.
+
+```tsx
+<TMDataGrid.Menu.Export columns="custom" label="Export all rows, choose columns" />
+```
+
+The picker is rendered by the `TMDataGrid` root and driven by `ui.state.exportPicker`, which holds `{ rows, options }` while it is open and `null` otherwise.
+`ui.actions.openExportPicker({ rows: "all", options })` opens it from a control of your own; `getExportableColumns(table)` is the list it shows.
+
+## TMDataGrid.Menu.ExportSelected
+
+A menu item that downloads the selected rows of the current view, in grid order, with the same props as `TMDataGrid.Menu.Export`.
+By default its text carries the count (`Export 3 selected rows`); `label` replaces it.
+It is disabled while nothing is selected.
+It renders nothing when row selection is off (`selectionMode: "highlight"` or `enableRowSelection: false`).
+
+A selected row the filters have since hidden is not written and not counted.
+
+## useTMDataGridExport
+
+The export as click handlers, for a button or an item of your own anywhere inside `TMDataGrid`:
+
+```tsx
+import { useTMDataGridExport } from "@jielga/tmdatagrid";
+
+function ExportButtons() {
+  const { exportAll, exportSelected, selectedCount, canExportSelected } =
+    useTMDataGridExport();
+
+  return (
+    <>
+      <Button size="xs" onClick={() => void exportAll()}>
+        Export
+      </Button>
+      {canExportSelected && (
+        <Button size="xs" disabled={selectedCount === 0} onClick={() => void exportSelected()}>
+          Export {selectedCount} selected
+        </Button>
+      )}
+    </>
+  );
+}
+```
+
+It takes a `TMDataGridExportOptions` argument, folded over the grid's `exportOptions` for this caller.
+`exportAll` and `exportSelected` take one more, folded over both for that call, which is how a control passes a chosen set of columns.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `exportAll` | `(overrides?) => Promise<void>` | Downloads every filtered and sorted row, all pages. |
+| `exportSelected` | `(overrides?) => Promise<void>` | Downloads the selected rows of the current view. Resolves without a download when none is selected. |
+| `selectedCount` | `number` | How many rows `exportSelected` would write. Subscribes to the selection. |
+| `canExportSelected` | `boolean` | `true` while row selection is on. |
+
+## Exporting from outside the grid
+
+`exportGrid` is the same export for code that holds the table and nothing else:
+
+```tsx
+import { exportGrid, jsonFormat } from "@jielga/tmdatagrid";
+
+await exportGrid({ table: grid.table, rows: "selected", options: { format: jsonFormat() } });
+```
+
+`rows` is `"all"` (the default), `"selected"`, or an array of TanStack rows of your own; `options.columns` picks the columns.
+`buildExportData({ table, rows, columns })` is the step before the file: the columns, their labels and the raw values as a `TMDataGridExportData`, for a format or a post-processing step of your own.
+`writeExportFile(data, settings)` writes and downloads it.
+
+## Writing your own format
+
+A format is an object with an id, a file extension, a MIME type and a `write` function.
+`write` receives the `TMDataGridExportData` and `{ includeHeaders }`, and returns the file as a string or a `Blob`, or a promise of either:
+
+```tsx
+import type { TMDataGridExportFormat } from "@jielga/tmdatagrid";
+
+export function markdownFormat(): TMDataGridExportFormat {
+  return {
+    id: "markdown",
+    extension: "md",
+    mimeType: "text/markdown",
+    write: ({ headers, rows }, { includeHeaders }) => {
+      const line = (cells: Array<unknown>) => `| ${cells.map(String).join(" | ")} |`;
+      const head = includeHeaders
+        ? [line(headers), line(headers.map(() => "---"))]
+        : [];
+      return [...head, ...rows.map(line)].join("\n");
+    },
+  };
+}
+```
+
+Set `decimalComma` on the format when it writes text with a decimal mark, so Ctrl+C writes the same mark.
+`formatExportValue(value, { decimalComma })` is the grid's own text rule, for a format that wants it.
+
+## Copy and the cell-range menu
+
+Under `cellSelection: "range"`, Ctrl+C and the **Export cells** item of the right-click menu write the selected rectangle through the same `exportOptions`, column meta and format.
+See [Copy and export](/docs/cell-selection#copy-and-export).
+
+## Labels
+
+| Label | Default | Used by |
+| --- | --- | --- |
+| `exportAll` | `"Export all rows"` | `TMDataGrid.Menu.Export` |
+| `exportSelected` | `(count) => "Export 3 selected rows"` | `TMDataGrid.Menu.ExportSelected` |
+| `exportCells` | `"Export cells"` | The cell-range menu |
+| `exportPickerTitle` | `` (format) => `Export as ${format}` `` | The column picker; `format` is the extension in upper case |
+| `exportPickerHint` | `(selected) => "Select the columns to export"`, or `… for the ${selected} selected rows` | The line under the picker's title |
+| `exportPickerConfirm` | `"Export"` | The column picker |
+| `exportPickerCancel` | `"Cancel"` | The column picker |
+| `exportPickerSelectAll` | `"Select all"` | The column picker |
+| `exportPickerCount` | `` (checked, total) => `${checked} of ${total}` `` | The column picker |
+| `exportPickerHidden` | `"Hidden"` | The column picker, on a column the grid hides |
+
+See [Localization](/docs/localization).
+
+## Testing
+
+`TMDataGrid.Menu.Export` is `data-dg-part="menu-export"` and `TMDataGrid.Menu.ExportSelected` is `data-dg-part="menu-export-selected"`.
+The column picker is `export-picker`, its checkboxes `export-column` with `data-column-id`, its select-all row `export-column-all` with the count `export-picker-count`, its search box `export-picker-search`, the line under the title `export-picker-hint`, and its buttons `export-picker-confirm` and `export-picker-cancel`.
+The search box and the picker share `columnsSearchPlaceholder` and `columnsNoMatch` with the column chooser.
+A download is an anchor with an object URL, clicked; a jsdom test stubs `URL.createObjectURL` and `HTMLAnchorElement.prototype.click` to read the file back.
+See [Testing](/docs/testing).
+
+## Deprecated names
+
+The names below still work and go in the next beta.
+
+| Deprecated | Use instead |
+| --- | --- |
+| `cellExport` on `TMDataGrid.Table` | `exportOptions` on `useTMDataGrid`; `separator` and `decimalComma` become `csvExcelFormat({ separator, decimalComma })` |
+| `exportGridToCsv({ table, options })` | `exportGrid({ table, options })` |
+| `TMDataGridCellExportOptions` · `DEFAULT_CELL_EXPORT_OPTIONS` | `TMDataGridExportOptions` · `DEFAULT_EXPORT_OPTIONS` |
+| `buildCellMatrix` · `buildGridCellMatrix` · `TMDataGridCellMatrix` | `buildExportData` · `TMDataGridExportData` |
+| `toExcelCsv(matrix, { separator })` | `csvExcelFormat({ separator }).write(data, options)` |
+| `downloadTextFile` | `downloadFile` |
+| `labels.exportCsv` | `labels.exportCells` |
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row for every export of the grid. |
+| `meta.enableExport` | Column meta | `boolean` | `true` | `false` leaves the column out of every export and of Ctrl+C. |
+| `meta.exportValue` | Column meta | `({ value, row, column }) => unknown` | – | The value written in place of `row.getValue`. |
+| `TMDataGrid.Menu.Export` | Component | `TMDataGridMenuExportProps` | – | Menu item: every filtered row. `columns="custom"` opens the picker. |
+| `TMDataGrid.Menu.ExportSelected` | Component | `TMDataGridMenuExportProps` | – | Menu item: the selected rows. Renders nothing when row selection is off. |
+| `ui.state.exportPicker` | UI state | `{ rows, options } \| null` | `null` | The column picker while open. |
+| `ui.actions.openExportPicker` · `closeExportPicker` | UI actions | – | – | Open the picker from your own code. |
+| `getExportableColumns` | Function | `(table) => Array<Column>` | – | Every column an export could take, hidden ones included. |
+| `useTMDataGridExport` | Hook | `(overrides?) => TMDataGridExportApi` | – | `exportAll`, `exportSelected`, `selectedCount`, `canExportSelected`. |
+| `exportGrid` | Function | `({ table, rows?, options? }) => Promise<void>` | – | Downloads the grid from outside a component. |
+| `buildExportData` | Function | `({ table, rows?, columns?, bounds? }) => TMDataGridExportData` | – | The columns, labels and values a format writes. |
+| `writeExportFile` | Function | `(data, settings) => Promise<void>` | – | Writes export data in a format and downloads it. |
+| `csvExcelFormat` · `csvFormat` · `tsvFormat` · `jsonFormat` | Functions | `(options?) => TMDataGridExportFormat` | – | The built-in formats. |
+| `guardFormula` · `formatExportValue` | Functions | – | – | The formula guard and the text rule, for a format of your own. |
+| `resolveExportOptions` | Function | `(...overrides) => TMDataGridExportSettings` | – | The defaults with overrides folded over, `undefined` fields skipped. |
+| `countSelectedExportRows` | Function | `(table) => number` | – | How many rows `"selected"` would write. |
+| `downloadFile` | Function | `({ fileName, content, mimeType }) => void` | – | Downloads a string or a `Blob`. |
+| `DEFAULT_EXPORT_OPTIONS` | Constant | `TMDataGridExportSettings` | – | `csvExcelFormat()`, `"export"`, `true`. |
+| `TMDataGridExportFormat` · `TMDataGridExportData` · `TMDataGridExportOptions` · `TMDataGridExportSettings` · `TMDataGridExportRows` · `TMDataGridExportApi` | Types | – | – | The export types. |
+| `data-dg-part` | Data attribute | `menu-export`, `menu-export-selected` | – | On the menu items. |