@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/skills/appearance/SKILL.md

@@ -5,24 +5,27 @@ description: >
   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
+  toolbar composition through children and TMDataGrid.Spacer, Mantine BoxProps
+  (mb, px, hiddenFrom) and withBottomBorder on the toolbar, 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.
+  building a toolbar, adding a button beside the built-in ones, filling the grid
+  menu (TMDataGrid.Menu, the column chooser as menu items), or translating the
+  interface.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 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'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/styling.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/toolbar.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/menu.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/localization.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/capabilities.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/labels.ts'
 ---
 
 # TMDataGrid - Appearance, toolbar and labels
@@ -118,7 +121,9 @@ element, and `TMDataGrid.Spacer` pushes what follows to the right.
   <TMDataGrid.LoadingIndicator />
   <ExportButton />
   <TMDataGrid.FilterButton />
-  <TMDataGrid.ColumnsButton />
+  <TMDataGrid.Menu>
+    <TMDataGrid.Menu.Columns />
+  </TMDataGrid.Menu>
 </TMDataGrid.Toolbar>
 ```
 
@@ -126,12 +131,60 @@ Each built-in renders nothing when its feature is off, so a read-only grid needs
 no conditionals: `FilterButton` under `enableColumnFilters: false` renders
 nothing at all.
 
+`TMDataGrid.Toolbar` and `TMDataGrid.Spacer` take Mantine's `BoxProps` - the
+style props (`mb`, `px`, `h`, `hiddenFrom`), `className`, `style` and `mod` -
+set on the element itself. `withBottomBorder` on the toolbar draws a 1px line in
+the theme's default border colour under it, the same line the header draws;
+default `false`. `TMDataGrid.Footer`, `FilterPanel`, `FilterPills` and
+`ColumnsPanel` take the same `BoxProps` on top of their own props.
+
+```tsx
+<TMDataGrid.Toolbar withBottomBorder px="sm" mb="xs">
+  <TMDataGrid.SummaryCount />
+  <TMDataGrid.Spacer hiddenFrom="sm" />
+  <TMDataGrid.FilterButton />
+</TMDataGrid.Toolbar>
+```
+
+### The grid menu
+
+`TMDataGrid.Menu` is the burger: a Mantine `Menu` whose children are the
+dropdown, so your own `Menu.Item`s sit beside the built-in items. It takes
+Mantine `MenuProps` (defaults `position="bottom-end"`, `shadow="md"`,
+`width={260}`, `withinPortal`), `icon` and `label` (default `labels.menuButton`).
+
+```tsx
+import { Menu } from "@mantine/core";
+
+<TMDataGrid.Menu>
+  <Menu.Item onClick={exportReport}>Export report</Menu.Item>
+  <Menu.Divider />
+  <Menu.Label>Columns</Menu.Label>
+  <TMDataGrid.Menu.Columns />
+</TMDataGrid.Menu>
+```
+
+`TMDataGrid.Menu.Columns` is the column chooser as menu items: `Menu.Search`,
+one checkbox item per hideable column, show/hide all and reset layout;
+it renders nothing when no column can be hidden. Its pieces
+`TMDataGrid.Menu.ColumnToggles` (`search` narrows the list),
+`.ShowHideAll` and `.ResetLayout` are exported for menus that want only some of
+them. Every piece needs a Mantine `Menu` around it and reads the grid from
+context, so it works in any Mantine menu rendered inside `TMDataGrid`, and in a
+`Menu.Sub` (pass `searchable={false}` there: `Menu.Search` registers on the
+root menu and switches off its type-ahead and arrow keys).
+
+The menu always renders, since it cannot see what its children render; a menu
+holding only `Menu.Columns` should be hidden with `canHideAny` under
+`enableHiding: false`. `TMDataGrid.ColumnsPanel` is the same chooser as plain
+controls, for a Popover, a Drawer or an inline layout.
+
 A button of your own reads the grid from context, which returns
 `{ table, ui, features, labels, controlSize, resetSettings }`:
 
 ```tsx
 import {
-  exportGridToCsv,
+  exportGrid,
   getGridCapabilities,
   useTMDataGridContext,
 } from "@jielga/tmdatagrid";
@@ -143,7 +196,7 @@ function ExportButton() {
   if (!canFilterAny) return null;
 
   return (
-    <Button size={controlSize} onClick={() => exportGridToCsv({ table })}>
+    <Button size={controlSize} onClick={() => void exportGrid({ table })}>
       Export
     </Button>
   );
@@ -206,7 +259,7 @@ own uses the same strings as the built-in parts.
 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).
+Source: `packages/tmdatagrid/docs/styling.md` (The stylesheet).
 
 ### CRITICAL A grid with no bounded height
 
@@ -226,7 +279,7 @@ Correct:
 <TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }} />
 ```
 
-Source: `src/docs/styling.md` (Layout).
+Source: `packages/tmdatagrid/docs/styling.md` (Layout).
 
 ### HIGH Setting `--dg-row-height` to change density
 
@@ -241,7 +294,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
 ```
 
-Source: `src/docs/styling.md` (The size scale).
+Source: `packages/tmdatagrid/docs/styling.md` (The size scale).
 
 ### HIGH A capability check without `features`
 
@@ -264,7 +317,7 @@ const { canSort } = getColumnCapabilities(column, features);
 if (!canSort) return null;
 ```
 
-Source: `src/docs/toolbar.md` (Why `features` is a second argument).
+Source: `packages/tmdatagrid/docs/toolbar.md` (Why `features` is a second argument).
 
 ### MEDIUM An inline `labels` object
 
@@ -286,7 +339,7 @@ const labels = { noResults: "Inga träffar" } satisfies TMDataGridLabelsOverride
 useTMDataGrid({ data, columns, labels });
 ```
 
-Source: `src/docs/localization.md` (Keep the object stable).
+Source: `packages/tmdatagrid/docs/localization.md` (Keep the object stable).
 
 ### MEDIUM Conditionally rendering built-in toolbar parts
 
@@ -294,7 +347,7 @@ 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).
+Source: `packages/tmdatagrid/docs/toolbar.md` (The built-in parts).
 
 ## Reference
 
@@ -306,7 +359,7 @@ Source: `src/docs/toolbar.md` (The built-in parts).
 | `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. |
+| `TMDataGrid.Toolbar` · `Spacer` | Components | `children`, `withBottomBorder`, Mantine `BoxProps` | `withBottomBorder: false` | The flex row, and the push-right. Style props set on the element. |
 | `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. |

package/skills/cell-selection/SKILL.md

@@ -1,25 +1,25 @@
 ---
 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 the in-row Tab walk over 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.
+  Cell cursor, ranges and the clipboard 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 the in-row Tab walk over controls inside cells, the
+  role flip from table/cell to grid/gridcell, ui.state.focusedCell and
+  ui.state.cellRange keyed by id, onFocusedCellChange, and the Copy / Export
+  cells / Include headers context menu that writes the rectangle in the grid's
+  exportOptions format. Load when adding keyboard cell navigation, selecting
+  blocks of cells, copying to a spreadsheet, or when Tab walks through controls
+  inside the grid body. Exporting whole rows is the data skill.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 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'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/cell-selection.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/cellNavigation.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/cellRange.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/export.ts'
 ---
 
 # TMDataGrid - Cell selection
@@ -115,31 +115,33 @@ 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
+Right-clicking inside the selection opens Copy, "Export cells" and an
 "Include headers" toggle. A right-click outside it moves the selection there
 first, the way a spreadsheet does. Your own `renderRowContextMenu` 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 opens straight into columns with å ä ö intact.
+"Export cells" writes the rectangle in the grid's export format - by default a
+CSV for a Nordic Excel: a `sep=;` first line, a UTF-8 BOM, CRLF endings,
+semicolons between fields and a comma as the decimal mark. The format, the file
+name and the header row are the grid's `exportOptions`:
 
 ```tsx
-<TMDataGrid.Table
-  cellExport={{ separator: ",", decimalComma: false, fileName: "employees" }}
-/>
+const grid = useTMDataGrid({
+  data,
+  columns,
+  cellSelection: "range",
+  exportOptions: { format: csvFormat(), 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.
+What gets written is the cell's **value**, not what it renders, for the file and
+for Ctrl+C alike; `meta.exportValue` substitutes a value and
+`meta.enableExport: false` drops a column from both. Ctrl+C writes numbers with
+the format's decimal mark, so what is pasted matches what is exported.
 
-`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>
-```
+Exporting every filtered row rather than the rectangle is
+`TMDataGrid.Menu.Export`, `TMDataGrid.Menu.ExportSelected` and
+`useTMDataGridExport`, covered by the data skill.
 
 ## Common mistakes
 
@@ -166,7 +168,7 @@ Correct:
 const OpenButton = ({ row }) => <Button onClick={() => open(row.id)}>Open</Button>;
 ```
 
-Source: `src/docs/cell-selection.md` (One tab stop).
+Source: `packages/tmdatagrid/docs/cell-selection.md` (One tab stop).
 
 ### HIGH Selectors written for `table` / `cell` roles
 
@@ -174,7 +176,7 @@ 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 `editing` turns it on implicitly.
 
-Source: `src/docs/cell-selection.md`, and the `testing` skill.
+Source: `packages/tmdatagrid/docs/cell-selection.md`, and the `testing` skill.
 
 ### HIGH Reading the selection as row and column indices
 
@@ -189,41 +191,40 @@ const row = grid.table.getRow(focusedCell.rowId);
 const value = row.getValue(focusedCell.columnId);
 ```
 
-Source: `src/docs/cell-selection.md` (Where the selection lives).
+Source: `packages/tmdatagrid/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.
+`32000`. Set `meta.exportValue` on the column, or post-process the data from
+`buildExportData`, if the file must match the screen.
 
-Source: `src/docs/cell-selection.md` (The CSV).
+Source: `packages/tmdatagrid/docs/cell-selection.md` (The file).
 
 ### 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.
+the export menu and of `exportOptions`, not of the clipboard path.
 
-Source: `src/docs/cell-selection.md` (Copy and export).
+Source: `packages/tmdatagrid/docs/cell-selection.md` (Copy and export).
 
 ## Reference
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `cellSelection` | Option | `"none" \| "single" \| "range"` | `"none"`, or `"single"` under `editing` | Turns the cursor, and the rectangle, on. |
+| `cellSelection` | Option | `TMDataGridCellSelectionMode`: `"none" \| "single" \| "range"` | `"none"`, or `"single"` under `editing` | 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. |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row of the Export cells item. |
 | `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. |
-| `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. |
+| `buildExportData` | Export | `({ table, rows, bounds }) => TMDataGridExportData` | – | The rectangle's values, with `bounds`; the whole grid without. |
+| `toClipboardText` · `writeClipboardText` | Exports | `(data, options?) => string` · `(text) => Promise<boolean>` | – | The pieces behind Ctrl+C: the tab-separated text, and the write that reports whether it landed. |
+| `TMDataGridClipboardTextOptions` | Type | `{ decimalComma?, escapeFormulas? }` | `true` · `true` | The options of `toClipboardText`. |
+| `formatExportValue` | Export | `(value, options) => string` | – | One value, formatted as the text formats would. |
+| `resolveRangeBounds` | Export | `({ range, rowIndexOf, columnIndexOf }) => TMDataGridRangeBounds \| null` | – | The range as row and column indices - the `bounds` for `buildExportData`, over `getDisplayedRows`. |
+| `ResolveRangeBoundsArgs` · `TMDataGridRangeBounds` | Types | – · `{ top, bottom, left, right }` | – | What `resolveRangeBounds` takes, and what it returns. |
 | `data-focused` | Data attribute | – | – | On the focused cell. |
 | `data-edge-top` · `-bottom` · `-left` · `-right` | Data attributes | – | – | On cells at the rectangle's border. |