@jielga/tmdatagrid 2.3.0 → 2.4.0

package/skills/options/references/typed-links.md

@@ -0,0 +1,134 @@
+# Typed links
+
+Reference for the `options` skill: `createTMDataGridUrlState`, what a link
+may name, the definition's members, and the TanStack Router setup.
+
+`createTMDataGridUrlState({ key, columns, slices? })` defines a grid's deep
+links from its columns. `columns` is the array the grid renders, built with
+`createTMDataGridColumnHelper`; each helper column carries its id, `meta.type`,
+value type, `meta.filter.operators` and its `enableColumnFilter`,
+`enableSorting` and `meta.filter.url` switches in its type only
+(`TMDataGridColumnInfo`, read with `TMDataGridColumnInfoOf`; the brand type is
+`TMDataGridTypedColumn`).
+
+```tsx
+const columns = columnHelper.columns([
+  columnHelper.accessor("department", { header: "Department", meta: { type: "select" } }),
+  columnHelper.accessor("salary", { header: "Salary", meta: { type: "number" } }),
+  columnHelper.accessor("email", { header: "Email", enableColumnFilter: false }),
+]);
+
+export const employeesUrl = createTMDataGridUrlState({
+  key: "employees",
+  columns,
+  slices: ["columnFilters", "sorting"],
+});
+
+const persist = { urlKey: employeesUrl.urlKey } satisfies TMDataGridPersistence;
+
+const href = `/employees?${employeesUrl.searchParams({
+  filters: { department: { operator: "isAnyOf", value: ["Design"] } },
+  sorting: [{ id: "salary", desc: true }],
+})}`;
+```
+
+What a link may name (`TMDataGridUrlInput`); anything else is a type error:
+
+- `filters` (`TMDataGridUrlFiltersInput`): only columns whose
+  `enableColumnFilter` is not `false` and `meta.filter.url` is not `false`.
+  With no such column, `filters` accepts no key at all.
+- The operator: one the column's `meta.type` offers, narrowed by
+  `meta.filter.operators`.
+- The value: a `number` for a number column (`between` takes
+  `[number | null, number | null]`, `null` leaving that end open); a `Date` or a
+  `YYYY-MM-DD` string for a date column (`TMDataGridDateInput`; a `Date` is
+  written as its local calendar day, a longer string is cut to 10 characters);
+  a `boolean` for a boolean column; a `string` for a string column; an array of
+  the column's own values (the element type for an array value) for `isAnyOf` /
+  `isNoneOf`; no `value` for `isEmpty` / `isNotEmpty`.
+- `sorting` (`TMDataGridUrlSortableId`): only columns whose `enableSorting` is
+  not `false`. `desc` defaults to `false`.
+- `globalFilter` and `pagination` (`{ pageIndex, pageSize }`): only when the
+  definition carries those slices. `slices` defaults to every data slice.
+- A column with an accessor function is named by its `id`; without an `id` it
+  cannot be named. A dotted accessor key is named with underscores
+  (`address_city`).
+- Only literal values count: `enableSorting: isAdmin` reads as not sortable.
+  Columns built without the helper offer nothing. A table-level
+  `enableColumnFilters` or `enableSorting` is not seen.
+
+The definition (`TMDataGridUrlState`):
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | The URL search param. |
+| `slices` | `TMDataGridDataSlice[]` | The data slices the param carries. Default: every data slice. |
+| `urlKey` | `TMDataGridPersistKey` | For `persist.urlKey`: the key, or `[key, slices]` when `slices` is set. |
+| `searchParams(input, { serialize? })` | `URLSearchParams` | The link as search params, encoded with `serialize` (default `JSON.stringify`, as the grid's default). Empty when the input sets nothing. Pass the `serialize` given to `persist`, if any. |
+| `search(input)` | `{ [key]: TMDataGridUrlPayload \| undefined }` | The link as a router search object. |
+| `payload(input)` | `TMDataGridUrlPayload \| undefined` | The param's value in the grid's state shape (filters as `{ id, value: { operator, value } }` with string values), or `undefined` when the input sets nothing. |
+| `validateSearch(search)` | `{ [key]?: TMDataGridUrlPayload }` | A route search validator: keeps the param when it is a plain object, drops anything else. The grid checks each slice itself on read. |
+| `persist(storage?)` | `{ urlKey, urlStorage? }` | Spread into `persist`. Without `storage`, only `urlKey`, and the grid uses the browser's URL. |
+
+`persist(storage)` takes a `TMDataGridUrlSearchStorage`,
+`{ get(name): unknown; set(name, value: TMDataGridUrlPayload | undefined): void }`,
+for a router that keeps objects in its search and encodes them itself, such as
+TanStack Router. `get` returns the param's value or `undefined` (a string value
+is passed to the grid unchanged); `set` receives the payload object, or
+`undefined` to remove the param. The bridge converts with JSON, so leave
+`serialize` and `deserialize` at their defaults with it.
+
+```tsx
+// TanStack Router: the route validates, the grid writes through the router.
+const employeesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/employees",
+  validateSearch: employeesUrl.validateSearch,
+  component: EmployeesPage,
+});
+
+function EmployeesPage() {
+  const router = useRouter();
+  const persist = useMemo(
+    () =>
+      employeesUrl.persist({
+        get: (name) => (router.state.location.search as Record<string, unknown>)[name],
+        set: (name, value) =>
+          void router.navigate({
+            to: ".",
+            search: (prev: Record<string, unknown>) => ({ ...prev, [name]: value }),
+            replace: true,
+          }),
+      }),
+    [router],
+  );
+  const grid = useTMDataGrid({ data, columns, persist });
+  // ...
+}
+
+<Link
+  to="/employees"
+  search={employeesUrl.search({
+    filters: { salary: { operator: "between", value: [40_000, 60_000] } },
+  })}
+/>;
+```
+
+- A route with its own search params spreads the validator:
+  `validateSearch: (s) => ({ ...employeesUrl.validateSearch(s), tab: ... })`.
+- With `createHashHistory()` the param sits after the `#` with the rest of the
+  router's search.
+- For URLs without percent escapes, give the router `parseSearch:
+  parseSearchWith(parse)` from `jsurl2`, and a `stringifySearch` that encodes
+  each object value with JSURL2's `stringify` and joins the pairs with
+  `encodeURIComponent`. TanStack Router's own `stringifySearchWith(stringify)`
+  joins them with `URLSearchParams`, which escapes JSURL2's `(`, `)`, `~` and
+  `!` again. JSURL2's `parse` also reads JSON, so older links still open. The
+  grid is unaffected. The full `stringifySearch` is on the
+  `typed-deep-links.md` docs page.
+- The grid reads its param once, on mount. A link to the route the grid is
+  already on changes the URL but not the grid; link from another route, or
+  remount the grid on that navigation.
+
+Source: `packages/tmdatagrid/docs/persistence.md` (Typed links) and
+`packages/tmdatagrid/docs/typed-deep-links.md`.

package/skills/rows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.4.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/row-selection.md'
   - 'Jielga/react:packages/tmdatagrid/docs/row-interaction.md'

package/skills/server-side/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.3.0'
+  library_version: '2.4.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.3.0'
+  library_version: '2.4.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.3.0'
+  library_version: '2.4.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.3.0'
+  library_version: '2.4.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/testing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'

package/src/components/TMDataGridFilterPills.tsx

@@ -2,6 +2,7 @@ import { Box, type BoxProps, Button, Pill, UnstyledButton } from "@mantine/core"
 import type { RowData } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import classes from "./TMDataGridFilterPills.module.css";
+import { resolveColumnOptions } from "../core/columnOptions";
 import { getColumnLabel, getColumnType } from "../core/columnUtils";
 import {
   formatFilterLabel,
@@ -9,7 +10,12 @@ import {
   isTMDataGridFilterValue,
 } from "../core/filterOperators";
 import type { TMDataGridSize } from "../core/sizes";
-import { openColumnFilter, type TMDataGridApi } from "../useTMDataGrid";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import {
+  openColumnFilter,
+  type TMDataGridApi,
+  type TMDataGridTable,
+} from "../useTMDataGrid";
 
 /** Mantine's style props (`mb="sm"`, `hiddenFrom="sm"`) are set on the wrapper. */
 export type TMDataGridFilterPillsProps<TData extends RowData> = BoxProps & {
@@ -55,6 +61,9 @@ export function TMDataGridFilterPills<TData extends RowData>({
   ...others
 }: TMDataGridFilterPillsProps<TData>) {
   const { table, labels } = api;
+  // The options readers take the row-type-erased table, like the rest of the
+  // chrome does through context.
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
   const columnFilters = useSelector(
     table.store,
     (state) => state.columnFilters,
@@ -76,6 +85,7 @@ export function TMDataGridFilterPills<TData extends RowData>({
       <Pill.Group size={size}>
         {activeFilters.map((filter) => {
           const column = table.getColumn(filter.id);
+          const erasedColumn = erased.getColumn(filter.id);
           const label = column ? getColumnLabel(column) : filter.id;
           const value = filter.value;
           // isFilterActive already vouched for the shape; this narrows it.
@@ -125,6 +135,10 @@ export function TMDataGridFilterPills<TData extends RowData>({
                   type: column ? getColumnType(column) : "string",
                   filter: value,
                   operatorLabels: labels.operators,
+                  options: erasedColumn
+                    ? resolveColumnOptions({ table: erased, column: erasedColumn })
+                    : undefined,
+                  labels,
                 })}
               </UnstyledButton>
             </Pill>

package/src/components/TMDataGridGroupColumn.tsx

@@ -8,7 +8,8 @@ import { useSelector } from "@tanstack/react-store";
 import { shallow } from "@tanstack/store";
 import classes from "./TMDataGridGroupColumn.module.css";
 import { ChevronRightIcon } from "./icons";
-import { getColumnLabel } from "../core/columnUtils";
+import { resolveColumnOptions } from "../core/columnOptions";
+import { getColumnLabel, getColumnType } from "../core/columnUtils";
 import { formatGroupValue, getGroupDataRows } from "../core/grouping";
 import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
@@ -30,7 +31,7 @@ export function GroupCell<TData extends RowData>({
 }: {
   row: Row<TMDataGridFeatures, TData>;
 }) {
-  const { labels } = useTMDataGridContext();
+  const { table, labels } = useTMDataGridContext();
   const tabIndex = useBodyControlTabIndex();
   const expanded = useSelector(row.table.store, () => row.getIsExpanded());
 
@@ -38,7 +39,21 @@ export function GroupCell<TData extends RowData>({
   // the indent alone is what places them under their group.
   if (!row.getIsGrouped()) return null;
 
-  const label = formatGroupValue(row.groupingValue, labels.blankGroupValue);
+  // `groupingValue` is TanStack's map key, the value already turned into a
+  // string: `true` arrives as "true", a Date as its English timestamp, `null`
+  // as "null". The first record's grouping value is the value itself.
+  const columnId = row.groupingColumnId;
+  const column = columnId === undefined ? undefined : table.getColumn(columnId);
+  const dataRows = getGroupDataRows(row);
+  const value =
+    columnId === undefined || dataRows[0] === undefined
+      ? row.groupingValue
+      : dataRows[0].getGroupingValue(columnId);
+  const label = formatGroupValue(value, labels.blankGroupValue, {
+    type: column ? getColumnType(column) : undefined,
+    options: column ? resolveColumnOptions({ table, column }) : undefined,
+    labels,
+  });
 
   return (
     <UnstyledButton
@@ -68,7 +83,7 @@ export function GroupCell<TData extends RowData>({
       {/* Data rows, not direct children and not `getLeafRows()`: a nested group
           counts the records under it, never the sub-groups in between. */}
       <span className={classes.groupCount}>
-        ({getGroupDataRows(row).length})
+        ({dataRows.length})
       </span>
     </UnstyledButton>
   );

package/src/components/TMDataGridHeaderFilterRow.tsx

@@ -268,7 +268,13 @@ export function TMDataGridHeaderFilterRow({
           <div
             key={header.id}
             role="columnheader"
-            aria-label={labels.filterOn(getColumnLabel(column))}
+            // Named only where there is a filter: a generated lane or a column
+            // that does not filter holds no control to name.
+            aria-label={
+              column.getCanFilter()
+                ? labels.filterOn(getColumnLabel(column))
+                : undefined
+            }
             data-dg-part="header-filter-cell"
             data-column-id={column.id}
             data-control-column={isControlColumn(column.id) || undefined}

package/src/core/filterOperators.ts

@@ -6,6 +6,9 @@ import type {
   TableFeatures,
 } from "@tanstack/react-table";
 import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridOption } from "./columnOptions";
+import type { TMDataGridLabels } from "./labels";
+import { formatValueText } from "./valueText";
 
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -75,7 +78,7 @@ export const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string> =
   isNotEmpty: "is not empty",
 };
 
-const STRING_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const STRING_OPERATORS = [
   "contains",
   "equals",
   "notEquals",
@@ -83,9 +86,9 @@ const STRING_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "endsWith",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
-const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const NUMBER_OPERATORS = [
   "equals",
   "notEquals",
   "greaterThan",
@@ -95,12 +98,12 @@ const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "between",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 // `equals` doubles as a date's "is": it compares by calendar day whenever the
 // cell holds a Date (see matchesFilter), so a separate `is` operator would be
 // the same comparison under a second name.
-const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const DATE_OPERATORS = [
   "equals",
   "notEquals",
   "before",
@@ -110,23 +113,23 @@ const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "between",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
-const BOOLEAN_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const BOOLEAN_OPERATORS = [
   "equals",
   "notEquals",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 // One set for both select types: the operators are about membership in the
 // filter's set, which reads the same whether the cell holds one value or many.
-const SELECT_OPERATORS: readonly TMDataGridFilterOperator[] = [
+const SELECT_OPERATORS = [
   "isAnyOf",
   "isNoneOf",
   "isEmpty",
   "isNotEmpty",
-];
+] as const satisfies readonly TMDataGridFilterOperator[];
 
 /** Operators that ignore the value input (the input is disabled for these). */
 const VALUELESS_OPERATORS: readonly TMDataGridFilterOperator[] = [
@@ -143,16 +146,27 @@ const ARRAY_OPERATORS: readonly TMDataGridFilterOperator[] = [
 /** Operators whose value is a `[min, max]` pair. */
 const RANGE_OPERATORS: readonly TMDataGridFilterOperator[] = ["between"];
 
-const OPERATORS_BY_TYPE: Record<
-  TMDataGridColumnType,
-  readonly TMDataGridFilterOperator[]
-> = {
+const OPERATORS_BY_TYPE = {
   string: STRING_OPERATORS,
   number: NUMBER_OPERATORS,
   boolean: BOOLEAN_OPERATORS,
   date: DATE_OPERATORS,
   select: SELECT_OPERATORS,
   multiSelect: SELECT_OPERATORS,
+} as const satisfies Record<
+  TMDataGridColumnType,
+  readonly TMDataGridFilterOperator[]
+>;
+
+/**
+ * The operators each column type offers, as a type: the same lists the filter
+ * panel offers, so a typed link can never name an operator the panel lacks.
+ *
+ * @internal Feeds the typed links in urlState.ts; not exported from the
+ * package.
+ */
+export type OperatorsByColumnType = {
+  [TType in TMDataGridColumnType]: (typeof OPERATORS_BY_TYPE)[TType][number];
 };
 
 const DEFAULT_OPERATOR_BY_TYPE: Record<
@@ -307,30 +321,39 @@ export function activeColumnFilters<TData extends RowData>(
  *
  * The type's default operator is left implicit - "First name: Sofia" reads the
  * way a person would say it - while any other operator is spelled out, since
- * that is the part a reader cannot guess.
+ * that is the part a reader cannot guess. A value with an option reads as the
+ * option's label, and a boolean as `labels.booleanTrue` / `booleanFalse`.
  */
 export function formatFilterLabel({
   label,
   type,
   filter,
   operatorLabels = FILTER_OPERATOR_LABELS,
+  options,
+  labels,
 }: {
   label: string;
   type: TMDataGridColumnType;
   filter: TMDataGridFilterValue;
   /** Localized operator names - `labels.operators`. Defaults to English. */
   operatorLabels?: Record<TMDataGridFilterOperator, string>;
+  /** The column's options, so a value reads as its option's label. */
+  options?: ReadonlyArray<TMDataGridOption>;
+  /** What a boolean value reads as. Defaults to English. */
+  labels?: Pick<TMDataGridLabels, "booleanTrue" | "booleanFalse">;
 }): string {
   const { operator, value } = filter;
   if (!operatorNeedsValue(operator)) {
     return `${label} ${operatorLabels[operator]}`;
   }
+  const valueText = (entry: string) =>
+    formatValueText(String(entry).trim(), { type, options, labels });
   const text =
     operator === "between" && Array.isArray(value)
-      ? value.map((entry) => String(entry).trim()).join("–")
+      ? value.map(valueText).join("–")
       : Array.isArray(value)
-        ? value.join(", ")
-        : String(value).trim();
+        ? value.map(valueText).join(", ")
+        : valueText(String(value));
   if (operator === getDefaultOperator(type)) return `${label}: ${text}`;
   return `${label} ${operatorLabels[operator]} ${text}`;
 }

package/src/core/grouping.ts

@@ -1,5 +1,6 @@
 import type { Row, RowData } from "@tanstack/react-table";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { formatValueText, type TMDataGridValueTextOptions } from "./valueText";
 
 /**
  * The data rows under a group row, at any depth.
@@ -29,14 +30,21 @@ const BLANK_GROUP_LABEL = "(Blank)";
  * Deliberately not the grouped column's own `cell` renderer: that renderer is
  * written for a data row and is free to reach into `row.original`, which on a
  * group row is the first leaf's record rather than anything about the group.
+ * `options` carries what the chrome knows of the column instead - its type,
+ * its option labels and the boolean labels.
  */
 export function formatGroupValue(
   value: unknown,
   blankLabel = BLANK_GROUP_LABEL,
+  options?: TMDataGridValueTextOptions,
 ): string {
-  if (value === null || value === undefined || value === "") {
+  if (
+    value === null ||
+    value === undefined ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0)
+  ) {
     return blankLabel;
   }
-  if (value instanceof Date) return value.toLocaleDateString();
-  return String(value);
+  return formatValueText(value, options);
 }

package/src/core/labels.ts

@@ -2,6 +2,7 @@ import {
   FILTER_OPERATOR_LABELS,
   type TMDataGridFilterOperator,
 } from "./filterOperators";
+import { BOOLEAN_LABELS_EN } from "./valueText";
 
 /**
  * Every user-facing string in the grid - menu items, panels, tooltips, the
@@ -55,7 +56,7 @@ export type TMDataGridLabels = {
   filterTo: string;
   /** `DgTriStateFilter`'s no-filter segment. */
   filterAll: string;
-  /** What a boolean column's `true` reads as - its filter choice and cell text. */
+  /** What a boolean `true` reads as - its filter choice, filter pill and group row. */
   booleanTrue: string;
   booleanFalse: string;
   addFilter: string;
@@ -225,8 +226,8 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   filterFrom: "From",
   filterTo: "To",
   filterAll: "All",
-  booleanTrue: "Yes",
-  booleanFalse: "No",
+  booleanTrue: BOOLEAN_LABELS_EN.booleanTrue,
+  booleanFalse: BOOLEAN_LABELS_EN.booleanFalse,
   addFilter: "Add filter",
   clearAllFilters: "Clear all",
   closeFilters: "Close filters",

package/src/core/persistence.ts

@@ -515,7 +515,15 @@ export function collectUrlExcludedColumnIds(
   return into;
 }
 
-function forEachLeafColumnDef(
+/**
+ * Visits every leaf column definition under `defs` with the id TanStack gives
+ * it: `id`, else the `accessorKey` with dots replaced by underscores, else a
+ * string `header`.
+ *
+ * @internal Shared by persistence and the typed links in urlState.ts; not
+ * exported from the package.
+ */
+export function forEachLeafColumnDef(
   defs: ReadonlyArray<unknown>,
   visit: (id: string, record: Record<string, unknown>) => void,
 ): void {