@jielga/tmdatagrid 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jielga/tmdatagrid",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.",
   "license": "MIT",
   "type": "module",

package/skills/appearance/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: appearance
+description: >
+  Theme, size, compose and translate a TMDataGrid. Covers the size scale (xs to
+  xl) and what it drives, every --dg-* CSS variable for metrics, colours and the
+  stacking ladder, the two stylesheets styles.css and styles.layer.css and why
+  only one may be imported, the bounded-height layout rule with minHeight 0,
+  toolbar composition through children and TMDataGrid.Spacer, writing a toolbar
+  button with useTMDataGridContext, hiding it the way the built-ins do with
+  getGridCapabilities and getColumnCapabilities, why capabilities take a
+  features argument under the React Compiler, and localization through the
+  labels option, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, mergeLabels and
+  grid.labels. Load when styling or theming the grid, choosing a density,
+  building a toolbar, adding a button beside the built-in ones, or translating
+  the interface.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '1.0.2'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/styling.md'
+  - 'Jielga/TMDataGrid:src/docs/toolbar.md'
+  - 'Jielga/TMDataGrid:src/docs/localization.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/capabilities.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/labels.ts'
+---
+
+# TMDataGrid - Appearance, toolbar and labels
+
+Everything set on the grid element or composed around it: the size scale, the
+CSS variables, the toolbar, and the strings.
+
+## Size
+
+`size` drives row height, header height, font size and cell padding together,
+and selects the size of every Mantine control the grid renders.
+
+| `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 |
+
+Row height is also required by the virtualizer **as a number**, so it cannot be
+defined in CSS alone. For a height outside the scale set `meta.rowHeight`, not
+the variable. `SIZE_ROW_HEIGHT` is the exported source of these values.
+
+## CSS variables
+
+`style` accepts custom properties and `className` reaches the same element from
+a stylesheet. Both are per instance - a grid is themed without a provider.
+
+```tsx
+<TMDataGrid
+  {...grid}
+  size="sm"
+  style={{ "--dg-row-selected-bg": "var(--mantine-color-blue-0)" }}
+/>
+```
+
+**Metrics:** `--dg-row-height`, `--dg-header-height`, `--dg-summary-height`,
+`--dg-entry-height`, `--dg-font-size`, `--dg-padding`. All default from `size`.
+The generated lanes are exempt from padding: they are fixed 36px tracks that
+centre their control.
+
+**Colours:** `--row-bg` (one row's own background - set this, never
+`background`), `--dg-row-selected-bg`, `--dg-row-highlight-bg`,
+`--dg-row-striped-bg`, `--dg-row-group-bg`, `--dg-match-highlight-bg`,
+`--dg-header-shadow-color`.
+
+**Layout internals:** `--dg-sticky-edge-range` (`20px`), the `--dg-edge-*`
+markers the grid sets on cell-range borders, and the `--dg-z-*` stacking ladder -
+change those only to slot something of your own between two layers.
+
+One stylesheet import, once, anywhere:
+
+```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. 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 the part everyone forgets: a flex item's default
+`min-height: auto` refuses to shrink below its content, so without it the grid
+grows past the viewport instead of scrolling.
+
+## Toolbar
+
+The toolbar is a flex row and nothing more. No slots API, no `actions` prop -
+your buttons sit beside the built-in ones because they are all just children,
+and `TMDataGrid.Spacer` pushes what follows to the right. That is the whole
+layout system.
+
+```tsx
+<TMDataGrid.Toolbar>
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Search />
+  <TMDataGrid.Spacer />
+  <TMDataGrid.LoadingIndicator />
+  <ExportButton />
+  <TMDataGrid.FilterButton />
+  <TMDataGrid.ColumnsButton />
+</TMDataGrid.Toolbar>
+```
+
+Each built-in renders nothing when its feature is off, so a read-only grid needs
+no conditionals: `FilterButton` under `enableColumnFilters: false` is simply
+absent.
+
+A button of your own reads the grid from context - `{ table, ui, features,
+labels, controlSize, resetSettings }`:
+
+```tsx
+import {
+  exportGridToCsv,
+  getGridCapabilities,
+  useTMDataGridContext,
+} from "@jielga/tmdatagrid";
+
+function ExportButton() {
+  const { table, features, controlSize } = useTMDataGridContext();
+  const { canFilterAny } = getGridCapabilities(table, features);
+
+  if (!canFilterAny) return null;
+
+  return (
+    <Button size={controlSize} onClick={() => exportGridToCsv({ table })}>
+      Export
+    </Button>
+  );
+}
+```
+
+`getGridCapabilities(table, features)` answers `canSortAny`, `canFilterAny`,
+`canHideAny`, `canPinAny`, `canReorderAny`, `canGroupAny`, `canSelectRows`,
+`canPaginate` and `canSearch`. `getColumnCapabilities(column, features)` answers
+the same for one column as `canSort`, `canFilter`, `canHide`, `canPin`,
+`canResize`, `canReorder` and `canGroup`.
+
+### Why `features` is a second argument
+
+`features` comes back from `useTMDataGrid` and is re-derived from the options
+object on every render. It is required **in addition to** TanStack's `getCanX()`
+methods because it is what makes the result reactive: `column.getCanSort()` is a
+method call on a column object whose identity survives an options change, so
+under the React Compiler that call is memoized and a grid whose `enableSorting`
+flipped to `false` would carry on rendering sort indicators. `features` supplies
+a value that changes; `getCanX()` still decides the outcome.
+
+The same rule applies anywhere in your app: read state through
+`useSelector(table.store, …)` and options through `features`, rather than
+calling methods on a long-lived object.
+
+## Labels
+
+Every string the grid renders, and every `aria-label`, comes from one labels
+object. English by default, and `labels` takes **any subset**, merged over the
+defaults.
+
+```tsx
+import { TMDATAGRID_LABELS_SV } from "@jielga/tmdatagrid";
+
+const grid = useTMDataGrid({ data, columns, labels: TMDATAGRID_LABELS_SV });
+```
+
+Labels that carry a value are functions, so a language can put the value where
+its grammar wants it:
+
+```tsx
+const labels = {
+  groupBy: (column) => `Gruppera på ${column}`,
+  pageRange: ({ from, to, total }) => `${from}–${to} av ${total}`,
+} satisfies TMDataGridLabelsOverride;
+```
+
+`TMDataGridLabels` is the full dictionary type, which is what makes a new
+translation a typed exercise rather than a guess. The resolved dictionary comes
+back as `grid.labels` and from `useTMDataGridContext().labels`, so a component
+of your own uses the same strings as the built-in chrome.
+
+## Common mistakes
+
+### CRITICAL Importing both stylesheets
+
+`styles.css` and `styles.layer.css` are the same rules, one wrapped in a
+`@layer`. Importing both means the unlayered copy wins every cascade contest,
+so an application that ordered its layers to put the grid underneath its own
+overrides silently gets the opposite.
+
+Source: `src/docs/styling.md` (The stylesheet).
+
+### CRITICAL A grid with no bounded height
+
+The grid does not size itself to its content, so inside a flex parent without
+`minHeight: 0` it grows past the viewport and the page scrolls instead of the
+body. Rows render, so nothing looks broken until the list is long.
+
+Wrong:
+
+```tsx
+<TMDataGrid {...grid} style={{ flex: 1 }} />
+```
+
+Correct:
+
+```tsx
+<TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }} />
+```
+
+Source: `src/docs/styling.md` (Layout).
+
+### HIGH Setting `--dg-row-height` to change density
+
+The virtualizer needs the row height as a number, and takes it from
+`meta.rowHeight` or `size` - not from the variable. Setting the variable alone
+leaves the measurement and the render disagreeing, so rows overlap or gaps open
+as you scroll.
+
+Correct:
+
+```tsx
+useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
+```
+
+Source: `src/docs/styling.md` (The size scale).
+
+### HIGH A capability check without `features`
+
+`getGridCapabilities` and `getColumnCapabilities` both take `features` as a
+second argument because it is the value that changes. Calling
+`column.getCanSort()` directly in a custom header or toolbar button memoizes
+against the column identity under the React Compiler, and the control keeps
+rendering after its option was switched off.
+
+Wrong:
+
+```tsx
+if (!column.getCanSort()) return null;
+```
+
+Correct:
+
+```tsx
+const { canSort } = getColumnCapabilities(column, features);
+if (!canSort) return null;
+```
+
+Source: `src/docs/toolbar.md` (Why `features` is a second argument).
+
+### MEDIUM An inline `labels` object
+
+The chrome re-renders when the labels object changes identity, and an inline
+literal is a new object every render. Keep it at module scope, or `useMemo` it.
+
+Wrong:
+
+```tsx
+useTMDataGrid({ data, columns, labels: { noResults: "Inga träffar" } });
+```
+
+Correct:
+
+```tsx
+const labels = { noResults: "Inga träffar" } satisfies TMDataGridLabelsOverride;
+
+useTMDataGrid({ data, columns, labels });
+```
+
+Source: `src/docs/localization.md` (Keep the object stable).
+
+### MEDIUM Conditionally rendering built-in toolbar parts
+
+Each built-in already renders nothing when its feature is off. Wrapping them in
+your own checks duplicates the capability logic, and the two drift apart the
+first time an option changes.
+
+Source: `src/docs/toolbar.md` (The built-in parts).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `size` | Prop | `MantineSize` | `"md"` | The whole density scale. |
+| `className` · `style` · `id` | Props | – | – | Set on the root element. `style` takes the `--dg-*` variables. |
+| `meta.rowHeight` | Option | `number` | From `size` | A row height outside the scale. |
+| `SIZE_ROW_HEIGHT` | Export | `Record<MantineSize, number>` | – | The row heights the scale table lists. |
+| `SIZE_CONTROL_SIZE` | Export | `Record<MantineSize, MantineSize>` | – | Which control size each grid size uses. |
+| `DEFAULT_TMDATAGRID_SIZE` | Export | `"md"` | – | The default size. |
+| `TMDataGrid.Toolbar` · `Spacer` | Components | `children` | – | The flex row, and the push-right. |
+| `useTMDataGridContext` | Hook | `() => TMDataGridContextValue` | – | `{ table, ui, features, labels, controlSize, resetSettings }`. |
+| `getGridCapabilities` | Export | `(table, features) => TMDataGridCapabilities` | – | What this grid can do, reactively. |
+| `getColumnCapabilities` | Export | `(column, features) => TMDataGridColumnCapabilities` | – | The same for one column. |
+| `readFeatureFlags` | Export | `(options) => TMDataGridFeatureFlags` | – | Derives the flags from an options object. |
+| `labels` | Option | `TMDataGridLabelsOverride` | English | Any subset, merged over the defaults. Keep it stable. |
+| `grid.labels` | Hook return | `TMDataGridLabels` | – | The resolved dictionary. |
+| `TMDATAGRID_LABELS_EN` · `TMDATAGRID_LABELS_SV` | Exports | `TMDataGridLabels` | – | The English base, and a complete Swedish dictionary. |
+| `TMDataGridLabels` · `TMDataGridLabelsOverride` | Exports | types | – | The full dictionary, and a partial one. |
+| `mergeLabels` | Export | `(base, override) => TMDataGridLabels` | – | The merge, for composing dictionaries. |
+| `meta.noResultsLabel` | Option | `string` | `labels.noResults` | Per-instance override of the filtered-empty message. |
+
+The CSS layer name `tmdatagrid` in `styles.layer.css` is public API and never
+changes.
+
+See also: the `rows` skill for `--row-bg` and per-row styling, and
+`getting-started` for the component catalog.

package/skills/cell-selection/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: cell-selection
+description: >
+  Cell cursor, ranges, clipboard and CSV export in TMDataGrid. Covers the
+  cellSelection option and its none / single / range modes, the keyboard map
+  (arrows, Shift+arrows, PageUp/PageDown, Home/End, Enter, F2, Escape, Space,
+  Ctrl+C), the one-tab-stop rule and useCellControlTabIndex for controls inside
+  cells, the role flip from table/cell to grid/gridcell, ui.state.focusedCell
+  and ui.state.cellRange keyed by id, onFocusedCellChange, the copy and export
+  context menu, the cellExport options and their Nordic Excel defaults, and
+  exportGridToCsv over every filtered row. Load when adding keyboard cell
+  navigation, selecting blocks of cells, copying to a spreadsheet, exporting
+  CSV, or when Tab walks through controls inside the grid body.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '1.0.2'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/cell-selection.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/cellNavigation.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/cellRange.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/core/cellExport.ts'
+---
+
+# TMDataGrid - Cell selection
+
+A cell cursor the arrow keys move, a rectangle of cells that can be dragged out,
+and a Ctrl+C that pastes into Excel as cells rather than as one string. Off by
+default.
+
+```tsx
+const grid = useTMDataGrid({ data, columns, cellSelection: "range" });
+```
+
+| Mode | What it gives |
+| --- | --- |
+| `"none"` (default) | Nothing |
+| `"single"` | One focused cell, moved with the arrow keys |
+| `"range"` | As `"single"`, plus a rectangle, Ctrl+C and the export menu |
+
+Setting `editMode` defaults `cellSelection` to `"single"`, since editing
+navigates by cursor. An explicit `cellSelection` always wins.
+
+Turning it on changes three things about the body:
+
+- The tab stop moves from the row to a cell, so the whole grid is **one** Tab
+  stop and the arrow keys walk it.
+- The grid reports itself as a `grid` of `gridcell`s rather than a `table` of
+  `cell`s, which is what tells a screen reader those keys are live.
+- The focused cell takes `data-focused`, selected ones `data-selected` and
+  `data-edge-*`.
+
+## Keys
+
+| Key | Does |
+| --- | --- |
+| Arrows | Moves one cell, clamped at the edges, no wrapping |
+| Shift+arrows | Extends the rectangle from its anchor (`"range"`) |
+| PageUp / PageDown | Moves one viewport of rows |
+| Home / End | First / last cell of the row |
+| Ctrl+Home / Ctrl+End | First / last cell of the grid |
+| Enter or F2 | Steps into the cell - its checkbox, link or button |
+| Escape | Steps back out, or drops the rectangle to the focused cell |
+| Space | Selects the row, as a row click does under `selectionMode: "row"` |
+| Ctrl+C | Copies the selection as tab-separated text |
+
+Enter and F2 are the pair a cell editor takes over. Until then they focus the
+first control in the cell, and the arrow keys go quiet while focus is in there -
+a cell's contents own their own keys.
+
+## One tab stop
+
+Tab from a cell leaves the grid. What makes that true is that controls inside
+body cells - the checkbox, the tree chevron, the details chevron - take
+`tabindex="-1"` while cell selection is on. Left tabbable, Tab would walk through
+one per mounted row, and how many that is depends on the scroll position.
+
+They stay reachable: Enter or F2 steps in, Escape steps out, and Space ticks the
+row from any of its cells. Header controls are untouched - the header row is not
+part of cell navigation.
+
+A custom cell with a control in it wants the same treatment:
+
+```tsx
+import { useCellControlTabIndex } from "@jielga/tmdatagrid";
+
+const OpenButton = ({ row }) => (
+  <Button tabIndex={useCellControlTabIndex()} onClick={() => open(row.id)}>
+    Open
+  </Button>
+);
+```
+
+The hook returns `-1` while cell selection is on and `0` otherwise, so the same
+cell works either way.
+
+## Where the selection lives
+
+`ui.state.focusedCell` is a `{ rowId, columnId }` pair, and `ui.state.cellRange`
+is two of them, the anchor and the moving corner. **Ids rather than indices**, so
+sorting, filtering and column reordering carry the selection with the cells
+instead of leaving it over whatever slid into those positions. A range whose
+corner is filtered away paints nothing, and comes back when the filter lifts.
+
+```tsx
+const focusedCell = useSelector(grid.ui, (state) => state.focusedCell);
+
+grid.ui.actions.setFocusedCell({ rowId: "42", columnId: "salary" });
+```
+
+One rectangle at a time; Ctrl+drag for a second, disjoint block is not
+supported.
+
+The generated lanes (checkbox, tree, details) are part of the selection - they
+take the tint and the outline so the block stays a rectangle - but are never
+*exported*, since they hold controls rather than values. A block covering
+nothing else has nothing to copy, and the Copy and Export items say so by being
+disabled.
+
+## Copy and export
+
+Ctrl+C puts the block on the clipboard as tab-separated text with CRLF between
+rows, the format Excel, Sheets and Numbers all produce themselves. Values only:
+Excel's own copy carries no header row either.
+
+Right-clicking inside the selection opens Copy, "Export as CSV for Excel" and an
+"Include headers" toggle. A right-click outside it moves the selection there
+first, the way a spreadsheet does. Your own `rowContextMenu` items are appended
+below a divider, so nothing is lost by turning cell selection on.
+
+The CSV is written for a Nordic Excel: a `sep=;` first line, a UTF-8 BOM, CRLF
+endings, semicolons between fields and a comma as the decimal mark. That
+combination is what makes the file open straight into columns with å ä ö intact.
+
+```tsx
+<TMDataGrid.Table
+  cellExport={{ separator: ",", decimalComma: false, fileName: "employees" }}
+/>
+```
+
+What gets written is the cell's **value**, not what it renders. Dates come out
+in the `sv-SE` form (`2026-07-31`), which Excel reads as a date.
+
+`exportGridToCsv({ table, options })` takes **every filtered row** instead of the
+selected block, with the same options and defaults. There is no built-in button
+for it:
+
+```tsx
+<Button onClick={() => exportGridToCsv({ table: grid.table })}>Export</Button>
+```
+
+## Common mistakes
+
+### CRITICAL A custom cell control that breaks the single tab stop
+
+A `<Button>` or `<Checkbox>` rendered in a body cell keeps its default tab index,
+so Tab walks through one per mounted row. How many that is depends on the scroll
+position, which makes the bug look intermittent.
+
+Wrong:
+
+```tsx
+const OpenButton = ({ row }) => <Button onClick={() => open(row.id)}>Open</Button>;
+```
+
+Correct:
+
+```tsx
+const OpenButton = ({ row }) => (
+  <Button tabIndex={useCellControlTabIndex()} onClick={() => open(row.id)}>
+    Open
+  </Button>
+);
+```
+
+Source: `src/docs/cell-selection.md` (One tab stop).
+
+### HIGH Selectors written for `table` / `cell` roles
+
+The grid reports `grid` and `gridcell` once cell selection is on, so a test or a
+query written against `getByRole("cell")` stops resolving the moment the option
+is set - including when `editMode` turns it on implicitly.
+
+Source: `src/docs/cell-selection.md`, and the `testing` skill.
+
+### HIGH Reading the selection as row and column indices
+
+`focusedCell` and `cellRange` hold `{ rowId, columnId }`. Code that converts them
+to indices to look values up gets the wrong cell after any sort, filter or column
+move - which is exactly what ids were chosen to avoid.
+
+Correct:
+
+```tsx
+const row = grid.table.getRow(focusedCell.rowId);
+const value = row.getValue(focusedCell.columnId);
+```
+
+Source: `src/docs/cell-selection.md` (Where the selection lives).
+
+### MEDIUM Expecting the export to match what the cells show
+
+A cell renders React - often a badge, a link or a formatted string - and the
+export writes the underlying value. A currency cell showing `32 000 kr` exports
+`32000`. Format in the data, or post-process the matrix from `buildCellMatrix`,
+if the file must match the screen.
+
+Source: `src/docs/cell-selection.md` (The CSV).
+
+### MEDIUM Expecting headers in the clipboard
+
+Ctrl+C copies values only, matching Excel's own copy. Headers are an option of
+the export menu and of `cellExport`, not of the clipboard path.
+
+Source: `src/docs/cell-selection.md` (Copy and export).
+
+## Reference
+
+| Name | Kind | Type | Default | What it does |
+| --- | --- | --- | --- | --- |
+| `cellSelection` | Option | `"none" \| "single" \| "range"` | `"none"`, or `"single"` under `editMode` | Turns the cursor, and the rectangle, on. |
+| `onFocusedCellChange` | Callback | `(cell \| null) => void` | – | Follows the cursor. |
+| `cellExport` | Table prop | `TMDataGridCellExportOptions` | Nordic Excel | Separator, decimal mark, headers, file name. |
+| `ui.state.focusedCell` | UI state | `{ rowId, columnId } \| null` | `null` | The cursor. |
+| `ui.state.cellRange` | UI state | `{ anchor, focus } \| null` | `null` | The rectangle's two corners. |
+| `ui.actions.setFocusedCell` · `setCellRange` | UI actions | – | – | Move either from your own code. |
+| `useCellControlTabIndex` | Hook | `() => 0 \| -1` | – | The tab index a control inside a body cell wants. |
+| `exportGridToCsv` | Export | `({ table, options? }) => void` | – | Downloads every filtered row as CSV. |
+| `buildGridCellMatrix` · `buildCellMatrix` | Exports | – | – | The value matrix behind the file, for post-processing. |
+| `toClipboardText` · `toExcelCsv` · `writeClipboardText` · `downloadTextFile` | Exports | – | – | The pieces behind Ctrl+C and the file. |
+| `formatExportValue` | Export | `(value, options) => string` | – | One value, formatted as the export would. |
+| `DEFAULT_CELL_EXPORT_OPTIONS` | Export | object | – | The Nordic Excel defaults, to spread over. |
+| `isSameCell` · `resolveCellMove` | Exports | – | – | The cursor arithmetic, for a custom navigator. |
+| `resolveRangeBounds` · `isWithinBounds` · `boundsEdges` · `boundsCellCount` | Exports | – | – | The rectangle arithmetic. |
+| `data-focused` | Data attribute | – | – | On the focused cell. |
+| `data-edge-top` · `-bottom` · `-left` · `-right` | Data attributes | – | – | On cells at the rectangle's border. |
+
+See also: the `editing` skill, which turns this on implicitly and takes over
+Enter and F2, and the `rows` skill for `rowContextMenu`, whose items are
+appended below the copy and export ones.