@jielga/tmdatagrid 1.0.1 → 1.0.2

package/skills/grouping/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: grouping
+description: >
+  Group TMDataGrid rows into a tree, and total them. Covers enableGrouping,
+  initialState.grouping, the generated GROUP_COLUMN_ID tree lane, why a grouped
+  column leaves the grid and how groupedColumnMode keeps it, aggregationFn and
+  aggregatedCell with the registered names (sum, mean, count, uniqueCount,
+  extent, …), why the grid clears TanStack's "auto" default, group-row
+  selection, why group rows are not data rows, why grouping suspends the pager
+  and isPagingActive, manualGrouping for server-side trees, and the summary row
+  through a column footer with aggregateColumn. Load when grouping rows,
+  aggregating a column, adding totals along the bottom edge, or when the pager
+  greys out.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '1.0.2'
+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'
+---
+
+# TMDataGrid - Grouping and totals
+
+Two independent things: grouping folds the rows into a tree and totals each
+category, and the summary row totals everything along the bottom edge.
+
+## Grouping
+
+On by default, and nothing changes until a column is grouped - the reader does
+that from **Group by …** in any column menu. To open already grouped, seed the
+state:
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  initialState: { grouping: ["department"] },
+});
+```
+
+Grouping a column **removes it** - its values have moved into the tree lane -
+and a generated Group column (`GROUP_COLUMN_ID`) appears at the front, pinned
+beside the checkbox lane. Each group row shows its value, its record count and a
+chevron. Grouping a second column nests.
+
+Because a grouped column is no longer in the grid, **Ungroup** lives on the tree
+column's menu, one item per grouped column. `groupedColumnMode: "reorder"`
+(TanStack's own default) keeps grouped columns in the grid, moved to the front,
+instead of removing them.
+
+## Aggregation
+
+Off unless asked for. A grouped grid is a tree, not a summary: a group row
+leaves every cell blank except the tree lane. Give a column an `aggregationFn`
+and it fills in.
+
+```tsx
+columnHelper.accessor("salary", {
+  header: "Salary",
+  aggregationFn: "sum",
+  aggregatedCell: (info) => <strong>{sek(Number(info.getValue()))}</strong>,
+  meta: { type: "number", align: "right" },
+});
+```
+
+`"sum"`, `"min"`, `"max"`, `"extent"`, `"mean"`, `"median"`, `"unique"`,
+`"uniqueCount"`, `"count"` and `"auto"` are registered, and a function is
+accepted too.
+
+TanStack's grouping feature defaults every column to `aggregationFn: "auto"`.
+**The grid clears that default**, so grouping does not silently start summing
+numeric columns. Setting `"auto"` yourself restores it.
+
+Grouping runs before sorting, so sorting sorts the rows *inside* each group and
+orders the groups by their aggregated value. A column with no aggregation has no
+value on a group row, so sorting on it reorders rows within each group and
+leaves the groups where they are.
+
+## Group rows are not data rows
+
+A group row is built on its first child's record, so handing it to a callback
+would hand over a real-looking row that 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
+
+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
+dash while only some are. Only the records reach `rowSelection` - a group row is
+never in it - so `getSelectedRowModel()` and the toolbar count are unaffected by
+how the tree is arranged. Under `enableMultiRowSelection: false` group rows carry
+no checkbox.
+
+`getGroupDataRows(row)` returns every record under a group row, at any depth.
+
+## Grouping suspends pagination
+
+**Grouping and the built-in pager do not work together, and grouping wins.** As
+soon as a column is grouped the grid renders the whole tree and relies on
+virtualization; `TMDataGrid.Footer` greys its pager out and replaces the range
+with `Grouped · all N rows`. Ungroup and paging resumes where it left off.
+
+This is deliberate. A page can only count one kind of thing, and once the rows
+are a tree neither answer is usable: counting every row splits a group across a
+page boundary, and counting top-level rows quietly redefines "rows per page" as
+groups per page. Rendering the whole tree is the grid's default mode anyway -
+pagination is the opt-in - so nothing is lost but the pager.
+
+`isPagingActive(table, features)` is exported so a custom pager can grey itself
+out the same way. To have both, page on the server: group there and feed the
+grid one page of a tree at a time with `manualPagination` and `manualGrouping`.
+
+## The summary row
+
+There is no flag. Give a column a `footer` and the row appears; it exists
+exactly when at least one visible column defines one.
+
+```tsx
+import { aggregateColumn } from "@jielga/tmdatagrid";
+
+columnHelper.accessor("salary", {
+  header: "Salary",
+  footer: ({ table }) =>
+    sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+});
+```
+
+`footer` is TanStack's own column option, rendered the way the header is.
+`aggregateColumn({ table, columnId, fn })` computes over every **filtered** row -
+all pages, following the filters live - through the registered aggregation
+functions, with `fn` defaulting to `"sum"`.
+
+```tsx
+aggregateColumn({ table, columnId: "age", fn: "mean" });
+aggregateColumn({ table, columnId: "location", fn: "uniqueCount" });
+```
+
+Following the filters is the point: a footer that keeps saying the same number
+while the reader narrows the grid looks like it is answering the question in
+front of them when it is not.
+
+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
+`--dg-summary-height`.
+
+## Common mistakes
+
+### CRITICAL Expecting group rows to total automatically
+
+Grouping alone leaves every cell blank on a group row, because the grid clears
+TanStack's `aggregationFn: "auto"` default. Nothing errors - the tree simply
+looks empty, which reads as a broken feature.
+
+Wrong:
+
+```tsx
+columnHelper.accessor("salary", { header: "Salary" });
+```
+
+Correct:
+
+```tsx
+columnHelper.accessor("salary", { header: "Salary", aggregationFn: "sum" });
+```
+
+Source: `src/docs/grouping.md` (Aggregation).
+
+### HIGH Looking for the grouped column in the grid
+
+`groupedColumnMode` defaults to `"remove"`, so grouping by Department takes the
+Department column out - its values are in the tree lane. Code that reads that
+column's cells, or a test that queries its header, stops finding it the moment a
+reader groups.
+
+Correct, when the column must stay:
+
+```tsx
+useTMDataGrid({ data, columns, groupedColumnMode: "reorder" });
+```
+
+Source: `src/docs/grouping.md` (What grouping does to the grid).
+
+### HIGH Combining the pager with grouping
+
+`enablePagination: true` and a grouped column cannot both be honoured. The pager
+greys out rather than 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).
+
+### HIGH Handing a group row to a row callback
+
+Group rows sit out `onRowClick`, the cell handlers, pinning, details and
+editing, and their `row.original` is an arbitrary child's record. A bulk action
+built from `row.original` on the tree lane acts on one record instead of the
+group.
+
+Correct:
+
+```tsx
+import { getGroupDataRows } from "@jielga/tmdatagrid";
+
+const records = getGroupDataRows(groupRow).map((row) => row.original);
+```
+
+Source: `src/docs/grouping.md` (Group rows are not data rows).
+
+### MEDIUM Totalling the page instead of the data
+
+`aggregateColumn` deliberately runs over every filtered row, all pages. Summing
+`table.getRowModel().rows` instead totals only what is currently paged in, which
+matches the screen but answers a different question - and under virtualization
+it is not even the whole page.
+
+Source: `src/docs/summary-row.md` (Totalling a column).
+
+### MEDIUM Grouping a server-paged grid
+
+`manualPagination: true` turns grouping off: the client holds one page and would
+build groups out of an arbitrary slice. Group on the server and declare it.
+
+Correct:
+
+```tsx
+useTMDataGrid({
+  data: page.rows,
+  columns,
+  manualPagination: true,
+  manualGrouping: true,
+  enableGrouping: true,
+});
+```
+
+Source: `src/docs/grouping.md` (Server-side grids).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `enableGrouping` | Table option | `boolean` | `true` | Group by and Ungroup menu items. Also a column option. |
+| `groupedColumnMode` | Table option | `"reorder" \| "remove" \| false` | `"remove"` | Whether a grouped column leaves the grid or moves to the front. |
+| `manualGrouping` | Table option | `boolean` | `false` | The rows arrive grouped. Required to group a server-paged grid. |
+| `initialState.grouping` | Table option | `string[]` | `[]` | Column ids grouped at mount. A settings slice, so it persists. |
+| `aggregationFn` | Column option | `TMDataGridAggregationName \| fn` | – | How a column fills in its group rows. Unset means blank. |
+| `aggregatedCell` | Column option | `(ctx) => ReactNode` | The `cell` renderer | Renders a group row's value differently. |
+| `footer` | Column option | `(ctx) => ReactNode` | – | Renders this column's summary cell, and summons the row. |
+| `aggregateColumn` | Export | `({ table, columnId, fn }) => unknown` | `fn: "sum"` | Aggregates over every filtered row, all pages. |
+| `TMDataGridAggregationName` | Export | type | – | The registered function names. |
+| `GROUP_COLUMN_ID` | Export | `"__group__"` | – | Id of the generated tree column. |
+| `formatGroupValue` | Export | `(value) => string` | – | How the tree lane renders a group's value. |
+| `getGroupDataRows` | Export | `(row) => Row[]` | – | Every record under a group row, at any depth. |
+| `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. |
+
+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

@@ -5,15 +5,16 @@ description: >
   of TanStack TableOptions, the default initialState (pagination, columnPinning,
   globalFilterFn), the meta object (loading, noResultsLabel, rowHeight,
   totalRowCount), the grid's own persist, enableColumnOrdering,
-  enablePagination, rowSelectionMode and highlightSelectedRows options, the
+  enablePagination, selectionMode and showSelectedBackground options, the
   persist option with dataKey/settingsKey slice selection and storageMode, the
-  returned table/ui/features triple, ui panel and column drag actions, and
-  reading grid state with useSelector. Load when configuring the hook,
-  persisting column layout or filters, or reacting to grid state from a parent.
+  returned api (table, ui, edit, features, labels, resetSettings, scrollToRow),
+  ui panel and column drag actions, and reading grid state with useSelector.
+  Load when configuring the hook, persisting column layout or filters, or
+  reacting to grid state from a parent.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.1'
+  library_version: '1.0.2'
 sources:
   - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
@@ -26,7 +27,7 @@ Creates the table instance and the state used by the grid interface.
 
 ```tsx
 const grid = useTMDataGrid<TData>(options);
-// { table, ui, features }
+// { table, ui, edit, features, labels, resetSettings, scrollToRow }
 ```
 
 Spread the result onto `TMDataGrid`.
@@ -38,18 +39,18 @@ All TanStack `TableOptions` are supported and passed through unchanged, includin
 flags and `rowCount`. The `features` option is supplied internally and cannot be
 overridden.
 
-`persist`, `enableColumnOrdering`, `enablePagination`, `rowSelectionMode` and
-`highlightSelectedRows` are the grid's own options and are consumed by the hook
+`persist`, `enableColumnOrdering`, `enablePagination`, `selectionMode` and
+`showSelectedBackground` are the grid's own options and are consumed by the hook
 rather than forwarded to TanStack.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `data` | `TData[]` | – | Row data. Keep the reference stable with `useMemo`. |
 | `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. |
-| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. |
+| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. Required once `editMode` is set. |
 | `enableRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes row selection and its checkbox column. |
-| `rowSelectionMode` | `"checkbox" \| "row"` | `"checkbox"` | `"row"` drops the checkbox column and selects on row click. Defined by the grid. |
-| `highlightSelectedRows` | `boolean` | Follows the mode | Highlight background on selected rows: off for `"checkbox"`, on for `"row"`. Colour is the `--dg-row-selected-bg` CSS variable. Defined by the grid. |
+| `selectionMode` | `"checkbox" \| "row" \| "checkboxAndHighlight" \| "highlight"` | `"checkbox"` | What selecting looks like and what a row click does. Defined by the grid - see the `rows` skill. |
+| `showSelectedBackground` | `boolean` | Follows the mode | Background tint on selected rows: off for `"checkbox"`, on for `"row"`. Colour is `--dg-row-selected-bg`. Defined by the grid. |
 | `enableSorting` | `boolean` | `true` | Enables sorting for the table. |
 | `enableColumnFilters` | `boolean` | `true` | Enables filtering for the table. |
 | `enableHiding` | `boolean` | `true` | Enables column visibility for the table. |
@@ -64,6 +65,8 @@ rather than forwarded to TanStack.
 | `initialState` | `Partial<TableState>` | See below | Merged over the grid defaults. |
 | `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
 | `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
+| `editMode` | `"cell" \| "cellConfirm" \| "row" \| "batch"` | off | Turns editing on. Brings `rowValidators`, `isRowEditable`, `onEditCommit`, `onEditCommitBatch`, `newRowDefaults`, `onRowAdd` and `onRowDelete` with it - see the `editing` skill. |
+| `labels` | `TMDataGridLabelsOverride` | English | Overrides for the grid's strings and `aria-label`s. |
 
 ### Default initial state
 
@@ -127,8 +130,12 @@ const persist = {
 
 | Group | Available slices |
 | --- | --- |
-| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination` |
-| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning` |
+| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
+
+`grouping` is a settings slice because it names columns rather than values, so it
+survives the data changing under it the way the column layout does. `expanded` is
+a data slice for the opposite reason.
 
 `DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` export the same values. Slice
 names are typed per group, so only valid names are accepted.
@@ -145,7 +152,11 @@ persistence is skipped rather than throwing.
 | --- | --- | --- |
 | `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
 | `ui` | `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
+| `edit` | `TMDataGridEditApi` | The edit engine, inert until `editMode` is set. See the `editing` skill. |
 | `features` | `TMDataGridFeatureFlags` | Table-level feature switches, re-read on each render. |
+| `labels` | `TMDataGridLabels` | The resolved label set, overrides merged over English. |
+| `resetSettings` | `() => void` | Puts the settings state back to a clean first visit. |
+| `scrollToRow` | `({ rowId, align? }) => boolean` | Scrolls a row into view through the virtualizer. `false` when the row is not in the current view. |
 
 Both stores are subscribable, which is how a parent reacts to grid state without
 owning it: