aplance-ui 1.5.1 → 1.6.0

package/registry/components/ui/data-table/utils.ts

@@ -1,471 +1,691 @@
-import type {
-  Column,
-  ColumnOrderState,
-  ColumnPinningState,
-  ColumnSizingState,
-  ExpandedState,
-  Updater,
-  VisibilityState,
-} from "@tanstack/react-table";
-import type { CSSProperties } from "react";
-import type {
-  ApplyPersistedTarget,
-  ColumnIdSource,
-  PersistedState,
-  SnapshotInput,
-} from "./types";
-
-/**
- * Per-cell style map for one column. Returns the fixed width plus the
- * sticky offset when the column is pinned. Reading offsets straight from
- * tanstack (`getStart`/`getAfter`) keeps header and body cells in sync
- * even after resizing or reordering - no manual bookkeeping needed.
- */
-export function getColumnStyle<TData>(
-  column: Column<TData, unknown>,
-  size: number,
-  extraWidth = 0,
-): CSSProperties {
-  const isPinned = column.getIsPinned();
-  const computedWidth = size + extraWidth;
-  const style: CSSProperties = {
-    width: `${computedWidth}px`,
-    minWidth: `${computedWidth}px`,
-    maxWidth: `${computedWidth}px`,
-  };
-  if (isPinned === "left") {
-    style.left = `${column.getStart("left")}px`;
-  } else if (isPinned === "right") {
-    style.right = `${column.getAfter("right")}px`;
-  }
-  return style;
-}
-
-/** Move `sourceId` to the position currently held by `targetId`. */
-export function reorderColumnOrder(
-  order: ColumnOrderState,
-  sourceId: string,
-  targetId: string,
-): ColumnOrderState {
-  const next = order.slice();
-  const fromIdx = next.indexOf(sourceId);
-  const toIdx = next.indexOf(targetId);
-  if (fromIdx === -1 || toIdx === -1) return order;
-  next.splice(fromIdx, 1);
-  next.splice(toIdx, 0, sourceId);
-  return next;
-}
-
-/**
- * Last visible pinned column on its side. Used by the divider style so
- * we don't draw an inset line between adjacent pinned columns - only at
- * the boundary between the pinned region and the scrolling center.
- */
-export function isLastPinned<TData>(column: Column<TData, unknown>): boolean {
-  const pinned = column.getIsPinned();
-  if (pinned !== "left" && pinned !== "right") return false;
-  return column.getIsLastColumn(pinned);
-}
-
-/**
- * Default formatter for aggregated values when a column does not provide
- * an `aggregatedCell`. Numbers fall back to `toLocaleString` and arrays
- * to a count; everything else is rendered as-is.
- */
-export function formatAggregated(value: unknown): string {
-  if (value == null) return "";
-  if (typeof value === "number") return value.toLocaleString();
-  if (Array.isArray(value)) return `${value.length} items`;
-  return String(value);
-}
-
-/**
- * Resolve the runtime column id from a raw `ColumnDef`. Mirrors how
- * tanstack derives ids: explicit `id` first, then `accessorKey` for
- * accessor columns. Useful when consumers need to build menus (visibility,
- * grouping, etc.) from the same column array they hand to the table -
- * tanstack only assigns the resolved id once the table is built, so
- * reading `c.id` directly off the def returns `undefined` for accessor
- * columns and breaks state maps keyed by id.
- */
-export function columnId(def: ColumnIdSource): string {
-  if (def.id) return def.id;
-  if (def.accessorKey != null) return String(def.accessorKey);
-  return "";
-}
-
-/**
- * TanStack `Updater<T>` is `T | ((old: T) => T)`. When `T` itself extends
- * `Function`, TypeScript widens the function branch to `((old: T) => T) |
- * (T & Function)` after the `typeof` narrowing - and `T & Function` has no
- * call signatures, so a cast is required to keep the compiler happy.
- */
-export function resolveUpdater<T>(updater: Updater<T>, prev: T): T {
-  return typeof updater === "function"
-    ? (updater as (old: T) => T)(prev)
-    : updater;
-}
-
-export const SELECT_COLUMN_ID = "select";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// State persistence helpers (URL search params / localStorage / manual).
-// Pure functions - no React. The hook-level orchestration in `useDataTable`
-// supplies the current state + setters and these functions take care of the
-// snapshot/apply/read/write mechanics.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Single source-of-truth for every URL param key used by the persistence
- * layer. Both `readSearchParams` and `writeSearchParams` reference these
- * values - adding or renaming a key is one edit here, not scattered string
- * literals across multiple functions.
- */
-export const PARAM_KEYS = {
-  pageIndex: "pageIndex",
-  pageSize: "pageSize",
-  sortBy: "sortBy",
-  sortDir: "sortDir",
-  columnOrder: "columnOrder",
-  columnVisibility: "columnVisibility",
-  columnPinning: "columnPinning",
-  columnSizing: "columnSizing",
-  grouping: "grouping",
-  expanded: "expanded",
-} as const;
-
-export type ParamKey = (typeof PARAM_KEYS)[keyof typeof PARAM_KEYS];
-
-/**
- * Reserved param keys used by the snapshot encoding itself. Filter keys must
- * not collide with these - when iterating filter keys we skip any reserved
- * names so a filter named `pageIndex` cannot stomp on the pagination param.
- * Derived from `PARAM_KEYS` so the two never drift apart.
- */
-export const RESERVED_PARAM_KEYS = new Set<string>(Object.values(PARAM_KEYS));
-
-const isNonEmptyExpanded = (e: ExpandedState | undefined): boolean =>
-  e !== undefined && (e === true || Object.keys(e).length > 0);
-
-/**
- * Structural equality for two `ExpandedState`s (each a boolean or an
- * id -> boolean record). Lets the snapshot skip persisting `expanded` while it
- * still matches the table's default.
- */
-const expandedEquals = (
-  a: ExpandedState | undefined,
-  b: ExpandedState | undefined,
-): boolean => {
-  if (a === b) return true;
-  if (typeof a === "boolean" || typeof b === "boolean") return false;
-  if (!a || !b) return false;
-  const aKeys = Object.keys(a);
-  if (aKeys.length !== Object.keys(b).length) return false;
-  return aKeys.every((k) => a[k] === b[k]);
-};
-
-/**
- * Build a `PersistedState` snapshot from current state, omitting empty/default
- * slices so the persisted blob (URL or storage) stays minimal.
- * `defaultPageSize` lives on `SnapshotInput` so callers don't need to thread
- * it as a separate argument - it's part of the snapshot's own context.
- */
-export function snapshotPersistedState(input: SnapshotInput): PersistedState {
-  const out: PersistedState = {};
-
-  const activeFilters: Record<string, string> = {};
-  for (const [k, v] of Object.entries(input.filterValues)) {
-    if (v) activeFilters[k] = v;
-  }
-  if (Object.keys(activeFilters).length > 0) out.filterValues = activeFilters;
-
-  // Only persist pagination when it actually differs from defaults -
-  // pageSize is always a truthy number so `if (pageSize)` would always fire.
-  if (
-    input.pagination.pageIndex > 0 ||
-    input.pagination.pageSize !== input.defaultPageSize
-  ) {
-    out.pagination = input.pagination;
-  }
-
-  if (input.sorting.length > 0) out.sorting = input.sorting;
-  if (input.columnOrder.length > 0) out.columnOrder = input.columnOrder;
-  if (Object.keys(input.columnVisibility).length > 0) {
-    out.columnVisibility = input.columnVisibility;
-  }
-  if (input.columnPinning.left?.length || input.columnPinning.right?.length) {
-    out.columnPinning = input.columnPinning;
-  }
-  if (Object.keys(input.columnSizing).length > 0) {
-    out.columnSizing = input.columnSizing;
-  }
-  if (input.grouping.length > 0) out.grouping = input.grouping;
-  // Persist expansion only when it deviates from the default - otherwise the
-  // default (`true` = all groups expanded) writes a noisy `?expanded=true` even
-  // when the user never touched a group.
-  if (
-    isNonEmptyExpanded(input.expanded) &&
-    !expandedEquals(input.expanded, input.defaultExpanded)
-  ) {
-    out.expanded = input.expanded;
-  }
-
-  return out;
-}
-
-/**
- * Apply a `PersistedState` blob back onto the controlled setters. Each slice
- * is independently optional - partial blobs (e.g. only `sorting`) work fine.
- * Unknown filter keys from a stale URL/blob are silently ignored.
- */
-export function applyPersistedState(
-  state: PersistedState,
-  target: ApplyPersistedTarget,
-): void {
-  if (state.filterValues) {
-    const next = { ...target.filterValues };
-    for (const key of target.filterKeys) {
-      const v = state.filterValues[key];
-      if (v !== undefined) next[key] = v;
-    }
-    target.setFilterValues(next);
-  }
-  if (state.pagination) target.setPagination(state.pagination);
-  if (state.sorting) target.setSorting(state.sorting);
-  if (state.columnOrder) target.setColumnOrder(state.columnOrder);
-  if (state.columnVisibility)
-    target.setColumnVisibility(state.columnVisibility);
-  if (state.columnPinning) target.setColumnPinning(state.columnPinning);
-  if (state.columnSizing) target.setColumnSizing(state.columnSizing);
-  if (state.grouping) target.setGrouping(state.grouping);
-  if (state.expanded !== undefined) target.setExpanded(state.expanded);
-}
-
-/**
- * Decode a URL `?...` query string into a `PersistedState` blob. Flat
- * encoding, hand-editable. `pageIndex` is stored 1-based for human
- * readability; `pageSize` falls back to `defaultPageSize` when absent.
- */
-export function readSearchParams(
-  filterKeys: string[],
-  paramMap: Partial<Record<string, string>>,
-  defaultPageSize: number,
-): PersistedState {
-  const out: PersistedState = {};
-  const params = new URLSearchParams(window.location.search);
-  const p = (k: string) => paramMap[k] ?? k;
-
-  const filterValues: Record<string, string> = {};
-  for (const key of filterKeys) {
-    const raw = params.get(p(key));
-    if (raw !== null) filterValues[key] = raw;
-  }
-  if (Object.keys(filterValues).length > 0) out.filterValues = filterValues;
-
-  const rawPage = params.get(p(PARAM_KEYS.pageIndex));
-  const rawSize = params.get(p(PARAM_KEYS.pageSize));
-  if (rawPage !== null || rawSize !== null) {
-    const pageIndex = rawPage !== null ? Math.max(0, Number(rawPage) - 1) : 0;
-    const pageSize =
-      rawSize !== null && Number.isFinite(Number(rawSize))
-        ? Number(rawSize)
-        : defaultPageSize;
-    out.pagination = {
-      pageIndex: Number.isFinite(pageIndex) ? pageIndex : 0,
-      pageSize,
-    };
-  }
-
-  const rawSortBy = params.get(p(PARAM_KEYS.sortBy));
-  const rawSortDir = params.get(p(PARAM_KEYS.sortDir));
-  if (rawSortBy) {
-    out.sorting = [{ id: rawSortBy, desc: rawSortDir === "desc" }];
-  }
-
-  const rawColOrder = params.get(p(PARAM_KEYS.columnOrder));
-  if (rawColOrder) out.columnOrder = rawColOrder.split(",");
-
-  const tryJson = <T>(key: ParamKey): T | undefined => {
-    const raw = params.get(p(key));
-    if (!raw) return undefined;
-    try {
-      return JSON.parse(raw) as T;
-    } catch {
-      return undefined;
-    }
-  };
-
-  const colVis = tryJson<VisibilityState>(PARAM_KEYS.columnVisibility);
-  if (colVis) out.columnVisibility = colVis;
-  const colPin = tryJson<ColumnPinningState>(PARAM_KEYS.columnPinning);
-  if (colPin) out.columnPinning = colPin;
-  const colSize = tryJson<ColumnSizingState>(PARAM_KEYS.columnSizing);
-  if (colSize) out.columnSizing = colSize;
-
-  const rawGrouping = params.get(p(PARAM_KEYS.grouping));
-  if (rawGrouping) out.grouping = rawGrouping.split(",");
-
-  const expanded = tryJson<ExpandedState>(PARAM_KEYS.expanded);
-  if (expanded !== undefined) out.expanded = expanded;
-
-  return out;
-}
-
-/**
- * Encode a `PersistedState` blob into the URL via `history.replaceState`.
- * `pageSize` is omitted when it matches `defaultPageSize` so a fresh URL
- * stays clean; reserved param keys are protected against filter-key collisions.
- */
-export function writeSearchParams(
-  state: PersistedState,
-  filterKeys: string[],
-  paramMap: Partial<Record<string, string>>,
-  defaultPageSize: number,
-): void {
-  const params = new URLSearchParams(window.location.search);
-  const p = (k: string) => paramMap[k] ?? k;
-
-  // Helper: set a JSON-serialised param or delete it when absent.
-  // Handles all truthy checks uniformly including `false` and `{}` for
-  // `expanded`, which are valid non-default states but would be dropped
-  // by a plain `if (value)` guard.
-  const setJson = (key: ParamKey, value: unknown): void => {
-    if (value !== undefined && value !== null) {
-      params.set(p(key), JSON.stringify(value));
-    } else {
-      params.delete(p(key));
-    }
-  };
-
-  // Filters - every declared filter key must be set or deleted (absent
-  // value === "cleared"). Keys outside the universe are left untouched.
-  const active = state.filterValues ?? {};
-  for (const key of filterKeys) {
-    if (RESERVED_PARAM_KEYS.has(key)) continue;
-    const value = active[key];
-    if (value) params.set(p(key), value);
-    else params.delete(p(key));
-  }
-
-  if (state.pagination && state.pagination.pageIndex > 0) {
-    params.set(p(PARAM_KEYS.pageIndex), String(state.pagination.pageIndex + 1));
-  } else {
-    params.delete(p(PARAM_KEYS.pageIndex));
-  }
-  if (state.pagination && state.pagination.pageSize !== defaultPageSize) {
-    params.set(p(PARAM_KEYS.pageSize), String(state.pagination.pageSize));
-  } else {
-    params.delete(p(PARAM_KEYS.pageSize));
-  }
-
-  const sort = state.sorting?.[0];
-  if (sort) {
-    params.set(p(PARAM_KEYS.sortBy), sort.id);
-    params.set(p(PARAM_KEYS.sortDir), sort.desc ? "desc" : "asc");
-  } else {
-    params.delete(p(PARAM_KEYS.sortBy));
-    params.delete(p(PARAM_KEYS.sortDir));
-  }
-
-  // Guard against empty arrays serialising to "" which reads back as [''].
-  if (state.columnOrder?.length) {
-    params.set(p(PARAM_KEYS.columnOrder), state.columnOrder.join(","));
-  } else {
-    params.delete(p(PARAM_KEYS.columnOrder));
-  }
-
-  setJson(PARAM_KEYS.columnVisibility, state.columnVisibility ?? null);
-  setJson(PARAM_KEYS.columnPinning, state.columnPinning ?? null);
-  setJson(PARAM_KEYS.columnSizing, state.columnSizing ?? null);
-
-  // Same empty-array guard for grouping.
-  if (state.grouping?.length) {
-    params.set(p(PARAM_KEYS.grouping), state.grouping.join(","));
-  } else {
-    params.delete(p(PARAM_KEYS.grouping));
-  }
-
-  // `expanded` can be `false` or `{}` - both are valid and must be preserved.
-  setJson(
-    PARAM_KEYS.expanded,
-    state.expanded !== undefined ? state.expanded : null,
-  );
-
-  const qs = params.toString();
-  window.history.replaceState(
-    null,
-    "",
-    qs ? `${window.location.pathname}?${qs}` : window.location.pathname,
-  );
-}
-
-/** Read a persisted blob from `localStorage` under `storageKey`. */
-export function readLocalStorage(storageKey: string): PersistedState {
-  try {
-    const raw = window.localStorage.getItem(storageKey);
-    if (!raw) return {};
-    return JSON.parse(raw) as PersistedState;
-  } catch {
-    return {};
-  }
-}
-
-/** Write (or remove, if empty) the persisted blob under `storageKey`. */
-export function writeLocalStorage(
-  storageKey: string,
-  state: PersistedState,
-): void {
-  try {
-    if (Object.keys(state).length === 0) {
-      window.localStorage.removeItem(storageKey);
-    } else {
-      window.localStorage.setItem(storageKey, JSON.stringify(state));
-    }
-  } catch {
-    /* quota exceeded or storage disabled - silently no-op */
-  }
-}
-
-export function normalizeColumnPinningState(
-  pinning: ColumnPinningState | undefined,
-  pinSelectionColumn: boolean,
-  defaultColumnPinning?: ColumnPinningState,
-): ColumnPinningState | undefined {
-  const left = pinning?.left ?? [];
-  const right = pinning?.right ?? [];
-
-  const defaultLeft = defaultColumnPinning?.left ?? [];
-  const defaultRight = defaultColumnPinning?.right ?? [];
-
-  const actualDefaultLeft =
-    pinSelectionColumn && !defaultLeft.includes(SELECT_COLUMN_ID)
-      ? [SELECT_COLUMN_ID, ...defaultLeft]
-      : defaultLeft;
-
-  const finalLeft =
-    pinSelectionColumn && !left.includes(SELECT_COLUMN_ID)
-      ? [SELECT_COLUMN_ID, ...left]
-      : left;
-
-  // Use a Set for O(n) lookup instead of repeated Array.includes (O(n²)).
-  const defaultLeftSet = new Set(actualDefaultLeft);
-  const orderedLeft = [
-    ...actualDefaultLeft.filter((id) => finalLeft.includes(id)),
-    ...finalLeft.filter((id) => !defaultLeftSet.has(id)),
-  ];
-
-  const dynamicRight = right.filter((id) => !defaultRight.includes(id));
-  const orderedRight = [
-    ...dynamicRight,
-    ...defaultRight.filter((id) => right.includes(id)),
-  ];
-
-  if (!pinning && actualDefaultLeft.length === 0 && defaultRight.length === 0) {
-    return undefined;
-  }
-
-  return {
-    left: orderedLeft,
-    right: orderedRight,
-  };
-}
+import {
+  aggregationFn_count,
+  aggregationFn_extent,
+  aggregationFn_first,
+  aggregationFn_last,
+  aggregationFn_max,
+  aggregationFn_mean,
+  aggregationFn_median,
+  aggregationFn_min,
+  aggregationFn_sum,
+  aggregationFn_unique,
+  aggregationFn_uniqueCount,
+  columnGroupingFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnResizingFeature,
+  columnSizingFeature,
+  columnVisibilityFeature,
+  createExpandedRowModel,
+  createGroupedRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  metaHelper,
+  rowAggregationFeature,
+  rowExpandingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_alphanumericCaseSensitive,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  sortFn_textCaseSensitive,
+  tableFeatures,
+  type Column,
+  type ColumnOrderState,
+  type ColumnPinningState,
+  type ColumnSizingState,
+  type ColumnVisibilityState,
+  type ExpandedState,
+  type RowData,
+  type Updater,
+} from "@tanstack/react-table";
+import type { CSSProperties, ReactNode } from "react";
+import type {
+  ApplyPersistedTarget,
+  ColumnIdSource,
+  DataTableColumnMeta,
+  DataTableFeatures,
+  DataTableMeta,
+  FilterField,
+  FilterInputField,
+  FilterPlacement,
+  PersistedState,
+  SnapshotInput,
+} from "./types";
+
+/**
+ * The TanStack Table features every DataTable registers, so only their code
+ * ships. Filtering is not among them: rows arrive already filtered (see
+ * `useDataTable`'s `filterFn`), so no filtered row model is needed. Rows run
+ * through sorting, then grouping and expansion, then pagination, so a
+ * client-side table sorts and groups every row before it pages them.
+ *
+ * The sort and aggregation functions are every built-in one, registered by
+ * name so a column's `sortFn: 'text'` or `aggregationFn: 'mean'` (and the
+ * default `'auto'` of both) resolves. The meta slots type `columnDef.meta` and
+ * `table.options.meta` for DataTable columns only, leaving other tables in the
+ * app untouched.
+ */
+export const dataTableFeatures = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowExpandingFeature,
+  columnGroupingFeature,
+  rowAggregationFeature,
+  columnOrderingFeature,
+  columnPinningFeature,
+  columnSizingFeature,
+  columnResizingFeature,
+  columnVisibilityFeature,
+  sortedRowModel: createSortedRowModel(),
+  groupedRowModel: createGroupedRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  sortFns: {
+    alphanumeric: sortFn_alphanumeric,
+    alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+    basic: sortFn_basic,
+    datetime: sortFn_datetime,
+    text: sortFn_text,
+    textCaseSensitive: sortFn_textCaseSensitive,
+  },
+  aggregationFns: {
+    count: aggregationFn_count,
+    extent: aggregationFn_extent,
+    first: aggregationFn_first,
+    last: aggregationFn_last,
+    max: aggregationFn_max,
+    mean: aggregationFn_mean,
+    median: aggregationFn_median,
+    min: aggregationFn_min,
+    sum: aggregationFn_sum,
+    unique: aggregationFn_unique,
+    uniqueCount: aggregationFn_uniqueCount,
+  },
+  columnMeta: metaHelper<DataTableColumnMeta>(),
+  tableMeta: metaHelper<DataTableMeta>(),
+});
+
+/**
+ * Per-cell style map for one column. Returns the fixed width plus the
+ * sticky offset when the column is pinned. Reading offsets straight from
+ * tanstack (`getStart`/`getAfter`) keeps header and body cells in sync
+ * even after resizing or reordering - no manual bookkeeping needed.
+ */
+export function getColumnStyle<TData extends RowData>(
+  column: Column<DataTableFeatures, TData, unknown>,
+  size: number,
+  extraWidth = 0,
+): CSSProperties {
+  const isPinned = column.getIsPinned();
+  const computedWidth = size + extraWidth;
+  const style: CSSProperties = {
+    width: `${computedWidth}px`,
+    minWidth: `${computedWidth}px`,
+    maxWidth: `${computedWidth}px`,
+  };
+  if (isPinned === "start") {
+    style.insetInlineStart = `${column.getStart("start")}px`;
+  } else if (isPinned === "end") {
+    style.insetInlineEnd = `${column.getAfter("end")}px`;
+  }
+  return style;
+}
+
+const NO_EXTRA_WIDTHS: Record<string, number> = {};
+
+/**
+ * Spread the body's spare width (`extraSpace`, px) across the columns that may
+ * grow, keyed by column id; the leftover pixels go to the first ones. Pinned
+ * columns never grow: tanstack computes sticky offsets from base sizes, so a
+ * wider pinned column would desync the offsets and overlap its neighbours.
+ * Neither does the select column, which keeps its compact width.
+ */
+export function growColumnWidths<TData extends RowData>(
+  columns: Column<DataTableFeatures, TData, unknown>[],
+  extraSpace: number,
+): Record<string, number> {
+  if (extraSpace <= 0) return NO_EXTRA_WIDTHS;
+  const growColumns = columns.filter(
+    (column) => !column.getIsPinned() && column.id !== SELECT_COLUMN_ID,
+  );
+  if (growColumns.length === 0) return NO_EXTRA_WIDTHS;
+
+  const baseExtra = Math.floor(extraSpace / growColumns.length);
+  let remainder = extraSpace - baseExtra * growColumns.length;
+  const widths: Record<string, number> = {};
+  for (const column of growColumns) {
+    const grow = baseExtra + (remainder > 0 ? 1 : 0);
+    if (grow > 0) widths[column.id] = grow;
+    if (remainder > 0) remainder -= 1;
+  }
+  return widths;
+}
+
+/** Move `sourceId` to the position currently held by `targetId`. */
+export function reorderColumnOrder(
+  order: ColumnOrderState,
+  sourceId: string,
+  targetId: string,
+): ColumnOrderState {
+  const next = order.slice();
+  const fromIdx = next.indexOf(sourceId);
+  const toIdx = next.indexOf(targetId);
+  if (fromIdx === -1 || toIdx === -1) return order;
+  next.splice(fromIdx, 1);
+  next.splice(toIdx, 0, sourceId);
+  return next;
+}
+
+/**
+ * The pinned column that meets the scrolling center: the last one of the
+ * start group, the first one of the end group (each the last counted inward
+ * from its own edge). Only it draws the divider, so adjacent pinned columns
+ * never get a line between them.
+ */
+export function isLastPinned<TData extends RowData>(
+  column: Column<DataTableFeatures, TData, unknown>,
+): boolean {
+  const pinned = column.getIsPinned();
+  if (pinned === "start") return column.getIsLastColumn("start");
+  if (pinned === "end") return column.getIsFirstColumn("end");
+  return false;
+}
+
+const formatAggregateValue = (value: unknown): string =>
+  typeof value === "number"
+    ? value.toLocaleString()
+    : value instanceof Date
+      ? value.toLocaleDateString()
+      : String(value);
+
+/**
+ * How a group row shows a column's aggregate when the column has no
+ * `aggregatedCell` of its own. Numbers and dates read in the viewer's locale.
+ * An `extent` (also what `auto` picks for a date column) reads as a
+ * `min - max` range, `unique` as a list, and a column with several
+ * aggregations as `name: value` pairs. Null when there is nothing to show,
+ * e.g. `auto` on a text column.
+ */
+export function formatAggregated(
+  value: unknown,
+  aggregationFn: unknown,
+): string | null {
+  if (value == null) return null;
+  if (Array.isArray(value)) {
+    const isRange = aggregationFn === "extent" || aggregationFn === "auto";
+    return value.map(formatAggregateValue).join(isRange ? " - " : ", ");
+  }
+  if (typeof value === "object" && !(value instanceof Date)) {
+    return Object.entries(value)
+      .map(([name, entry]) => `${name}: ${formatAggregated(entry, name) ?? ""}`)
+      .join(", ");
+  }
+  return formatAggregateValue(value);
+}
+
+/**
+ * Resolve the runtime column id from a raw `ColumnDef`. Mirrors how
+ * tanstack derives ids: explicit `id` first, then `accessorKey` for
+ * accessor columns. Useful when consumers need to build menus (visibility,
+ * grouping, etc.) from the same column array they hand to the table -
+ * tanstack only assigns the resolved id once the table is built, so
+ * reading `c.id` directly off the def returns `undefined` for accessor
+ * columns and breaks state maps keyed by id.
+ */
+export function columnId(def: ColumnIdSource): string {
+  if (def.id) return def.id;
+  if (def.accessorKey != null) return String(def.accessorKey);
+  return "";
+}
+
+/**
+ * TanStack `Updater<T>` is `T | ((old: T) => T)`. When `T` itself extends
+ * `Function`, TypeScript widens the function branch to `((old: T) => T) |
+ * (T & Function)` after the `typeof` narrowing - and `T & Function` has no
+ * call signatures, so a cast is required to keep the compiler happy.
+ */
+export function resolveUpdater<T>(updater: Updater<T>, prev: T): T {
+  return typeof updater === "function"
+    ? (updater as (old: T) => T)(prev)
+    : updater;
+}
+
+export const SELECT_COLUMN_ID = "select";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// State persistence helpers (URL search params / localStorage / manual).
+// Pure functions - no React. The hook-level orchestration in `useDataTable`
+// supplies the current state + setters and these functions take care of the
+// snapshot/apply/read/write mechanics.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Single source-of-truth for every URL param key used by the persistence
+ * layer. Both `readSearchParams` and `writeSearchParams` reference these
+ * values - adding or renaming a key is one edit here, not scattered string
+ * literals across multiple functions.
+ */
+export const PARAM_KEYS = {
+  pageIndex: "pageIndex",
+  pageSize: "pageSize",
+  sortBy: "sortBy",
+  sortDir: "sortDir",
+  columnOrder: "columnOrder",
+  columnVisibility: "columnVisibility",
+  columnPinning: "columnPinning",
+  columnSizing: "columnSizing",
+  grouping: "grouping",
+  expanded: "expanded",
+} as const;
+
+export type ParamKey = (typeof PARAM_KEYS)[keyof typeof PARAM_KEYS];
+
+/**
+ * Reserved param keys used by the snapshot encoding itself. Filter keys must
+ * not collide with these - when iterating filter keys we skip any reserved
+ * names so a filter named `pageIndex` cannot stomp on the pagination param.
+ * Derived from `PARAM_KEYS` so the two never drift apart.
+ */
+export const RESERVED_PARAM_KEYS = new Set<string>(Object.values(PARAM_KEYS));
+
+const isNonEmptyExpanded = (e: ExpandedState | undefined): boolean =>
+  e !== undefined && (e === true || Object.keys(e).length > 0);
+
+/**
+ * Structural equality for two `ExpandedState`s (each a boolean or an
+ * id -> boolean record). Lets the snapshot skip persisting `expanded` while it
+ * still matches the table's default.
+ */
+const expandedEquals = (
+  a: ExpandedState | undefined,
+  b: ExpandedState | undefined,
+): boolean => {
+  if (a === b) return true;
+  if (typeof a === "boolean" || typeof b === "boolean") return false;
+  if (!a || !b) return false;
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  return aKeys.every((k) => a[k] === b[k]);
+};
+
+/**
+ * Build a `PersistedState` snapshot from current state, omitting empty/default
+ * slices so the persisted blob (URL or storage) stays minimal.
+ * `defaultPageSize` lives on `SnapshotInput` so callers don't need to thread
+ * it as a separate argument - it's part of the snapshot's own context.
+ */
+export function snapshotPersistedState(input: SnapshotInput): PersistedState {
+  const out: PersistedState = {};
+
+  const activeFilters: Record<string, string> = {};
+  for (const [k, v] of Object.entries(input.filterValues)) {
+    if (v) activeFilters[k] = v;
+  }
+  if (Object.keys(activeFilters).length > 0) out.filterValues = activeFilters;
+
+  // Only persist pagination when it actually differs from defaults -
+  // pageSize is always a truthy number so `if (pageSize)` would always fire.
+  if (
+    input.pagination.pageIndex > 0 ||
+    input.pagination.pageSize !== input.defaultPageSize
+  ) {
+    out.pagination = input.pagination;
+  }
+
+  if (input.sorting.length > 0) out.sorting = input.sorting;
+  if (input.columnOrder.length > 0) out.columnOrder = input.columnOrder;
+  if (Object.keys(input.columnVisibility).length > 0) {
+    out.columnVisibility = input.columnVisibility;
+  }
+  if (input.columnPinning.start.length || input.columnPinning.end.length) {
+    out.columnPinning = input.columnPinning;
+  }
+  if (Object.keys(input.columnSizing).length > 0) {
+    out.columnSizing = input.columnSizing;
+  }
+  if (input.grouping.length > 0) out.grouping = input.grouping;
+  // Persist expansion only when it deviates from the default - otherwise the
+  // default (`true` = all groups expanded) writes a noisy `?expanded=true` even
+  // when the user never touched a group.
+  if (
+    isNonEmptyExpanded(input.expanded) &&
+    !expandedEquals(input.expanded, input.defaultExpanded)
+  ) {
+    out.expanded = input.expanded;
+  }
+
+  return out;
+}
+
+/** A pinning side's column ids: an absent side is empty, anything else null. */
+const pinnedIds = (side: unknown): string[] | null =>
+  side === undefined
+    ? []
+    : Array.isArray(side) && side.every((id) => typeof id === "string")
+      ? side
+      : null;
+
+/**
+ * A persisted pinning blob in the shape the table reads, or undefined. The URL
+ * and storage are outside the app's control (a hand-edited link, a blob an
+ * older build wrote), and pinning is read on every render, so a malformed
+ * blob must not reach the table: it is ignored and the default pins stay.
+ * Either side may be left out, but not both.
+ */
+const persistedPinning = (value: unknown): ColumnPinningState | undefined => {
+  if (typeof value !== "object" || value === null) return undefined;
+  const { start, end } = value as Record<string, unknown>;
+  if (start === undefined && end === undefined) return undefined;
+  const startIds = pinnedIds(start);
+  const endIds = pinnedIds(end);
+  return startIds && endIds ? { start: startIds, end: endIds } : undefined;
+};
+
+/**
+ * Apply a `PersistedState` blob back onto the controlled setters. Each slice
+ * is independently optional - partial blobs (e.g. only `sorting`) work fine.
+ * Unknown filter keys from a stale URL/blob are silently ignored, and so is
+ * a pinning blob of the wrong shape.
+ */
+export function applyPersistedState(
+  state: PersistedState,
+  target: ApplyPersistedTarget,
+): void {
+  if (state.filterValues) {
+    const next = { ...target.filterValues };
+    for (const key of target.filterKeys) {
+      const v = state.filterValues[key];
+      if (v !== undefined) next[key] = v;
+    }
+    target.setFilterValues(next);
+  }
+  if (state.pagination) target.setPagination(state.pagination);
+  if (state.sorting) target.setSorting(state.sorting);
+  if (state.columnOrder) target.setColumnOrder(state.columnOrder);
+  if (state.columnVisibility)
+    target.setColumnVisibility(state.columnVisibility);
+  const columnPinning = persistedPinning(state.columnPinning);
+  if (columnPinning) target.setColumnPinning(columnPinning);
+  if (state.columnSizing) target.setColumnSizing(state.columnSizing);
+  if (state.grouping) target.setGrouping(state.grouping);
+  if (state.expanded !== undefined) target.setExpanded(state.expanded);
+}
+
+/**
+ * Decode a URL `?...` query string into a `PersistedState` blob. Flat
+ * encoding, hand-editable. `pageIndex` is stored 1-based for human
+ * readability; `pageSize` falls back to `defaultPageSize` when absent.
+ */
+export function readSearchParams(
+  filterKeys: string[],
+  paramMap: Partial<Record<string, string>>,
+  defaultPageSize: number,
+): PersistedState {
+  const out: PersistedState = {};
+  const params = new URLSearchParams(window.location.search);
+  const p = (k: string) => paramMap[k] ?? k;
+
+  const filterValues: Record<string, string> = {};
+  for (const key of filterKeys) {
+    const raw = params.get(p(key));
+    if (raw !== null) filterValues[key] = raw;
+  }
+  if (Object.keys(filterValues).length > 0) out.filterValues = filterValues;
+
+  const rawPage = params.get(p(PARAM_KEYS.pageIndex));
+  const rawSize = params.get(p(PARAM_KEYS.pageSize));
+  if (rawPage !== null || rawSize !== null) {
+    const pageIndex = rawPage !== null ? Math.max(0, Number(rawPage) - 1) : 0;
+    const pageSize =
+      rawSize !== null && Number.isFinite(Number(rawSize))
+        ? Number(rawSize)
+        : defaultPageSize;
+    out.pagination = {
+      pageIndex: Number.isFinite(pageIndex) ? pageIndex : 0,
+      pageSize,
+    };
+  }
+
+  const rawSortBy = params.get(p(PARAM_KEYS.sortBy));
+  const rawSortDir = params.get(p(PARAM_KEYS.sortDir));
+  if (rawSortBy) {
+    out.sorting = [{ id: rawSortBy, desc: rawSortDir === "desc" }];
+  }
+
+  const rawColOrder = params.get(p(PARAM_KEYS.columnOrder));
+  if (rawColOrder) out.columnOrder = rawColOrder.split(",");
+
+  const tryJson = <T>(key: ParamKey): T | undefined => {
+    const raw = params.get(p(key));
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return undefined;
+    }
+  };
+
+  const colVis = tryJson<ColumnVisibilityState>(PARAM_KEYS.columnVisibility);
+  if (colVis) out.columnVisibility = colVis;
+  const colPin = tryJson<ColumnPinningState>(PARAM_KEYS.columnPinning);
+  if (colPin) out.columnPinning = colPin;
+  const colSize = tryJson<ColumnSizingState>(PARAM_KEYS.columnSizing);
+  if (colSize) out.columnSizing = colSize;
+
+  const rawGrouping = params.get(p(PARAM_KEYS.grouping));
+  if (rawGrouping) out.grouping = rawGrouping.split(",");
+
+  const expanded = tryJson<ExpandedState>(PARAM_KEYS.expanded);
+  if (expanded !== undefined) out.expanded = expanded;
+
+  return out;
+}
+
+/**
+ * The longest query string written to the URL. A reload or a shared link
+ * sends it to the server, and proxies refuse a request line past a few
+ * kilobytes (nginx's default is 8 KB): past this, the open rows leave it.
+ */
+export const MAX_SEARCH_LENGTH = 4000;
+
+/**
+ * Encode a `PersistedState` blob into the URL via `history.replaceState`.
+ * `pageSize` is omitted when it matches `defaultPageSize` so a fresh URL
+ * stays clean; reserved param keys are protected against filter-key collisions.
+ * `expanded` is the one value that grows with use (every row opened adds to
+ * it): once the query string passes `MAX_SEARCH_LENGTH`, it leaves the URL
+ * while the rows stay open on the page, so opening rows never pushes a reload
+ * or a shared link past a proxy's limit.
+ */
+export function writeSearchParams(
+  state: PersistedState,
+  filterKeys: string[],
+  paramMap: Partial<Record<string, string>>,
+  defaultPageSize: number,
+): void {
+  const params = new URLSearchParams(window.location.search);
+  const p = (k: string) => paramMap[k] ?? k;
+
+  // Helper: set a JSON-serialised param or delete it when absent.
+  // Handles all truthy checks uniformly including `false` and `{}` for
+  // `expanded`, which are valid non-default states but would be dropped
+  // by a plain `if (value)` guard.
+  const setJson = (key: ParamKey, value: unknown): void => {
+    if (value !== undefined && value !== null) {
+      params.set(p(key), JSON.stringify(value));
+    } else {
+      params.delete(p(key));
+    }
+  };
+
+  // Filters - every declared filter key must be set or deleted (absent
+  // value === "cleared"). Keys outside the universe are left untouched.
+  const active = state.filterValues ?? {};
+  for (const key of filterKeys) {
+    if (RESERVED_PARAM_KEYS.has(key)) continue;
+    const value = active[key];
+    if (value) params.set(p(key), value);
+    else params.delete(p(key));
+  }
+
+  if (state.pagination && state.pagination.pageIndex > 0) {
+    params.set(p(PARAM_KEYS.pageIndex), String(state.pagination.pageIndex + 1));
+  } else {
+    params.delete(p(PARAM_KEYS.pageIndex));
+  }
+  if (state.pagination && state.pagination.pageSize !== defaultPageSize) {
+    params.set(p(PARAM_KEYS.pageSize), String(state.pagination.pageSize));
+  } else {
+    params.delete(p(PARAM_KEYS.pageSize));
+  }
+
+  const sort = state.sorting?.[0];
+  if (sort) {
+    params.set(p(PARAM_KEYS.sortBy), sort.id);
+    params.set(p(PARAM_KEYS.sortDir), sort.desc ? "desc" : "asc");
+  } else {
+    params.delete(p(PARAM_KEYS.sortBy));
+    params.delete(p(PARAM_KEYS.sortDir));
+  }
+
+  // Guard against empty arrays serialising to "" which reads back as [''].
+  if (state.columnOrder?.length) {
+    params.set(p(PARAM_KEYS.columnOrder), state.columnOrder.join(","));
+  } else {
+    params.delete(p(PARAM_KEYS.columnOrder));
+  }
+
+  setJson(PARAM_KEYS.columnVisibility, state.columnVisibility ?? null);
+  setJson(PARAM_KEYS.columnPinning, state.columnPinning ?? null);
+  setJson(PARAM_KEYS.columnSizing, state.columnSizing ?? null);
+
+  // Same empty-array guard for grouping.
+  if (state.grouping?.length) {
+    params.set(p(PARAM_KEYS.grouping), state.grouping.join(","));
+  } else {
+    params.delete(p(PARAM_KEYS.grouping));
+  }
+
+  // `expanded` can be `false` or `{}` - both are valid and must be preserved.
+  setJson(
+    PARAM_KEYS.expanded,
+    state.expanded !== undefined ? state.expanded : null,
+  );
+  if (params.toString().length > MAX_SEARCH_LENGTH) {
+    params.delete(p(PARAM_KEYS.expanded));
+  }
+
+  const qs = params.toString();
+  window.history.replaceState(
+    null,
+    "",
+    qs ? `${window.location.pathname}?${qs}` : window.location.pathname,
+  );
+}
+
+/** Read a persisted blob from `localStorage` under `storageKey`. */
+export function readLocalStorage(storageKey: string): PersistedState {
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return {};
+    return JSON.parse(raw) as PersistedState;
+  } catch {
+    return {};
+  }
+}
+
+/** Write (or remove, if empty) the persisted blob under `storageKey`. */
+export function writeLocalStorage(
+  storageKey: string,
+  state: PersistedState,
+): void {
+  try {
+    if (Object.keys(state).length === 0) {
+      window.localStorage.removeItem(storageKey);
+    } else {
+      window.localStorage.setItem(storageKey, JSON.stringify(state));
+    }
+  } catch {
+    /* quota exceeded or storage disabled - silently no-op */
+  }
+}
+
+/**
+ * Order a pinning state around its anchors: the select column first at the
+ * start when rows are selectable, then the default start pins, then the rest;
+ * at the end, the default end pins stay on the outer edge with newer pins
+ * inside them. Undefined when nothing is pinned and nothing anchors a pin.
+ */
+export function normalizeColumnPinningState(
+  pinning: ColumnPinningState | undefined,
+  pinSelectionColumn: boolean,
+  defaultColumnPinning?: Partial<ColumnPinningState>,
+): ColumnPinningState | undefined {
+  const start = pinning?.start ?? [];
+  const end = pinning?.end ?? [];
+
+  const defaultStart = defaultColumnPinning?.start ?? [];
+  const defaultEnd = defaultColumnPinning?.end ?? [];
+
+  const anchoredStart =
+    pinSelectionColumn && !defaultStart.includes(SELECT_COLUMN_ID)
+      ? [SELECT_COLUMN_ID, ...defaultStart]
+      : defaultStart;
+
+  const finalStart =
+    pinSelectionColumn && !start.includes(SELECT_COLUMN_ID)
+      ? [SELECT_COLUMN_ID, ...start]
+      : start;
+
+  if (!pinning && anchoredStart.length === 0 && defaultEnd.length === 0) {
+    return undefined;
+  }
+
+  // Use a Set for O(n) lookup instead of repeated Array.includes (O(n²)).
+  const anchoredStartSet = new Set(anchoredStart);
+  const defaultEndSet = new Set(defaultEnd);
+  return {
+    start: [
+      ...anchoredStart.filter((id) => finalStart.includes(id)),
+      ...finalStart.filter((id) => !anchoredStartSet.has(id)),
+    ],
+    end: [
+      ...end.filter((id) => !defaultEndSet.has(id)),
+      ...defaultEnd.filter((id) => end.includes(id)),
+    ],
+  };
+}
+
+/** Where a filter sits: its own placement, or `auto`. */
+export const placementOf = (field: FilterField): FilterPlacement =>
+  field.placement ?? "auto";
+
+/** An input filter's value: what it holds, or its default until someone sets it. */
+const filterValueOf = (
+  field: FilterInputField,
+  values: Record<string, string>,
+): string => values[field.key] ?? field.defaultValue ?? "";
+
+/** Whether an input filter holds something other than its default. */
+export const isFilterSet = (
+  field: FilterInputField,
+  values: Record<string, string>,
+): boolean => filterValueOf(field, values) !== (field.defaultValue ?? "");
+
+/** A filter's control: an action as it renders, a field with its value. */
+export const renderFilter = (
+  field: FilterField,
+  values: Record<string, string>,
+  onChange: (key: string, value: string) => void,
+): ReactNode =>
+  field.type === "action"
+    ? field.render()
+    : field.render({
+        value: filterValueOf(field, values),
+        onChange: (value) => onChange(field.key, value),
+      });