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

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/editing#adding-and-deleting-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/editing#the-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. |

package/docs/summary-row.md

@@ -0,0 +1,76 @@
+# Summary row
+
+A sticky row along the bottom edge holding totals for the whole grid: a count,
+a sum, or any other single number per column. It is independent of
+[grouping](/docs/grouping), which totals each category instead of everything.
+
+There is no flag. Give a column a `footer` and the row appears. The row exists
+whenever at least one visible column defines one.
+
+```tsx
+columnHelper.accessor("salary", {
+  header: "Salary",
+  footer: ({ table }) =>
+    sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+});
+```
+
+```demo
+file: rows/SummaryRow.tsx
+```
+
+`footer` is TanStack's own column option, rendered the way the header is: each
+cell renders that column's renderer with the header context. It can render
+anything: a static label, a count, or its own calculation.
+
+## Totalling a column
+
+`aggregateColumn({ table, columnId, fn })` computes over every **filtered** row
+(all pages, following the filters live) through the registered aggregation
+functions. `fn` defaults to `"sum"`.
+
+Every data row counts once.
+Grouping builds its group rows from this model rather than into it, so a grouped grid totals its records and not its records plus their subtotals.
+A tree built with `getSubRows` counts parents and children alike.
+
+It totals `data`, so under [`editing.draft`](/docs/editing) a committed edit is not in the total until `edit.saveDrafts()` sends it and the new `data` arrives.
+An edited cell shows its draft and the summary row does not follow it.
+The same holds for a group row's `aggregatedCell`: no group row has a form, so aggregates read the committed values throughout.
+
+```tsx
+aggregateColumn({ table, columnId: "salary" });                 // sum
+aggregateColumn({ table, columnId: "age", fn: "mean" });        // average
+aggregateColumn({ table, columnId: "location", fn: "uniqueCount" });
+```
+
+It takes `table`, so the same total can be read anywhere the table is in
+reach - a toolbar readout as much as a `footer`:
+
+```tsx
+const { table } = useTMDataGrid({ data, columns });
+
+<TMDataGrid.Toolbar>
+  <Text size="xs">
+    Payroll {sek(Number(aggregateColumn({ table, columnId: "salary" })))}
+  </Text>
+</TMDataGrid.Toolbar>;
+```
+
+## Layout
+
+Pinned columns keep their lanes in the summary row, and the row sits under the
+pinned-lane gradients in the stacking order. The generated lanes - checkbox,
+tree, details, row numbers - define no `footer`, so their summary cells stay
+blank.
+
+The row is sticky, so it stays put while the body scrolls, and its height is
+`--dg-summary-height`.
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `footer` | Column option | `(ctx) => ReactNode` | – | Renders this column's summary cell. Defining one on any column adds the row. |
+| `aggregateColumn` | Export | `({ table, columnId, fn }) => unknown` | `fn: "sum"` | Aggregates a column over every filtered row, all pages. |
+| `TMDataGridAggregationName` | Export | type | – | The registered function names - `sum`, `mean`, `count`, `uniqueCount`, … |
+| `--dg-summary-height` | CSS variable | length | From `size` | Height of the summary row. |