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

package/skills/filtering/SKILL.md

@@ -3,24 +3,27 @@ name: filtering
 description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
-  meta.type offers each, meta.filter.defaultOperator, isFilterActive and the
-  half-typed filter, the filter panel, TMDataGrid.FilterButton,
-  TMDataGrid.FilterPills with its api prop, openColumnFilter, replacing a value
-  control with DgRangeSliderFilter / DgDateRangeFilter / DgAutocompleteFilter /
-  DgTriStateFilter or a meta.filter.control component, per-column filterFn, and
-  the quick search: TMDataGrid.Search, quickSearchMode fuzzy or contains,
-  fuzzyGlobalFilterFn, enableMatchHighlighting and enableGlobalFilter. Load when
-  adding filters, choosing operators, building a filter control, showing active
-  filters outside the grid, or wiring a search box.
+  meta.type offers each, meta.filter.operators to offer a column only a subset
+  of them, meta.filter.defaultOperator, isFilterActive and the half-typed
+  filter, the filters option and its surfaces (popup, sidebar, none, plus
+  inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
+  TMDataGrid.FilterButton, TMDataGrid.FilterPills with its api prop,
+  openColumnFilter, replacing a value control with DgRangeSliderFilter /
+  DgDateRangeFilter / DgAutocompleteFilter / DgTriStateFilter or a
+  meta.filter.control component, per-column filterFn, and the quick search:
+  TMDataGrid.Search, quickSearchMode fuzzy or contains, fuzzyGlobalFilterFn,
+  enableMatchHighlighting and enableGlobalFilter. Load when adding filters,
+  choosing operators, building a filter control, showing active filters outside
+  the grid, or wiring a search box.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.21'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/filtering.md'
-  - 'Jielga/TMDataGrid:src/docs/quick-search.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/filterOperators.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/quickSearch.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/filtering.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/quick-search.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/filterOperators.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/quickSearch.ts'
 ---
 
 # TMDataGrid - Filtering
@@ -48,7 +51,9 @@ leaving that end open).
 
 A filter with an empty value **stays in state** so the panel keeps its row while
 the user types. It matches every row, does not set the header indicator and
-produces no pill. `isFilterActive(value)` tests for that state; presence in
+produces no pill. `isFilterActive(value)` tests for that state, and
+`activeColumnFilters(columnFilters | table)` applies it across the slice and
+types what it hands back (entries in any other value shape are dropped); presence in
 `columnFilters` does not.
 
 ## Operators
@@ -80,16 +85,105 @@ columnHelper.accessor("salary", {
 });
 ```
 
-## The panel and the pills
+`meta.filter.operators` narrows the list a column offers to a subset of its
+type's - for a column whose backend answers only some operators, so the user is
+never offered one the query cannot express. The panel dropdown and the header
+funnel show only those, in the type's order. An operator the type does not
+offer is ignored; a list that leaves nothing falls back to the type's full set.
+Without `defaultOperator`, a fresh filter opens on the type's default when it is
+offered, else on the first offered operator.
 
-`TMDataGrid.FilterPanel` is column, operator and value rows under a "Filters"
-header, above "Add filter" and "Clear all". It is rendered by
-`TMDataGrid.Table`; Escape and a click outside close it, with `FilterButton`
-exempt from the click-away so it stays a toggle. Closing only hides it; the
-filters stay. **Clear all** drops every filter, half-typed ones included.
+```tsx
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: ["contains", "equals", "isEmpty", "isNotEmpty"] } },
+});
+```
+
+`getColumnOperators(column)` returns the resolved list and
+`getColumnDefaultOperator(column)` the operator a fresh filter opens on. The
+`server-side` skill shows the list typed together with the API mapping table.
+
+## The filters option
+
+`filters` on `useTMDataGrid` picks the surface. It is read field by field, so a
+literal is fine.
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `surface` | `"popup" \| "sidebar" \| "none"` | `"popup"` | What `TMDataGrid.Table` renders and `FilterButton` toggles. |
+| `sidebarSide` | `"left" \| "right"` | `"right"` | Which side the sidebar sits on. Ignored by the other surfaces. |
+| `sidebarWidth` | `string` | `"280px"` | Sidebar width, any CSS length. Ignored by the other surfaces. |
+| `defaultOpen` | `boolean` | `true` under `"sidebar"`, else `false` | Whether the surface starts open. Read once, at mount. Under `"none"`, the starting value of `ui.state.filterPanelOpen`. |
+| `inHeader` | `boolean` | `false` | A second header row of per-column controls. Independent of `surface`. |
+
+`surface` and `inHeader` are separate choices: `{ surface: "none", inHeader: true }`
+is header filters alone, `{ inHeader: true }` keeps the popup as well.
+
+```tsx
+useTMDataGrid({ data, columns, filters: { surface: "sidebar", inHeader: true } });
+```
+
+**Popup** - the default. Floats over the first body rows. A pointerdown
+outside, Escape, and emptying it (the last row removed, or **Clear all**) all
+close it; `FilterButton` is exempt from the click-away so it stays a toggle.
+
+**Sidebar** - the same panel beside the rows, inside the grid frame and under
+the toolbar. The rows give up the width rather than being covered, a click in
+the table does not dismiss it, and clearing the filters leaves it standing.
+Escape closes it. It starts open, being a layout choice; its rows are
+`layout="stacked"`, since 280px has no room for the triple.
+
+**Header filters** - `inHeader: true` adds a header row of value controls, one
+per filterable column, on the same column tracks as everything else. The
+column and operator dropdowns are not there: the column is the one the cell
+sits over, and the operator is a funnel button beside the input, tinted off its
+default. The column menu's Filter item and the funnel indicator both come off,
+having nothing left to reveal; the filtered column's tinted title stays. A
+narrow column clips its control - give it a `minSize`.
 
-`TMDataGrid.FilterPills` takes the grid as an `api` prop instead of reading
-context, so active filters can live in a page header or anywhere else:
+Clearing a header control removes the column's `columnFilters` entry rather
+than leaving an empty one, unless the user also picked a non-default operator,
+which is kept. Panel rows still keep their empty filters.
+
+`FilterButton` still toggles whatever `surface` names. `openColumnFilter` does
+not: under `inHeader` it always focuses the header control and leaves the
+surface closed.
+
+**None** - `surface: "none"` renders no panel and no `FilterButton`, so a
+hand-placed `TMDataGrid.FilterPanel` is the only one. Read
+`ui.state.filterPanelOpen` if it belongs behind a control of your own.
+
+## TMDataGrid.FilterPanel
+
+The panel of filter rows - one column / operator / value triple per filter, over "Add filter" and "Clear all".
+A plain block with no title, no close button and no open state: it renders wherever it is mounted, and the popup and sidebar surfaces are wrappers around it.
+It must be inside `<TMDataGrid>` (it reads the grid from context) and it only reads and writes `columnFilters`, so a `manualFiltering` grid gets it for free.
+Closing a surface only hides it; the filters stay.
+**Clear all** drops every filter, half-typed ones included.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout` | `"row" \| "stacked"` | `"row"` | `"row"` is side by side and wants about 550px; `"stacked"` fills a narrow host. Passed to every value control as its `layout`. |
+
+```tsx
+<Drawer opened={open} onClose={close}>
+  <TMDataGrid.FilterPanel layout="stacked" />
+</Drawer>
+```
+
+## TMDataGrid.FilterButton
+
+The toolbar button that toggles the filter surface, tinted with the count of active filters.
+Opening an empty panel seeds a filter row on the first filterable column; with filters already in state it opens on those.
+Renders nothing when no column can be filtered, and nothing under `surface: "none"`.
+No props.
+
+## TMDataGrid.FilterPills
+
+One pill per **active** filter, `First name: Sofia ✕`, where the ✕ clears it and a click on the label calls `openColumnFilter`.
+The label spells the operator out unless it is the type's default: `Age is greater than 30`, but `First name: Sofia`.
+It takes the grid as an `api` prop instead of reading context, so it renders anywhere on the page.
 
 ```tsx
 import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
@@ -97,11 +191,18 @@ import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
 <TMDataGridFilterPills api={grid} onPillClick={(columnId) => focus(columnId)} />;
 ```
 
-One pill per **active** filter, `First name: Sofia ✕`, where ✕ clears it and a
-click on the label reopens the panel on its column. The label spells the
-operator out unless it is the type's default: `Age is greater than 30`, but
-`First name: Sofia`. `openColumnFilter(api, columnId)` does the same reopening
-from anywhere, seeding an empty row if the column has none.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `api` | `TMDataGridApi<TData>` | - | The object returned by `useTMDataGrid`. |
+| `size` | `MantineSize` | `"sm"` | Pill size. |
+| `showClearAll` | `boolean` | `true` | "Clear all", shown once two filters are active. |
+| `onPillClick` | `(columnId: string) => void` | - | Replaces the default click behaviour. |
+| `className` | `string` | - | Added to the wrapper class. |
+
+## openColumnFilter
+
+`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row - or, under `inHeader`, scrolls the column's header control into view and focuses it, leaving the surface closed.
+It is what a pill's label and the column menu's Filter item both call.
 
 ## Replacing the value control
 
@@ -220,12 +321,13 @@ const activeCount = columnFilters.length;
 Correct:
 
 ```tsx
-import { isFilterActive } from "@jielga/tmdatagrid";
+import { activeColumnFilters } from "@jielga/tmdatagrid";
 
-const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+// The entries that narrow anything, with `value` typed rather than `unknown`.
+const active = activeColumnFilters(columnFilters);
 ```
 
-Source: `src/docs/filtering.md` (How a filter is stored).
+Source: `packages/tmdatagrid/docs/filtering.md` (How a filter is stored).
 
 ### HIGH Assuming `value` is always a string
 
@@ -246,7 +348,7 @@ if (operatorTakesRangeValue(operator)) {
 }
 ```
 
-Source: `src/tmdatagrid/core/filterOperators.ts`.
+Source: `packages/tmdatagrid/src/core/filterOperators.ts`.
 
 ### HIGH A numeric column with no `meta.type`
 
@@ -255,7 +357,7 @@ Source: `src/tmdatagrid/core/filterOperators.ts`.
 `between` never appear in the panel, and comparisons run as text, where `"9"`
 sorts above `"10"`.
 
-Source: `src/docs/filtering.md` (Operators).
+Source: `packages/tmdatagrid/docs/filtering.md` (Operators).
 
 ### HIGH A filter control defined inside the component
 
@@ -272,7 +374,7 @@ const StatusFilter: TMDataGridFilterControlComponent = (args) => { /* … */ };
 meta: { filter: { control: StatusFilter } }
 ```
 
-Source: `src/docs/filtering.md` (Writing your own).
+Source: `packages/tmdatagrid/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Writing the whole filter from a custom control
 
@@ -292,7 +394,7 @@ Correct:
 onChange(picked);
 ```
 
-Source: `src/docs/filtering.md` (Writing your own).
+Source: `packages/tmdatagrid/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Expecting match highlighting in a custom cell
 
@@ -301,7 +403,7 @@ does not modify a custom renderer's output. A column with a `cell` renderer
 shows no marks whatever `enableMatchHighlighting` is set to. Equality operators
 highlight nothing either.
 
-Source: `src/docs/quick-search.md` (Match highlighting).
+Source: `packages/tmdatagrid/docs/quick-search.md` (Match highlighting).
 
 ### MEDIUM Expecting fuzzy ranking to survive a sort
 
@@ -309,7 +411,7 @@ The rank ordering applies only while the search is the sole narrowing. Any sort
 or grouping replaces it. The ordering is derived and never written into
 `sorting`, so there is nothing to clear afterwards.
 
-Source: `src/docs/quick-search.md` (Fuzzy by default).
+Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 
 ## Reference
 
@@ -318,20 +420,26 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button and the menu item. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
-| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter opens on. |
+| `meta.filter.operators` | Column meta | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. |
+| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
 | `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
 | `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |
 | `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. Removes the input, or one column's participation. |
 | `globalFilterFn` | Table option | filter fn | fuzzy | Overrides the matching, and the ranking with it. |
-| `TMDataGrid.FilterPanel` | Component | – | – | The panel of filter rows. |
+| `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"`, Mantine `BoxProps` | `"row"` | The panel of filter rows, as a plain block. Style props set on it. |
+| `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |
+| `TMDataGridFilterControlArgs.layout` | Type | `"row" \| "stacked" \| "header"` | – | How much room a value control has, and whether it names itself. |
+| `filterValueShape` | Export | `(operator) => "scalar" \| "set" \| "range"` | – | Which shape an operator's value takes. |
 | `TMDataGrid.FilterButton` | Component | – | – | Toolbar button opening the panel, with an active count. |
-| `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, `className` | – | Active filters as removable pills, renderable anywhere. |
+| `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, Mantine `BoxProps` | – | Active filters as removable pills, renderable anywhere. Style props set on the wrapper. |
 | `TMDataGrid.Search` | Component | `placeholder`, `debounce` (`250`), `w` (`220`) | – | The debounced quick-search input. |
 | `openColumnFilter` | Export | `(api, columnId) => void` | – | Opens the panel on a column. |
 | `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value narrows anything. |
+| `activeColumnFilters` | Export | `(columnFilters \| table) => Array<{ id, value }>` | – | The filters in the grid's own value shape that narrow anything, typed. |
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
+| `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | One column's list after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
 | `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
 | `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator expects. |

package/skills/getting-started/SKILL.md

@@ -4,19 +4,19 @@ description: >
   Set up TMDataGrid, a compound React data grid built on TanStack Table v9 and
   Mantine. Covers useTMDataGrid, the TMDataGrid root, context, the component
   catalog (Table, Footer, Toolbar, Spacer, SummaryCount, Search,
-  LoadingIndicator, EditActions, FilterButton, ColumnsButton, FilterPanel,
-  FilterPills, ColumnsPanel), the size scale and the bounded-height layout
-  requirement. Load when adding a grid, choosing which parts to render, or when
-  rows do not appear.
+  LoadingIndicator, DraftActions, FilterButton, Menu, FilterPanel, FilterPills,
+  ColumnsPanel), the size scale and the bounded-height layout requirement. Load
+  when adding a grid, choosing which parts to render, or when rows do not
+  appear.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.21'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/getting-started.md'
-  - 'Jielga/TMDataGrid:src/docs/anatomy.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/sizes.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/getting-started.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/anatomy.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/sizes.ts'
 ---
 
 # TMDataGrid - Getting started
@@ -80,7 +80,9 @@ export function Employees({ data }: { data: Employee[] }) {
         <TMDataGrid.SummaryCount />
         <TMDataGrid.Spacer />
         <TMDataGrid.FilterButton />
-        <TMDataGrid.ColumnsButton />
+        <TMDataGrid.Menu>
+          <TMDataGrid.Menu.Columns />
+        </TMDataGrid.Menu>
       </TMDataGrid.Toolbar>
 
       <TMDataGrid.Table<Employee> />
@@ -149,18 +151,18 @@ flex column.
 | Component | Props | Notes |
 | --- | --- | --- |
 | `TMDataGrid` | `table`, `ui`, `features`, `size`, `className`, `style` | Root. Provides context. `style` also takes CSS variables: `--dg-row-selected-bg`, `--dg-row-height`, `--dg-header-height`, `--dg-font-size`, `--dg-padding`. |
-| `TMDataGrid.Table` | `onRowClick(row)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, filter panel. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
+| `TMDataGrid.Table` | `onRowClick(row)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, and whichever filter surface the `filters` option asks for. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
 | `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`), `pagination` render prop | Pagination controls. Renders nothing unless pagination is enabled. |
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
 | `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
 | `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. |
 | `TMDataGrid.LoadingIndicator` | - | Small spinner while `meta.loading` is `true` and rows stay on screen. |
-| `TMDataGrid.EditActions` | `renderActions` | Save with the pending count, and Discard. Renders nothing while editing is off - see the `editing` skill. |
-| `TMDataGrid.FilterButton` | - | Toggles filter panel. Renders nothing if no column is filterable. |
-| `TMDataGrid.ColumnsButton` | - | Opens column manager. Renders nothing if no column is hideable. |
-| `TMDataGrid.FilterPanel` | - | Rendered by `.Table`; exported for custom layouts. Header close button, Escape, click-away, "Add filter" and "Clear all". |
-| `TMDataGrid.ColumnsPanel` | - | Rendered by `.ColumnsButton`; exported for custom layouts. |
+| `TMDataGrid.DraftActions` | `renderActions` | Save with the pending count, and Discard. Renders nothing while editing is off - see the `editing` skill. |
+| `TMDataGrid.FilterButton` | - | Toggles the filter surface, seeding a filter row on the first filterable column. Renders nothing if no column is filterable, or under `filters.surface: "none"`. |
+| `TMDataGrid.Menu` | `children`, `icon`, `label`, Mantine `MenuProps` | The burger and its dropdown: your own `Menu.Item`s, and `TMDataGrid.Menu.Columns`, the column chooser as menu items (renders nothing if no column is hideable). See the `appearance` skill. |
+| `TMDataGrid.FilterPanel` | `layout` (`"row"` \| `"stacked"`, default `"row"`) | Filter rows over "Add filter" / "Clear all", as a plain block. Rendered by `.Table` inside the popup and the sidebar; place it yourself under `filters.surface: "none"`. See the `filtering` skill. |
+| `TMDataGrid.ColumnsPanel` | - | The column chooser as plain controls, for a Popover or a Drawer. |
 | `TMDataGrid.FilterPills` | `api`, `size` (default `"sm"`), `showClearAll` (default `true`), `onPillClick(columnId)`, `className` | One pill per active filter, ✕ to clear it. Takes the api as a prop, so it can be rendered outside the grid. Also exported as `TMDataGridFilterPills`. |
 
 Pass the row type so `onRowClick` stays typed:

package/skills/grouping/SKILL.md

@@ -14,12 +14,12 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.21'
 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,7 +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
-- carry `data-grouped` and `data-depth`, with `--dg-row-group-bg` behind them
+- 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
 
 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
@@ -140,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
@@ -166,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
 
@@ -181,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
 
@@ -190,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:
 
@@ -205,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
 
@@ -215,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
 
@@ -235,7 +252,7 @@ useTMDataGrid({
 });
 ```
 
-Source: `src/docs/grouping.md` (Server-side grids).
+Source: `packages/tmdatagrid/docs/grouping.md` (Server-side grids).
 
 ## Reference
 
@@ -256,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 | – | – | On group rows, and the nesting level on every row. |
+| `data-grouped` · `data-depth` | Data attributes | – | – | `"true"` on group rows (published on every row), 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.2'
+  library_version: '2.0.0-beta.21'
 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
@@ -62,10 +62,11 @@ rather than forwarded to TanStack.
 | `onFocusedCellChange` | `(cell \| null) => void` | – | Fires whenever the focused cell moves. |
 | `overscan` | `number` | `6` | Rows the virtualizer keeps mounted above and below the viewport. Defined by the grid. |
 | `columnResizeMode` | `"onChange" \| "onEnd"` | `"onChange"` | Resize update strategy. |
-| `initialState` | `Partial<TableState>` | See below | Merged over the grid defaults. |
+| `initialState` | `Partial<TableState>` | See below | The state the grid starts from, read once on mount. Merged over the grid defaults. |
+| `state` | `Partial<TableState>` | – | Controlled state. Each slice requires its `onXChange` - see below. |
 | `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
 | `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
-| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. `mode` (`"cell" \| "cellConfirm" \| "row" \| "draft"`) picks the commit policy; the object also holds `onCommit`, `onCommitDrafts`, `rowValidators`, `isRowEditable`, `newRowDefaults`, `newRowsSticky`, `onRowAdd` and `onRowDelete` - see the `editing` skill. |
+| `editing` | `TMDataGridEditingOptions` | off | Turns editing on. Two axes: `mode` (`"cell" \| "cellConfirm" \| "row"`) picks what counts as a commit, `draft` picks whether it parks in the draft store; the object also holds `onCommit`, `onSaveDrafts`, `rowValidators`, `isRowEditable`, `newRowDefaults`, `newRowsSticky` (keeps committed new rows in the sticky entry block instead of sorting them in with the body), `onRowAdd` and `onRowDelete` - see the `editing` skill. |
 | `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. |
 
 ### Default initial state
@@ -73,9 +74,38 @@ 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
+
+`state` makes a slice controlled: the parent owns the value, the grid reads it
+every render, and all writes go through the matching `onXChange`. Without the
+callback the slice cannot change; the grid logs a console warning in
+development. For a starting value only, use `initialState`.
+
+```tsx
+const [columnVisibility, setColumnVisibility] = useState({ play: false });
+
+const grid = useTMDataGrid({
+  data,
+  columns,
+  state: { columnVisibility },
+  onColumnVisibilityChange: setColumnVisibility,
+});
+```
+
+- A key set to `undefined` is ignored; the slice is uncontrolled.
+- Slices compare structurally between renders, so the `state` object can be
+  built inline. `Date`s compare by time; `Map`s and class instances compare by
+  identity and belong in `useState` or `useMemo`.
+- `atoms` also controls a slice, with no callback. Takes precedence over
+  `state` for the same slice.
+- `columnVisibility` toggles user-defined columns only. Entries for the
+  generated columns are ignored; enable or disable those through their feature
+  options. The tree column's entry follows `grouping`.
+- `persist` cannot restore a controlled slice; it still writes it to storage.
+
 ## meta
 
 | Field | Type | Default | Description |
@@ -178,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` |