@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/docs/row-selection.md

@@ -0,0 +1,134 @@
+# Row selection
+
+Picking rows out of the grid, and reading back what was picked. The grid
+separates two things: a set of rows for a bulk action, and a single highlighted
+row. `selectionMode` sets which of them a click drives, and defaults to
+`"checkbox"`.
+
+```tsx
+const grid = useTMDataGrid({ data, columns });                        // "checkbox"
+const rows = useTMDataGrid({ data, columns, selectionMode: "row" });
+const master = useTMDataGrid({ data, columns, selectionMode: "highlight" });
+```
+
+```demo
+file: rows/SelectionModes.tsx
+```
+
+## The four modes
+
+`selectionMode` sets what selecting looks like and what a bare row click does.
+A click can toggle a multi-selection or move a highlight, not both, so the two
+are one option rather than two.
+
+| Mode | Checkbox column | Row click |
+| ---- | --------------- | --------- |
+| `"checkbox"` | yes, multi-select | nothing |
+| `"row"` | no | selects, with the usual modifiers |
+| `"checkboxAndHighlight"` | yes, multi-select | highlights one row |
+| `"highlight"` | no | highlights one row - no selection at all |
+
+The first two write to TanStack's `rowSelection`, so the toolbar count,
+`getSelectedRowModel()` and persistence all behave the same either way.
+
+Under `"row"` the click follows the usual desktop-list conventions: a plain
+click replaces the selection with this row, Ctrl/Cmd toggles it and leaves the
+rest, Shift selects the range from the anchor, Ctrl+Shift adds that range. Rows are
+focusable in this mode, and Space or Enter toggles the focused row.
+
+`enableRowSelection: false` removes the checkbox column and row-click
+selection in any mode. It has no effect under `"highlight"`, which selects
+nothing.
+
+## The highlighted row
+
+The highlighted row is state of its own rather than a slice of `rowSelection`,
+so `"checkboxAndHighlight"` runs both at once: tick rows for a bulk action,
+click one to open its detail panel beside the grid.
+
+`defaultHighlightedRowId` seeds it and `onHighlightedRowChange` follows it,
+typically into a route for a master–detail view:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  selectionMode: "highlight",
+  onHighlightedRowChange: (rowId) =>
+    navigate({ to: "/employees/$id", params: { id: rowId ?? "" } }),
+});
+```
+
+For a panel that opens under the row instead of beside the grid, see
+[Row details](/docs/row-details). A grid can use both.
+
+## Acting on a selection
+
+Read the selection through the table store with TanStack Store's
+[`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference), rather
+than by calling a method directly. The table identity is stable across renders,
+so the React Compiler caches a bare `getSelectedRowModel()` call and the
+toolbar stops updating.
+
+```tsx
+const selected = useSelector(
+  grid.table.store,
+  () => grid.table.getSelectedRowModel().rows,
+);
+```
+
+```demo
+file: rows/SelectionState.tsx
+hint: Tick a few rows - the toolbar turns into a bulk-action bar and back.
+```
+
+## Highlighting selected rows
+
+`showSelectedBackground` follows the mode: on for `"row"`, off for
+`"checkbox"`. Set it explicitly for checkboxes and a background, or for row
+selection with no background change.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, showSelectedBackground: true });
+```
+
+The colour is `--dg-row-selected-bg`, which defaults to
+`--mantine-primary-color-light`. Change it on the grid element rather than
+touching the flag:
+
+```tsx
+<TMDataGrid
+  {...grid}
+  style={{ "--dg-row-selected-bg": "color-mix(in srgb, var(--mantine-color-blue-6) 12%, transparent)" }}
+/>
+```
+
+Rows carry `data-selected` whenever they are selected, `data-selected-bg` when
+they also take the background, and `data-highlighted` on the highlighted row.
+[Custom styling](/docs/row-styling) can key off any of them.
+
+## Group rows
+
+A group row's checkbox selects every record under it, at any depth, including
+records inside collapsed sub-groups. It shows a tick once all of them are
+selected and a dash while only some are. Only the records are written to
+`rowSelection`. See [Grouping](/docs/grouping#selection).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `selectionMode` | Option | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a row click does. |
+| `enableRowSelection` | Table option | `boolean \| (row) => boolean` | `true` | `false` removes the checkbox column and row-click selection. |
+| `enableMultiRowSelection` | Table option | `boolean` | `true` | `false` limits the selection to one row and drops group checkboxes. |
+| `showSelectedBackground` | Option | `boolean` | Follows the mode | Whether selected rows take a background tint. |
+| `defaultHighlightedRowId` | Option | `string \| null` | `null` | Row highlighted at mount. |
+| `onHighlightedRowChange` | Callback | `(rowId: string \| null) => void` | – | Fires when the highlight moves. |
+| `SELECT_COLUMN_ID` | Export | `"__select__"` | – | Id of the generated checkbox column. |
+| `getSelectableRowIds` | Export | `(table) => string[]` | – | Ids the header checkbox would select. |
+| `resolveRowSelectionClick` | Export | `(args) => ResolvedRowSelection` | – | The desktop-list click rules, for a custom surface. |
+| `--dg-row-selected-bg` | CSS variable | colour | `--mantine-primary-color-light` | Selected row background. |
+| `--dg-row-highlight-bg` | CSS variable | colour | Themed | Highlighted row background. |
+| `data-selected` | Data attribute | – | – | On every selected row. |
+| `data-selected-bg` | Data attribute | – | – | On selected rows that also take the background. |
+| `data-highlighted` | Data attribute | – | – | On the highlighted row. |

package/docs/row-styling.md

@@ -0,0 +1,133 @@
+# Row styling
+
+Colouring rows by their contents, such as an overdue invoice in red.
+
+```tsx
+<TMDataGrid.Table<Employee>
+  rowStyle={(row) =>
+    !row.getIsGrouped() && row.original.status === "Terminated"
+      ? { "--row-bg": "color-mix(in srgb, var(--mantine-color-red-6) 12%, transparent)" }
+      : undefined
+  }
+/>
+```
+
+Group rows are handed to `rowStyle` and `rowClassName` too, and a group row's `original` is an arbitrary child's record.
+Guard a callback that reads `original` with `row.getIsGrouped()`, or match `data-grouped="true"` to style the group rows themselves.
+
+```demo
+file: rows/RowStyling.tsx
+hint: Select and hover a coloured row - both still show through the row background.
+```
+
+## Set the row background
+
+Set `--row-bg` rather than `background`. Hover, selection, the highlight, the
+cell range and striping each add a background over the row and are composed
+against `--row-bg`; `background` overrides all of them, so a coloured row stops
+responding to hover and selection.
+
+```tsx
+rowStyle={() => ({ background: "pink" })}          // hover and selection hidden
+rowStyle={() => ({ "--row-bg": "pink" })}          // both still show
+```
+
+`rowStyle` accepts `CSSProperties` or an object of custom properties. The type
+is a union, so a callback returning either compiles.
+
+Pick a colour that reads under both colour schemes. A `-0` Mantine shade
+(`red-0`) is near-white, which turns unreadable behind light text in the dark
+scheme; mixing a mid shade into transparency tints both schemes evenly:
+`color-mix(in srgb, var(--mantine-color-red-6) 12%, transparent)`.
+
+The grid composes `--row-bg` over the theme's body colour, so a translucent value tints the row and stays opaque under the pinned columns and the pinned rows.
+
+## One cell, not the row
+
+There is no `cellStyle` or `cellClassName`. Style a single cell from the
+column's own `cell` renderer, which owns the element you want to colour:
+
+```tsx
+columnHelper.accessor("age", {
+  cell: ({ getValue }) => {
+    const age = getValue();
+    return <span style={{ color: age > 60 ? "var(--mantine-color-red-6)" : undefined }}>{age}</span>;
+  },
+});
+```
+
+From a stylesheet, match the cell's `data-column-id` under a `rowClassName`.
+Body cells carry no `data-dg-part`; the coordinate attributes identify them:
+
+```css
+.overdue [data-column-id="dueDate"] {
+  font-weight: 600;
+}
+```
+
+## Classes instead
+
+`rowClassName` takes the same shape and adds to the grid's own classes, for
+when the styling belongs in a stylesheet:
+
+```tsx
+<TMDataGrid.Table<Invoice>
+  rowClassName={(row) => (row.original.overdue ? classes.overdue : undefined)}
+/>
+```
+
+```css
+.overdue {
+  --row-bg: color-mix(in srgb, var(--mantine-color-red-6) 12%, transparent);
+  font-weight: 600;
+}
+```
+
+## Striping
+
+`striped` gives every second row `--dg-row-striped-bg`. Striping follows the
+row's **position in the view**, so it survives sorting, filtering and
+virtualization rather than sticking to particular records.
+
+```tsx
+<TMDataGrid.Table striped />
+```
+
+Pinned rows are not striped: they have left the scrolling order.
+
+## Styling by state
+
+Rows carry data attributes for their state, so a stylesheet can target any of
+it without a callback:
+
+| Attribute | On |
+| --- | --- |
+| `data-selected` | Selected rows |
+| `data-selected-bg` | Selected rows that also take the background |
+| `data-highlighted` | The highlighted row |
+| `data-grouped` | Every row: `"true"` on group rows, `"false"` on the rest |
+| `data-depth` | Every row. The nesting level |
+| `data-context-menu` | The row whose context menu is open |
+| `data-row-id` | Every row. Its id, which [tests](/docs/testing) key off |
+
+The state attributes are published as `"true"` or `"false"`, so match the
+value; the bare attribute selector matches every row:
+
+```css
+[data-dg-part="row"][data-grouped="true"] {
+  --row-bg: color-mix(in srgb, var(--mantine-color-gray-6) 12%, transparent);
+  font-weight: 600;
+}
+```
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `rowStyle` | Table prop | `TMDataGridRowStyle \| (row) => TMDataGridRowStyle` | – | Inline style for a body row. |
+| `rowClassName` | Table prop | `string \| (row) => string \| undefined` | – | Class for a body row, added after the grid's own. |
+| `striped` | Table prop | `boolean` | `false` | Every second row takes `--dg-row-striped-bg`. |
+| `TMDataGridRowStyle` | Export | type | – | `CSSProperties` or an object of `--*` custom properties. |
+| `--row-bg` | CSS variable | colour | – | The row's own background, composed over the body colour and under hover, selection and range. |
+| `--dg-row-striped-bg` | CSS variable | colour | Themed | The stripe colour. |
+| `--dg-row-height` | CSS variable | length | From `size` | Row height. `meta.rowHeight` is the supported way to change it. |

package/docs/scrolling.md

@@ -0,0 +1,111 @@
+# Scrolling and virtualization
+
+Virtualization is **always on**. There is no flag and no threshold: only the
+rows within the viewport, plus a small overscan, are mounted, at any row
+count.
+
+```tsx
+const grid = useTMDataGrid({ data, columns }); // 200 rows or 200 000
+```
+
+Rows only. Columns are not virtualized: every column that is visible is in the
+DOM, header and body alike, however far off-screen it sits. A grid with a few
+dozen columns is fine; hide the ones a user does not need rather than relying
+on the viewport to do it.
+
+## Overscan
+
+How many rows stay mounted on each side of the viewport. Defaults to `6`.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, overscan: 12 });
+```
+
+Raise it if a fast scroll flashes blank rows; lower it when rows are expensive
+to render.
+
+## Row height
+
+Taken from `meta.rowHeight`, or from the `size` prop when that is not set. Rows
+are **fixed height**, so the virtualizer's estimate is exact and the scrollbar
+does not drift as you scroll.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
+```
+
+[Row details](/docs/row-details) are the exception: a row showing a panel is as
+tall as the panel, so those rows are measured after they mount.
+`renderDetailsEstHeight` is what the virtualizer assumes for one it has not
+measured yet.
+
+## Scrolling to a row
+
+```tsx
+const { scrollToRow } = useTMDataGrid({ data, columns, getRowId });
+
+scrollToRow({ rowId: "42", align: "center" });
+```
+
+Under virtualization the target row may not be mounted, so
+`element.scrollIntoView()` cannot find it. `align` is `"start"`, `"center"`,
+`"end"` or `"auto"`, which scrolls only if the row is out of view.
+
+It answers whether the row could be reached. `false` means the row is not in
+the current view - filtered out, on another page, or an id matching no row -
+and nothing scrolled. A pinned row answers `true` without scrolling.
+
+The hook reaches the virtualizer through `scrollerRef`, which `TMDataGrid.Table`
+fills in. That is internal wiring rather than an API: spread the whole grid
+object onto `<TMDataGrid>`, because a hand-assembled prop list that leaves it
+out has no scrolling.
+
+While the draft store is running, `TMDataGrid.DraftActions` hands its
+`renderActions` slot an `actions.scrollToFirstOpenRow(align?)` that goes to the
+first row [left open](/docs/editing#the-draft-store), without your having to
+track the ids.
+
+## Edge callbacks
+
+`TMDataGrid.Table` reports arrivals at each edge, firing **once** when the
+scroll reaches it rather than on every scroll event:
+
+```tsx
+<TMDataGrid.Table
+  onScrollToBottom={() => console.log("at the end")}
+  onScrollToRight={() => console.log("at the last column")}
+/>
+```
+
+For loading more rows, use [`onReachEnd`](/docs/server-side#infinite-scroll)
+instead. It fires a number of rows before the bottom, and latches per row count
+so a pending fetch is not requested twice.
+
+## Scroll shadows
+
+Two soft shadows, both driven by `animation-timeline: scroll(…)` rather than by
+a scroll listener.
+
+**Under the header.** Once body rows scroll beneath the sticky header, a shadow
+appears along its bottom edge, indicating rows above the viewport. A grid with
+nothing to scroll shows none. `--dg-header-shadow-color` recolours it.
+
+**Beside a pinned lane.** A [pinned column](/docs/column-layout#pinning) shows a
+band over the data next to it, and only while it is covering content: it fades
+in over the first 20px of horizontal scroll and fades out again at the far
+end.
+
+Where `animation-timeline` is unsupported, the header's own border draws the
+boundary and the pinned band is always on.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `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. Answers whether it could be reached. |
+| `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
+| `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
+| `--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. |

package/docs/server-query.md

@@ -0,0 +1,246 @@
+# A server-backed search
+
+The grid's state is filters, sorting and a page index.
+An API takes a request body of its own: its own field names, its own operator set, its own status codes, and pages counted from 1.
+This recipe is the layer between the two, and the grid state that goes into it is shown as the request that comes out.
+
+```demo
+file: recipes/ServerQuery.tsx
+hint: Filter Amount or City and watch the request body under the grid change, then the result set follow it.
+extraSources: data/orderSearchApi.ts
+height: 700
+```
+
+The grid does no filtering, sorting or paging here.
+See [Server-side data](/docs/server-side) for the `manual*` options themselves; this page is about what to send them.
+
+## What the endpoint takes
+
+The demo's API is deliberately not grid-shaped:
+
+```ts
+type OrderSearchRequest = {
+  filter: { and: Array<Predicate> };
+  orderBy: Array<{ field: string; direction: "ASC" | "DESC" }>;
+  page: { number: number; size: number };
+};
+
+type Predicate =
+  | { field: string; op: "in" | "notIn"; values: Array<string | number> }
+  | { field: string; op: "range"; from?: string | number; to?: string | number }
+  | { field: string; op: "isNull" | "isNotNull" }
+  // …and the scalar form, for every remaining operator:
+  | { field: string; op: "eq" | "like" | "lt" | "gte"; value: string | number };
+```
+
+The response is a page envelope, not an array:
+
+```ts
+type OrderSearchResponse = {
+  items: Array<OrderRecord>;
+  page: { number: number; size: number; totalPages: number; totalItems: number };
+};
+```
+
+Forwarding `columnFilters` unchanged, as [Server-side data](/docs/server-side#sending-filters) describes, works when you own the endpoint.
+When you do not, the translation has to live somewhere, and one module that both directions pass through is easier to keep correct than a translation spread across the fetch, the columns and the cells.
+
+## Two tables, three functions
+
+The whole layer is `toSearchRequest` over two lookup tables, plus `toRow` on the way back.
+
+`QUERY_FIELDS` maps a column id onto an API field, together with the cast from what the filter control writes to what the field holds.
+Every filter control writes strings; `totalAmount` is a number and `status` an enum, so neither end is the right place for the conversion.
+
+```ts
+const QUERY_FIELDS: Record<string, { field: string; cast: (raw: string) => string | number }> = {
+  id: { field: "orderRef", cast: Number },
+  amount: { field: "totalAmount", cast: Number },
+  status: { field: "status", cast: (raw) => STATUS_CODES[raw] ?? raw },
+};
+```
+
+A column missing from the table is one the API cannot query.
+`toPredicate` returns `undefined` for it and the filter is dropped, rather than a field the endpoint would reject being sent.
+
+`PREDICATE_OPS` maps the grid's operators onto the endpoint's.
+Declare it as a `Record` over `TMDataGridFilterOperator` and not a `Partial`: an operator added by a later version of the grid then fails the build here, where it can be answered, instead of arriving at the server unmapped.
+
+```ts
+const PREDICATE_OPS: Record<TMDataGridFilterOperator, PredicateOp> = {
+  contains: "like",
+  between: "range",
+  before: "lt",
+  lessThan: "lt",
+  isAnyOf: "in",
+  isEmpty: "isNull",
+  // …and one line for every remaining operator.
+};
+```
+
+Several grid operators collapse onto one API operator.
+A date `before` and a number `lessThan` are both `lt` once the value has been cast.
+
+## Offering only what the endpoint answers
+
+The demo's endpoint answers every operator the grid has, which is the exception.
+An endpoint that has `like` and `eq` but no prefix match should not offer `startsWith` in the panel, because the only honest thing to do with it there is drop it, and a filter that silently does nothing looks like a bug.
+`meta.filter.operators` narrows a column to the operators the query can express, and the mapping table is then declared over exactly that list:
+
+```ts
+const TEXT_OPERATORS = [
+  "contains",
+  "equals",
+  "isEmpty",
+  "isNotEmpty",
+] as const satisfies readonly TMDataGridFilterOperator[];
+
+const TEXT_OPS: Record<(typeof TEXT_OPERATORS)[number], PredicateOp> = {
+  contains: "like",
+  equals: "eq",
+  isEmpty: "isNull",
+  isNotEmpty: "isNotNull",
+};
+
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: TEXT_OPERATORS } },
+});
+```
+
+One list feeds both the column and the type of the table, so an operator cannot be offered without a mapping, or mapped without being offered.
+A fresh filter on the column opens on `meta.filter.defaultOperator` when that is set, else on the type's default when the list holds it - `contains` here - else on the list's first entry.
+
+The lookup at the boundary still returns `undefined` for an operator it has no entry for.
+A filter restored by `persist` from before the list was narrowed can carry one, and dropping it is the same rule as dropping a column the API cannot query.
+
+## The three value shapes
+
+`TMDataGridFilterValue` is `{ operator, value }`, and the operator decides what `value` holds.
+A mapping function has to branch on all four cases, in this order:
+
+| Operator | `value` | Sent as |
+| --- | --- | --- |
+| `isEmpty`, `isNotEmpty` | Not used | `{ field, op }` |
+| `isAnyOf`, `isNoneOf` | `ReadonlyArray<string>` | `{ field, op, values }` |
+| `between` | `[min, max]`, either end possibly `""` | `{ field, op, from?, to? }` |
+| Everything else | `string` | `{ field, op, value }` |
+
+An empty end of a `between` pair leaves that side of the interval open, so it becomes an absent bound rather than an empty string.
+
+## What not to send
+
+A filter whose value is still empty stays in the grid's state so the panel keeps its row while the user types.
+It matches every row, so sending it as a predicate would narrow the result set to nothing.
+`activeColumnFilters` is the test, applied across the slice: it hands back the entries that narrow the grid, with their values typed as `TMDataGridFilterValue` rather than as `unknown`.
+
+```ts
+activeColumnFilters(state.columnFilters)
+  .map((filter) => toPredicate(filter.id, filter.value))
+  .filter((predicate): predicate is Predicate => predicate !== undefined);
+```
+
+## Keying the fetch on the request
+
+The request is JSON, so the JSON is both what you send and what the fetch can key on:
+
+```tsx
+const requestJson = useMemo(
+  () => JSON.stringify(toSearchRequest({ columnFilters, sorting, pagination }), null, 2),
+  [columnFilters, sorting, pagination],
+);
+
+const request = useMemo(() => JSON.parse(requestJson) as OrderSearchRequest, [requestJson]);
+```
+
+`request` then changes identity only when the query changes.
+Opening the filter panel and adding an empty row moves `columnFilters` and leaves the request alone, so no request is sent.
+With TanStack Query, the same string is the `queryKey`.
+
+Two things the effect owes the server:
+
+- **Debounce.** The filter value input updates on every keystroke, so a request per keystroke is what you get without it.
+- **Cancel.** A response that arrived after the query moved on is not this query's. A `cancelled` flag in the cleanup is enough; an `AbortController` on a real `fetch` is better.
+
+```tsx
+useEffect(() => {
+  let cancelled = false;
+  setLoading(true);
+
+  const timer = setTimeout(() => {
+    void searchOrders(request).then((response) => {
+      if (cancelled) return;
+      setRows(response.items.map(toRow));
+      setPage(response.page);
+      setLoading(false);
+    });
+  }, 300);
+
+  return () => {
+    cancelled = true;
+    clearTimeout(timer);
+  };
+}, [request]);
+```
+
+## Paging against a page envelope
+
+Three numbers, in three places:
+
+| The API's | The grid's | Written as |
+| --- | --- | --- |
+| `page.number`, counted from 1 | `pagination.pageIndex`, counted from 0 | `number: pageIndex + 1` |
+| `page.totalItems`, the matched count | `rowCount` | `rowCount: page?.totalItems ?? 0` |
+| `page.totalPages` | `state.pageCount`, derived from `rowCount / pageSize` | Nothing; the grid computes it |
+
+`pageCount` follows from `rowCount`, so a response's `totalPages` needs forwarding only when the server pages by something other than the size the grid asked for.
+Set `pageCount: -1` when the total is unknown, as an endpoint returning a cursor rather than a count leaves it.
+
+The footer shows the page number through the `renderPagination` slot, keeping the built-in page-size select and pager on either side of it:
+
+```tsx
+<TMDataGrid.Footer
+  renderPagination={({ Controls }) => (
+    <>
+      <Controls.PageSize />
+      <Controls.PageNumber />
+      <Controls.Pager />
+    </>
+  )}
+/>
+```
+
+A filter or a sort changes what page 3 means, and under `manualPagination` the grid takes itself back to page 1 when it does - see [the page index](/docs/server-side#the-page-index).
+The change callbacks are therefore the plain setters.
+
+`meta.totalRowCount` is the unfiltered total, which no filtered response carries.
+Take it from a separate count call, or from the one the page was opened with.
+Without it, `SummaryCount` shows the matched count alone rather than comparing it against the rows of one page.
+
+## What the client no longer knows
+
+Holding one page costs the grid the two things it derives from holding all of them.
+
+**Faceted options.** `meta.options: "faceted"` reads the distinct values present in `data`, which is now one page of them.
+The grid warns once per column about it.
+A select column declares its own set instead:
+
+```tsx
+columnHelper.accessor("city", {
+  meta: { type: "select", options: CITIES },
+});
+```
+
+**Rows off the page.** Row selection is keyed by `getRowId`, so ids selected on an earlier page stay in `rowSelection` while their rows are unmounted.
+Read the state rather than the row models, as [Server-side data](/docs/server-side#row-selection) describes.
+
+## Reference
+
+The pieces this recipe composes:
+
+| Piece | Documented on |
+| --- | --- |
+| `manualFiltering`, `manualSorting`, `manualPagination`, `rowCount`, `meta.loading`, `meta.totalRowCount` | [Server-side data](/docs/server-side) |
+| `TMDataGridFilterValue`, `TMDataGridFilterOperator`, `activeColumnFilters`, `meta.filter.operators`, `meta.filter.defaultOperator` | [Filtering](/docs/filtering) |
+| `meta.options` | [Defining columns](/docs/columns) |
+| `Footer` `renderPagination`, `Controls.PageSize`, `Controls.PageNumber`, `Controls.Pager` | [Pagination](/docs/pagination) |