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

package/docs/query-builder.md

@@ -0,0 +1,175 @@
+# A query builder form
+
+A search form holds dates, a title filter and a list of extra conditions. The
+conditions are rows, so the condition builder is a grid, wrapped as a form
+field: rows come in through `value`, and approved changes go back out through
+`onChange`.
+
+```demo
+file: recipes/QueryBuilderForm.tsx
+hint: Add a condition and pick Status - the value editor becomes a select. Delete every condition, or repeat one, and Search says why it will not.
+height: 560
+```
+
+The form holds the array; the grid holds the row being edited. The grid never
+mutates `data`, so the form's state is only ever what the user has approved.
+
+## Wrapping the grid as a field
+
+The grid is wrapped once, as an ordinary controlled component:
+
+```tsx
+function ConditionsGrid({ value, onChange }: {
+  value: Array<QueryCondition>;
+  onChange: (next: Array<QueryCondition>) => void;
+}) {
+  const grid = useTMDataGrid({
+    data: value,
+    columns,
+    getRowId: (row) => String(row.id),
+    editing: {
+      mode: "row",
+      rowValidators,
+      onCommit: ({ rowId, value: row }) =>
+        onChange(value.map((c) => (String(c.id) === rowId ? row : c))),
+      onRowAdd: ({ value: row }) =>
+        onChange([...value, { ...row, id: Math.min(0, ...value.map((c) => c.id)) - 1 }]),
+      onRowDelete: ({ rowId }) =>
+        onChange(value.filter((c) => String(c.id) !== rowId)),
+      newRowDefaults: () => ({ id: 0, field: "title", operator: "contains", value: "" }),
+    },
+  });
+  return (
+    <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
+      <TMDataGrid.Table<QueryCondition> />
+    </TMDataGrid>
+  );
+}
+```
+
+And handed to the form as a field:
+
+```tsx
+<form.Field
+  name="conditions"
+  validators={{
+    onChange: ({ value }) =>
+      value.length === 0 ? "Add at least one condition" : undefined,
+  }}
+>
+  {(field) => (
+    <ConditionsGrid value={field.state.value} onChange={field.handleChange} />
+  )}
+</form.Field>
+```
+
+`field.handleChange` is the `onChange`: it writes the array into the form and
+runs the field's validators. `onChange` carries the whole next array rather than
+a diff.
+
+- **Map by row id, never by index.** A sort or a delete moves the index; the
+  draft is keyed by the id.
+- **`data` identity stays stable.** `field.state.value` changes identity only
+  when a row is written, which is what `data` requires.
+  See [useTMDataGrid](/docs/use-tm-data-grid).
+- **New rows count down from `-1`.** `Math.min(0, ...ids) - 1`, so an emptied
+  grid starts at `-1` rather than `-Infinity` and existing negative ids keep
+  descending. The grid's `tempId` never leaves the grid: the id you assign in
+  `editing.onRowAdd` is the one the form sees.
+
+## Where validation belongs
+
+A rule that can be decided from one row belongs to the grid. A rule that needs
+the other rows, or the collection as a whole, belongs to the form.
+
+| Rule | Owner | Written as |
+| --- | --- | --- |
+| "The condition needs a value" | Grid | `editing.rowValidators.onSubmit` |
+| "A date, for a date field" | Grid | `meta.edit.editor` per column |
+| "At least one condition" | Form | the `conditions` field's `onChange` validator |
+| "No two conditions repeat a field and operator" | Form | the same place |
+
+A row's form is seeded with that row's values only, so it cannot see the array,
+and the grid's `edit.store` publishes field names but not values, so the form
+cannot see a draft.
+
+## Editors that follow the row
+
+In a `[field, operator, value]` builder the value cell means something
+different on every row. `meta.edit.editor` receives the row's live form, so one
+component can switch on the *draft* field rather than the committed one, and
+picking a new field resets its dependents:
+
+```tsx
+const FieldEditor: TMDataGridEditorComponent = ({ field, form, size }) => (
+  <Select
+    size={size}
+    data={[...FIELDS]}
+    value={String(field.state.value)}
+    onChange={(next) => {
+      if (next === null) return;
+      field.handleChange(next);
+      form.setFieldValue("operator", OPERATORS[next as QueryField][0]);
+      form.setFieldValue("value", "");
+    }}
+  />
+);
+```
+
+The operator and value editors read the sibling with TanStack Store's
+[`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference):
+`useSelector(form.store, (state) => state.values.field)`, so switching Field
+mid-edit switches them immediately. See
+[Editors and validation](/docs/editors) for the editor's full API.
+
+## Which mode
+
+`editing.mode: "row"`. A condition is approved as a unit: the pencil opens the
+whole row, Save commits it, and `editing.onCommit` hands the form one finished
+condition. The form's rules run at that point.
+
+**Not `draft: true`.** A draft store holds every commit inside the grid and
+calls nothing until `edit.saveDrafts()`, so the form's array goes stale the
+moment typing starts: "at least one condition" counts rows the user may have
+marked for deletion, a duplicate sitting in a draft passes unseen, and the
+form's submit saves an array missing every pending edit.
+
+To use the store anyway, invert where the save happens: `grid.edit.saveDrafts()`
+becomes the only way rows reach the form, and the form's submit is gated on the
+grid holding no draft -
+`useSelector(grid.edit.store, (s) => s.openRowIds.length === 0)`.
+
+## Submitting
+
+The form submits only while the grid holds no draft.
+
+```tsx
+const hasOpenDraft = useSelector(grid.edit.store, (s) => s.openRowIds.length > 0);
+
+<Button type="submit" disabled={!canSubmit || hasOpenDraft}>
+  {hasOpenDraft ? "Finish the open condition" : "Search"}
+</Button>
+```
+
+The alternative is to flush instead of block. `await grid.edit.commitAll()`
+before `form.handleSubmit()` submits every open row through the normal
+`editing.onCommit` path, in every mode; with `draft: true` follow it with
+`grid.edit.saveDrafts()`. Rows that fail their own validation
+stay open, so the submit fails.
+
+Two constraints apply to a native `<form>` around a grid:
+
+- The grid's buttons cannot submit it. Mantine buttons default to
+  `type="button"`, so only your own `type="submit"` button submits.
+- Enter inside a cell editor commits the cell, not the form. The editor
+  prevents the default, so implicit form submission never fires.
+
+## Reference
+
+The pieces this recipe composes:
+
+| Piece | Documented on |
+| --- | --- |
+| `data`, `getRowId`, `editing.mode`, `editing.onCommit`, `editing.onRowAdd`, `editing.onRowDelete`, `editing.newRowDefaults`, `edit.store` | [Editing](/docs/editing) |
+| `editing.rowValidators`, `meta.edit.editor`, the editor contract | [Editors and validation](/docs/editors) |
+| `useForm`, `form.Field`, field validators | TanStack Form's own docs |

package/docs/quick-search.md

@@ -0,0 +1,83 @@
+# Quick search
+
+One box over every column. `TMDataGrid.Search` is a debounced input writing
+TanStack's `globalFilter` state. There is no option to turn it on: render the
+component, or do not.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.Search />
+</TMDataGrid.Toolbar>
+```
+
+```demo
+file: data/QuickSearch.tsx
+hint: Try “Stckholm”. Fuzzy finds it; contains does not.
+extraSources: data/employeeColumns.tsx
+```
+
+## Fuzzy by default
+
+Typos and skipped characters still match, and while the search is the only thing
+narrowing the grid (no sort, no grouping) the rows are ordered by **match
+quality**, best first.
+
+That ordering is derived and never written into `sorting`: no column takes
+`aria-sort`, nothing is written to the persisted slices, and the next sort click
+replaces it.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, quickSearchMode: "contains" });
+```
+
+`"contains"` restores plain substring matching. An explicit `globalFilterFn`
+overrides both, and switches the rank ordering off with it.
+
+`fuzzyGlobalFilterFn` is exported for building your own input over the same
+matching.
+
+## Match highlighting
+
+Opt in with `enableMatchHighlighting: true` and cells mark the matched part of
+their text, while the quick search is active or a `contains` / `starts with` /
+`ends with` column filter is.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enableMatchHighlighting: true });
+```
+
+What is marked is the **contiguous, case-insensitive** occurrence of the search
+term, so a fuzzy typo-match with no contiguous occurrence is not highlighted.
+Equality operators highlight nothing.
+
+**Default-rendered cells only.** A column with its own `cell` renderer is
+excluded: the grid reproduces the default value-to-string render with the marks
+added, and does not modify a custom renderer's output.
+
+The mark colour is `--dg-match-highlight-bg`, a yellow that follows the Mantine
+colour scheme.
+
+## Opting columns out
+
+`enableGlobalFilter: false` on a column takes it out of the search; on the table
+it removes the input entirely. The generated lanes are already excluded.
+
+A search input of your own can skip the component and call
+`table.setGlobalFilter` directly. The state is TanStack's own, so a
+[`manualFiltering`](/docs/server-side) grid forwards it to the server, and it is
+one of the persisted `data` slices.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `TMDataGrid.Search` | Component | – | – | The debounced quick-search input. |
+| `placeholder` | Search prop | `string` | `labels.searchPlaceholder` | Input placeholder. |
+| `debounce` | Search prop | `number` | `250` | Pause before the filter applies, in ms. `0` filters per keystroke. |
+| `w` | Search prop | `number \| string` | `220` | Input width. |
+| `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the search matches. |
+| `enableMatchHighlighting` | Option | `boolean` | `false` | Mark the matched text in default-rendered cells. |
+| `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. `false` removes the input, or one column's participation. |
+| `globalFilterFn` | Table option | filter fn | `fuzzy` | Overrides the matching, and the rank ordering with it. |
+| `fuzzyGlobalFilterFn` | Export | filter fn | – | The default matcher, for a custom input. |
+| `--dg-match-highlight-bg` | CSS variable | colour | Themed yellow | The mark colour. |

package/docs/row-details.md

@@ -0,0 +1,113 @@
+# Row details
+
+A panel that opens underneath a row, spanning every column, holding whatever
+does not fit in the cells - a summary card, an action strip, a nested table.
+
+Setting `renderDetails` turns the lane on. There is no separate flag.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  renderDetails: ({ row }) => <EmployeeCard employee={row.original} />,
+});
+```
+
+```demo
+file: rows/DetailsPanel.tsx
+hint: Expand a few rows - the panels differ in height, and each one is measured.
+height: 460
+```
+
+The panel is as tall as whatever it renders. The grid measures each one, so
+they need not be uniform. `renderDetailsEstHeight` (default `160`) is what the
+virtualizer assumes for a panel it has not measured yet, which keeps the
+scrollbar accurate for rows that open off screen.
+
+## The details lane
+
+Setting `renderDetails` prepends a generated chevron column,
+`DETAILS_COLUMN_ID` (`"__details__"`), pinned to the left after the checkbox
+and tree columns - `[checkbox, tree, details, …]`.
+
+It is a system lane: as wide as the chevron it holds, with no resize handle and
+no column menu, and it cannot be hidden, moved, resized or unpinned. Its header
+is a control rather than a title, expanding and collapsing every panel at once.
+
+Group rows get no chevron: they expand into their children from the tree lane.
+
+## Opening a row from elsewhere
+
+Which rows are open is TanStack's own `expanded` state, so anything can open
+one - a context menu item, a double-click, a button in your own cell:
+
+```tsx
+<Menu.Item onClick={() => row.toggleExpanded()}>Show details</Menu.Item>
+```
+
+Anything reading `row.getIsExpanded()` inside a cell has to subscribe to the
+store with TanStack Store's
+[`useSelector`](https://tanstack.com/store/latest/docs/framework/react/reference), or the
+React Compiler caches the call along with the `row` identity and the control
+never updates:
+
+```tsx
+const expanded = useSelector(row.table.store, () => row.getIsExpanded());
+```
+
+Because it is the standard state, `table.toggleAllRowsExpanded()`,
+`initialState.expanded` and persistence all work with it. It is one of the
+`data` slices, so open panels survive a reload on a
+[persisted](/docs/use-tm-data-grid#persist) grid.
+
+> TanStack resets `expanded` whenever the `data` array changes, which would
+> close every panel on each draft commit. The grid therefore sets
+> `autoResetExpanded: false`; pass `autoResetExpanded: true` to have a new
+> `data` array close the panels.
+
+## The two kinds of expanding
+
+TanStack keeps one `expanded` state, and the grid uses it for two unrelated
+things: opening a group row into its children, and opening a data row into its
+panel. The controls are kept separate. The details header only opens and closes
+panels, and "Expand all groups" in the tree menu only unfolds the tree.
+
+`table.toggleAllRowsExpanded()` is the one that does not distinguish them: it
+writes the state's whole-table form, which is every group and every panel at
+once. `resolveExpandAll` and `areAllRowsExpanded` are exported for anything
+building its own control:
+
+```tsx
+table.setExpanded(
+  resolveExpandAll({
+    rows: table.getPrePaginatedRowModel().flatRows,
+    expanded: table.store.state.expanded,
+    target: "details",
+    expand: true,
+  }),
+);
+```
+
+## Panel behaviour
+
+The panel is a cell spanning the row, inside the row element. It takes the row's
+background, moves with it and is measured with it, but it is **not a row**:
+`aria-rowcount` still counts records, and a click or right-click inside it does
+not select or highlight the row underneath. It carries
+`data-dg-part="details"` with the row's `data-row-id`. See
+[Testing](/docs/testing).
+
+Group rows have no panel. Expanding one opens its children.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `renderDetails` | Option | `({ row, table }) => ReactNode` | – | Contents of the panel. Setting it adds the lane. |
+| `renderDetailsEstHeight` | Option | `number` | `160` | Height the virtualizer assumes for an unmeasured panel. |
+| `initialState.expanded` | Table option | `ExpandedState` | `{}` | Rows open at mount. A data slice, so it persists. |
+| `autoResetExpanded` | Table option | `boolean` | `false` | `true` closes the panels when the `data` array changes. Off by default, so a draft commit keeps them open. |
+| `DETAILS_COLUMN_ID` | Export | `"__details__"` | – | Id of the generated chevron column. |
+| `resolveExpandAll` | Export | `(args) => ExpandedState` | – | Expand or collapse every group, or every panel, but not both. |
+| `areAllRowsExpanded` | Export | `(args) => boolean` | – | Whether every row of one target is open. |
+| `data-dg-part="details"` | Data attribute | – | – | The panel element, carrying the row's `data-row-id`. |

package/docs/row-interaction.md

@@ -0,0 +1,148 @@
+# Clicks and context menus
+
+Handling clicks in the body: a row click, a cell click, a double-click, and a
+right-click for a menu.
+
+Every handler here **composes** with what the click already does. Setting
+`onRowClick` does not replace selection or the highlight; both still happen,
+and your handler runs as well.
+
+```tsx
+<TMDataGrid.Table<Employee> onRowClick={(row) => open(row.original.id)} />
+```
+
+Pass the row type, as above, and `row.original` is typed.
+
+```demo
+file: rows/ClickAndContextMenu.tsx
+hint: Click, double-click and right-click anywhere in the body.
+```
+
+## The click handlers
+
+| Prop | Argument | Notes |
+| --- | --- | --- |
+| `onRowClick` | `row` | Rows show a pointer cursor when set. |
+| `onCellClick` | `{ cell, row, column, event }` | The cell cursor still moves. |
+| `onCellDoubleClick` | same | A double-click that opens an editor still does. |
+| `onCellContextMenu` | same | `renderRowContextMenu` and the cell-selection menu still open. |
+
+None of the four fires on a group row: a group row is built on its first
+child's record rather than on one of its own.
+
+## Context menus
+
+Right-clicking a row opens a Mantine `Menu` at the pointer. The grid renders the
+`Menu` and its `Menu.Dropdown`, opens it at the cursor, and closes it on Escape,
+on an outside click, on a body scroll, and after an item is picked. The render
+prop supplies only the contents, so anything valid in a dropdown works:
+`Menu.Item`, `Menu.Label`, `Menu.Divider`, `Menu.Sub`, or your own components.
+
+```tsx
+<TMDataGrid.Table<Employee>
+  renderRowContextMenu={({ row, cell }) => (
+    <>
+      <Menu.Label>{row.original.firstName}</Menu.Label>
+      <Menu.Item onClick={() => open(row.original.id)}>Open</Menu.Item>
+      <Menu.Item
+        onClick={() =>
+          navigator.clipboard.writeText(String(cell?.getValue() ?? ""))
+        }
+      >
+        Copy cell value
+      </Menu.Item>
+      <Menu.Divider />
+      <Menu.Item color="red" onClick={() => remove(row.original.id)}>
+        Delete
+      </Menu.Item>
+    </>
+  )}
+/>
+```
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `table` | `Table<TMDataGridFeatures, TData>` | For actions that read wider state, such as `getSelectedRowModel()`. |
+| `row` | `Row<TMDataGridFeatures, TData>` | The right-clicked row. |
+| `cell` | `Cell<…> \| null` | The cell under the pointer, so a per-cell action such as "copy value" is possible. `null` only if a custom cell renderer stopped the event. |
+| `close` | `() => void` | Closes the menu. `Menu.Item` already closes on click, so this is for content that is not a menu item. |
+
+The render prop is called **during render**, and only for the row whose menu is
+open. Keep it a pure function of its arguments and do the work in the item
+handlers.
+
+Return `null` to leave a row without a menu. The browser's own context menu
+stays suppressed over the grid either way:
+
+```tsx
+renderRowContextMenu={({ row }) => (row.original.locked ? null : <Menu.Item>Edit</Menu.Item>)}
+```
+
+### The right-clicked row
+
+A right-click does not select or highlight the row. The grid marks it with
+`data-context-menu` while its menu is open, which gives it the hover background.
+An action that should apply to a multi-selection can read the selection off
+`table` and fall back to the clicked row:
+
+```tsx
+renderRowContextMenu={({ table, row }) => {
+  const selected = table.getSelectedRowModel().rows;
+  const targets = selected.some((r) => r.id === row.id) ? selected : [row];
+  return <Menu.Item onClick={() => archive(targets)}>Archive {targets.length}</Menu.Item>;
+}}
+```
+
+### Taking the whole menu
+
+Under `cellSelection: "range"` a right-click inside the selection opens the
+copy and export items too. By default they appear above a divider and yours
+below, which is what happens when the render prop does not use `internalItems`.
+See [Cell selection](/docs/cell-selection#copy-and-export).
+
+`internalItems` is those built-in items. **Using it takes over the
+composition**: the menu becomes exactly what you return, in the order you
+return it.
+
+```tsx
+renderRowContextMenu={({ row, internalItems }) => (
+  <>
+    <Menu.Item onClick={() => open(row.id)}>Open</Menu.Item>
+    <Menu.Divider />
+    {internalItems}
+  </>
+)}
+```
+
+Accept `internalItems` without rendering it to drop the built-in items
+entirely.
+
+### Menu options
+
+`rowContextMenuProps` is passed to the Mantine `Menu` unchanged, apart from its
+open state:
+
+```tsx
+<TMDataGrid.Table<Employee>
+  renderRowContextMenu={items}
+  rowContextMenuProps={{ width: 260, shadow: "lg", position: "right-start" }}
+/>
+```
+
+On touch devices a long press (500 ms) opens the same menu. Mantine sets
+`user-select: none` on the element it attaches a context menu to, so body cell
+text is not selectable with the mouse in a grid that has one.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `onRowClick` | Table prop | `(row) => void` | – | Row click. Adds a pointer cursor. |
+| `onCellClick` | Table prop | `(args) => void` | – | Cell click. Receives `{ cell, row, column, event }`. |
+| `onCellDoubleClick` | Table prop | `(args) => void` | – | Cell double-click. |
+| `onCellContextMenu` | Table prop | `(args) => void` | – | Cell right-click. |
+| `renderRowContextMenu` | Table prop | `({ table, row, cell, close, internalItems }) => ReactNode` | – | Contents of the row's context menu. `null` for no menu. |
+| `renderColumnMenuItems` | Table prop | `({ column, table, internalItems }) => ReactNode[]` | – | Contents of a column's menu. An empty list removes the button. |
+| `rowContextMenuProps` | Table prop | `MenuProps` | – | Passed to the Mantine `Menu`. |
+| `TMDataGridCellEventArgs` | Export | type | – | The argument the three cell handlers receive. |
+| `data-context-menu` | Data attribute | – | – | On the row whose menu is open. |

package/docs/row-pinning.md

@@ -0,0 +1,132 @@
+# Row pinning and numbering
+
+Two independent features: rows stuck to the top or bottom of the body so they
+stay in view, and a gutter numbering the rows.
+
+## Pinning rows
+
+Opt in with `enableRowPinning: true`, or a per-row predicate.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enableRowPinning: true });
+```
+
+Pinned rows leave the scrolling order and render in sticky blocks: top-pinned
+rows under the header (and under the entry block while one is open),
+bottom-pinned rows above the summary row.
+
+There is no built-in pin gesture and no pin icon. The grid provides `row.pin()`
+on every row, callable from anywhere a row is rendered. Two places are
+convenient for it.
+
+A **lane of your own**, a display column whose cell is a pin button:
+
+```tsx
+function PinToggle({ row }: { row: Row<TMDataGridFeatures, Employee> }) {
+  // Subscribed rather than called in the component body: the React Compiler
+  // caches a bare call along with the stable `row` identity.
+  const pinned = useSelector(row.table.store, () => row.getIsPinned());
+  return (
+    <ActionIcon
+      variant={pinned === false ? "subtle" : "light"}
+      color={pinned === false ? "gray" : "blue"}
+      aria-label={pinned === false ? "Pin to top" : "Unpin"}
+      // The row underneath may select or highlight on click.
+      onClick={(event) => {
+        event.stopPropagation();
+        row.pin(pinned === false ? "top" : false);
+      }}
+    >
+      {pinned === false ? <IconPin size={16} /> : <IconPinFilled size={16} />}
+    </ActionIcon>
+  );
+}
+
+const pinColumn = columnHelper.display({
+  id: "pin",
+  header: "",
+  // Columns are fluid - `minmax(minSize, flex fr)` - so a control lane states
+  // one width three times to opt out. See [Sizing](/docs/column-layout#sizing).
+  size: 44,
+  minSize: 44,
+  maxSize: 44,
+  meta: { label: "Pin", align: "center" },
+  enableResizing: false,
+  enableSorting: false,
+  cell: ({ row }) => <PinToggle row={row} />,
+});
+```
+
+Or the **row context menu**, which reaches a row at either edge as well as one
+in the body:
+
+```tsx
+<TMDataGrid.Table<Employee>
+  renderRowContextMenu={({ row }) => (
+    <>
+      {row.getIsPinned() !== "top" && (
+        <Menu.Item onClick={() => row.pin("top")}>Pin to top</Menu.Item>
+      )}
+      {row.getIsPinned() !== false && (
+        <Menu.Item onClick={() => row.pin(false)}>Unpin</Menu.Item>
+      )}
+    </>
+  )}
+/>
+```
+
+Include a way to unpin.
+
+```demo
+file: rows/PinningAndNumbers.tsx
+hint: Click a pin, or right-click a row for either edge, then scroll.
+```
+
+`row.pin("top" | "bottom" | false)`, `row.getIsPinned()` and `row.getCanPin()`
+are TanStack's own APIs; the state is `rowPinning: { top: string[], bottom:
+string[] }`, settable wholesale with `table.setRowPinning()` or seeded through
+`initialState`.
+
+### Pinned row behaviour
+
+Selection, editing, details, the context menu and per-row styling all behave as
+they do in the body. Pinned rows are excluded only from the features that
+depend on scroll *order* - striping and the cell range - and the row-number
+gutter leaves them unnumbered.
+
+Also note:
+
+- A pinned row stays at its edge even when a filter or the pager would have
+  dropped it from the body.
+- A pinned id whose row leaves `data` (a delete, a server-side page swap) is not
+  shown. It stays in state and the row returns to its edge if its data comes
+  back.
+- **Group rows never pin.** A leaf whose group is collapsed stays hidden while
+  pinned.
+- `rowPinning` is **not** persisted. Row ids are data, and the settings group
+  holds layout only.
+
+## Numbering rows
+
+`enableRowNumbers: true` adds a gutter, outermost left, before every other
+lane.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, enableRowNumbers: true });
+```
+
+It numbers **the current view**: sorted, filtered, and continuing across pages
+rather than restarting on each one. The number is a position, not an identifier
+for the record; for that, add a column of your own over the record's id. Group
+rows and pinned rows take no number.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enableRowPinning` | Table option | `boolean \| (row) => boolean` | `false` | Whether rows can be pinned. |
+| `initialState.rowPinning` | Table option | `{ top: string[], bottom: string[] }` | empty | Rows pinned at mount. Not persisted. |
+| `enableRowNumbers` | Option | `boolean` | `false` | Adds the row-number gutter. |
+| `row.pin` | Row method | `("top" \| "bottom" \| false) => void` | – | Pins or unpins one row. |
+| `row.getIsPinned` | Row method | `() => "top" \| "bottom" \| false` | – | Where a row is pinned. |
+| `ROW_NUMBER_COLUMN_ID` | Export | `"__rowNumber__"` | – | Id of the generated number gutter. |