@jielga/tmdatagrid 0.5.0 → 1.0.0

package/src/tmdatagrid/core/filterControls.ts

@@ -0,0 +1,45 @@
+import type { Column } from "@tanstack/react-table";
+import type { ComponentType } from "react";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridOption } from "./columnOptions";
+import type { TMDataGridFilterOperator } from "./filterOperators";
+import type { TMDataGridLabels } from "./labels";
+import type { TMDataGridSize } from "./sizes";
+
+/**
+ * What a filter control is handed — the value slot of one filter-panel row.
+ *
+ * The contract is value-only: the control reads `operator` to shape itself
+ * (a `between` pair renders two ends, an `equals` a single input) and calls
+ * `onChange` with the bare value; the grid composes the operator-aware
+ * `TMDataGridFilterValue` around it. A control never builds that wrapper and
+ * never writes the operator — `table` is the escape hatch for the rare
+ * control that must.
+ */
+export type TMDataGridFilterControlArgs = {
+  column: Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+  table: TMDataGridTable<TMDataGridRowData>;
+  /** The row's currently selected operator. Read-only for the control. */
+  operator: TMDataGridFilterOperator;
+  /** The bare filter value — never the `{ operator, value }` wrapper. */
+  value: string | ReadonlyArray<string>;
+  /** Writes the bare value; the grid pairs it with the current operator. */
+  onChange: (next: string | ReadonlyArray<string>) => void;
+  /**
+   * The column's options through `resolveColumnOptions`, pre-resolved for a
+   * column that declares `meta.options` or is select-shaped. Empty otherwise —
+   * a control wanting faceted values on other columns resolves them itself.
+   */
+  options: ReadonlyArray<TMDataGridOption>;
+  size: TMDataGridSize;
+  labels: TMDataGridLabels;
+};
+
+/**
+ * `meta.filterControl` — replaces the built-in value control for this column.
+ * Rendered as JSX, never invoked as a bare function, so hooks are legal
+ * inside. Define it at module scope so its identity is stable across renders.
+ */
+export type TMDataGridFilterControlComponent =
+  ComponentType<TMDataGridFilterControlArgs>;

package/src/tmdatagrid/core/filterOperators.ts

@@ -9,8 +9,10 @@ import type { Row, RowData, TableFeatures } from "@tanstack/react-table";
  * `manualFiltering` table (just forward `columnFilters` to the API).
  *
  * `value` is a string array under `isAnyOf` / `isNoneOf` (the set the cell is
- * tested against) and a single string everywhere else — dates travel as ISO
- * `YYYY-MM-DD` strings, booleans as `"true"` / `"false"`. Still plain JSON.
+ * tested against), a `[min, max]` pair under `between` (an empty string means
+ * that end is open), and a single string everywhere else — dates travel as
+ * ISO `YYYY-MM-DD` strings, booleans as `"true"` / `"false"`. Still plain
+ * JSON.
  */
 export type TMDataGridFilterValue = {
   operator: TMDataGridFilterOperator;
@@ -35,6 +37,7 @@ export type TMDataGridFilterOperator =
   | "greaterThanOrEqual"
   | "lessThan"
   | "lessThanOrEqual"
+  | "between"
   | "before"
   | "after"
   | "onOrBefore"
@@ -54,6 +57,7 @@ export const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string> =
   greaterThanOrEqual: "is greater than or equal to",
   lessThan: "is less than",
   lessThanOrEqual: "is less than or equal to",
+  between: "is between",
   before: "is before",
   after: "is after",
   onOrBefore: "is on or before",
@@ -81,6 +85,7 @@ const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "greaterThanOrEqual",
   "lessThan",
   "lessThanOrEqual",
+  "between",
   "isEmpty",
   "isNotEmpty",
 ];
@@ -95,6 +100,7 @@ const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "after",
   "onOrBefore",
   "onOrAfter",
+  "between",
   "isEmpty",
   "isNotEmpty",
 ];
@@ -127,6 +133,9 @@ const ARRAY_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "isNoneOf",
 ];
 
+/** Operators whose value is a `[min, max]` pair. */
+const RANGE_OPERATORS: readonly TMDataGridFilterOperator[] = ["between"];
+
 const OPERATORS_BY_TYPE: Record<
   TMDataGridColumnType,
   readonly TMDataGridFilterOperator[]
@@ -174,6 +183,22 @@ export function operatorTakesArrayValue(
   return ARRAY_OPERATORS.includes(operator);
 }
 
+/** Whether the operator's value is a `[min, max]` pair — `between`. */
+export function operatorTakesRangeValue(
+  operator: TMDataGridFilterOperator,
+): boolean {
+  return RANGE_OPERATORS.includes(operator);
+}
+
+/** The untouched value a fresh filter starts with — the operator's shape, empty. */
+export function emptyValueForOperator(
+  operator: TMDataGridFilterOperator,
+): string | ReadonlyArray<string> {
+  if (operatorTakesArrayValue(operator)) return [];
+  if (operatorTakesRangeValue(operator)) return ["", ""];
+  return "";
+}
+
 export function isTMDataGridFilterValue(
   value: unknown,
 ): value is TMDataGridFilterValue {
@@ -193,8 +218,10 @@ export function isTMDataGridFilterValue(
 export function isFilterActive(value: unknown): boolean {
   if (!isTMDataGridFilterValue(value)) return false;
   if (!operatorNeedsValue(value.operator)) return true;
+  // A `between` pair is `["", ""]` while untouched, so an array is active
+  // once some entry says something, not merely by existing.
   return Array.isArray(value.value)
-    ? value.value.length > 0
+    ? value.value.some((entry) => String(entry).trim() !== "")
     : typeof value.value === "string" && value.value.trim() !== "";
 }
 
@@ -221,7 +248,12 @@ export function formatFilterLabel({
   if (!operatorNeedsValue(operator)) {
     return `${label} ${operatorLabels[operator]}`;
   }
-  const text = Array.isArray(value) ? value.join(", ") : String(value).trim();
+  const text =
+    operator === "between" && Array.isArray(value)
+      ? value.map((entry) => String(entry).trim()).join("–")
+      : Array.isArray(value)
+        ? value.join(", ")
+        : String(value).trim();
   if (operator === getDefaultOperator(type)) return `${label}: ${text}`;
   return `${label} ${operatorLabels[operator]} ${text}`;
 }
@@ -246,6 +278,29 @@ function toIsoDay(value: unknown): string | null {
   return null;
 }
 
+/** One end of a `between` interval. An empty bound is an open end. */
+function boundHolds(
+  cellValue: unknown,
+  bound: string,
+  end: "min" | "max",
+): boolean {
+  const boundText = bound.trim();
+  if (boundText === "") return true;
+
+  const numericCell = typeof cellValue === "number" ? cellValue : Number.NaN;
+  const numericBound = Number(boundText);
+  if (!Number.isNaN(numericCell) && !Number.isNaN(numericBound)) {
+    return end === "min"
+      ? numericCell >= numericBound
+      : numericCell <= numericBound;
+  }
+
+  const cellDay = toIsoDay(cellValue);
+  const boundDay = toIsoDay(boundText);
+  if (cellDay === null || boundDay === null) return false;
+  return end === "min" ? cellDay >= boundDay : cellDay <= boundDay;
+}
+
 function isEmptyCell(cellValue: unknown): boolean {
   return (
     cellValue === null ||
@@ -276,6 +331,19 @@ export function matchesFilter(
     return operator === "isAnyOf" ? hit : !hit;
   }
 
+  // A closed or half-open interval. Each present end must hold; an empty end
+  // is open — and a fully empty pair matches everything, the same way a blank
+  // needle does. Ends compare the way the single-ended operators would:
+  // numerically when both sides are numbers, by calendar day otherwise.
+  if (operator === "between") {
+    const [min, max] = Array.isArray(value)
+      ? [String(value[0] ?? ""), String(value[1] ?? "")]
+      : [String(value), ""];
+    return (
+      boundHolds(cellValue, min, "min") && boundHolds(cellValue, max, "max")
+    );
+  }
+
   const filterText =
     typeof value === "string" ? value.trim() : value.join(",").trim();
   if (filterText === "") return true;

package/src/tmdatagrid/core/labels.ts

@@ -30,12 +30,27 @@ export type TMDataGridLabels = {
   columnsNoMatch: (search: string) => string;
   columnsShowHideAll: string;
   columnsReset: string;
+  /** Tooltip on the reset button, stating everything the reset covers. */
+  columnsResetHint: string;
+  /** Menu/panel name of the generated row-number gutter. */
+  rowNumberColumnLabel: string;
+  /**
+   * The truly-empty message — no data and no filters. Filtered-empty says
+   * {@link noResults} instead; only one of the two is the user's own doing.
+   */
+  noRows: string;
 
   // Filter panel
   filterColumn: string;
   filterOperator: string;
   filterValue: string;
   filterValuePlaceholder: string;
+  /** The lower bound of a `between` filter. */
+  filterFrom: string;
+  /** The upper bound of a `between` filter. */
+  filterTo: string;
+  /** `DgTriStateFilter`'s no-filter segment. */
+  filterAll: string;
   /** What a boolean column's `true` reads as — its filter choice and cell text. */
   booleanTrue: string;
   booleanFalse: string;
@@ -79,6 +94,36 @@ export type TMDataGridLabels = {
   noResults: string;
   loading: string;
 
+  // Cell editing
+  /** `aria-label` of an open cell editor's input. */
+  editCell: (column: string) => string;
+  /** cellConfirm's ✓ beside the input. */
+  confirmEdit: string;
+  /** cellConfirm's ✕ beside the input. */
+  cancelEdit: string;
+  /** The generated edit lane's name in the column manager. */
+  editColumnLabel: string;
+  /** The lane's pencil. */
+  editRow: string;
+  /** The lane's ✓ while a row edit is open. */
+  saveRow: string;
+  /** The lane's ✕ while a row edit is open. */
+  cancelRowEdit: string;
+  /** Save tooltip when field errors block the row, with no row message. */
+  editRowErrors: string;
+  /** `EditActions`' Save, with the dirty-row count. */
+  saveAllEdits: (rows: number) => string;
+  /** `EditActions`' Discard. */
+  discardAllEdits: string;
+  /** The entry row's ✓ — commit the add. */
+  confirmNewRow: string;
+  /** The entry row's ✕ — drop the entry. */
+  discardNewRow: string;
+  /** The lane's trash can. */
+  deleteRow: string;
+  /** The lane's undo on a row marked deleted (batch). */
+  restoreRow: string;
+
   // Cell selection menu
   cellCount: (count: number) => string;
   copy: string;
@@ -128,12 +173,19 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   columnsSearchPlaceholder: "Search",
   columnsNoMatch: (search) => `No columns match “${search}”`,
   columnsShowHideAll: "Show/Hide All",
-  columnsReset: "RESET",
+  columnsReset: "RESET LAYOUT",
+  columnsResetHint:
+    "Resets column visibility, order, widths, pinning and grouping",
+  rowNumberColumnLabel: "Row number",
+  noRows: "No rows to show",
 
   filterColumn: "Column",
   filterOperator: "Operator",
   filterValue: "Value",
   filterValuePlaceholder: "Filter value",
+  filterFrom: "From",
+  filterTo: "To",
+  filterAll: "All",
   booleanTrue: "Yes",
   booleanFalse: "No",
   addFilter: "Add filter",
@@ -173,6 +225,21 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   noResults: "No rows match your filters",
   loading: "Loading",
 
+  editCell: (column) => `Edit ${column}`,
+  confirmEdit: "Save",
+  cancelEdit: "Cancel",
+  editColumnLabel: "Edit",
+  editRow: "Edit row",
+  saveRow: "Save row",
+  cancelRowEdit: "Cancel edit",
+  editRowErrors: "Fix the marked cells",
+  saveAllEdits: (rows) => (rows === 1 ? "Save 1 row" : `Save ${rows} rows`),
+  discardAllEdits: "Discard",
+  confirmNewRow: "Add row",
+  discardNewRow: "Discard new row",
+  deleteRow: "Delete row",
+  restoreRow: "Restore row",
+
   cellCount: (count) => (count === 1 ? "1 cell" : `${count} cells`),
   copy: "Copy",
   exportCsv: "Export as CSV for Excel",

package/src/tmdatagrid/core/labelsSv.ts

@@ -21,6 +21,7 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
     greaterThanOrEqual: "är större än eller lika med",
     lessThan: "är mindre än",
     lessThanOrEqual: "är mindre än eller lika med",
+    between: "är mellan",
     before: "är före",
     after: "är efter",
     onOrBefore: "är på eller före",
@@ -40,12 +41,19 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
   columnsSearchPlaceholder: "Sök",
   columnsNoMatch: (search) => `Inga kolumner matchar ”${search}”`,
   columnsShowHideAll: "Visa/dölj alla",
-  columnsReset: "ÅTERSTÄLL",
+  columnsReset: "ÅTERSTÄLL LAYOUT",
+  columnsResetHint:
+    "Återställer kolumnernas synlighet, ordning, bredder, fästning och gruppering",
+  rowNumberColumnLabel: "Radnummer",
+  noRows: "Inga rader att visa",
 
   filterColumn: "Kolumn",
   filterOperator: "Operator",
   filterValue: "Värde",
   filterValuePlaceholder: "Filtervärde",
+  filterFrom: "Från",
+  filterTo: "Till",
+  filterAll: "Alla",
   booleanTrue: "Ja",
   booleanFalse: "Nej",
   addFilter: "Lägg till filter",
@@ -85,6 +93,21 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
   noResults: "Inga rader matchar dina filter",
   loading: "Laddar",
 
+  editCell: (column) => `Redigera ${column}`,
+  confirmEdit: "Spara",
+  cancelEdit: "Avbryt",
+  editColumnLabel: "Redigera",
+  editRow: "Redigera rad",
+  saveRow: "Spara rad",
+  cancelRowEdit: "Avbryt redigering",
+  editRowErrors: "Åtgärda de markerade cellerna",
+  saveAllEdits: (rows) => (rows === 1 ? "Spara 1 rad" : `Spara ${rows} rader`),
+  discardAllEdits: "Förkasta",
+  confirmNewRow: "Lägg till rad",
+  discardNewRow: "Släng ny rad",
+  deleteRow: "Ta bort rad",
+  restoreRow: "Återställ rad",
+
   cellCount: (count) => (count === 1 ? "1 cell" : `${count} celler`),
   copy: "Kopiera",
   exportCsv: "Exportera som CSV för Excel",

package/src/tmdatagrid/core/matchHighlight.ts

@@ -0,0 +1,96 @@
+import type { RowData } from "@tanstack/react-table";
+import {
+  isTMDataGridFilterValue,
+  type TMDataGridFilterOperator,
+} from "./filterOperators";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/** A matched slice of a cell's text, `start` inclusive to `end` exclusive. */
+export type TMDataGridMatchRange = { start: number; end: number };
+
+/**
+ * The operators whose match is a contiguous substring — the ones highlighting
+ * can point at. Equality highlights nothing: marking the whole cell says
+ * nothing the filter did not already say.
+ */
+const HIGHLIGHTABLE_OPERATORS: ReadonlyArray<TMDataGridFilterOperator> = [
+  "contains",
+  "startsWith",
+  "endsWith",
+];
+
+/**
+ * Every needle that could highlight in a given column, keyed by column id —
+ * the quick search for the columns it searches, plus any contains-family
+ * column filter. `null` while nothing highlightable is active, which is the
+ * common case and the cheap one.
+ *
+ * The fuzzy quick search still contributes its raw text: when the needle
+ * occurs contiguously it is highlighted, and a typo-match simply shows no
+ * highlight — the honest answer to what a non-contiguous match "is".
+ */
+export function buildMatchNeedles<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+): Map<string, ReadonlyArray<string>> | null {
+  const state = table.store.state;
+  const global =
+    typeof state.globalFilter === "string" ? state.globalFilter.trim() : "";
+
+  const byColumn = new Map<string, Array<string>>();
+  for (const filter of state.columnFilters) {
+    if (!isTMDataGridFilterValue(filter.value)) continue;
+    const { operator, value } = filter.value;
+    if (!HIGHLIGHTABLE_OPERATORS.includes(operator)) continue;
+    if (typeof value !== "string" || value === "") continue;
+    const needles = byColumn.get(filter.id) ?? [];
+    needles.push(value);
+    byColumn.set(filter.id, needles);
+  }
+
+  if (global === "" && byColumn.size === 0) return null;
+
+  const map = new Map<string, ReadonlyArray<string>>();
+  for (const column of table.getAllLeafColumns()) {
+    const needles: Array<string> = [];
+    if (global !== "" && column.getCanGlobalFilter()) needles.push(global);
+    const own = byColumn.get(column.id);
+    if (own !== undefined) needles.push(...own);
+    if (needles.length > 0) map.set(column.id, needles);
+  }
+  return map.size > 0 ? map : null;
+}
+
+/**
+ * Where the needles occur in the text, case-insensitively, merged where they
+ * overlap or touch — so two needles covering "St" and "tock" come back as one
+ * range rather than nested marks. `null` when nothing matches.
+ */
+export function findMatchRanges(
+  text: string,
+  needles: ReadonlyArray<string>,
+): Array<TMDataGridMatchRange> | null {
+  const haystack = text.toLowerCase();
+  const found: Array<TMDataGridMatchRange> = [];
+  for (const needle of needles) {
+    const lowered = needle.toLowerCase();
+    if (lowered === "") continue;
+    let index = haystack.indexOf(lowered);
+    while (index !== -1) {
+      found.push({ start: index, end: index + lowered.length });
+      index = haystack.indexOf(lowered, index + 1);
+    }
+  }
+  if (found.length === 0) return null;
+
+  found.sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged: Array<TMDataGridMatchRange> = [];
+  for (const range of found) {
+    const last = merged.at(-1);
+    if (last !== undefined && range.start <= last.end) {
+      last.end = Math.max(last.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}

package/src/tmdatagrid/core/persistence.ts

@@ -78,6 +78,17 @@ export type TMDataGridPersistence = {
   deserialize?: (value: string) => unknown;
 };
 
+/**
+ * Version stamped into every stored payload, under a key no state slice can
+ * collide with. A payload whose version does not match is dropped whole: a
+ * migration would be guessing at a shape this code no longer knows, and the
+ * cost of dropping is one lost layout. Payloads written before versioning
+ * existed (≤0.4.0) have no stamp and are dropped the same way — the 1.0
+ * wave's one-time break, named in its changeset.
+ */
+export const PERSIST_PAYLOAD_VERSION = 1;
+const VERSION_FIELD = "__v";
+
 type ResolvedKey = { key: string; slices: ReadonlyArray<keyof GridState> };
 
 function resolveKey<TSlice extends string>(
@@ -201,6 +212,7 @@ function readSlices(
     if (typeof parsed !== "object" || parsed === null) return {};
 
     const record = parsed as Record<string, unknown>;
+    if (record[VERSION_FIELD] !== PERSIST_PAYLOAD_VERSION) return {};
     const restored: Record<string, unknown> = {};
     // Only copy the selected slices. A payload written before the selection was
     // narrowed cannot reintroduce slices the caller has since opted out of.
@@ -222,7 +234,7 @@ function writeSlices(
   serialize: (value: Partial<GridState>) => string,
 ): void {
   if (!storage || !resolved) return;
-  const payload: Record<string, unknown> = {};
+  const payload: Record<string, unknown> = { [VERSION_FIELD]: PERSIST_PAYLOAD_VERSION };
   for (const slice of resolved.slices) payload[slice] = state[slice];
   try {
     storage.setItem(resolved.key, serialize(payload as Partial<GridState>));
@@ -250,17 +262,99 @@ const defaultDeserialize = (value: string): unknown => JSON.parse(value);
 const defaultSerialize = (value: Partial<GridState>): string =>
   JSON.stringify(value);
 
-/** State to merge into `initialState`, read once on mount. */
+/**
+ * The leaf column ids a set of column defs will produce, by TanStack's own
+ * derivation: `id`, else `accessorKey` with dots replaced by underscores,
+ * else a string `header`. Mirrored here so restored state can be realigned
+ * against the columns that will actually exist — deriving ids any other way
+ * would realign against names the table never uses.
+ */
+export function collectLeafColumnIds(
+  defs: ReadonlyArray<unknown>,
+  into: string[] = [],
+): string[] {
+  for (const def of defs) {
+    if (typeof def !== "object" || def === null) continue;
+    const record = def as Record<string, unknown>;
+    if (Array.isArray(record.columns) && record.columns.length > 0) {
+      collectLeafColumnIds(record.columns, into);
+      continue;
+    }
+    const accessorKey =
+      typeof record.accessorKey === "string" ? record.accessorKey : undefined;
+    const id =
+      (typeof record.id === "string" ? record.id : undefined) ??
+      accessorKey?.replaceAll(".", "_") ??
+      (typeof record.header === "string" ? record.header : undefined);
+    if (id !== undefined) into.push(id);
+  }
+  return into;
+}
+
+/**
+ * Drops restored entries that name columns the grid no longer has.
+ *
+ * A stored layout outlives the column set: a column removed between deploys
+ * would otherwise linger forever — a ghost id in the order, a width for
+ * nothing, and worse, a *filter or sort that is active but has no column to
+ * show for itself*. New columns need no counterpart here: TanStack appends
+ * columns missing from `columnOrder` on its own, in definition order.
+ */
+function realignToColumns(
+  restored: Partial<GridState>,
+  known: ReadonlySet<string>,
+): Partial<GridState> {
+  const has = (id: unknown): boolean =>
+    typeof id === "string" && known.has(id);
+  const keepIds = (values: ReadonlyArray<string>) => values.filter(has);
+  const keepKeys = <T,>(record: Record<string, T>) =>
+    Object.fromEntries(Object.entries(record).filter(([id]) => has(id)));
+  const keepEntries = <T extends { id: string }>(entries: ReadonlyArray<T>) =>
+    entries.filter((entry) => has(entry.id));
+
+  const realigned: Partial<GridState> = { ...restored };
+  if (restored.columnOrder) realigned.columnOrder = keepIds(restored.columnOrder);
+  if (restored.grouping) realigned.grouping = keepIds(restored.grouping);
+  if (restored.columnVisibility) {
+    realigned.columnVisibility = keepKeys(restored.columnVisibility);
+  }
+  if (restored.columnSizing) {
+    realigned.columnSizing = keepKeys(restored.columnSizing);
+  }
+  if (restored.columnPinning) {
+    realigned.columnPinning = {
+      left: keepIds(restored.columnPinning.left ?? []),
+      right: keepIds(restored.columnPinning.right ?? []),
+    };
+  }
+  if (restored.sorting) realigned.sorting = keepEntries(restored.sorting);
+  if (restored.columnFilters) {
+    realigned.columnFilters = keepEntries(restored.columnFilters);
+  }
+  return realigned;
+}
+
+/**
+ * State to merge into `initialState`, read once on mount.
+ *
+ * With `knownColumnIds` — every id the grid is about to construct, generated
+ * lanes included — the column-shaped slices are realigned first; see
+ * {@link realignToColumns}. Without it the payload is returned as stored.
+ */
 export function readPersistedState(
   persistence?: TMDataGridPersistence,
+  knownColumnIds?: ReadonlyArray<string>,
 ): Partial<GridState> {
   const storage = resolveStorage(persistence);
   const { data, settings } = resolveKeys(persistence);
   const deserialize = persistence?.deserialize ?? defaultDeserialize;
-  return {
+  const restored = {
     ...readSlices(storage, settings, deserialize),
     ...readSlices(storage, data, deserialize),
   };
+  return knownColumnIds === undefined
+    ? restored
+    : realignToColumns(restored, new Set(knownColumnIds));
 }
 
 /** Writes both payloads. Called on every table state change. */