@jielga/tmdatagrid 2.2.0 → 2.3.0

package/skills/options/SKILL.md

@@ -9,16 +9,16 @@ description: >
   labels, editing, filters, exportOptions, enableColumnOrdering,
   enablePagination, resetPageOnQueryChange, enableRowNumbers, selectionMode,
   showSelectedBackground, cellSelection, renderDetails, overscan,
-  quickSearchMode), persist with dataKey/settingsKey slices and storageMode, the
-  returned api (table, ui, edit, features, labels, resetSettings, scrollToRow),
-  ui actions, and reading grid state with useSelector over table.store, since
-  table.getState() does not exist in v9. Load when configuring the hook, looking
-  up an option's default, persisting layout or filters, or reacting to grid
-  state from a parent.
+  quickSearchMode), persist with dataKey/settingsKey slices, storageMode and
+  urlKey deep links, the returned api (table, ui, edit, features, labels,
+  resetSettings, scrollToRow), ui actions, and reading grid state with
+  useSelector over table.store, since table.getState() does not exist in v9.
+  Load when configuring the hook, looking up an option's default, persisting
+  layout or filters, or reacting to grid state from a parent.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/use-tm-data-grid.md'
   - 'Jielga/react:packages/tmdatagrid/docs/persistence.md'
@@ -160,14 +160,17 @@ const grid = useTMDataGrid({
 ## persist
 
 Restores table state on mount and writes it back on every change. State is split
-across two keys because the groups have different lifetimes: column configuration
-stays valid indefinitely, while filters and pagination go stale as the data
-changes. Separate keys let one group be cleared without touching the other.
+across three keys because the groups have different lifetimes: column configuration
+stays valid indefinitely, filters and pagination go stale as the data
+changes, and a deep link has to travel with the page URL. Separate keys let one
+group be cleared without touching the others.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `dataKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
 | `settingsKey` | `TMDataGridPersistKey<TMDataGridSettingsSlice>`: `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `urlKey` | `TMDataGridPersistKey<TMDataGridDataSlice>`: `string \| [string, DataSlice[]]` | – | Search param for data slices kept in the URL. See [Deep links](#deep-links). |
+| `urlStorage` | `TMDataGridUrlStorage`: `{ get(name): string \| null; set(name, value: string \| null): void }` | `location.search` and `history.replaceState` | Reads and writes the URL param. |
 | `storageMode` | `TMDataGridStorageMode`: `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. `"sessionStorage"` is per tab. |
 | `serialize` | `(value) => string` | `JSON.stringify` | Serializes before storing. |
 | `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
@@ -203,6 +206,7 @@ const persist = {
 | Group | Available slices |
 | --- | --- |
 | `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination`, `expanded` |
+| `urlKey` | The data slices. A slice listed here is taken out of `dataKey`. |
 | `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning`, `grouping` |
 
 `grouping` is a settings slice because it names columns rather than values, so it
@@ -227,6 +231,73 @@ dropped.
 
 Source: `packages/tmdatagrid/docs/persistence.md` (Behaviour).
 
+### Deep links
+
+`urlKey` keeps data slices in one URL search param, so a link to the page opens
+the grid on the same filters. The string is the param name; a bare key takes
+every data slice, a tuple a subset, as with `dataKey`.
+
+```tsx
+const persist = {
+  settingsKey: "employees.settings",
+  // Sorting is remembered per browser; the filters travel in the link.
+  dataKey: ["employees.data", ["sorting"]],
+  urlKey: ["employees", ["columnFilters", "globalFilter"]],
+} satisfies TMDataGridPersistence;
+```
+
+- A slice lives in one group. A slice listed under `urlKey` is taken out of
+  `dataKey`: a bare `dataKey` hands it over silently, while a `dataKey` tuple
+  that names the slice explicitly is reported with `console.error` on mount.
+- The param carries only the slices whose value differs from the initial state
+  (`initialState` merged over the grid defaults), and only the column filters
+  that are active. When nothing differs, the param is removed. A link without the param, or without a slice, opens on the
+  initial state; a URL slice never falls back to storage.
+- Writes use `history.replaceState`, never `pushState`. Only the grid's own
+  param changes; the path, the hash, other params and `history.state` are kept.
+  Two grids on one page use two keys.
+- The URL payload has no version stamp, so a bookmarked link survives a
+  release. The shape guards and the realignment against existing columns apply
+  as for storage, and `serialize` / `deserialize` apply to the URL payload too.
+- `meta.filter.url: false` on a column keeps its filter out of the param, on
+  read and on write. The column's filter is then not persisted anywhere, and a
+  filter on it in `initialState` still applies when a link is opened. The
+  flag has no effect unless `urlKey` carries `columnFilters`.
+- `urlStorage` replaces the default read and write of the param, for a router
+  that owns the URL. `get` returns the param's string or `null`; `set` receives
+  the string, or `null` to remove the param. `set` is only called when the
+  value changed. Keep `persist` referentially stable here too: react-router
+  rebuilds `setSearchParams` on every URL change, so read it through a ref.
+
+```tsx
+// react-router: let the router do the replace.
+const [, setSearchParams] = useSearchParams();
+const setSearchParamsRef = useRef(setSearchParams);
+setSearchParamsRef.current = setSearchParams;
+
+const persist = useMemo(
+  () =>
+    ({
+      urlKey: ["employees", ["columnFilters"]],
+      urlStorage: {
+        get: (name) => new URLSearchParams(window.location.search).get(name),
+        set: (name, value) =>
+          setSearchParamsRef.current(
+            (prev) => {
+              if (value === null) prev.delete(name);
+              else prev.set(name, value);
+              return prev;
+            },
+            { replace: true },
+          ),
+      },
+    }) satisfies TMDataGridPersistence,
+  [],
+);
+```
+
+Source: `packages/tmdatagrid/docs/persistence.md` (Deep links).
+
 ## Return value
 
 | Field | Type | Description |

package/skills/rows/SKILL.md

@@ -8,16 +8,16 @@ description: >
   reading a selection through the table store, onRowClick / onCellClick /
   onCellDoubleClick / onCellContextMenu, the renderRowContextMenu slot with its
   internalItems handback, renderColumnMenuItems and rowContextMenuProps, per-row
-  styling with rowStyle, rowClassName, striped and the --row-bg rule, the row
-  details panel through renderDetails, detailsColumnPosition and
-  DETAILS_COLUMN_ID, row pinning with enableRowPinning and row.pin, and the
-  row-number gutter through enableRowNumbers. Load when selecting rows, reacting
-  to a click, opening a detail panel, colouring rows by their data, pinning rows
-  to an edge, or numbering them.
+  styling with rowStyle, rowClassName, striped, highlightOnHover and the
+  --row-bg rule, the row details panel through renderDetails,
+  detailsColumnPosition and DETAILS_COLUMN_ID, row pinning with enableRowPinning
+  and row.pin, and the row-number gutter through enableRowNumbers. Load when
+  selecting rows, reacting to a click, opening a detail panel, colouring rows by
+  their data, pinning rows to an edge, or numbering them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/react:packages/tmdatagrid/docs/row-interaction.md'
@@ -213,8 +213,15 @@ them and they stop showing. `striped` follows position in the view, so it
 survives sorting and filtering rather than sticking to records, and pinned rows
 are not striped.
 
+The hover tint follows the gestures a row answers: a row takes it under
+`selectionMode: "row"` or a highlight mode, `onRowClick` or
+`renderRowContextMenu`, and a group row never does. A grid with none of those
+shows no hover tint. `highlightOnHover` on the Table overrides that: `true`
+tints every row, `false` none.
+
 Rows carry `data-selected`, `data-selected-bg`, `data-highlighted`,
-`data-grouped`, `data-depth`, `data-context-menu` and `data-row-id`, so a
+`data-grouped`, `data-depth`, `data-context-menu`, `data-highlight-on-hover`
+and `data-row-id`, so a
 stylesheet can target any of it without a callback. The boolean attributes are
 present, with the value `"true"`, only while they apply - `data-grouped` only
 on group rows - so `[data-grouped]` and `[data-grouped="true"]` are
@@ -247,7 +254,9 @@ Which rows are open is TanStack's own `expanded` state, so anything can open
 one - `row.toggleExpanded()` from a menu item, `initialState.expanded`,
 `table.toggleAllRowsExpanded()` - and it persists as a `data` slice. The panel
 is a cell spanning the row, not a row: `aria-rowcount` still counts records, and
-a click inside it does not select the row underneath. Group rows have no panel;
+a click inside it does not select the row underneath. It has no padding: content
+fills the row edge to edge, and content that should line up with the cell text
+pads itself with `padding: var(--dg-padding)`. Group rows have no panel;
 expanding one opens its children.
 
 Rows are virtualized. A row that leaves the viewport and the `overscan`

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/server-side.md'
   - 'Jielga/react:packages/tmdatagrid/docs/server-query.md'

package/skills/testing/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:playwright/support/DataGrid.ts'

package/skills/testing-components/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/test/gallery/main.tsx'

package/skills/testing-editing/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.2.0'
+  library_version: '2.3.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'

package/src/components/TMDataGridFilterPills.module.css

@@ -13,13 +13,15 @@
    shape readable against any surface. Scoped through `.filterPills` for the
    specificity to beat Mantine's own rule whichever stylesheet loads last. */
 .filterPills .pill {
-  background-color: light-dark(
-    var(--mantine-color-gray-1),
-    var(--mantine-color-dark-5)
-  );
-  color: light-dark(var(--mantine-color-black), var(--mantine-color-dark-0));
-  border: 1px solid
-    light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-3));
+  background-color: var(--mantine-color-gray-1);
+  color: var(--mantine-color-black);
+  border: 1px solid var(--mantine-color-gray-3);
+}
+
+:where([data-mantine-color-scheme="dark"]) .filterPills .pill {
+  background-color: var(--mantine-color-dark-5);
+  color: var(--mantine-color-dark-0);
+  border-color: var(--mantine-color-dark-3);
 }
 
 /* The label is a button so a pill can be clicked back open, but it must read as

package/src/components/TMDataGridTable.module.css

@@ -84,7 +84,13 @@
   --row-bg: var(--dg-row-new-bg, var(--mantine-color-body));
 }
 
-.bodyRow:hover {
+/* The hover tint, on the rows that carry `data-highlight-on-hover` - by default
+   the rows that answer a click or a right-click, see the Table's
+   `highlightOnHover`. `:where()` adds no specificity, so the rule stays at the
+   weight of the state rules around it: declared after the stripe and the entry
+   tint, which it wins, and before the selection and highlight rules, which win
+   over it. */
+.bodyRow:where([data-highlight-on-hover="true"]):hover {
   --row-bg: var(--mantine-color-default-hover);
 }
 
@@ -320,7 +326,9 @@
   /* Base and tint, exactly as .bodyCell paints them. */
   background-color: var(--mantine-color-body);
   background-image: linear-gradient(var(--row-bg), var(--row-bg));
-  padding: var(--dg-padding);
+  /* No padding: the panel is the user's content, and a nested grid or a tab
+     strip wants the full width. Content that should line up with the cell
+     text pads itself with var(--dg-padding). */
   /* The row above may be the selection control, which turns text selection off
      for everything inside it. A panel is content, so it takes both back. */
   user-select: text;
@@ -477,14 +485,15 @@
    the browser's default so the colour is the grid's to state - override with
    `--dg-match-highlight-bg` on the grid. */
 .matchHighlight {
-  background-color: var(
-    --dg-match-highlight-bg,
-    light-dark(var(--mantine-color-yellow-2), rgba(250, 176, 5, 0.35))
-  );
+  background-color: var(--dg-match-highlight-bg, var(--mantine-color-yellow-2));
   color: inherit;
   border-radius: 2px;
 }
 
+:where([data-mantine-color-scheme="dark"]) .matchHighlight {
+  background-color: var(--dg-match-highlight-bg, rgba(250, 176, 5, 0.35));
+}
+
 /* The summary row - one sticky row of column footers along the bottom edge,
    rendered only while at least one column defines `footer`. Same subgrid
    placement as the header, so its cells sit exactly on the body's tracks.

package/src/components/TMDataGridTable.tsx

@@ -90,7 +90,7 @@ import {
   resolveRowSelectionClick,
 } from "../core/rowSelection";
 import { readPinnedRows } from "../core/rowPinning";
-import { isFilterActive, isTMDataGridFilterValue } from "../core/filterOperators";
+import { filterNarrowsRows } from "../core/filterOperators";
 import { buildMatchNeedles, findMatchRanges } from "../core/matchHighlight";
 import { ROW_NUMBER_COLUMN_ID } from "./TMDataGridRowNumberColumn";
 import { SearchIcon } from "./icons";
@@ -631,6 +631,14 @@ export type TMDataGridTableProps<TData extends RowData> = {
    * stay put while the virtualizer mounts and unmounts rows.
    */
   striped?: boolean;
+  /**
+   * Whether a body row takes the hover tint under the pointer. Unset, a row
+   * takes it when the row itself answers a gesture: `selectionMode: "row"`,
+   * a highlight mode, `onRowClick` or `renderRowContextMenu`. Group rows sit
+   * out those gestures and so sit out the tint too. `true` tints every row,
+   * `false` none. The row carries `data-highlight-on-hover` while it applies.
+   */
+  highlightOnHover?: boolean;
   /**
    * Called when the scroll *arrives* at an edge - once per arrival, not per
    * scroll event, and not on mount (the grid starts at the top-left edge).
@@ -751,6 +759,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   rowClassName,
   rowStyle,
   striped = false,
+  highlightOnHover,
   onScrollToTop,
   onScrollToBottom,
   onScrollToLeft,
@@ -1480,18 +1489,12 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   const isEmpty = rows.length === 0 && pinnedRowCount === 0;
   // Which emptiness this is. A column filter counts by the rule the pills, the
   // header indicator and the page reset use, so the grid has one definition
-  // of "active": an envelope counts once `isFilterActive` says so - the
-  // half-typed `{ operator, value: "" }` the filter panel seeds filters
-  // nothing - and a value that is not an envelope always counts, since a raw
-  // value written by consumer code narrows the rows as far as the grid can
-  // tell. The body already subscribes to the whole table store, so these
-  // reads are reactive.
+  // of "active" - see `filterNarrowsRows`. The half-typed
+  // `{ operator, value: "" }` the filter panel seeds filters nothing. The body
+  // already subscribes to the whole table store, so these reads are reactive.
   const emptyGlobalFilter = table.store.state.globalFilter;
   const hasActiveFilters =
-    table.store.state.columnFilters.some(
-      (entry) =>
-        !isTMDataGridFilterValue(entry.value) || isFilterActive(entry.value),
-    ) ||
+    table.store.state.columnFilters.some(filterNarrowsRows) ||
     (typeof emptyGlobalFilter === "string"
       ? emptyGlobalFilter.trim() !== ""
       : emptyGlobalFilter != null);
@@ -2833,6 +2836,14 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
               ) => {
               const isGroupRow = row.getIsGrouped();
               const isInteractive = rowGesturesFor(row);
+              // The hover tint promises that the row answers the pointer, so
+              // by default it follows the gestures the row takes: the ones
+              // behind `isInteractive`, and the context menu - which a group
+              // row sits out as well, see the row's onContextMenu below.
+              const highlightsOnHover =
+                highlightOnHover ??
+                (isInteractive ||
+                  (renderRowContextMenu !== undefined && !isGroupRow));
               const rowCells = [
                 ...row.getStartVisibleCells(),
                 ...row.getCenterVisibleCells(),
@@ -2940,6 +2951,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                   data-selects-on-click={
                     (selectsOnRowClick && !isGroupRow) || undefined
                   }
+                  data-highlight-on-hover={highlightsOnHover || undefined}
                   aria-selected={
                     features.rowSelection ? row.getIsSelected() : undefined
                   }

package/src/components/sticky.module.css

@@ -5,9 +5,11 @@
    A box-shadow is drawn per cell, and its blur fades in at each cell's own top
    and bottom edge - stacked down a column that reads as banding at every row
    seam. Instead: a gradient pseudo element pinned to `top: 0; bottom: 0` so
-   consecutive cells butt together into one unbroken band. Mantine sets
-   `color-scheme` on the root, so light-dark() resolves without a second
-   selector.
+   consecutive cells butt together into one unbroken band.
+
+   The dark scheme is a second rule under Mantine's `data-mantine-color-scheme`
+   attribute, not the `light-dark` function: scripts/package-stylesheets.test.mjs
+   says why.
 
    No border. A 1px line the colour of the grid's own borders drew a hard rule
    between the pinned lanes and the data, so the pinned columns read as a
@@ -31,8 +33,8 @@
   left: 100%;
   background: linear-gradient(
     to right,
-    light-dark(rgba(0, 0, 0, 0.07), rgba(0, 0, 0, 0.26)),
-    light-dark(rgba(0, 0, 0, 0.025), rgba(0, 0, 0, 0.09)) 45%,
+    rgba(0, 0, 0, 0.07),
+    rgba(0, 0, 0, 0.025) 45%,
     transparent
   );
 }
@@ -41,8 +43,26 @@
   right: 100%;
   background: linear-gradient(
     to left,
-    light-dark(rgba(0, 0, 0, 0.07), rgba(0, 0, 0, 0.26)),
-    light-dark(rgba(0, 0, 0, 0.025), rgba(0, 0, 0, 0.09)) 45%,
+    rgba(0, 0, 0, 0.07),
+    rgba(0, 0, 0, 0.025) 45%,
+    transparent
+  );
+}
+
+:where([data-mantine-color-scheme="dark"]) .stickyLeft::after {
+  background: linear-gradient(
+    to right,
+    rgba(0, 0, 0, 0.26),
+    rgba(0, 0, 0, 0.09) 45%,
+    transparent
+  );
+}
+
+:where([data-mantine-color-scheme="dark"]) .stickyRight::after {
+  background: linear-gradient(
+    to left,
+    rgba(0, 0, 0, 0.26),
+    rgba(0, 0, 0, 0.09) 45%,
     transparent
   );
 }

package/src/core/filterControls.ts

@@ -106,4 +106,12 @@ export type TMDataGridColumnFilterOptions = {
    * See {@link TMDataGridFilterControlComponent}.
    */
   control?: TMDataGridFilterControlComponent;
+  /**
+   * Whether this column's filter goes into the `persist.urlKey` search param.
+   * Defaults to `true`. `false` keeps it out of the param, on read and on
+   * write. Only has an effect when `urlKey` carries `columnFilters`, and since such
+   * a slice is not stored under `dataKey` either, the filter is then not
+   * persisted anywhere.
+   */
+  url?: boolean;
 };

package/src/core/filterOperators.ts

@@ -251,6 +251,19 @@ export function isFilterActive(value: unknown): boolean {
     : typeof value.value === "string" && value.value.trim() !== "";
 }
 
+/**
+ * Whether one `columnFilters` entry narrows the rows, by the one rule the grid
+ * uses for "active": an envelope counts once {@link isFilterActive} says so,
+ * and a value that is not an envelope always counts, since a raw value written
+ * by consumer code narrows the rows as far as the grid can tell.
+ *
+ * @internal Shared by the empty state and the `urlKey` param; not exported
+ * from the package.
+ */
+export function filterNarrowsRows(entry: { value: unknown }): boolean {
+  return !isTMDataGridFilterValue(entry.value) || isFilterActive(entry.value);
+}
+
 /** One column's filter, typed - what `columnFilters` holds per entry. */
 export type TMDataGridColumnFilter = {
   id: string;