@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/skills/columns/SKILL.md

@@ -4,26 +4,26 @@ description: >
   Define and arrange TMDataGrid columns. Covers createTMDataGridColumnHelper,
   every column meta field (label, type, options, flex, align, autoSize,
   enableOrdering, and the meta.filter and meta.edit namespaces holding
-  defaultOperator, control, enabled, field, editor, validate and mapValue), the
-  six column types, fluid minmax sizing versus fixed width with minSize /
-  maxSize / size, autosizing and autosizeColumn, hiding through enableHiding and
-  the columns panel, pinning and why a pinned column becomes fixed-width,
-  ordering with enableColumnOrdering, meta.enableOrdering, moveColumn,
-  moveColumnByStep, getStepTargetColumn and the pinned regions, resetSettings,
-  sorting with multi-sort through isMultiSortEvent and a custom sortFn, and the
-  generated lanes. Load when adding or changing columns, controlling widths,
-  hiding, pinning, reordering or sorting them.
+  operators, defaultOperator, control, enabled, field, editor, validate and
+  mapValue), the six column types, fluid minmax sizing versus fixed width with
+  minSize / maxSize / size, autosizing and autosizeColumn, hiding through
+  enableHiding and the columns panel, pinning and why a pinned column becomes
+  fixed-width, ordering with enableColumnOrdering, meta.enableOrdering,
+  moveColumn, moveColumnByStep, getStepTargetColumn and the pinned regions,
+  resetSettings, sorting with multi-sort through isMultiSortEvent and a custom
+  sortFn, and the generated lanes. Load when adding or changing columns,
+  controlling widths, hiding, pinning, reordering or sorting them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/columns.md'
-  - 'Jielga/TMDataGrid:src/docs/column-layout.md'
-  - 'Jielga/TMDataGrid:src/docs/sorting.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/columnUtils.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/columnOrdering.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/autosize.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/columns.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/column-layout.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/sorting.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/columnUtils.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/columnOrdering.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/autosize.ts'
 ---
 
 # TMDataGrid - Columns
@@ -93,22 +93,9 @@ What the column **is** stays flat; what the filter panel and the edit engine do
 with it sits in their namespaces. `type` and `options` are read by both stages,
 which is why they are in neither.
 
-`meta.filter`:
-
-| Field | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `defaultOperator` | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter on this column starts with. |
-| `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
-
-`meta.edit`:
-
-| Field | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. |
-| `field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
-| `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
-| `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
-| `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+`meta.filter` holds `operators`, `defaultOperator` and `control`; `meta.edit`
+holds `enabled`, `field`, `editor`, `validate` and `mapValue`. Their fields are
+in [references/columns-api.md](references/columns-api.md).
 
 ```tsx
 meta: {
@@ -118,6 +105,14 @@ meta: {
 }
 ```
 
+The type of `meta` is `TMDataGridColumnMeta<TData>`. On a column declared with
+`createTMDataGridColumnHelper<TData>()`, the `row` that a `meta.options`
+function and a `meta.edit.enabled` function receive is
+`Row<TMDataGridFeatures, TData>`, so `row.original` needs no cast and no
+annotation. A column written without the helper keeps the untyped row,
+`Row<TMDataGridFeatures, TMDataGridRowData>`, where `row.original` is
+`Record<string, unknown>`.
+
 `enableOrdering` lives in `meta` because column ordering is the one feature
 TanStack defines no column option for. `meta.edit` only acts once `editing` is
 set: see the `editing` skill. `meta.filter` belongs to the `filtering` skill.
@@ -140,6 +135,28 @@ columnHelper.accessor("department", {
 Dates travel as ISO `YYYY-MM-DD` strings and booleans as `"true"` / `"false"`,
 so the filter model stays plain JSON whatever the type.
 
+### meta.options
+
+`meta.options` is a list of `TMDataGridOption`s
+(`{ value, label?, color?, disabled?, group? }`) or bare strings, `"faceted"`
+for the distinct values in the data, or a function of `TMDataGridOptionsArgs`
+(`{ table, column, row? }`). `row` is set when a cell editor asks and absent for
+the filter panel:
+
+```tsx
+meta: {
+  type: "select",
+  options: ({ row }) => (row ? citiesFor(row.original.country) : allCities),
+}
+```
+
+`resolveColumnOptions({ table, column, row? })` normalises all three forms into
+`Array<TMDataGridOption>` for a custom control, and `optionsToComboboxData`
+turns that list into Mantine `Select` / `MultiSelect` data. A select column with
+no options still filters, on the faceted values.
+
+Source: `packages/tmdatagrid/docs/columns.md` (Options).
+
 ## Sizing
 
 Columns are fluid. Each track is `minmax(minSize, flex fr)`.
@@ -174,21 +191,26 @@ consumer code.
 
 All three write state that persists together, so a grid comes back arranged the
 way it was left. `resetSettings()` from the hook clears visibility, order,
-pinning and widths in one go, and the columns panel offers it as **Reset
+pinning and widths in one go, and the column chooser offers it as **Reset
 layout**.
 
 **Hiding** is `columnVisibility`, driven by "Hide column" in a column menu and by
-`TMDataGrid.ColumnsButton` with the panel behind it.
+the column chooser: `TMDataGrid.Menu.Columns` in the grid menu, **Manage
+columns** as a submenu of every column menu, and `TMDataGrid.ColumnsPanel` as
+plain controls for a host that is not a menu. See the `appearance` skill.
 
 **Pinning** is "Pin to left" / "Pin to right" in the column menu. A pinned
 column also becomes fixed-width: sticky offsets are computed from `getSize()`,
 which cannot resolve an `fr` value, so the grid stores the rendered width in
-`columnSizing` at the moment it is pinned and nothing jumps.
+`columnSizing` at the moment it is pinned and nothing jumps. A column pinned
+from `initialState.columnPinning` has no rendered width to store, so it takes
+its `size` - TanStack's default of `150` where none is set - and `minSize`
+does not apply.
 
 **Ordering** is header dragging plus "Move left" / "Move right". A column can
 only move **within its own pinned region** - pinning splits the grid into left,
 centre and right, then `columnOrder` sequences the centre while
-`columnPinning.left` and `.right` sequence the pinned lanes. Unpin a column
+`columnPinning.start` and `.end` sequence the pinned lanes. Unpin a column
 first to move it out of one. A neighbour that cannot move acts as a wall rather
 than being stepped over, and columns inside a header group are not movable in
 either direction, because `columnOrder` sequences leaf columns.
@@ -244,7 +266,7 @@ Standard TanStack column options. Each also removes the corresponding interface.
 | Option | Effect when `false` |
 | --- | --- |
 | `enableSorting` | No sort indicator, no sort menu items, no click-to-sort. |
-| `enableColumnFilter` | No filter menu item. Excluded from the filter panel's column list. |
+| `enableColumnFilter` | No filter menu item. Excluded from the filter panel's column list, and its header filter cell is empty. |
 | `enableHiding` | No hide menu item. Checkbox disabled in the column manager. |
 | `enablePinning` | No pin menu items. |
 | `enableResizing` | The divider is displayed but cannot be dragged. |
@@ -270,7 +292,7 @@ asks for it.
 
 They are structural: fixed width, no column menu, and they cannot be sorted,
 filtered, resized, re-pinned or moved. The checkbox lane anchors the left pinned
-region, so no column can be placed in front of it. `isControlColumn(column)`
+region, so no column can be placed in front of it. `isControlColumn(columnId)`
 identifies them.
 
 ## Common mistakes
@@ -299,7 +321,33 @@ columnHelper.accessor("email", {
 });
 ```
 
-Source: `src/docs/column-layout.md` (Sizing).
+The corollary is that a pinned column is fixed-width and does use `size`, so a
+column that is pinned needs one.
+
+Source: `packages/tmdatagrid/docs/column-layout.md` (Sizing).
+
+### HIGH Pinning a column at mount without size
+
+A column pinned interactively keeps the width it was rendering, which the grid
+writes into `columnSizing`. A column pinned from `initialState.columnPinning`
+has no rendered width, so it takes `size` - TanStack's default of `150` where
+none is set - and `minSize` does not apply.
+
+Wrong:
+
+```tsx
+columnHelper.accessor("name", { header: "Name", minSize: 220 });
+initialState: { columnPinning: { start: ["name"], end: [] } },
+```
+
+Correct:
+
+```tsx
+columnHelper.accessor("name", { header: "Name", minSize: 220, size: 220 });
+initialState: { columnPinning: { start: ["name"], end: [] } },
+```
+
+Source: `packages/tmdatagrid/docs/column-layout.md` (Pinning).
 
 ### HIGH Addressing a dotted column by its accessor key
 
@@ -321,7 +369,7 @@ initialState: { columnVisibility: { address_city: false } },
 The edit path is the exception: `meta.edit.field` and validation issue paths
 stay dotted, because they address the data, not the column.
 
-Source: `src/docs/columns.md` (The column helper).
+Source: `packages/tmdatagrid/docs/columns.md` (The column helper).
 
 ### CRITICAL A component header without `meta.label`
 
@@ -344,7 +392,7 @@ columnHelper.accessor("fullName", {
 });
 ```
 
-Source: `src/tmdatagrid/core/columnUtils.ts`.
+Source: `packages/tmdatagrid/src/core/columnUtils.ts`.
 
 ### HIGH A numeric column without `meta.type`
 
@@ -353,7 +401,7 @@ Source: `src/tmdatagrid/core/columnUtils.ts`.
 as text - `"9"` above `"10"`. The column still sorts and filters, which is why
 it is easy to miss.
 
-Source: `src/tmdatagrid/core/filterOperators.ts`.
+Source: `packages/tmdatagrid/src/core/filterOperators.ts`.
 
 ### HIGH Expecting a move across pinned regions to work
 
@@ -368,7 +416,7 @@ table.getColumn("salary")?.pin(false);
 moveColumn({ table, columnId: "salary", targetId: "age", side: "before" });
 ```
 
-Source: `src/docs/column-layout.md` (Regions).
+Source: `packages/tmdatagrid/docs/column-layout.md` (Regions).
 
 ### HIGH Reaching for the v8 name of a v9 option
 
@@ -390,7 +438,7 @@ columnHelper.accessor("priority", { header: "Priority", sortFn: byRank });
 ```
 
 Source: `@tanstack/table-core` `rowSortingFeature.types.d.ts`, and
-`src/tmdatagrid/useTMDataGrid.tsx` (the registered `sortFns`).
+`packages/tmdatagrid/src/useTMDataGrid.tsx` (the registered `sortFns`).
 
 ### MEDIUM Expecting autosize to measure every row
 
@@ -398,7 +446,7 @@ Autosizing fits the **mounted** rows plus overscan, not every row, because
 virtualization leaves the rest with no DOM to measure. A column autosized at the
 top of a long list can be too narrow for a value further down.
 
-Source: `src/docs/column-layout.md` (Autosizing).
+Source: `packages/tmdatagrid/docs/column-layout.md` (Autosizing).
 
 ### MEDIUM Reordering a column inside a header group
 
@@ -407,31 +455,38 @@ the group header spanning columns that no longer belong to it. Grouped-header
 columns are therefore immovable in both directions, whatever `meta.enableOrdering`
 says.
 
-Source: `src/docs/column-layout.md` (Regions).
-
-## Reference
-
-| Name | Kind | Type | Default | What it does |
-| --- | --- | --- | --- | --- |
-| `createTMDataGridColumnHelper` | Export | `<TData>() => helper` | – | The typed column helper. |
-| `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / – | Width bounds, and the fixed width once one applies. |
-| `enableSorting` · `enableColumnFilter` · `enableHiding` · `enablePinning` · `enableResizing` · `enableGrouping` | Column options | `boolean` | `true` | Per-column switches, each removing its interface. |
-| `enableColumnOrdering` | Option | `boolean` | `true` | Header dragging and the move menu items. Grid-defined. |
-| `enableMultiSort` · `maxMultiSortColCount` · `isMultiSortEvent` | Table options | – | Shift held | Multi-column sorting. |
-| `sortFn` | Column option | name or `(rowA, rowB, columnId) => number` | `"auto"` | The comparator for one column. Not v8's `sortingFn`. |
-| `initialState.columnOrder` · `.columnPinning` · `.columnVisibility` · `.columnSizing` | Table options | – | – | Layout at mount. Settings slices, persisted under `settingsKey`. |
-| `initialState.sorting` | Table option | `Array<{ id, desc }>` | `[]` | Sort at mount. A data slice, persisted under `dataKey`. |
-| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning and widths. |
-| `moveColumn` | Export | `({ table, columnId, targetId, side }) => void` | – | Moves a column beside another. |
-| `moveColumnByStep` | Export | `({ table, columnId, direction }) => void` | – | Moves it one place. |
-| `getStepTargetColumn` | Export | `(args) => Column \| null` | – | What a step would swap with, or `null` at a region edge. |
-| `getColumnRegion` | Export | `(column) => "left" \| "center" \| "right"` | – | Which pinned region a column is in. |
-| `isColumnReorderable` | Export | `(column, features) => boolean` | – | Whether this column may move at all. |
-| `autosizeColumn` | Export | `({ table, columnId, container }) => void` | – | Fits a column to its mounted content. |
-| `measureColumnContentWidth` | Export | `(args) => number` | – | The measurement behind it. |
-| `getColumnLabel` · `getColumnType` · `getColumnDefaultOperator` · `isControlColumn` | Exports | – | – | What the built-in controls read off a column. |
-| `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | ids | – | The generated lanes. |
-| `TMDataGrid.ColumnsButton` · `TMDataGrid.ColumnsPanel` | Components | – | – | Manage columns, and Reset layout. |
+Source: `packages/tmdatagrid/docs/column-layout.md` (Regions).
+
+### MEDIUM Computing a cross-row value in accessorFn
+
+`accessorFn` is handed one row, so a share of a total, a rank or a running
+total has nothing to compute against. Derive the collection once and give the
+grid the finished shape.
+
+Wrong:
+
+```tsx
+columnHelper.accessor((row) => (row.value / total) * 100, { id: "pctOfTotal" });
+```
+
+Correct:
+
+```tsx
+const rows = useMemo(() => {
+  const total = holdings.reduce((sum, h) => sum + h.value, 0);
+  return holdings.map((h) => ({ ...h, pctOfTotal: (h.value / total) * 100 }));
+}, [holdings]);
+
+columnHelper.accessor("pctOfTotal", { header: "Share" });
+```
+
+Source: `packages/tmdatagrid/docs/columns.md` (Columns derived from the other rows).
+
+## References
+
+- [Columns API](references/columns-api.md) - every column option, column meta
+  field, export and type belonging to defining, sizing, hiding, pinning,
+  ordering and sorting columns.
 
 See also: the `filtering` skill for operators and filter controls, the `editing`
 skill for the editing meta fields, and the `grouping` skill for what grouping

package/skills/columns/references/columns-api.md

@@ -0,0 +1,59 @@
+# Columns API
+
+Reference for the `columns` skill.
+
+## meta.filter and meta.edit
+
+`meta.filter` belongs to the `filtering` skill:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `operators` | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. For a backend that answers only some. |
+| `defaultOperator` | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter on this column starts with. |
+| `control` | `TMDataGridFilterControlComponent` | By `meta.type` | Replaces the value control in this column's filter row. Module scope. |
+
+`meta.edit` belongs to the `editing` skill, and only acts once `editing` is set:
+
+| Field | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `enabled` | `boolean \| ((row) => boolean)` | editable where a field maps | Whether this column's cells edit. `row` is typed by the column helper. |
+| `field` | `string` | The `accessorKey` | The data path an edit writes to. The only way an `accessorFn` column edits. |
+| `editor` | `TMDataGridEditorComponent` | By `meta.type` | Replaces the cell editor. Module scope. |
+| `validate` | `TMDataGridFieldValidate` | – | Field-level validation. A bare schema means `onChange`. |
+| `mapValue` | `TMDataGridEditValueMap` | – | Maps each value an editor writes, on every keystroke. |
+
+## Exports and options
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `createTMDataGridColumnHelper` | Export | `<TData>() => TMDataGridColumnHelper<TData>` | – | The typed column helper. `meta` callbacks receive `Row<TMDataGridFeatures, TData>`. |
+| `TMDataGridColumnHelper` | Type | – | – | The helper's type. |
+| `TMDataGridColumnMeta` | Type | `TMDataGridColumnMeta<TData = TMDataGridRowData>` | – | The type of `meta`. Typed against the row when the column is declared with the helper. |
+| `meta.options` | Column meta | `TMDataGridOptionsSource`: array \| `"faceted"` \| `(args: TMDataGridOptionsArgs) => …` | – | The choices of a `select` / `multiSelect` column. |
+| `TMDataGridOption` | Type | `{ value, label?, color?, disabled?, group? }` | – | One choice. A bare string is shorthand for `{ value }`. |
+| `TMDataGridOptionsArgs` | Type | `{ table, column, row? }` | – | What a `meta.options` function receives. `row` is absent when the filter panel asks. |
+| `resolveColumnOptions` | Export | `({ table, column, row?, fallback? }) => Array<TMDataGridOption>` | – | Normalises all three `meta.options` forms. Empty when the column declares none. |
+| `optionsToComboboxData` | Export | `(options) => ComboboxData` | – | Options as Mantine `Select` / `MultiSelect` data, groups folded in. |
+| `minSize` / `maxSize` / `size` | Column options | `number` | `80` / – / – | Width bounds, and the fixed width once one applies. |
+| `enableSorting` · `enableColumnFilter` · `enableHiding` · `enablePinning` · `enableResizing` · `enableGrouping` | Column options | `boolean` | `true` | Per-column switches, each removing its interface. |
+| `enableColumnOrdering` | Option | `boolean` | `true` | Header dragging and the move menu items. Grid-defined. |
+| `enableMultiSort` · `maxMultiSortColCount` · `isMultiSortEvent` | Table options | – | Shift held | Multi-column sorting. |
+| `sortFn` | Column option | name or `(rowA, rowB, columnId) => number` | `"auto"` | The comparator for one column. Not v8's `sortingFn`. |
+| `initialState.columnOrder` · `.columnPinning` · `.columnVisibility` · `.columnSizing` | Table options | – | – | Layout at mount. Settings slices, persisted under `settingsKey`. |
+| `initialState.sorting` | Table option | `Array<{ id, desc }>` | `[]` | Sort at mount. A data slice, persisted under `dataKey`. |
+| `resetSettings` | Hook return | `() => void` | – | Clears visibility, order, pinning and widths. |
+| `moveColumn` | Export | `({ table, columnId, targetId, side }) => void` | – | Moves a column beside another. |
+| `moveColumnByStep` | Export | `({ table, columnId, direction }) => void` | – | Moves it one place. `direction` is `-1` or `1`. |
+| `MoveColumnArgs` · `ColumnStepArgs` | Types | – | – | What `moveColumn` takes, and what `moveColumnByStep` and `getStepTargetColumn` take. |
+| `TMDataGridDropSide` | Type | `"before" \| "after"` | – | The `side` of `MoveColumnArgs`: which edge of the target column the moved column lands on. |
+| `getStepTargetColumn` | Export | `(args) => Column \| null` | – | What a step would swap with, or `null` at a region edge. |
+| `getColumnRegion` | Export | `(columnPinning, columnId) => TMDataGridColumnRegion` | – | Which pinned region a column is in. |
+| `TMDataGridColumnRegion` | Type | `"start" \| "center" \| "end"` | – | What `getColumnRegion` returns. |
+| `keepGeneratedColumnsOutermost` | Export | `(columnPinning) => ColumnPinningState` | – | Puts the generated lanes back on the outside of both pinned lanes. The grid runs it after every pin; call it on a `columnPinning` you write yourself. |
+| `getColumnCapabilities(column, features).canReorder` | Export | `boolean` | – | Whether this column may move at all. |
+| `autosizeColumn` | Export | `({ table, columnId, container }) => void` | – | Fits a column to its mounted content. |
+| `getColumnLabel` · `getColumnType` · `getColumnDefaultOperator` · `isControlColumn` | Exports | – | – | What the built-in controls read off a column. |
+| `isGeneratedColumn` | Export | `(columnId) => boolean` | – | Whether the grid generated the column - the four control lanes plus the tree column. |
+| `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | ids | – | The generated lanes. |
+| `TMDataGrid.Menu.Columns` · `TMDataGrid.ColumnsPanel` | Components | `searchable` · Mantine `BoxProps` | – | The column chooser, as menu items and as plain controls. Style props set on the panel. |
+| `TMDataGridColumnSearchable` | Type | `boolean \| "auto"` | `"auto"` | The `searchable` prop of both: a search box from six hideable columns under `"auto"`, `true` always, `false` never. |

package/skills/data/SKILL.md

@@ -10,17 +10,23 @@ description: >
   onReachEnd is better for loading more, the header and pinned-lane depth
   shadows, and the four empty states in precedence order with meta.loading,
   renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator and
-  TMDataGrid.SummaryCount. Load when adding a pager, tuning scrolling, scrolling
-  to a row, or deciding what an empty grid should say.
+  TMDataGrid.SummaryCount, and export: TMDataGrid.Menu.Export and
+  Menu.ExportSelected, useTMDataGridExport, exportGrid, exportOptions, the
+  csvExcel / csv / tsv / json formats, meta.exportValue and meta.enableExport.
+  Load when adding a pager, tuning scrolling, scrolling to a row, deciding what
+  an empty grid should say, or exporting rows to Excel or CSV.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/pagination.md'
-  - 'Jielga/TMDataGrid:src/docs/scrolling.md'
-  - 'Jielga/TMDataGrid:src/docs/loading-and-empty.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/pagination.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/scrolling.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/loading-and-empty.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/export.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/pagination.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/export.ts'
 ---
 
 # TMDataGrid - Pagination, scrolling and empty states
@@ -77,7 +83,10 @@ pieces, already wired.
 `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are what the default
 footer renders, in that order, so a custom layout can keep the parts it wants
 instead of rebuilding them. They behave exactly as before, including greying out
-under a suspended pager.
+under a suspended pager. `Controls.PageNumber` - the "Page 3 of 200" label a
+server-paged grid usually shows in place of a row range - is a fourth control,
+not in the default footer; put it in through the slot rather than writing it by
+hand.
 
 `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
 `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
@@ -178,6 +187,67 @@ server-driven grid refetching with rows still on screen keeps showing them.
 total, where the total is `meta.totalRowCount` when provided and the pre-filtered
 count otherwise.
 
+## Export
+
+Every filtered and sorted row across every page, or the selected rows, as a
+file. The built-in entry points are menu items; a button of your own uses the
+hook.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: csvFormat(), fileName: "employees" },
+});
+
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.ExportSelected />
+</TMDataGrid.Menu>
+```
+
+```tsx
+function ExportButton() {
+  const { exportAll, exportSelected, selectedCount, canExportSelected } =
+    useTMDataGridExport();
+  return <Button onClick={() => void exportAll()}>Export</Button>;
+}
+```
+
+What is written: the data columns in render order (never the generated lanes,
+never a column with `meta.enableExport: false`), every row after filtering and
+sorting (a grouped grid writes the records under every group, never the group
+rows), and each cell's **value** rather than what it renders -
+`meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+`columns` on `exportOptions`, the items and the functions is `"visible"` (the
+default), `"all"` (hidden columns too) or a list of ids; `columns="custom"` on
+a menu item opens a picker instead - every exportable column, the visible ones
+ticked, Export and Cancel - driven by `ui.state.exportPicker` and
+`ui.actions.openExportPicker`. `TMDataGrid.Menu.ExportSelected` counts and
+writes the ticked rows of the current view, in grid order; it renders nothing
+when row selection is off.
+
+Formats, each a `TMDataGridExportFormat` from a factory:
+
+| Factory | Writes |
+| --- | --- |
+| `csvExcelFormat()` (default) | BOM, `sep=;` line, CRLF, `;` fields, `,` decimal - opens straight into columns in Excel. `separator`, `decimalComma` for another locale. |
+| `csvFormat()` | RFC 4180: `,` fields, `.` decimal, BOM, no `sep=` line - for Google Sheets, Numbers and tooling. |
+| `tsvFormat()` | Tab-separated, the clipboard shape as a file. |
+| `jsonFormat()` | One object per row keyed by column label, numbers as numbers, dates as ISO strings. |
+| `xlsxFormat()` | Excel workbook, from the separate `@jielga/tmdatagrid-xlsx` package. |
+
+The text formats guard against formula injection by default: a value starting
+with `=`, `+`, `-` or `@` that is not a number is prefixed with `'`.
+`escapeFormulas: false` on the format turns that off.
+
+`exportGrid({ table, rows: "all" | "selected" | rows, options })` is the same
+export for code outside a component; `buildExportData` is the step before the
+file. A format of your own is `{ id, extension, mimeType, write(data, { includeHeaders }) }`
+returning a string, a `Blob`, or a promise of either.
+
+Source: `packages/tmdatagrid/docs/export.md`.
+
 ## Common mistakes
 
 ### CRITICAL Turning pagination on to make a large grid fast
@@ -186,7 +256,7 @@ Virtualization is already unconditional, so paging a 200 000-row grid changes
 nothing about rendering cost. It only changes how users navigate. Enable it when
 they should move page by page, not for performance.
 
-Source: `src/docs/pagination.md`, `src/docs/scrolling.md`.
+Source: `packages/tmdatagrid/docs/pagination.md`, `packages/tmdatagrid/docs/scrolling.md`.
 
 ### CRITICAL A variable row height
 
@@ -207,7 +277,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
 ```
 
-Source: `src/docs/scrolling.md` (Row height).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Row height).
 
 ### HIGH `scrollIntoView` on a row that is not mounted
 
@@ -223,7 +293,7 @@ grid.scrollToRow({ rowId: "4000", align: "center" });
 `scrollToRow` returns `false` when the row is not in the current view (filtered
 out, on another page, or an id matching no row) and nothing scrolled.
 
-Source: `src/docs/scrolling.md` (Scrolling to a row).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Scrolling to a row).
 
 ### HIGH Loading more rows from `onScrollToBottom`
 
@@ -231,7 +301,7 @@ It fires at the very bottom, so the user waits at the end of the list for the
 fetch. `onReachEnd` fires a number of rows earlier and latches per row count, so
 a pending fetch is not requested twice.
 
-Source: `src/docs/scrolling.md` (Edge callbacks).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Edge callbacks).
 
 ### HIGH `SummaryCount` reporting the page under manual pagination
 
@@ -250,7 +320,7 @@ useTMDataGrid({
 });
 ```
 
-Source: `src/docs/loading-and-empty.md` (Counting what is there).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (Counting what is there).
 
 ### MEDIUM Rendering an empty message while data is loading
 
@@ -264,7 +334,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { loading: isFetching } });
 ```
 
-Source: `src/docs/loading-and-empty.md` (What wins).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
 
 ### MEDIUM Trusting the pager while grouped
 
@@ -272,7 +342,7 @@ Source: `src/docs/loading-and-empty.md` (What wins).
 grid is rendering the whole tree. A custom pager must read
 `isPagingActive(table, features)` rather than the page count.
 
-Source: `src/docs/pagination.md` (Grouping suspends it).
+Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 
 ## Reference
 
@@ -283,14 +353,18 @@ Source: `src/docs/pagination.md` (Grouping suspends it).
 | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
 | `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
 | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
-| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `pagination` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. |
-| `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
-| `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
+| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
+| `TMDataGridFooterProps` | Type | – | – | The props of `TMDataGrid.Footer`. |
+| `Footer` `renderPagination` | Slot | `(args: TMDataGridPaginationSlotArgs) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
+| `TMDataGridPaginationSlotArgs` | Type | `TMDataGridPaginationApi & { Controls }` | – | What `renderPagination` receives: `{ state, actions, Controls }`. |
+| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | The pager API, outside the Footer. |
+| `TMDataGridPaginationApi` | Type | `{ state, actions }` | – | What `getTMDataGridPaginationApi` returns. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot argument. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |
 | `overscan` | Option | `number` | `6` | Rows kept mounted beyond each edge of the viewport. |
 | `meta.rowHeight` | Option | `number` | From `size` | Row height in pixels. The virtualizer needs a number. |
 | `scrollToRow` | Hook return | `({ rowId, align? }) => boolean` | `align: "auto"` | Scrolls a row into view, mounted or not. |
+| `TMDataGridScrollToRowArgs` | Export | `{ rowId, align? }` | – | What `scrollToRow` takes. |
 | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
 | `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
 | `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |
@@ -301,6 +375,26 @@ Source: `src/docs/pagination.md` (Grouping suspends it).
 | `TMDataGrid.SummaryCount` | Component | `children` replaces the text | – | Visible rows out of total. |
 | `--dg-header-shadow-color` | CSS variable | colour | Themed | The shadow under the sticky header. |
 | `--dg-sticky-edge-range` | CSS variable | length | `20px` | How far the pinned-lane band takes to fade in. |
+| `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 | `TMDataGridExportValueGetter`: `({ value, row, column }) => unknown` | – | The value written in place of `row.getValue`. |
+| `TMDataGrid.Menu.Export` · `TMDataGrid.Menu.ExportSelected` | Components | `TMDataGridMenuExportProps` | – | Menu items: every filtered row, and the selected rows. `columns="custom"` opens the picker. |
+| `ui.state.exportPicker` | UI state | `TMDataGridExportPickerRequest \| null` | `null` | The column picker while open: `{ rows, options }`. |
+| `getExportableColumns` | Export | `(table) => Array<Column>` | – | Every column an export could take, hidden ones included. The list the picker shows. |
+| `useTMDataGridExport` | Hook | `(overrides?) => TMDataGridExportApi` | – | `exportAll`, `exportSelected`, `selectedCount`, `canExportSelected`. |
+| `exportGrid` | Export | `(args: ExportGridArgs) => Promise<void>` | – | Downloads the grid from outside a component. `ExportGridArgs` is `{ table, rows?, options? }`. |
+| `buildExportData` | Export | `(args: BuildExportDataArgs) => TMDataGridExportData` | – | The columns, labels and values a format writes. `BuildExportDataArgs` is `{ table, rows?, columns?, bounds? }`. |
+| `TMDataGridExportRows` · `TMDataGridExportColumns` | Types | `"all" \| "selected" \| rows` · `"visible" \| "all" \| ReadonlyArray<string>` | `"all"` · `"visible"` | Which rows and which columns an export takes. |
+| `writeExportFile` | Export | `(data, settings) => Promise<void>` | – | Writes export data in a format and downloads it. |
+| `downloadFile` | Export | `({ fileName, content, mimeType }) => void` | – | Downloads a string or a `Blob`. |
+| `csvExcelFormat` · `csvFormat` · `tsvFormat` · `jsonFormat` | Exports | `(options?) => TMDataGridExportFormat` | – | The built-in formats. |
+| `TMDataGridCsvFormatOptions` · `TMDataGridTsvFormatOptions` · `TMDataGridJsonFormatOptions` | Types | – | – | The options of `csvExcelFormat` and `csvFormat`, of `tsvFormat`, and of `jsonFormat`. |
+| `TMDataGridExportWriteOptions` | Type | `{ includeHeaders }` | – | The second argument of a format's `write`. |
+| `guardFormula` · `formatExportValue` | Exports | `(text) => string` · – | – | The formula guard and the text rule, for a format of your own. |
+| `resolveExportOptions` | Export | `(...overrides) => TMDataGridExportSettings` | – | The defaults with overrides folded over, `undefined` fields skipped. |
+| `countSelectedExportRows` | Export | `(table) => number` | – | How many rows `"selected"` would write. |
+| `DEFAULT_EXPORT_OPTIONS` | Constant | `TMDataGridExportSettings` | – | The defaults `exportOptions` merges over. |
+| `TMDataGridExportSettings` | Type | `Required<TMDataGridExportOptions>` | – | Export options with every field set. |
 
 See also: the `server-side` skill for `manualPagination` and `onReachEnd`, and
 the `grouping` skill for why the pager suspends.