@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/docs/loading-and-empty.md

@@ -0,0 +1,92 @@
+# Loading and empty states
+
+A grid can have nothing to show for four different reasons, and the body says
+which one it is: still fetching, emptied by a filter, or holding no data.
+
+```demo
+file: data/LoadingAndEmpty.tsx
+hint: Switch to loaded, then search for something that cannot match, to see the other branch.
+extraSources: data/employeeColumns.tsx
+```
+
+## Precedence
+
+An empty body shows exactly one thing, decided in this order:
+
+1. **Loading** - `meta.loading` is true: a centred loader. A grid that is
+   fetching never reports itself as empty.
+2. **Entry rows** - an open entry row from `edit.addRow()`: the entry block
+   only, with no message beside the form.
+3. **`renderEmptyState`** - your node, centred where the message would be.
+4. **Filtered-empty** - a filter or search is active: a search icon and
+   `labels.noResults` ("No rows match your filters").
+5. **Truly-empty** - no data at all: `labels.noRows` ("No rows to show").
+
+## Replacing the message
+
+`renderEmptyState` replaces states 4 and 5 with one render prop.
+`hasActiveFilters` says which of the two it is replacing, so one prop can render
+two different messages:
+
+```tsx
+<TMDataGrid.Table<Employee>
+  renderEmptyState={({ hasActiveFilters, table }) =>
+    hasActiveFilters ? (
+      <Stack align="center" gap="xs">
+        <Text c="dimmed">Nothing matches your filters</Text>
+        <Button variant="light" onClick={() => table.resetColumnFilters()}>
+          Clear filters
+        </Button>
+      </Stack>
+    ) : (
+      <Stack align="center" gap="xs">
+        <Text c="dimmed">No employees yet</Text>
+        <Button onClick={openCreateModal}>Add the first one</Button>
+      </Stack>
+    )
+  }
+/>
+```
+
+## Loading with rows on screen
+
+The body's loading state only appears while the grid is **empty**. A
+server-driven grid refetching with rows still on screen keeps showing them
+rather than blanking the body on every page change.
+
+`TMDataGrid.LoadingIndicator` covers that case: a small spinner while
+`meta.loading` is true, and nothing otherwise. Place it where you want it,
+typically after `Spacer`.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.LoadingIndicator />
+</TMDataGrid.Toolbar>
+```
+
+## Counting what is there
+
+`TMDataGrid.SummaryCount` shows visible rows out of the total. The total is
+`meta.totalRowCount` when you provide it, and the pre-filtered row count
+otherwise. A [server-side](/docs/server-side) grid must provide it, because the
+client only holds one page.
+
+```tsx
+<TMDataGrid.SummaryCount>
+  {visible} of {total} employees
+</TMDataGrid.SummaryCount>
+```
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |
+| `meta.noResultsLabel` | Option | `string` | `labels.noResults` | The filtered-empty message, without a render prop. |
+| `meta.totalRowCount` | Option | `number` | Pre-filtered count | The total `SummaryCount` reports. |
+| `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. |
+| `TMDataGrid.LoadingIndicator` | Component | – | – | Spinner while `meta.loading`, for when the body has rows. |
+| `TMDataGrid.SummaryCount` | Component | `children` replaces the text | – | Visible rows out of total. |
+| `labels.noRows` · `labels.noResults` | Labels | `string` | English defaults | The two built-in messages. See [Localization](/docs/localization). |

package/docs/localization.md

@@ -0,0 +1,79 @@
+# Localization
+
+Every string the grid renders - menu items, panels, tooltips, the pager and
+every `aria-label` - comes from one labels object. English by default.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  labels: { noResults: "Inga rader matchar dina filter" },
+});
+```
+
+`labels` takes **any subset** and merges it over the defaults.
+
+```demo
+file: customization/Localization.tsx
+extraSources: data/employeeColumns.tsx
+```
+
+## A complete translation
+
+A full Swedish dictionary ships as `TMDATAGRID_LABELS_SV`:
+
+```tsx
+import { TMDATAGRID_LABELS_SV } from "@jielga/tmdatagrid";
+
+const grid = useTMDataGrid({ data, columns, labels: TMDATAGRID_LABELS_SV });
+```
+
+`TMDATAGRID_LABELS_EN` is the English base, and `TMDataGridLabels` is the full
+dictionary type, so a missing key in a new translation is a compile error.
+
+## Labels that carry a value
+
+These labels are functions, so each language can place the value where its
+grammar requires:
+
+```tsx
+labels: {
+  groupBy: (column) => `Gruppera på ${column}`,
+  pageRange: ({ from, to, total }) => `${from}–${to} av ${total}`,
+}
+```
+
+## Keep the object stable
+
+Define it at module scope, or memoize it. The grid re-renders when the labels
+object changes identity.
+
+```tsx
+const labels = { noResults: "Inga träffar" } satisfies TMDataGridLabelsOverride;
+```
+
+## Reading them yourself
+
+The resolved dictionary comes back from the hook as `grid.labels`, and from
+context as `useTMDataGridContext().labels`, so a
+[toolbar component of your own](/docs/toolbar) uses the same strings as the
+built-in parts, in whatever language is configured.
+
+`mergeLabels(base, override)` is the merge itself, exported for composing
+dictionaries before passing one in.
+
+`meta.noResultsLabel` remains as a per-instance override of
+`labels.noResults`.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `labels` | Option | `TMDataGridLabelsOverride` | English | Any subset, merged over the defaults. Keep it stable. |
+| `grid.labels` | Hook return | `TMDataGridLabels` | – | The resolved dictionary. |
+| `TMDATAGRID_LABELS_EN` | Export | `TMDataGridLabels` | – | The English base. |
+| `TMDATAGRID_LABELS_SV` | Export | `TMDataGridLabels` | – | A complete Swedish dictionary. |
+| `TMDataGridLabels` | Export | type | – | The full dictionary. What a new translation must cover. |
+| `TMDataGridLabelsOverride` | Export | type | – | A partial dictionary. |
+| `mergeLabels` | Export | `(base, override) => TMDataGridLabels` | – | The merge, for composing dictionaries. |
+| `meta.noResultsLabel` | Option | `string` | `labels.noResults` | Per-instance override of the filtered-empty message. |

package/docs/menu.md

@@ -0,0 +1,143 @@
+# Grid menu
+
+`TMDataGrid.Menu` is the burger button at the end of the toolbar and the Mantine `Menu` it opens.
+Its children are the dropdown: Mantine `Menu.Item`s of your own, and the built-in items under `TMDataGrid.Menu.*`.
+
+```tsx
+import { Menu } from "@mantine/core";
+
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.FilterButton />
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Export />
+    <Menu.Item onClick={saveView}>Save view</Menu.Item>
+    <Menu.Divider />
+    <Menu.Label>Columns</Menu.Label>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+</TMDataGrid.Toolbar>
+```
+
+```demo
+file: customization/GridMenu.tsx
+hint: The burger holds the app's own items above the column chooser.
+```
+
+A custom item reads the grid from context, the same way a [toolbar button](/docs/toolbar#buttons-of-your-own) does.
+`TMDataGrid.Menu.Export` and `TMDataGrid.Menu.ExportSelected` are the built-in export items; their props and formats are on [Export](/docs/export).
+Mantine's `Menu.Divider`, `Menu.Label` and `Menu.Sub` work as they do in any Mantine menu; the grid wraps nothing of Mantine's.
+
+`TMDataGrid.Menu` always renders: it cannot see whether its children render anything.
+A menu holding only `TMDataGrid.Menu.Columns` on a grid with `enableHiding: false` opens empty, so hide it with the same check the built-in buttons use:
+
+```tsx
+const { table, features } = useTMDataGridContext();
+const { canHideAny } = getGridCapabilities(table, features);
+
+{canHideAny && (
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
+)}
+```
+
+## The column chooser as menu items
+
+`TMDataGrid.Menu.Columns` is the whole chooser: one checkbox item per column that can be hidden, a search box once there are six of them, **Show/Hide All** and **Reset layout**.
+It renders nothing when no column can be hidden.
+The pieces it is made of are exported for menus that want only some of them.
+
+| Component | Renders |
+| --- | --- |
+| `TMDataGrid.Menu.Columns` | `Menu.Search`, the toggles, a divider, show/hide all and reset layout. By default the search box shows from six columns; `searchable` shows it always and `searchable={false}` never. |
+| `TMDataGrid.Menu.ColumnToggles` | One item per hideable column, with a checkbox that shows both states. `search` narrows the list to the labels containing it. |
+| `TMDataGrid.Menu.ShowHideAll` | One checkbox item over the same list. An indeterminate box marks a partial state, and a click then shows all. |
+| `TMDataGrid.Menu.ResetLayout` | One item calling `resetSettings()`: visibility, order, pinning and widths. |
+
+Each of them needs a Mantine `Menu` around it and reads the grid from context, so they work in any Mantine menu rendered inside `TMDataGrid`, not only in the burger:
+
+```tsx
+<Menu width={260} withinPortal>
+  <Menu.Target>
+    <Button size="compact-xs" variant="subtle">
+      View
+    </Button>
+  </Menu.Target>
+  <Menu.Dropdown>
+    <Menu.Item onClick={() => setDensity("compact")}>Compact rows</Menu.Item>
+    <Menu.Divider />
+    <TMDataGrid.Menu.ColumnToggles />
+    <Menu.Divider />
+    <TMDataGrid.Menu.ShowHideAll />
+    <TMDataGrid.Menu.ResetLayout />
+  </Menu.Dropdown>
+</Menu>
+```
+
+### As a submenu
+
+Every column header's menu has **Manage columns**, a `Menu.Sub` holding `TMDataGrid.Menu.Columns`.
+The same composition works in a menu of your own:
+
+```tsx
+<Menu.Sub>
+  <Menu.Sub.Target>
+    <Menu.Sub.Item>Manage columns</Menu.Sub.Item>
+  </Menu.Sub.Target>
+  <Menu.Sub.Dropdown>
+    <TMDataGrid.Menu.Columns searchable={false} />
+  </Menu.Sub.Dropdown>
+</Menu.Sub>
+```
+
+`searchable` is for a block at the top level of a dropdown.
+`Menu.Search` registers on the root menu, which switches off type-ahead and the arrow keys of every dropdown of that menu, so a search box inside a submenu breaks the keyboard behaviour of the menu around it.
+ArrowDown from the search box moves to the first listed column, whatever sits above the block.
+
+### The panel instead
+
+`TMDataGrid.ColumnsPanel` is the same chooser as plain controls, for a host that is not a menu: a Popover, a Drawer, or a settings page.
+
+```tsx
+const [opened, setOpened] = useState(false);
+
+<Popover opened={opened} onChange={setOpened} withinPortal trapFocus>
+  <Popover.Target>
+    <ActionIcon aria-label="Columns" onClick={() => setOpened((open) => !open)}>
+      <IconColumns3 size={18} />
+    </ActionIcon>
+  </Popover.Target>
+  <Popover.Dropdown p={0}>
+    <TMDataGrid.ColumnsPanel />
+  </Popover.Dropdown>
+</Popover>
+```
+
+## Labels
+
+`labels.menuButton` is the burger's tooltip and `aria-label`.
+The chooser uses the panel's strings: `columnsSearchPlaceholder`, `columnsNoMatch`, `columnsShowHideAll` and `columnsReset`.
+See [Localization](/docs/localization).
+
+## Testing
+
+The burger is `data-dg-part="menu-button"`.
+The items publish the same parts as the panel: `columns-search`, `columns-toggle` with `data-column-id`, `columns-toggle-all` and `columns-reset`, so a test written against the panel reads the same on the menu.
+The export items are `menu-export` and `menu-export-selected`.
+See [Testing](/docs/testing).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `TMDataGrid.Menu` | Component | Mantine `MenuProps` without `children`, plus `children`, `icon`, `label` | `position="bottom-end"`, `shadow="md"`, `width={260}`, `withinPortal` | The burger and its dropdown. `icon` replaces the burger; `label` is the tooltip and `aria-label`, default `labels.menuButton`. |
+| `TMDataGrid.Menu.Columns` | Component | `searchable?: boolean \| "auto"` | `"auto"` | The whole column chooser as menu items. `"auto"` shows the search box from six columns. Renders nothing when no column can be hidden. |
+| `TMDataGrid.Menu.ColumnToggles` | Component | `search?: string` | – | One checkbox item per hideable column. |
+| `TMDataGrid.Menu.ShowHideAll` | Component | – | – | One checkbox item over every hideable column. |
+| `TMDataGrid.Menu.ResetLayout` | Component | – | – | Calls `resetSettings()`. |
+| `TMDataGrid.Menu.Export` · `.ExportSelected` | Components | `TMDataGridExportOptions` | – | The export items. Props on [Export](/docs/export). |
+| `TMDataGrid.ColumnsPanel` | Component | – | – | The chooser as plain controls, for a host that is not a menu. |
+| `labels.menuButton` | Option | `string` | `"Menu"` | The burger's tooltip and `aria-label`. |
+| `TMDataGridMenuProps` · `TMDataGridMenuColumnsProps` · `TMDataGridMenuExportProps` | Export | types | – | The prop types. |

package/docs/migrating-to-2.md

@@ -0,0 +1,163 @@
+# Migrating from the 2.0 beta
+
+2.0.0 removes every name deprecated during the 2.0 beta, stops exporting a set of internal helpers, and changes what three edit calls resolve.
+This page lists each change and the code that replaces it, from any `2.0.0-beta` release.
+
+## Read the batch edit results
+
+`edit.commitAll()` and `edit.saveDrafts()` resolve an object instead of a `boolean`:
+
+| Call | Resolves |
+| --- | --- |
+| `edit.commitAll()` | `{ ok, committed, open }` |
+| `edit.saveDrafts()` | `{ ok, saved, kept, reopened }` |
+| `edit.addRows(rows, options)` | `{ ok, committed, open }` - `ok` is new |
+
+Important: a check on the old `boolean` still compiles and is now always true.
+Search your code for `commitAll()` and `saveDrafts()` and read `ok`:
+
+```tsx
+// beta
+if (await grid.edit.saveDrafts()) notify("Saved");
+
+// 2.0.0
+const { ok, kept, reopened } = await grid.edit.saveDrafts();
+if (ok) notify("Saved");
+else notify(`${kept.length + reopened.length} rows need attention`);
+```
+
+Each list holds row ids, and temp ids for new rows.
+`ok` is `true` when `open` is empty, or, for `saveDrafts()`, when `kept` and `reopened` are both empty.
+See [Saving the store](/docs/draft-store#saving-the-store) for what each list means.
+
+The `actions.save` and `actions.commitAll` that `TMDataGrid.DraftActions` passes to a custom slot resolve the same objects.
+
+`edit.commit(rowId)` still resolves a `boolean`.
+
+## Rename the onSaveDrafts return type
+
+The type of what `editing.onSaveDrafts` may return is renamed `TMDataGridSaveDraftsResponse`.
+`TMDataGridSaveDraftsResult` is now the type `edit.saveDrafts()` resolves, so code that kept the old name for the callback fails to compile:
+
+```tsx
+// beta
+import type { TMDataGridSaveDraftsResult } from "@jielga/tmdatagrid";
+
+// 2.0.0
+import type { TMDataGridSaveDraftsResponse } from "@jielga/tmdatagrid";
+```
+
+## Replace removed names
+
+| Removed | Use instead |
+| --- | --- |
+| `edit.submitAll()` | `edit.commitAll()`, then `edit.saveDrafts()` |
+| `editing.onCommitDrafts` | `editing.onSaveDrafts` |
+| `rows` and `added` in the `onSaveDrafts` payload | `updated` and `created` |
+| `TMDataGridEditCommitDraftsArgs` | `TMDataGridSaveDraftsArgs` |
+| `state.pendingCount` in a `TMDataGrid.DraftActions` slot | `state.draftCount` or `state.openCount` |
+| `cellExport` on `TMDataGrid.Table` | `exportOptions` on `useTMDataGrid` |
+| `exportGridToCsv` | `exportGrid` |
+| `TMDataGridCellExportOptions`, `DEFAULT_CELL_EXPORT_OPTIONS`, `fromCellExportOptions` | `TMDataGridExportOptions`, `DEFAULT_EXPORT_OPTIONS` |
+| `buildCellMatrix`, `buildGridCellMatrix`, `BuildCellMatrixArgs`, `TMDataGridCellMatrix` | `buildExportData`, `BuildExportDataArgs`, `TMDataGridExportData` |
+| `toExcelCsv` | `csvExcelFormat` |
+| `downloadTextFile` | `downloadFile` |
+| `labels.exportCsv` | `labels.exportCells` |
+
+### submitAll
+
+`submitAll()` was `commitAll()` followed by `saveDrafts()`.
+Call both, and combine the results where one answer is needed:
+
+```tsx
+const committed = await grid.edit.commitAll();
+const saved = await grid.edit.saveDrafts();
+const ok = committed.ok && saved.ok;
+```
+
+### The CSV export options
+
+`separator` and `decimalComma` move into a format; `includeHeaders` and `fileName` stay in the options:
+
+```tsx
+// beta
+<TMDataGrid.Table cellExport={{ separator: ",", decimalComma: false, fileName: "orders" }} />;
+exportGridToCsv({ table, options: { separator: ",", decimalComma: false } });
+
+// 2.0.0
+const exportOptions = {
+  format: csvExcelFormat({ separator: ",", decimalComma: false }),
+  fileName: "orders",
+} satisfies TMDataGridExportOptions;
+
+const grid = useTMDataGrid({ data, columns, exportOptions });
+await exportGrid({ table: grid.table, options: exportOptions });
+```
+
+`exportOptions` on the hook applies to every export the grid offers, the cell-range menu included.
+
+### The matrix functions
+
+The export functions now return values, not text.
+A format writes the text:
+
+```tsx
+// beta
+const csv = toExcelCsv(buildGridCellMatrix({ table }), { separator: ";" });
+downloadTextFile({ fileName: "export.csv", text: csv });
+
+// 2.0.0
+const data = buildExportData({ table });
+const csv = await csvExcelFormat().write(data, { includeHeaders: true });
+downloadFile({ fileName: "export.csv", content: csv, mimeType: "text/csv;charset=utf-8" });
+```
+
+For a cell range, pass `rows` and `bounds` to `buildExportData` instead of `rows`, `columns` and `bounds` to `buildCellMatrix`.
+`toClipboardText(data)` writes the tab-separated text for the clipboard.
+
+## Remove annotations from meta callbacks
+
+The `row` that `meta.options` and `meta.edit.enabled` callbacks receive is typed with the row type of `createTMDataGridColumnHelper<TData>()`.
+Remove casts on `row.original`.
+A callback whose parameter is annotated with the untyped row no longer compiles; remove the annotation:
+
+```tsx
+// beta
+meta: {
+  edit: {
+    enabled: (row: Row<TMDataGridFeatures, TMDataGridRowData>) =>
+      (row.original as Employee).status !== "Terminated",
+  },
+}
+
+// 2.0.0
+meta: {
+  edit: { enabled: (row) => row.original.status !== "Terminated" },
+}
+```
+
+Columns built without the helper keep the untyped row.
+
+## Replace un-exported helpers
+
+These names are internal to the grid and are no longer exported from `@jielga/tmdatagrid`.
+An import of one fails to compile:
+
+| Removed | Use instead |
+| --- | --- |
+| `getDefaultOperator` | `getColumnDefaultOperator(column)` |
+| `isColumnEditableForRow` | `edit.canEditCell(row, column)` |
+| `isColumnReorderable` | `getColumnCapabilities(column, features).canReorder` |
+| `measureColumnContentWidth` | `autosizeColumn` |
+| `tmDataGridFeatures` | The `TMDataGridFeatures` type |
+| `isSameCell`, `resolveCellMove`, `ResolveCellMoveArgs`, `TMDataGridCellCoords`, `TMDataGridCellNav` | No public replacement; internal to the grid. |
+| `boundsCellCount`, `boundsEdges`, `isWithinBounds` | No public replacement; internal to the grid. |
+| `getColumnFilterControl` | No public replacement; internal to the grid. |
+| `TMDataGridColumnLayout` | No public replacement; internal to the grid. |
+
+## Behaviour changes
+
+- Under `editing.draft` without `onSaveDrafts`, a deletion whose `onRowDelete` throws keeps its deletion mark and is reported in `kept`.
+  In the beta, `saveDrafts()` rejected and the mark was lost.
+- The Swedish labels `TMDATAGRID_LABELS_SV` say "Välj" for selecting: "Välj alla", "Välj alla rader", "Välj rad" and "Välj grupp".
+  Update tests that find these controls by their Swedish name.

package/docs/pagination.md

@@ -0,0 +1,144 @@
+# Pagination
+
+**Off by default.** The grid renders every filtered and sorted row and relies
+on [virtualization](/docs/scrolling), which handles any row count. Turn paging
+on when users should move through the data a page at a time, not to keep a
+large grid responsive.
+
+There are three modes.
+
+**No pagination** - the default. `TMDataGrid.Footer` renders nothing.
+
+```tsx
+const grid = useTMDataGrid({ data, columns });
+```
+
+**Client pagination** - the table pages the data itself, and the Footer renders
+its pager. Initial page size is 25, configurable through
+`initialState.pagination`.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enablePagination: true });
+```
+
+**Manual pagination** - the server pages, and the grid stops.
+`manualPagination: true` implies `enablePagination`, so no extra flag is
+needed. See [Server-side data](/docs/server-side).
+
+```tsx
+const grid = useTMDataGrid({
+  data: page.rows,
+  columns,
+  manualPagination: true,
+  rowCount: page.total,
+  state: { pagination },
+  onPaginationChange: setPagination,
+});
+```
+
+```demo
+file: data/Pagination.tsx
+extraSources: data/employeeColumns.tsx
+```
+
+`enablePagination` is defined by the grid rather than by TanStack, which ships
+the pagination state and APIs but no `enable` option.
+
+## Replacing the pager
+
+`TMDataGrid.Footer` takes a `renderPagination` slot, handed three things: the
+`state` the pager is showing, the `actions` it can take, and `Controls` - the
+built-in pieces, already wired.
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ state, actions, Controls }) => (
+    <Group>
+      <Controls.PageSize />
+      <Button onClick={actions.previousPage} disabled={!state.canPreviousPage}>
+        Back
+      </Button>
+      <Text>
+        {state.pageIndex + 1} / {state.pageCount}
+      </Text>
+      <Button onClick={actions.nextPage} disabled={!state.canNextPage}>
+        Next
+      </Button>
+    </Group>
+  )}
+/>
+```
+
+The default footer renders `PageSize`, `Range` and `Pager`, in that order. A
+control kept from `Controls` behaves as it does in the default footer, including
+greying out while a grouping suspends paging.
+
+| Member | Renders |
+| --- | --- |
+| `Controls.PageSize` | "Rows per page" and its select |
+| `Controls.Range` | The "1–25 of 300" label |
+| `Controls.PageNumber` | The "Page 3 of 200" label |
+| `Controls.Pager` | The previous and next buttons |
+
+`PageNumber` is not in the default footer.
+It is the label a server-paged grid usually shows in place of a row range, so it is put in through the slot:
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ Controls }) => (
+    <>
+      <Controls.PageSize />
+      <Controls.PageNumber />
+      <Controls.Pager />
+    </>
+  )}
+/>
+```
+
+It reads `pageCount`, so a grid declaring `pageCount: -1` shows "Page 3" alone.
+
+`state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
+`canPreviousPage`, `canNextPage`, the `from` / `to` bounds of the current page,
+and `isPagingActive`. `actions` carries `setPageIndex`, `setPageSize`,
+`previousPage`, `nextPage`, `firstPage` and `lastPage`.
+
+`getTMDataGridPaginationApi(table)` returns the same `{ state, actions }`
+outside the Footer, for a pager that lives elsewhere on the page. `Controls` is
+not included: those components are bound to the grid's context and work only
+inside the slot.
+
+## Grouping
+
+While a column is grouped the pager greys itself out and the range is replaced
+with `Grouped · all N rows`. See
+[Grouping](/docs/grouping#grouping-and-pagination).
+
+A custom pager can grey itself out the same way:
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ state, actions }) => (
+    <MyPager {...state} {...actions} disabled={!state.isPagingActive} />
+  )}
+/>
+```
+
+`isPagingActive` is live state: whether the pager is currently slicing
+anything. `getGridCapabilities(...).canPaginate` is configuration: whether
+paging is switched on at all. The two differ while a grouping is active.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enablePagination` | Option | `boolean` | `false` | Client-side paging and the Footer's pager. Grid-defined. |
+| `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
+| `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. |
+| `resetPageOnQueryChange` | Option | `boolean` | `true` | Back to page 1 when a filter, the quick search, the sort or the grouping changes. `false` keeps the page. See [Server-side data](/docs/server-side#the-page-index). |
+| `TMDataGrid.Footer` | Component | – | – | 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. |
+| `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot's argument. |
+| `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |