@jielga/tmdatagrid 2.0.0-beta.8 → 2.0.0

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) |

package/docs/server-side.md

@@ -0,0 +1,206 @@
+# Server-side data
+
+When the client holds one page and the server does the work, paging, sorting and
+filtering all become round trips and the grid stops doing them itself.
+
+The grid reads rows through `getPaginatedRowModel()` and totals through
+`getRowCount()` and `getPageCount()`, all of which respect TanStack's manual
+modes. A server-driven grid therefore requires only the standard `manual*`
+configuration. `manualPagination: true` also switches the grid's pagination flag
+on, so `TMDataGrid.Footer` renders its pager without `enablePagination`.
+
+When the total is unknown, declare `pageCount: -1`: the next button stays
+enabled and the `pagination` render prop receives `pageCount: -1`.
+
+## Usage
+
+```tsx
+const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 });
+const [sorting, setSorting] = useState([]);
+const [columnFilters, setColumnFilters] = useState([]);
+
+const { data, isFetching } = useQuery({
+  queryKey: ["employees", pagination, sorting, columnFilters],
+  queryFn: () => fetchEmployees({ pagination, sorting, columnFilters }),
+  placeholderData: keepPreviousData,
+});
+
+const grid = useTMDataGrid({
+  columns,
+  data: data?.rows ?? [],
+  getRowId: (row) => String(row.id),
+
+  manualPagination: true,
+  manualSorting: true,
+  manualFiltering: true,
+  rowCount: data?.total ?? 0,
+
+  state: { pagination, sorting, columnFilters },
+  onPaginationChange: setPagination,
+  onSortingChange: setSorting,
+  onColumnFiltersChange: setColumnFilters,
+
+  meta: { loading: isFetching, totalRowCount: data?.totalUnfiltered },
+});
+```
+
+```demo
+file: data/ServerSide.tsx
+hint: Sorting, searching and paging are all round trips against a server with 500 ms of latency.
+extraSources: data/orders.ts
+```
+
+## Differences from client-side data
+
+| Concern | Client-side | Server-side |
+| --- | --- | --- |
+| Rendered rows | The current page, sliced locally | The rows returned by the server |
+| Footer total | Pre-paginated row count | `options.rowCount` |
+| `SummaryCount` total | Pre-filtered row count | `meta.totalRowCount`; without it, the count renders alone |
+| Loading state | Not applicable | `meta.loading` |
+
+No additional configuration is required. Column menus, the filter panel and the
+column manager behave identically in both modes.
+
+## The page index
+
+A column filter, the quick search or a sort changes what page 3 means.
+The result set is a different one, and it may not have a page 3 at all - so the grid resets `pageIndex` to 0 whenever the query changes, on every grid.
+The reset is applied in the same event as the change, so one request goes out, for the first page of the new query.
+
+`resetPageOnQueryChange: false` switches it off.
+
+TanStack's `autoResetPageIndex` is a different rule and does not cover this.
+It fires on a change to `data` - which server-side is the response landing, after the request was sent, and under `editing.draft` every commit - so the grid switches it off everywhere and resets on the query change itself.
+
+## Column options
+
+`meta.options: "faceted"` reads the distinct values present in `data`, which server-side is one page of them.
+The dropdown then offers whatever happened to be on the page the user is looking at, and looks correct while being wrong.
+Declare the set instead, as a list or a function.
+The grid warns once per column when a faceted column resolves under `manualFiltering` or `manualPagination`.
+
+## Sending filters
+
+Filter values are plain JSON:
+
+```json
+[
+  { "id": "lastName", "value": { "operator": "contains", "value": "holm" } },
+  { "id": "age", "value": { "operator": "greaterThan", "value": "30" } },
+  { "id": "status", "value": { "operator": "isAnyOf", "value": ["Paid", "Pending"] } },
+  { "id": "hired", "value": { "operator": "onOrAfter", "value": "2026-01-01" } }
+]
+```
+
+Forward `columnFilters` unchanged and translate it at the API boundary.
+`activeColumnFilters` hands back the entries that are narrowing the grid, typed:
+`ColumnFiltersState` types `value` as `unknown`, and an entry whose value is
+still empty matches every row.
+
+```ts
+import { activeColumnFilters } from "@jielga/tmdatagrid";
+
+const active = activeColumnFilters(columnFilters);
+// [{ id: "lastName", value: { operator: "contains", value: "holm" } }]
+```
+
+It takes the `columnFilters` array, or the table where the grid owns the slice.
+`isFilterActive(value)` is the single-value test it is built on.
+Only the grid's own `{ operator, value }` shape is read: an entry holding some
+other value - a custom filter control writing raw values - is dropped.
+
+Debounce requests. The filter value input updates on every keystroke.
+
+An endpoint that answers only some operators - `contains` and `equals` but no
+`startsWith` - should not have the rest offered. `meta.filter.operators` on the
+column narrows the panel and the header funnel to the operators the query can
+express; see [Operators](/docs/filtering#operators).
+
+For an endpoint that speaks its own query language rather than taking the
+grid's filter model, see [A server-backed search](/docs/server-query): one
+mapping layer turning filters, sorting and the page index into a request body,
+and the response envelope back into rows.
+
+## Persistence
+
+`persist` works unchanged. `dataKey` restores filters, sorting and pagination
+before the first request, so reloading the page repeats the query the user last
+ran.
+
+If the same state is also held in your own `useState`, initialise it from the
+same source or let the grid own it. Do not maintain both independently.
+
+## Row selection
+
+Row selection is keyed by `getRowId`, so ids must be stable across pages. With
+`manualPagination`, rows selected on an earlier page remain in `rowSelection`
+even though they are no longer mounted. Read the state rather than the row
+models:
+
+```ts
+const selectedIds = Object.keys(grid.table.store.state.rowSelection);
+```
+
+## Infinite scroll
+
+An alternative to the pager: keep every fetched row in `data` and load more as
+the user scrolls. `onReachEnd` on `TMDataGrid.Table` fires as the scroll nears
+the last row. Append the next page and the virtualizer keeps its position:
+
+```tsx
+const [rows, setRows] = useState<Order[]>([]);
+
+const grid = useTMDataGrid({
+  data: rows,
+  columns,
+  getRowId: (row) => String(row.id),
+  meta: { loading: isFetching, totalRowCount: total },
+  enableSorting: false,
+  enableColumnFilters: false,
+});
+
+<TMDataGrid.Table onReachEnd={() => void fetchNextPage()} />
+```
+
+```demo
+file: data/InfiniteScroll.tsx
+hint: Scroll to the bottom and keep going. 100 rows arrive at a time and the scroll position holds.
+extraSources: data/orders.ts
+height: 460
+```
+
+Fetch page zero yourself on mount. `onReachEnd` does not fire on an empty grid.
+
+`onReachEnd` fires once per row count, so a pending fetch is not requested again
+until its rows land. `reachEndThreshold` (default 10) sets how many rows before
+the end it fires. `TMDataGrid.LoadingIndicator` in the toolbar shows the fetch,
+since the body keeps showing the rows it already has.
+
+Two constraints apply:
+
+- **Sorting and filtering must be server-side** (`manualSorting` /
+  `manualFiltering`) or disabled. The client only holds a prefix of the data, so
+  a client-side sort would order that prefix and present it as the whole. When a
+  server-side sort or filter changes, reset the accumulated rows and start from
+  page zero.
+- **Not compatible with `enablePagination`.** The pager slices the same scroll
+  the callback watches, so the end reached is the page's rather than the data's.
+  The grid warns once if both are set.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
+| `manualSorting` | Table option | `boolean` | `false` | The server sorts. |
+| `manualFiltering` | Table option | `boolean` | `false` | The server filters, column filters and quick search alike. |
+| `manualGrouping` | Table option | `boolean` | `false` | The rows arrive grouped. See [Grouping](/docs/grouping#server-side-grids). |
+| `rowCount` | Table option | `number` | – | The true total. `pageCount: -1` when it is unknown. |
+| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. See [Loading and empty states](/docs/loading-and-empty). |
+| `meta.totalRowCount` | Option | `number` | – | The unfiltered total, for `SummaryCount`. |
+| `resetPageOnQueryChange` | Option | `boolean` | `true` | Back to page 1 when a filter, the quick search, the sort or the grouping changes. |
+| `onReachEnd` | Table prop | `() => void` | – | Fires as the scroll nears the last row. Latches per row count. |
+| `reachEndThreshold` | Table prop | `number` | `10` | How many rows before the end it fires. |
+| `activeColumnFilters` | Export | `(columnFilters \| table) => Array<{ id, value }>` | – | The filters in the grid's own value shape that narrow anything, typed. |
+| `isFilterActive` | Export | `(value) => boolean` | – | Whether one filter value narrows anything. |

package/docs/sorting.md

@@ -0,0 +1,101 @@
+# Sorting
+
+On by default. Click a header to sort it, click again to reverse, click a third
+time to clear. The column menu has the same three actions.
+
+```tsx
+const grid = useTMDataGrid({ data, columns });
+```
+
+```demo
+file: columns/Sorting.tsx
+hint: Click a header to sort, Shift+click a second to append - the badge beside the arrow is its priority.
+```
+
+## Sorting by more than one column
+
+Shift+click a second header to **add** it to the sort rather than replace it.
+While more than one column sorts, each sorted header shows its priority - 1, 2,
+… - beside the arrow, so the order they are applied in is visible.
+
+A plain click still replaces the whole sort, and the menu's Sort items do the
+same.
+
+This is TanStack's own `isMultiSortEvent`, so `enableMultiSort`,
+`maxMultiSortColCount` and a custom `isMultiSortEvent` all pass straight
+through:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  maxMultiSortColCount: 3,
+  // Ctrl rather than Shift, say.
+  isMultiSortEvent: (event) => event.ctrlKey,
+});
+```
+
+## Turning it off
+
+`enableSorting: false` on the table removes click-to-sort, the indicator and
+the menu items everywhere; on a column it removes them for that column alone.
+
+```tsx
+columnHelper.accessor("avatar", { header: "", enableSorting: false });
+```
+
+A column whose menu has no remaining items renders no menu button and does not
+handle right-click, so the browser's own menu opens instead.
+
+## Where the state lives
+
+Sorting writes TanStack's `sorting` state, an array of `{ id, desc }` in
+priority order. Seed it, control it, or read it like any other slice:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  initialState: { sorting: [{ id: "lastName", desc: false }] },
+});
+```
+
+It is a **data** slice: it names a column and a direction over the data itself,
+so a [persisted](/docs/use-tm-data-grid#persist) grid comes back sorted the way
+it was left, under `dataKey`. For a server that does the sorting, see
+[Server-side data](/docs/server-side).
+
+Grouping runs first, so a grouped grid sorts rows within each group and orders
+the groups by their aggregated value. See
+[Grouping](/docs/grouping#sorting-a-grouped-grid).
+
+## Custom comparators
+
+`sortFn` on the column takes any of TanStack's registered names, or a function
+of two rows and the column id. It is `sortFn` in v9, not v8's `sortingFn`.
+
+```tsx
+columnHelper.accessor("priority", {
+  header: "Priority",
+  sortFn: (rowA, rowB) =>
+    RANK[rowA.original.priority] - RANK[rowB.original.priority],
+});
+```
+
+## The header menu
+
+The menu opens from the ⋮ button on the header, or from a right-click anywhere
+on it. The items are the same either way; a right-click opens it at the
+pointer.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enableSorting` | Table option | `boolean` | `true` | Also a column option. `false` removes indicator, menu items and click-to-sort. |
+| `enableMultiSort` | Table option | `boolean` | `true` | Whether Shift+click appends instead of replacing. |
+| `maxMultiSortColCount` | Table option | `number` | `Infinity` | How many columns may sort at once. |
+| `isMultiSortEvent` | Table option | `(event) => boolean` | Shift held | What counts as "append to the sort". |
+| `sortFn` | Column option | name \| `(rowA, rowB, columnId) => number` | `"auto"` | The comparator for one column. v9's name for v8's `sortingFn`. |
+| `initialState.sorting` | Table option | `Array<{ id, desc }>` | `[]` | Sort at mount. A settings slice, so it persists. |
+| `manualSorting` | Table option | `boolean` | `false` | The server sorts; the grid stops. |

package/docs/styling.md

@@ -0,0 +1,126 @@
+# Size, styling and theming
+
+The grid is themed through CSS custom properties, and sized through Mantine's
+standard `size` scale. Both are set on the root element, so a grid can be
+themed per instance without a provider.
+
+```tsx
+<TMDataGrid {...grid} size="sm" style={{ "--dg-row-selected-bg": "color-mix(in srgb, var(--mantine-color-blue-6) 12%, transparent)" }} />
+```
+
+```demo
+file: customization/Styling.tsx
+hint: Every value the controls change is a CSS variable set on the grid element.
+extraSources: data/employeeColumns.tsx
+```
+
+## The size scale
+
+`size` drives row height, header height, font size and cell padding together,
+and selects the size of every Mantine control the grid renders - the page-size
+select, the filter inputs, the column checkboxes.
+
+| `size` | Row height | Header height | Font size | Cell padding |
+| --- | --- | --- | --- | --- |
+| `xs` | 34px | 32px | `xs` | 6px |
+| `sm` | 42px | 38px | `sm` | 8px |
+| `md` (default) | 52px | 44px | `sm` | 10px |
+| `lg` | 62px | 52px | `md` | 14px |
+| `xl` | 72px | 60px | `lg` | 18px |
+
+```demo
+file: getting-started/DensityAndLayout.tsx
+```
+
+Row height is also required by the virtualizer **as a number**, so it cannot be
+defined in CSS alone. `SIZE_ROW_HEIGHT` is the exported source of these values,
+and the stylesheet mirrors them. To use a height outside the scale, set
+`meta.rowHeight` rather than the variable.
+
+## CSS variables
+
+`style` accepts custom properties, and `className` reaches the same element
+from a stylesheet.
+The wrapper components - `Toolbar`, `Spacer`, `Footer`, `FilterPanel`, `FilterPills` and `ColumnsPanel` - take Mantine's `BoxProps` on top of their own props, so `mb="sm"` or `hiddenFrom="sm"` on any of them sets the element itself; see [Toolbar](/docs/toolbar#style-props).
+
+### Metrics
+
+| Variable | Default | Applies to |
+| --- | --- | --- |
+| `--dg-row-height` | From `size` | Row height. Prefer `meta.rowHeight` - the virtualizer needs the number. |
+| `--dg-header-height` | From `size` | Header row height |
+| `--dg-summary-height` | From `size` | [Summary row](/docs/summary-row) height |
+| `--dg-entry-height` | From `size` | The sticky [entry block](/docs/adding-rows#adding-rows) |
+| `--dg-font-size` | From `size` | Cell and header font size |
+| `--dg-padding` | From `size` | Horizontal cell padding. The generated lanes are excluded: they are fixed 36px tracks that centre their control. |
+| `--dg-radius` | `--mantine-radius-md` | The frame's corner radius. `0` squares the grid off. The root clips its overflow, so the header and the last row follow it. |
+
+### Colours
+
+Both colour schemes are supported. The grid's own stylesheet resolves its
+colours with `light-dark()`, so it follows Mantine's scheme without a prop or a
+second import. A default of **Themed** below means exactly that: the variable
+resolves to one value under the light scheme and another under the dark one.
+Set such a variable and you take over both schemes, so give it a value that
+reads in each - `light-dark()` works in your own value too.
+
+| Variable | Default | Applies to |
+| --- | --- | --- |
+| `--row-bg` | – | One row's own background. Set this, never `background`. See [Row styling](/docs/row-styling#set-the-row-background). |
+| `--dg-row-selected-bg` | `--mantine-primary-color-light` | [Selected](/docs/row-selection) rows |
+| `--dg-row-highlight-bg` | Themed | The highlighted row |
+| `--dg-row-striped-bg` | Themed | Every second row under `striped` |
+| `--dg-row-group-bg` | Themed | [Group](/docs/grouping) rows |
+| `--dg-row-new-bg` | Green tint | New rows entered into the [draft store](/docs/draft-store) |
+| `--dg-match-highlight-bg` | Themed yellow | [Marked](/docs/quick-search#match-highlighting) text |
+| `--dg-header-shadow-color` | Themed | The shadow under the sticky header |
+
+### Layout internals
+
+| Variable | Default | Applies to |
+| --- | --- | --- |
+| `--dg-sticky-edge-range` | `20px` | How far the pinned-lane band takes to fade in |
+| `--dg-edge-top` · `-bottom` · `-left` · `-right` | – | Set by the grid to mark [cell-range](/docs/cell-selection) borders |
+| `--dg-z-header` · `-pinned-cell` · `-summary-row` · … | – | The stacking order. Change these only to place something of your own between two layers. |
+
+## The stylesheet
+
+One import, once, anywhere in your app:
+
+```tsx
+import "@jielga/tmdatagrid/styles.css";
+```
+
+`@jielga/tmdatagrid/styles.layer.css` is the same stylesheet wrapped in a
+`@layer`, for an application that orders its own layers and needs the grid to
+sit at a known place in that order. Import **one** of the two, never both.
+
+## Layout
+
+The grid fills the box you give it and scrolls inside it. It does not size
+itself to its content: a virtualized grid has no content height to measure.
+
+```tsx
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
+    <TMDataGrid.Table />
+  </TMDataGrid>
+</div>
+```
+
+`minHeight: 0` is required. A flex item's default `min-height: auto` will not
+shrink below its content, so without it the grid grows past the viewport instead
+of scrolling.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `size` | Prop | `MantineSize` | `"md"` | The whole density scale. |
+| `className` | Prop | `string` | – | Added to the root element's classes. |
+| `style` | Prop | `CSSProperties` + `--*` | – | Root element styles, including the variables above. |
+| `id` | Prop | `string` | – | Set on the root element. |
+| `meta.rowHeight` | Option | `number` | From `size` | A row height outside the scale. |
+| `SIZE_ROW_HEIGHT` | Export | `Record<MantineSize, number>` | – | The row heights listed in the table above. |
+| `SIZE_CONTROL_SIZE` | Export | `Record<MantineSize, MantineSize>` | – | Which control size each grid size uses. |
+| `DEFAULT_TMDATAGRID_SIZE` | Export | `"md"` | – | The default. |