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

package/docs/columns.md

@@ -0,0 +1,262 @@
+# Defining columns
+
+A column declares where its value comes from, what kind of value it is, and how
+to render it. Which filter operators it offers, which editor it opens and how
+it sorts all follow from `meta.type`.
+
+## The column helper
+
+`createTMDataGridColumnHelper<TData>()` returns a TanStack column helper bound
+to the grid's feature set, so that `meta` and `filterFn` are correctly typed.
+
+```tsx
+const columnHelper = createTMDataGridColumnHelper<Employee>();
+
+const columns = columnHelper.columns([
+  columnHelper.accessor("salary", {
+    header: "Salary",
+    minSize: 130,
+    meta: { type: "number", align: "right" },
+    cell: (info) => formatSek(info.getValue()),
+  }),
+  columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
+    id: "fullName",
+    header: "Full name",
+    meta: { label: "Full name" },
+  }),
+]);
+```
+
+**Define columns at module scope.** A new array on every render rebuilds the
+table's column model and discards the user's column widths and order.
+
+```demo
+file: getting-started/ColumnDefinitions.tsx
+```
+
+An accessor may be a key of the row or a function over it. A function needs an
+explicit `id`, and a `meta.label` for the name shown in menus and the columns
+panel.
+
+A dotted `accessorKey` reads a nested field, and the column id it derives
+replaces the dots: `accessorKey: "address.city"` makes column id
+`address_city`, while the edit path stays `"address.city"`. Anything that
+addresses the column by id - `initialState`, `editing.columns`, `moveColumn`,
+a test selector - takes the underscore form; the dotted form silently matches
+nothing.
+
+### Columns derived from the other rows
+
+`accessorFn` is handed one row, so a value that depends on the rest - a share
+of a total, a rank, a running total - cannot be an accessor. Derive the
+collection once and hand the grid the finished shape; the column is then a
+plain `accessorKey`:
+
+```tsx
+const rows = useMemo(() => {
+  const total = holdings.reduce((sum, holding) => sum + holding.value, 0);
+
+  return holdings.map((holding) => ({
+    ...holding,
+    pctOfTotal: (holding.value / total) * 100,
+  }));
+}, [holdings]);
+
+columnHelper.accessor("pctOfTotal", {
+  header: "Share",
+  meta: { type: "number", align: "right" },
+  cell: (info) => `${info.getValue().toFixed(1)}%`,
+});
+```
+
+[A portfolio rebalancer](/docs/portfolio-rebalancer) works one through, from
+the derived rows to a validator that reads them all.
+
+## meta
+
+`meta` carries what a TanStack column definition has no field for. What the
+column is sits at the top level; what the filter panel and the edit engine do
+with it sits in the `filter` and `edit` namespaces.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | String header, or column id | Name used in menus and the column manager. Required when `header` is a component. |
+| `type` | `"string" \| "number" \| "boolean" \| "date" \| "select" \| "multiSelect"` | `"string"` | What the values are. Selects the filter operators, the filter control and the cell editor. |
+| `options` | `TMDataGridOptionsSource` | - | The choices of a `select` / `multiSelect` column. See [Options](#options). |
+| `flex` | `number` | `1` | Share of the remaining width. |
+| `align` | `"left" \| "right" \| "center"` | `"left"` | Alignment, applied to both header and cells. |
+| `autoSize` | `boolean` | `false` | Fit the column to its content once, on the render its first cells appear in. |
+| `enableOrdering` | `boolean` | `true` | `false` keeps the column where it is. |
+| `filter` | `TMDataGridColumnFilterOptions` | - | How this column filters. See [meta.filter](#metafilter). |
+| `edit` | `TMDataGridColumnEditOptions` | - | How this column is edited. See [meta.edit](#metaedit). |
+
+### meta.filter
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultOperator` | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter starts with. See [Filtering](/docs/filtering#operators). |
+| `control` | `TMDataGridFilterControlComponent` | By type and operator | Replaces the filter panel's value control. See [Filtering](/docs/filtering#replacing-the-value-control). |
+
+```tsx
+meta: {
+  type: "number",
+  filter: { defaultOperator: "between", control: DgRangeSliderFilter },
+}
+```
+
+### meta.edit
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean \| (row) => boolean` | `true` | Whether cells in this column may be edited. See [Editing](/docs/editing#which-cells-edit). |
+| `field` | `string` | The `accessorKey` | The data path an edit writes to, for a column built on `accessorFn`. |
+| `editor` | `TMDataGridEditorComponent` | By `type` | Replaces the cell editor. See [Editors](/docs/editors#writing-your-own). |
+| `validate` | `TMDataGridFieldValidate` | - | Per-cell validation. See [Validation](/docs/editors#validation). |
+| `mapValue` | `TMDataGridEditValueMap` | - | Maps each value an editor writes. See [Mapping the value](/docs/editors#mapping-the-value-as-it-is-typed). |
+
+```tsx
+meta: {
+  type: "string",
+  edit: {
+    enabled: (row) => row.original.status !== "Terminated",
+    validate: z.string().min(2, "At least two characters"),
+    mapValue: ({ value }) =>
+      typeof value === "string" ? value.toUpperCase() : value,
+  },
+}
+```
+
+Omit both namespaces to get the defaults: any column mapping to a data path is
+editable once `editing` is set, and every column filters by its type.
+
+## Column types
+
+`meta.type` declares what a column's values are. The filter panel offers that
+type's operators and renders a matching value control: a date input for `date`,
+a Yes/No dropdown for `boolean`, a multi-select of the column's options for
+`select` and `multiSelect`. With editing on, the same declaration picks the
+editor.
+
+Dates may be `Date` instances or ISO `YYYY-MM-DD` strings in the data; the
+comparison is by calendar day either way, and filter values always travel as ISO
+strings. The date control is the native `<input type="date">`; `@mantine/dates`
+is not used.
+
+A column whose value is none of the six types - an object such as a
+`{ from, to }` range - renders through its own `cell`, but sorting, the filter
+panel and quick search operate on the raw value. Set `enableSorting`,
+`enableColumnFilter` and `enableGlobalFilter` to `false` on such a column.
+
+### Options
+
+`select` and `multiSelect` columns declare their choices once, in `meta.options`,
+and every consumer of them (the filter panel, the cell editor) reads the same
+source:
+
+```tsx
+// A fixed set, strings or full options:
+meta: {
+  type: "select",
+  options: [
+    "Pending",
+    { value: "Paid", label: "Paid in full", color: "green" },
+  ],
+}
+
+// The distinct values present in the data (low-cardinality columns):
+meta: { type: "select", options: "faceted" }
+
+// Computed. `row` is set when a cell editor asks and absent for the filter
+// panel, so row-dependent options can branch on it. `row.original` is
+// `unknown` here - cast it to the row type:
+meta: {
+  type: "select",
+  options: ({ row }) =>
+    row ? citiesFor((row.original as Employee).country) : allCities,
+}
+```
+
+`resolveColumnOptions({ table, column, row? })` normalises all three forms and is
+exported for custom controls; `optionsToComboboxData` turns the result into what
+Mantine's `Select` and `MultiSelect` take, `group` fields included.
+
+A select column that declares no options still filters: the panel falls back to
+the faceted values. Mantine's dropdowns are not virtualized, so use the function
+form for very large sets.
+
+## Header groups
+
+`columnHelper.group` nests columns under a shared header. The group is a header
+row, not a column - the leaves keep all the behaviour. `columns` takes another
+`columnHelper.columns` call, not a bare array:
+
+```tsx
+columnHelper.group({
+  id: "person",
+  header: "Person",
+  columns: columnHelper.columns([
+    columnHelper.accessor("firstName", { header: "First" }),
+    columnHelper.accessor("lastName", { header: "Last" }),
+  ]),
+});
+```
+
+```demo
+file: getting-started/HeaderGroups.tsx
+hint: Sort, filter and resize the leaves; the group header follows them.
+```
+
+Columns inside a group cannot be reordered, regardless of `meta.enableOrdering`:
+`columnOrder` sequences leaf columns, so moving one would leave the group header
+spanning columns that no longer belong to it.
+
+## Per-column feature switches
+
+Standard TanStack column options. Each removes the corresponding interface for
+that column alone.
+
+| Option | Effect when `false` |
+| --- | --- |
+| `enableSorting` | No sort indicator and no sort menu items. See [Sorting](/docs/sorting). |
+| `enableColumnFilter` | No filter menu item, and no entry in the panel's column list. |
+| `enableHiding` | No hide menu item, and no checkbox in the column manager. |
+| `enablePinning` | No pin menu items. |
+| `enableResizing` | The divider stays as a separator but cannot be dragged. |
+| `meta.enableOrdering` | No header dragging and no move menu items. |
+
+Sizing, pinning, ordering and visibility are covered on
+[Visibility, pinning, ordering and size](/docs/column-layout).
+
+## The generated columns
+
+Five lanes the grid adds when a feature needs them. All are **system lanes**:
+fixed width, no column menu, no resize handle, never exported, never hidden and
+never listed in the columns panel.
+
+| Id | Appears when | Where |
+| --- | --- | --- |
+| `ROW_NUMBER_COLUMN_ID` | `enableRowNumbers` | Outermost left, before everything. See [Row pinning and numbering](/docs/row-pinning#numbering-rows). |
+| `SELECT_COLUMN_ID` | A checkbox selection mode | First, pinned left. See [Row selection](/docs/row-selection). |
+| `GROUP_COLUMN_ID` | A column is grouped | Front, beside the checkbox lane. See [Grouping](/docs/grouping). |
+| `DETAILS_COLUMN_ID` | `renderDetails` is set | Left, after checkbox and tree. See [Row details](/docs/row-details). |
+| `EDIT_COLUMN_ID` | `editing.mode: "row"`, `editing.draft`, or `editing.onRowDelete` | Appended, pinned right, and stays outside anything the user pins right. See [Editing](/docs/editing). |
+
+The checkbox lane cannot be moved: it anchors the left pinned region, and no
+column can be placed in front of it.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `createTMDataGridColumnHelper` | Export | `<TData>() => helper` | – | A TanStack column helper typed against the grid's features. |
+| `meta.label` | Column meta | `string` | Header or id | Name in menus and the columns panel. |
+| `meta.type` | Column meta | six types | `"string"` | What the values are; drives filters and editors. |
+| `meta.options` | Column meta | array \| `"faceted"` \| `(args) => …` | – | The choices of an option column. |
+| `meta.align` | Column meta | `"left" \| "right" \| "center"` | `"left"` | Header and cell alignment. |
+| `meta.filter` | Column meta | `TMDataGridColumnFilterOptions` | – | How the column filters: `defaultOperator`, `control`. |
+| `meta.edit` | Column meta | `TMDataGridColumnEditOptions` | – | How the column edits: `enabled`, `field`, `editor`, `validate`, `mapValue`. |
+| `resolveColumnOptions` | Export | `({ table, column, row? }) => options` | – | Normalises all three `meta.options` forms. |
+| `optionsToComboboxData` | Export | `(options) => ComboboxData` | – | Options as Mantine `Select` data. |
+| `getColumnLabel` · `getColumnType` · `isControlColumn` | Exports | `(column) => …` | – | How the built-in controls read a column. |
+| `isGeneratedColumn` | Export | `(columnId) => boolean` | – | Whether the grid generated the column - the four control lanes plus the tree column. |
+| `SELECT_COLUMN_ID` · `GROUP_COLUMN_ID` · `DETAILS_COLUMN_ID` · `EDIT_COLUMN_ID` · `ROW_NUMBER_COLUMN_ID` | Exports | `string` | – | Ids of the five generated lanes. |

package/docs/components.md

@@ -0,0 +1,304 @@
+# Components and hooks
+
+Every hook and component the package exports.
+A part whose props belong to one topic is documented on that topic's page, and listed here with a link; everything else - the root, the Table, and the parts whose props scatter across every topic - is written up in full below.
+The options `useTMDataGrid` takes are on [useTMDataGrid](/docs/use-tm-data-grid).
+
+```tsx
+import { TMDataGrid, useTMDataGrid } from "@jielga/tmdatagrid";
+```
+
+The parts of the grid are reached through the `TMDataGrid` object.
+`TMDataGridSearch`, `TMDataGridFilterPills`, `TMDataGridDraftActions`, the editors and the filter controls are also exported by name; the remaining parts are available only as `TMDataGrid.Part`.
+
+## useTMDataGrid
+
+Creates the table instance, the UI store and the edit engine.
+Spread its result onto `TMDataGrid`:
+
+```tsx
+const grid = useTMDataGrid({ data, columns });
+
+<TMDataGrid {...grid}>
+  <TMDataGrid.Table />
+</TMDataGrid>;
+```
+
+`useTMDataGrid<TData>(options: UseTMDataGridOptions<TData>): TMDataGridApi<TData>`
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `table` | `TMDataGridTable<TData>` | The TanStack table instance. State lives in `table.store`. |
+| `ui` | `TMDataGridUiStore` | Panels, drag state, focused cell and cell range. |
+| `edit` | `TMDataGridEditApi` | The [editing engine](/docs/editing). Inert until `editing` is set. |
+| `features` | `TMDataGridFeatureFlags` | Feature switches, re-read from the options on every render. |
+| `labels` | `TMDataGridLabels` | The [dictionary](/docs/localization), merged over the English defaults. |
+| `renderDetails` | `TMDataGridDetailsRenderer<TData> \| undefined` | The [details renderer](/docs/row-details), passed through to the Table. |
+| `renderDetailsEstHeight` | `number` | The option, or `160`. |
+| `overscan` | `number` | The option, or `6`. |
+| `resetSettings` | `() => void` | Puts visibility, order, widths, pinning and grouping back to a first visit. |
+| `scrollToRow` | `({ rowId, align? }) => boolean` | Scrolls a row into view. Returns `false` when the row is not in the current view. |
+
+## useTMDataGridContext
+
+Returns the grid from inside a component rendered under `TMDataGrid`.
+It throws when called outside one.
+
+```tsx
+const { table, labels, controlSize } = useTMDataGridContext();
+```
+
+The value carries every field `useTMDataGrid` returns, plus three resolved from `size`:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `size` | `TMDataGridSize` | The `size` prop set on `TMDataGrid`. |
+| `rowHeight` | `number` | Row height in pixels, from `size` and `meta.rowHeight`. |
+| `controlSize` | `TMDataGridSize` | The Mantine control size that pairs with `size`. |
+
+## TMDataGrid
+
+The root element.
+It provides the grid to every part through context, and takes every field `useTMDataGrid` returns alongside these props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | – | The grid's parts, in render order. |
+| `size` | `TMDataGridSize` | `"md"` | The [size scale](/docs/styling#the-size-scale). |
+| `className` · `style` · `id` | `string` · `CSSProperties` · `string` | – | Set on the root element. Give the grid a bounded height - see [Layout](/docs/styling#layout). |
+| `data-testid` | `string` | – | Names the grid for [tests](/docs/testing). Set it when a page holds more than one grid. |
+
+## TMDataGrid.Table
+
+The scrollable surface: the header, the virtualized body and the filter panel.
+Pass the row type so the handlers are typed:
+
+```tsx
+<TMDataGrid.Table<Employee> onRowClick={(row) => open(row.original.id)} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onRowClick` | `(row) => void` | – | Called when a body row is clicked. Rows show a pointer cursor when set. See [Clicks and context menus](/docs/row-interaction). |
+| `onCellClick` · `onCellDoubleClick` · `onCellContextMenu` | `(args: TMDataGridCellEventArgs) => void` | – | Called on cell click, double-click and right-click. Receive `{ cell, row, column, event }`. See [Clicks and context menus](/docs/row-interaction). |
+| `renderRowContextMenu` | `TMDataGridRowContextMenuRenderer` | – | Contents of a row's context menu. Receives `{ table, row, cell, close, internalItems }`. See [Context menus](/docs/row-interaction#context-menus). |
+| `rowContextMenuProps` | `Omit<MenuProps, "opened" \| "onChange" \| "children">` | – | Props passed to the Mantine `Menu` behind the context menu. |
+| `renderColumnMenuItems` | `TMDataGridColumnMenuItemsRenderer` | – | Contents of a column's menu. Returning an empty array leaves the column with no menu button. See [The column menu](/docs/column-layout#the-column-menu). |
+| `rowClassName` | `string \| (row) => string` | – | Class for a body row. See [Row styling](/docs/row-styling). |
+| `rowStyle` | `TMDataGridRowStyle \| (row) => TMDataGridRowStyle` | – | Inline style for a body row. Set `--row-bg` rather than `background`. See [Row styling](/docs/row-styling#set-the-row-background). |
+| `striped` | `boolean` | `false` | If set, every second row takes `--dg-row-striped-bg`. See [Striping](/docs/row-styling#striping). |
+| `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | `() => void` | – | Called once on arriving at that edge, not on mount and not per scroll event. See [Edge callbacks](/docs/scrolling#edge-callbacks). |
+| `onReachEnd` | `() => void` | – | Called as the scroll nears the last row, once per row count. Sorting and filtering must be server-side. See [Infinite scroll](/docs/server-side#infinite-scroll). |
+| `reachEndThreshold` | `number` | `10` | Rows before the end at which `onReachEnd` fires. |
+| `renderEmptyState` | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. See [Loading and empty states](/docs/loading-and-empty). |
+| `cellExport` | `TMDataGridCellExportOptions` | – | Deprecated. Set `exportOptions` on `useTMDataGrid` instead; until it goes, it is merged over that for the cell-range menu only. See [Export](/docs/export). |
+| `aria-label` · `aria-labelledby` | `string` | – | The grid's accessible name, announced on entry and matched by `getByRole("grid", { name })`. |
+
+Note that `onReachEnd` and `enablePagination` slice the same scroll: the pager caps the rows, so the end reached is the page's.
+Setting both logs a warning.
+
+## TMDataGrid.Toolbar
+
+A flex row above the grid. See [Toolbar](/docs/toolbar).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | – | The toolbar's contents, in render order. |
+| `withBottomBorder` | `boolean` | `false` | A 1px bottom border in the theme's default border colour, the line the header draws under itself. |
+| Mantine `BoxProps` | | – | Style props (`mb`, `px`, `hiddenFrom`, …), `className`, `style` and `mod`, set on the row. |
+
+## TMDataGrid.Spacer
+
+Pushes the toolbar items after it to the right.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| Mantine `BoxProps` | | – | Style props, `className` and `style`, set on the spacer. |
+
+## TMDataGrid.Search
+
+A debounced quick-search input that writes the grid's global filter.
+It renders nothing when no column is searchable. See [Quick search](/docs/quick-search).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `placeholder` | `string` | `labels.searchPlaceholder` | Placeholder text. |
+| `debounce` | `number` | `250` | Milliseconds between the last keystroke and the filter being written. |
+| `w` | `number \| string` | `220` | Width of the input. |
+
+## The filter parts
+
+Filtering owns these three, so their props are on that page rather than repeated here.
+
+| Component | What it is | Props |
+| --- | --- | --- |
+| `TMDataGrid.FilterButton` | Toggles the filter surface, tinted with the count of active filters. Renders nothing when no column can be filtered, and nothing under `filters.surface: "none"`. | None. [Filtering](/docs/filtering#tmdatagridfilterbutton) |
+| `TMDataGrid.FilterPanel` | The filter rows, as a plain block with no title, no close button and no open state - the popup and sidebar [surfaces](/docs/filtering#the-filters-option) wrap it. | `layout`, Mantine `BoxProps`. [Filtering](/docs/filtering#tmdatagridfilterpanel) |
+| `TMDataGrid.FilterPills` · `TMDataGridFilterPills` | One pill per active filter. Takes the grid as an `api` prop rather than from context, so it renders anywhere on the page. | `api`, `size`, `showClearAll`, `onPillClick`, `className`. [Filtering](/docs/filtering#tmdatagridfilterpills) |
+
+`openColumnFilter(api, columnId)` sends the user to a column's filter control; it is documented with them, on [Filtering](/docs/filtering#opencolumnfilter).
+
+## TMDataGrid.Menu
+
+The burger at the end of the toolbar and the Mantine `Menu` it opens.
+Its children are the dropdown. See [Grid menu](/docs/menu).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | – | The dropdown: your own `Menu.Item`s and the `TMDataGrid.Menu.*` items. |
+| `icon` | `ReactNode` | The burger | The trigger's icon. |
+| `label` | `string` | `labels.menuButton` | The trigger's tooltip and `aria-label`. |
+| Mantine `MenuProps` | | `position="bottom-end"`, `shadow="md"`, `width={260}`, `withinPortal` | Passed to the `Menu`. |
+
+`TMDataGrid.Menu.Columns`, `.ColumnToggles`, `.ShowHideAll` and `.ResetLayout` are the column chooser as menu items, for this menu or any Mantine `Menu` inside the grid.
+`Columns` takes `searchable` (default `"auto"`, a search box from six columns), `ColumnToggles` takes `search`; the other two take no props.
+
+## TMDataGrid.ColumnsPanel
+
+The column chooser as plain controls: a checkbox list of the hideable columns, a search box once there are six of them, a show-all toggle and a reset button.
+For a Popover, a Drawer or an inline layout; `TMDataGrid.Menu.Columns` is the same thing as menu items.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `searchable` | `boolean \| "auto"` | `"auto"` | The search box over the list. `"auto"` shows it from six columns, `true` always, `false` never. |
+| Mantine `BoxProps` | | – | Style props (`w`, `p`, …), `className` and `style`, set on the panel block. |
+
+## TMDataGrid.LoadingIndicator
+
+A spinner, shown while `meta.loading` is `true`. See [Loading and empty states](/docs/loading-and-empty).
+
+No props.
+
+## TMDataGrid.SummaryCount
+
+The row count, as shown over total.
+The total comes from `meta.totalRowCount` when set, and from the unfiltered row count otherwise.
+While a column is grouped the shown count includes the group rows and the total keeps counting records, so `42 / 42` reads `48 / 42` under six groups; pass `children` to show a count of your own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | – | Replaces the count with your own text. |
+
+## TMDataGrid.DraftActions
+
+Save and Discard for pending edits.
+It renders nothing unless `editing` is set. See [Editing](/docs/editing).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `renderActions` | `(args: TMDataGridDraftActionsSlotArgs) => ReactNode` | – | Replaces both buttons. Receives `{ state, actions, Controls }`. |
+
+The slot argument carries the state, the operations and the built-in pieces:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `state.draftCount` | `number` | Rows in the draft store: committed edits, committed entry rows and deletion marks. This is what Save sends. |
+| `state.openCount` | `number` | Rows still open, so not part of the save. |
+| `state.openRowIds` | `ReadonlyArray<string>` | The ids behind `openCount`, in the order the grid opened them. An entered row appears as its `tempId`. |
+| `state.pendingCount` | `number` | **Deprecated.** Reads as `draftCount + openCount`. |
+| `state.isSubmitting` | `boolean` | `true` while any open row is submitting. Not the save; see `state.isSaving`. |
+| `state.isSaving` | `boolean` | `true` while `saveDrafts` is in flight, until the consumer's callbacks settle. The built-in Save shows it as its loading state. |
+| `actions.save` | `() => Promise<boolean>` | Sends the draft store. Open rows are left alone. |
+| `actions.commitAll` | `() => Promise<boolean>` | Submits every open row, committing the ones that validate. |
+| `actions.discard` | `() => void` | Drops open form state and the draft store alike. |
+| `actions.scrollToRow` | `({ rowId, align? }) => boolean` | [`scrollToRow`](/docs/scrolling#scrolling-to-a-row), passed through. |
+| `actions.scrollToFirstOpenRow` | `(align?) => boolean` | Scrolls to the first open row in display order. `false` when none could be reached. |
+| `Controls.Save` · `Controls.Discard` · `Controls.OpenRowsNote` | `() => ReactNode` | The built-in pieces, to place in your own layout. |
+
+The two orderings differ: `openRowIds` is the order the grid opened the rows,
+while `scrollToFirstOpenRow` takes "first" in display order, so it follows the
+current sort, filter and page. `openRowIds[0]` need not be the row it reaches.
+
+## TMDataGrid.Footer
+
+The pager bar: rows per page, the current range, and previous and next.
+It renders nothing when pagination is off. See [Pagination](/docs/pagination).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `pageSizeOptions` | `ReadonlyArray<number>` | `[10, 25, 50, 100]` | The choices in the rows-per-page select. |
+| `renderPagination` | `(args: TMDataGridPaginationSlotArgs) => ReactNode` | – | Replaces the pager. Receives `{ state, actions, Controls }`. |
+| Mantine `BoxProps` | | – | Style props (`mt`, `px`, …), `className` and `style`, set on the footer bar. |
+
+The slot argument holds the paging state, its operations and the built-in controls:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `state` | `TMDataGridPaginationState` | `pageIndex`, `pageSize`, `pageCount`, `rowCount`, `canPreviousPage`, `canNextPage`, `isPagingActive`, and the 1-based `from` and `to`. |
+| `actions` | `TMDataGridPaginationActions` | `setPageIndex`, `setPageSize`, `previousPage`, `nextPage`, `firstPage`, `lastPage`. |
+| `Controls.PageSize` · `Controls.Range` · `Controls.Pager` | `() => ReactNode` | The three built-in controls, to place in your own layout. |
+
+`pageCount` is `-1` when a manual grid declares an unknown total, and `isPagingActive` is `false` while a grouping suspends paging.
+`getTMDataGridPaginationApi(table, isPaging?)` returns the same `state` and `actions` for a pager built outside the grid.
+
+## Editors
+
+The control a cell opens for editing.
+The grid picks one from the column's `meta.type`, and `meta.edit.editor` replaces it. See [Editors and validation](/docs/editors).
+
+| Component | Renders | Used for `meta.type` |
+| --- | --- | --- |
+| `TMDataGridStringEditor` | Mantine `TextInput` | `"string"` |
+| `TMDataGridNumberEditor` | `NumberInput`, writing `null` for an empty cell | `"number"` |
+| `TMDataGridBooleanEditor` | `Checkbox` | `"boolean"` |
+| `TMDataGridDateEditor` | `TextInput` with `type="date"` | `"date"` |
+| `TMDataGridSelectEditor` | `Select`, committing on pick in `"cell"` mode | `"select"` |
+| `TMDataGridMultiSelectEditor` | `MultiSelect`, committing on Enter or blur | `"multiSelect"` |
+
+Every editor takes the same argument object, `TMDataGridEditorArgs`, so a custom editor can wrap a built-in rather than replace it:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `field` | `TMDataGridEditField` | The TanStack Form field for this cell. |
+| `form` | `TMDataGridRowEditForm` | The whole row form, for an editor that reads sibling fields. |
+| `cell` · `row` · `column` · `table` | TanStack instances | The cell being edited and its surroundings. |
+| `commit` | `() => Promise<boolean>` | Commits the edit, as Enter would. |
+| `cancel` | `() => void` | Drops the draft, as Escape would. |
+| `size` | `TMDataGridSize` | The grid's resolved control size. |
+| `seedText` | `string \| undefined` | Set when typing opened the editor. |
+
+## Filter controls
+
+The value control in a filter row.
+The grid picks one from the column's `meta.type` and the current operator, and `meta.filter.control` replaces it. See [Filtering](/docs/filtering).
+
+| Component | Renders | Suits |
+| --- | --- | --- |
+| `TMDataGridFilterValueInput` | A text input, a multi-select, a boolean select or a from/to pair, by operator | Every column. This is the default. |
+| `DgRangeSliderFilter` | `RangeSlider` bounded by the values in the data | `number` columns with `between` |
+| `DgDateRangeFilter` | Two `type="date"` inputs | `date` columns with `between` |
+| `DgAutocompleteFilter` | `Autocomplete` over the column's values | Text columns with a scalar operator |
+| `DgTriStateFilter` | `SegmentedControl` of all, true and false | `boolean` columns |
+
+Each of the four specialised controls falls back to `TMDataGridFilterValueInput` for the operators it does not handle.
+Every control takes the same argument object, `TMDataGridFilterControlArgs`:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `column` · `table` | TanStack instances | The column being filtered, and the table. |
+| `operator` | `TMDataGridFilterOperator` | The row's selected operator. A control reads it and never writes it. |
+| `value` | `string \| ReadonlyArray<string>` | The bare filter value, never the `{ operator, value }` wrapper. |
+| `onChange` | `(next: string \| ReadonlyArray<string>) => void` | Writes the bare value. The grid pairs it with the current operator. |
+| `options` | `ReadonlyArray<TMDataGridOption>` | The column's options, resolved for a column declaring `meta.options` or a select type. Empty otherwise. |
+| `size` | `TMDataGridSize` | The grid's resolved control size. |
+| `labels` | `TMDataGridLabels` | The resolved dictionary. |
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `useTMDataGrid` | Hook | `(options) => TMDataGridApi` | – | Creates the table, UI store and edit engine. |
+| `useTMDataGridContext` | Hook | `() => TMDataGridContextValue` | – | The grid, from inside any part. Throws outside `TMDataGrid`. |
+| `TMDataGrid` | Component | – | – | The root element. Provides the grid through context. |
+| `TMDataGrid.Table` | Component | – | – | Header, virtualized body and filter panel. |
+| `TMDataGrid.Toolbar` · `.Spacer` | Components | – | – | The toolbar row, and the gap that pushes items right. |
+| `TMDataGrid.Search` | Component | – | – | Quick search input. Also `TMDataGridSearch`. |
+| `TMDataGrid.FilterButton` · `.FilterPanel` | Components | – | – | The filter UI. Props on [Filtering](/docs/filtering). |
+| `TMDataGrid.Menu` · `.ColumnsPanel` | Components | – | – | The burger menu, and the column chooser as plain controls. |
+| `TMDataGrid.LoadingIndicator` · `.SummaryCount` | Components | – | – | Fetch spinner, and the row count. |
+| `TMDataGrid.DraftActions` | Component | – | – | Save and Discard. Also `TMDataGridDraftActions`. |
+| `TMDataGrid.Footer` | Component | – | – | The pager bar. |
+| `TMDataGrid.FilterPills` | Component | – | – | Active filters as pills. Also `TMDataGridFilterPills`. Props on [Filtering](/docs/filtering). |
+| `openColumnFilter` | Export | `(api, columnId) => void` | – | Sends the user to a column's filter control. See [Filtering](/docs/filtering#opencolumnfilter). |
+| `getTMDataGridPaginationApi` | Function | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | Paging state and actions for a pager of your own. |
+| `DEFAULT_EXPORT_OPTIONS` | Constant | `TMDataGridExportSettings` | – | The export defaults `exportOptions` merges over. See [Export](/docs/export). |