@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/docs/row-interaction.md

@@ -0,0 +1,149 @@
+# 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. |
+| `TMDataGridRowContextMenuArgs` | Type | `{ table, row, cell, close, internalItems }` | – | What `renderRowContextMenu` receives. |
+| `renderColumnMenuItems` | Table prop | `TMDataGridColumnMenuItemsRenderer` | – | Sets the column menu's contents. An empty list removes the menu button. See [Column header menu](/docs/column-menu). |
+| `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. |

package/docs/row-selection.md

@@ -0,0 +1,136 @@
+# 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. |
+| `TMDataGridSelectionMode` | Type | – | – | The type of `selectionMode`. |
+| `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. |
+| `ResolveRowSelectionClickArgs` · `TMDataGridRowClickModifiers` | Types | – | – | What `resolveRowSelectionClick` takes, and its `modifiers`: `{ toggle, extend }`. |
+| `--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` | Group rows |
+| `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 present, with the value `"true"`, only on the rows
+they apply to, so the bare attribute and the value match the same rows:
+
+```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,112 @@
+# 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/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. |
+| `TMDataGridScrollToRowArgs` | Type | `{ rowId, align? }` | – | What `scrollToRow` takes. |
+| `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
+| `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
+| `--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. |