@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/skills/grouping/SKILL.md

@@ -14,12 +14,12 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/grouping.md'
-  - 'Jielga/TMDataGrid:src/docs/summary-row.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/grouping.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/summary.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/grouping.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/summary-row.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/grouping.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/summary.ts'
 ---
 
 # TMDataGrid - Grouping and totals
@@ -86,9 +86,12 @@ would pass a row that looks real but is the wrong one. Group rows therefore:
 - do not fire `onRowClick` or the cell handlers
 - cannot be highlighted, pinned, or given a details panel
 - never edit
+- are still handed to `rowStyle` and `rowClassName`, with that child's record
+  as `original`, so guard a callback reading `original` with
+  `row.getIsGrouped()` and colour the group rows with `--dg-row-group-bg`
 - carry `data-grouped="true"` and `data-depth`, with `--dg-row-group-bg`
-  behind them. `data-grouped` is on every row, `"true"` or `"false"`, so match
-  the value rather than the bare attribute
+  behind them. `data-grouped` is present only on group rows, so
+  `[data-grouped]` and `[data-grouped="true"]` are equivalent
 
 A group row's checkbox selects every record under it at any depth, including
 records inside collapsed sub-groups, showing a tick once all are selected and a
@@ -142,7 +145,9 @@ aggregateColumn({ table, columnId: "location", fn: "uniqueCount" });
 ```
 
 It follows the filters deliberately. A total that does not change as the user
-narrows the grid is misleading.
+narrows the grid is misleading. Its only argument is `table`, so a toolbar
+readout or any other component holding the table reads the same total without a
+`footer`.
 
 Pinned columns keep their lanes in the summary row, the generated lanes define
 no `footer` so their cells stay blank, and the row is sticky at
@@ -168,7 +173,7 @@ Correct:
 columnHelper.accessor("salary", { header: "Salary", aggregationFn: "sum" });
 ```
 
-Source: `src/docs/grouping.md` (Aggregation).
+Source: `packages/tmdatagrid/docs/grouping.md` (Aggregation).
 
 ### HIGH Looking for the grouped column in the grid
 
@@ -183,7 +188,7 @@ Correct, when the column must stay:
 useTMDataGrid({ data, columns, groupedColumnMode: "reorder" });
 ```
 
-Source: `src/docs/grouping.md` (What grouping does to the grid).
+Source: `packages/tmdatagrid/docs/grouping.md` (What grouping does to the grid).
 
 ### HIGH Combining the pager with grouping
 
@@ -192,14 +197,16 @@ out instead of paging the tree, so a footer count wired to `getPageCount()`
 reports a number nobody can navigate to. Read
 `isPagingActive(table, features)` before trusting the pager state.
 
-Source: `src/docs/grouping.md` (Grouping suspends pagination).
+Source: `packages/tmdatagrid/docs/grouping.md` (Grouping suspends pagination).
 
 ### HIGH Handing a group row to a row callback
 
 Group rows do not fire `onRowClick` or the cell handlers, and cannot be pinned,
 expanded or edited. Their `row.original` is an arbitrary child's record, so a
 bulk action built from `row.original` on the tree lane acts on one record
-instead of the group.
+instead of the group. `rowStyle` and `rowClassName` are the callbacks group
+rows do reach, so one reading `row.original` colours the group by whichever
+child came first.
 
 Correct:
 
@@ -207,9 +214,17 @@ Correct:
 import { getGroupDataRows } from "@jielga/tmdatagrid";
 
 const records = getGroupDataRows(groupRow).map((row) => row.original);
+
+<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
+  }
+/>;
 ```
 
-Source: `src/docs/grouping.md` (Group rows are not data rows).
+Source: `packages/tmdatagrid/docs/grouping.md` (Group rows are not data rows).
 
 ### MEDIUM Totalling the page instead of the data
 
@@ -217,7 +232,7 @@ Source: `src/docs/grouping.md` (Group rows are not data rows).
 `table.getRowModel().rows` instead totals only what is currently paged in, and
 under virtualization not even that: only the mounted rows.
 
-Source: `src/docs/summary-row.md` (Totalling a column).
+Source: `packages/tmdatagrid/docs/summary-row.md` (Totalling a column).
 
 ### MEDIUM Grouping a server-paged grid
 
@@ -237,7 +252,7 @@ useTMDataGrid({
 });
 ```
 
-Source: `src/docs/grouping.md` (Server-side grids).
+Source: `packages/tmdatagrid/docs/grouping.md` (Server-side grids).
 
 ## Reference
 
@@ -258,7 +273,7 @@ Source: `src/docs/grouping.md` (Server-side grids).
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything. `false` while grouped. |
 | `--dg-row-group-bg` | CSS variable | colour | Themed | Group row background. |
 | `--dg-summary-height` | CSS variable | length | From `size` | Height of the summary row. |
-| `data-grouped` · `data-depth` | Data attributes | – | – | `"true"` on group rows (published on every row), and the nesting level on every row. |
+| `data-grouped` · `data-depth` | Data attributes | – | – | `"true"` on group rows (absent on the rest), and the nesting level on every row. |
 
 See also: the `rows` skill for selection and the details lane, and the `data`
 skill for the pager grouping suspends.

package/skills/options/SKILL.md

@@ -14,11 +14,11 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/persistence.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/use-tm-data-grid.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/persistence.ts'
 ---
 
 # TMDataGrid - useTMDataGrid
@@ -74,7 +74,7 @@ rather than forwarded to TanStack.
 | Slice | Default |
 | --- | --- |
 | `pagination` | `{ pageIndex: 0, pageSize: 25 }` - inert until pagination is enabled |
-| `columnPinning.left` | The checkbox column, followed by any columns you provide |
+| `columnPinning.start` | The checkbox column, followed by any columns you provide |
 | `globalFilterFn` | `"includesString"` |
 
 ### Controlled state
@@ -208,8 +208,8 @@ const filterPanelOpen = useSelector(grid.ui, (state) => state.filterPanelOpen);
 | --- | --- |
 | `openFilterPanel` | `(columnId?: string \| null) => void` |
 | `closeFilterPanel` | `() => void` |
-| `setColumnsPanelOpen` | `(open: boolean) => void` |
-| `toggleColumnsPanel` | `() => void` |
+| `focusPanelFilter` | `(columnId: string \| null) => void` |
+| `focusHeaderFilter` | `(columnId: string \| null) => void` |
 | `startColumnDrag` | `(columnId: string) => void` |
 | `endColumnDrag` | `() => void` |
 | `setHighlightedRow` | `(rowId: string \| null) => void` |

package/skills/rows/SKILL.md

@@ -17,14 +17,15 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/row-selection.md'
-  - 'Jielga/TMDataGrid:src/docs/row-interaction.md'
-  - 'Jielga/TMDataGrid:src/docs/row-styling.md'
-  - 'Jielga/TMDataGrid:src/docs/row-details.md'
-  - 'Jielga/TMDataGrid:src/docs/row-pinning.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/rowSelection.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-selection.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-interaction.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/column-menu.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-styling.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-details.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/row-pinning.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/rowSelection.ts'
 ---
 
 # TMDataGrid - Rows
@@ -187,13 +188,15 @@ array rather than a node:
 
 Returning an empty list leaves the column with no menu button at all.
 
+Source: `packages/tmdatagrid/docs/column-menu.md`.
+
 ## Row styling
 
 ```tsx
 <TMDataGrid.Table<Employee>
   striped
   rowStyle={(row) =>
-    row.original.status === "Terminated"
+    !row.getIsGrouped() && row.original.status === "Terminated"
       ? { "--row-bg": "color-mix(in srgb, var(--mantine-color-red-6) 12%, transparent)" }
       : undefined
   }
@@ -211,8 +214,9 @@ are not striped.
 Rows carry `data-selected`, `data-selected-bg`, `data-highlighted`,
 `data-grouped`, `data-depth`, `data-context-menu` and `data-row-id`, so a
 stylesheet can target any of it without a callback. The boolean attributes are
-published on every row as `"true"` or `"false"`, so match the value
-(`[data-grouped="true"]`), not the bare attribute. Pick a `--row-bg` that
+present, with the value `"true"`, only while they apply - `data-grouped` only
+on group rows - so `[data-grouped]` and `[data-grouped="true"]` are
+equivalent. Pick a `--row-bg` that
 reads under both colour schemes - a `-0` Mantine shade is near-white and
 unreadable in dark mode; mix a mid shade into transparency instead.
 
@@ -295,7 +299,7 @@ Correct:
 rowStyle={() => ({ "--row-bg": "pink" })}
 ```
 
-Source: `src/docs/row-styling.md` (Set `--row-bg`, not `background`).
+Source: `packages/tmdatagrid/docs/row-styling.md` (Set `--row-bg`, not `background`).
 
 ### CRITICAL Reading the selection without subscribing
 
@@ -317,7 +321,7 @@ const selected = useSelector(grid.table.store, () =>
 );
 ```
 
-Source: `src/docs/row-selection.md` (Acting on a selection).
+Source: `packages/tmdatagrid/docs/row-selection.md` (Acting on a selection).
 
 ### HIGH Looking for the highlight in `rowSelection`
 
@@ -338,7 +342,7 @@ Correct:
 const current = useSelector(grid.ui, (state) => state.highlightedRowId);
 ```
 
-Source: `src/docs/row-selection.md` (The highlight is not a selection).
+Source: `packages/tmdatagrid/docs/row-selection.md` (The highlight is not a selection).
 
 ### HIGH Expecting a click handler to replace the built-in behaviour
 
@@ -353,7 +357,7 @@ Correct, when the click should only navigate:
 useTMDataGrid({ data, columns, selectionMode: "highlight" });
 ```
 
-Source: `src/docs/row-interaction.md`.
+Source: `packages/tmdatagrid/docs/row-interaction.md`.
 
 ### HIGH Reading `row.getIsExpanded()` in a cell without subscribing
 
@@ -366,7 +370,7 @@ Correct:
 const expanded = useSelector(row.table.store, () => row.getIsExpanded());
 ```
 
-Source: `src/docs/row-details.md` (Opening a row from elsewhere).
+Source: `packages/tmdatagrid/docs/row-details.md` (Opening a row from elsewhere).
 
 ### MEDIUM Assuming group rows behave like data rows
 
@@ -375,7 +379,7 @@ Group rows are built on their first child's record. They do not fire
 never pin, they take no row number, and they have no details panel. A handler
 written as though every row reaches it silently skips them.
 
-Source: `src/docs/row-interaction.md`, `src/docs/row-pinning.md`.
+Source: `packages/tmdatagrid/docs/row-interaction.md`, `packages/tmdatagrid/docs/row-pinning.md`.
 
 ### MEDIUM Open panels closing when `data` is replaced
 
@@ -388,7 +392,7 @@ Correct:
 useTMDataGrid({ data, columns, renderDetails, autoResetExpanded: false });
 ```
 
-Source: `src/docs/row-details.md`.
+Source: `packages/tmdatagrid/docs/row-details.md`.
 
 ### MEDIUM Expecting pinned rows to persist
 
@@ -396,7 +400,7 @@ Source: `src/docs/row-details.md`.
 layout store outlives any one data set. A pinned id whose row leaves `data` is
 not shown, and returns to its edge if the data comes back.
 
-Source: `src/docs/row-pinning.md`.
+Source: `packages/tmdatagrid/docs/row-pinning.md`.
 
 ## References
 

package/skills/server-side/SKILL.md

@@ -4,16 +4,22 @@ description: >
   Drive TMDataGrid from a server with TanStack manual modes - manualPagination,
   manualSorting, manualFiltering, rowCount, controlled state and onXChange
   callbacks. Covers the loading and totalRowCount meta fields, forwarding the
-  plain-JSON columnFilters model to an API with isFilterActive, persistence
-  interaction, and row selection across pages. Load when the grid is backed by a
-  paginated API rather than a local array.
+  plain-JSON columnFilters model to an API with activeColumnFilters, mapping
+  filters, sorting and the page index onto an endpoint's own query language
+  (field table, operator table, the three value shapes, meta.filter.operators
+  for an endpoint that answers only some operators, keying the fetch on the
+  request, paging against a page envelope), the first-page reset on a query
+  change, persistence interaction, and row selection across pages. Load when the
+  grid is backed by a paginated API rather than a local array, or when
+  translating grid filters into server-side queries.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/server-side.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-side.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/server-query.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/useTMDataGrid.tsx'
 ---
 
 # TMDataGrid - Server-side data
@@ -68,12 +74,32 @@ const grid = useTMDataGrid({
 | --- | --- | --- |
 | 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` |
+| `SummaryCount` total | Pre-filtered row count | `meta.totalRowCount`; the count alone without it |
 | Loading state | Not applicable | `meta.loading` |
 
 Column menus, the filter panel and the column manager behave identically in both
 modes.
 
+## The page index
+
+Under `manualPagination` the grid resets `pageIndex` to 0 whenever the query
+changes - a column filter, the quick search or the sort - so the next request
+never asks for page 8 of a result set that now has three. The reset lands in
+the same event as the change, so one request goes out. Pass the plain setters
+as the change callbacks; do not pair them with a page reset of your own.
+
+`resetPageOnQueryChange: false` switches it off. TanStack's
+`autoResetPageIndex` is a different rule: it defaults to `!manualPagination`
+and fires on a change to `data`, which server-side is the response landing.
+
+## Column options
+
+`meta.options: "faceted"` reads the distinct values in `data`, which
+server-side is one page of them - the dropdown then offers whatever was on the
+page the user is looking at. Declare the set as a list or a function instead.
+The grid warns once per column when a faceted column resolves under
+`manualFiltering` or `manualPagination`.
+
 ## Sending filters
 
 Filter values are plain JSON, so `columnFilters` forwards without transformation:
@@ -85,17 +111,136 @@ Filter values are plain JSON, so `columnFilters` forwards without transformation
 ]
 ```
 
-Translate at the API boundary, and skip entries whose value is still empty -
-those match all rows:
+Translate at the API boundary. `activeColumnFilters` hands back the entries
+that narrow anything, typed - `ColumnFiltersState` types `value` as `unknown`,
+and an entry whose value is still empty matches all rows:
 
 ```ts
-import { isFilterActive } from "@jielga/tmdatagrid";
+import { activeColumnFilters } from "@jielga/tmdatagrid";
 
-const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+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.
 
+## Mapping onto the endpoint's query language
+
+An API takes a request body of its own: its own field names, its own operator
+set, its own status codes, and pages counted from 1. The layer between the
+grid's state and that body is one function over two lookup tables, plus one
+function on the way back:
+
+- **A field table** keyed by column id, giving the API field and the cast from
+  the string every filter control writes to the type the field holds
+  (`Number`, an enum code). A column missing from the table is one the API
+  cannot query: the mapping drops the filter rather than sending a field the
+  endpoint would reject.
+- **An operator table** from `TMDataGridFilterOperator` to the API's operators.
+  Several grid operators collapse onto one - a date `before` and a number
+  `lessThan` are both `lt` once the value is cast. Declare it as a `Record`, not
+  a `Partial`, so an operator added by a later grid version fails the build
+  here rather than reaching the server unmapped.
+- **`toRow`** from the API's record to the grid's row type.
+
+```ts
+const QUERY_FIELDS: Record<string, { field: string; cast: (raw: string) => string | number }> = {
+  id: { field: "orderRef", cast: Number },
+  amount: { field: "totalAmount", cast: Number },
+  status: { field: "status", cast: (raw) => STATUS_CODES[raw] ?? raw },
+};
+
+const PREDICATE_OPS: Record<TMDataGridFilterOperator, PredicateOp> = {
+  contains: "like",
+  between: "range",
+  before: "lt",
+  lessThan: "lt",
+  isAnyOf: "in",
+  isEmpty: "isNull",
+  // ...one line for every remaining operator.
+};
+```
+
+### The three value shapes
+
+`TMDataGridFilterValue` is `{ operator, value }`, and the operator decides what
+`value` holds. Branch on all four cases, in this order:
+
+| Operator | `value` | Sent as |
+| --- | --- | --- |
+| `isEmpty`, `isNotEmpty` | Not used | `{ field, op }` |
+| `isAnyOf`, `isNoneOf` | `ReadonlyArray<string>` | `{ field, op, values }` |
+| `between` | `[min, max]`, either end possibly `""` | `{ field, op, from?, to? }` |
+| Everything else | `string` | `{ field, op, value }` |
+
+An empty end of a `between` pair leaves that side open: an absent bound, not an
+empty string. Run `activeColumnFilters` over the slice first so a half-typed
+filter is not sent as a predicate that narrows the result to nothing.
+
+### An endpoint that answers only some operators
+
+Most endpoints do not have every operator the grid has - `like` and `eq` but no
+prefix match is common. Do not offer what you would have to drop.
+`meta.filter.operators` narrows the column to the operators the query can
+express, and the mapping table is declared over exactly that list, so one
+cannot be offered without a mapping or mapped without being offered:
+
+```ts
+const TEXT_OPERATORS = [
+  "contains",
+  "equals",
+  "isEmpty",
+  "isNotEmpty",
+] as const satisfies readonly TMDataGridFilterOperator[];
+
+const TEXT_OPS: Record<(typeof TEXT_OPERATORS)[number], PredicateOp> = {
+  contains: "like",
+  equals: "eq",
+  isEmpty: "isNull",
+  isNotEmpty: "isNotNull",
+};
+
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: TEXT_OPERATORS } },
+});
+```
+
+A fresh filter opens on `meta.filter.defaultOperator` when set, else on the
+type's default when the list holds it, else on the first entry. The lookup at
+the boundary still returns `undefined` for an unmapped operator: a filter
+restored by `persist` from before the list was narrowed can carry one.
+
+### Keying the fetch on the request
+
+Serialize the request with `JSON.stringify` inside `useMemo` over
+`columnFilters`, `sorting` and `pagination`, and key the fetch effect (or the
+TanStack Query `queryKey`) on that string. Opening the panel and adding an
+empty row moves `columnFilters` but leaves the request unchanged, so nothing is
+sent. The effect owes the server a debounce (the value input updates on every
+keystroke) and a cancel (a `cancelled` flag in the cleanup, or an
+`AbortController` on a real `fetch`).
+
+### Paging against a page envelope
+
+| The API's | The grid's | Written as |
+| --- | --- | --- |
+| `page.number`, counted from 1 | `pagination.pageIndex`, counted from 0 | `number: pageIndex + 1` |
+| `page.totalItems`, the matched count | `rowCount` | `rowCount: page?.totalItems ?? 0` |
+| `page.totalPages` | `state.pageCount`, derived from `rowCount / pageSize` | Nothing; the grid computes it |
+
+Forward `totalPages` only when the server pages by something other than the
+size the grid asked for. `pageCount: -1` when the total is unknown. Show the
+page number through the Footer's `renderPagination` slot with
+`<Controls.PageSize /><Controls.PageNumber /><Controls.Pager />`.
+`meta.totalRowCount` is the unfiltered total, which no filtered response
+carries: take it from a separate count call.
+
 ## Persistence
 
 `persist` works unchanged. `dataKey` restores filters, sorting and pagination
@@ -126,18 +271,26 @@ Without `rowCount` the table derives the total from the rows it was handed -
 one page - so `getPageCount()` returns 1. The footer shows "1–25 of 25" and the
 next-page button is disabled, with no error. Pass the server total.
 
-### Filters sent without isFilterActive
+### Filters sent without activeColumnFilters
 
 An empty filter value stays in `columnFilters` while the user is still typing.
 Forwarded verbatim it becomes `operator: "contains", value: ""` at the API,
-which most backends translate into a real predicate. Filter with
-`isFilterActive` first.
+which most backends translate into a real predicate. Map over
+`activeColumnFilters(columnFilters)` instead of over the slice.
 
 ### SummaryCount without meta.totalRowCount
 
-`SummaryCount` falls back to the pre-filtered row count, which under manual
-filtering is just the current page. It reads "25 of 25" regardless of how many
-rows the server holds. Pass the unfiltered total as `meta.totalRowCount`.
+Without it there is no denominator to show: the pre-filtered row count is the
+current page, so the grid renders the matched count alone rather than a
+plausible-looking wrong total. Pass the unfiltered total as
+`meta.totalRowCount` to get the "42 / 5000" form back.
+
+### Offering operators the endpoint cannot answer
+
+The panel offers every operator of the column's type, and a mapping that drops
+`startsWith` leaves the user with a filter that silently does nothing. Declare
+`meta.filter.operators` on the column with the operators the endpoint answers,
+and type the operator table over that same list.
 
 ### Unstable getRowId across pages