@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/src/{tmdatagrid/core → core}/filterControls.ts

@@ -34,8 +34,36 @@ export type TMDataGridFilterControlArgs = {
   options: ReadonlyArray<TMDataGridOption>;
   size: TMDataGridSize;
   labels: TMDataGridLabels;
+  /**
+   * How much room the control has, and whether it names itself. The same
+   * vocabulary as `TMDataGrid.FilterPanel`'s own `layout` prop, plus the one
+   * value only a header cell can be in.
+   *
+   * | Layout | Where | Field |
+   * | --- | --- | --- |
+   * | `"row"` | A filter row laid out side by side | Labelled, fixed width |
+   * | `"stacked"` | A filter row in a narrow host - the sidebar | Labelled, full width |
+   * | `"header"` | One header cell, under `filters.inHeader` | `aria-label`, full width |
+   *
+   * Every built-in control honours it. A custom control that ignores it still
+   * works - it will simply look the same everywhere.
+   */
+  layout: TMDataGridFilterControlLayout;
 };
 
+/** How much room a filter control has. See `layout`. */
+export type TMDataGridFilterControlLayout = "row" | "stacked" | "header";
+
+/**
+ * The two a filter *panel* can be in - {@link TMDataGridFilterControlLayout}
+ * without the header cell, which is not a panel. `TMDataGrid.FilterPanel`'s
+ * `layout` prop.
+ */
+export type TMDataGridFilterPanelLayout = Exclude<
+  TMDataGridFilterControlLayout,
+  "header"
+>;
+
 /**
  * `meta.filter.control` - replaces the built-in value control for this column.
  * Rendered as JSX, never invoked as a bare function, so hooks are legal
@@ -58,10 +86,19 @@ export type TMDataGridFilterControlComponent =
  * declaration of each feeds the filter panel and the cell editor alike.
  */
 export type TMDataGridColumnFilterOptions = {
+  /**
+   * The operators this column offers, a subset of the type's own. For a
+   * column backed by an endpoint that answers only some of them - `contains`
+   * and `equals`, say - so the panel and the header funnel never offer an
+   * operator the query cannot express. Kept in the type's order; one the type
+   * does not offer is ignored, and a list that leaves nothing falls back to
+   * the type's full set.
+   */
+  operators?: readonly TMDataGridFilterOperator[];
   /**
    * The operator a fresh filter on this column starts with, instead of the
    * type's default - a salary column can open on `"between"`. Must be one of
-   * the type's own operators.
+   * the operators the column offers.
    */
   defaultOperator?: TMDataGridFilterOperator;
   /**

package/src/{tmdatagrid/core → core}/filterOperators.ts

@@ -1,4 +1,10 @@
-import type { Row, RowData, TableFeatures } from "@tanstack/react-table";
+import type {
+  ColumnFiltersState,
+  Row,
+  RowData,
+  TableFeatures,
+} from "@tanstack/react-table";
+import type { TMDataGridTable } from "../useTMDataGrid";
 
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -210,6 +216,25 @@ export function isTMDataGridFilterValue(
   );
 }
 
+/**
+ * The three value shapes an operator can take. A set is not a range, even
+ * though both are arrays.
+ */
+export type TMDataGridFilterValueShape = "scalar" | "set" | "range";
+
+/**
+ * Which shape an operator's value takes. A typed value survives an operator or
+ * column change only within its shape, which is the rule both the panel and
+ * the header controls use when the operator changes.
+ */
+export function filterValueShape(
+  operator: TMDataGridFilterOperator,
+): TMDataGridFilterValueShape {
+  if (operatorTakesArrayValue(operator)) return "set";
+  if (operatorTakesRangeValue(operator)) return "range";
+  return "scalar";
+}
+
 /**
  * A filter only narrows the row set once it has something to compare against.
  * Half-typed filters stay in state (so the panel keeps rendering their row) but
@@ -225,6 +250,44 @@ export function isFilterActive(value: unknown): boolean {
     : typeof value.value === "string" && value.value.trim() !== "";
 }
 
+/** One column's filter, typed - what `columnFilters` holds per entry. */
+export type TMDataGridColumnFilter = {
+  id: string;
+  value: TMDataGridFilterValue;
+};
+
+/**
+ * The column filters that are actually narrowing the grid, typed.
+ *
+ * `ColumnFiltersState` types `value` as `unknown`, so the first line of a
+ * server-side mapping layer is otherwise a cast back to the shape the grid
+ * itself wrote, wrapped in the same "drop the half-typed ones" filter every
+ * consumer writes:
+ *
+ * ```ts
+ * const predicates = activeColumnFilters(table).map((filter) =>
+ *   toPredicate(filter.id, filter.value),
+ * );
+ * ```
+ *
+ * Takes the table, or a `columnFilters` array where the consumer owns the
+ * slice. Reading it from the table reads the current value and does not
+ * subscribe; inside a component, subscribe to `columnFilters` the way the
+ * grid's own chrome does.
+ */
+export function activeColumnFilters<TData extends RowData>(
+  source: TMDataGridTable<TData> | ColumnFiltersState,
+): Array<TMDataGridColumnFilter> {
+  const columnFilters = Array.isArray(source)
+    ? source
+    : source.store.state.columnFilters;
+  return columnFilters.flatMap((entry) =>
+    isTMDataGridFilterValue(entry.value) && isFilterActive(entry.value)
+      ? [{ id: entry.id, value: entry.value }]
+      : [],
+  );
+}
+
 /**
  * One-line description of a single filter, as shown on a filter pill.
  *

package/src/core/filterSurface.ts

@@ -0,0 +1,99 @@
+/**
+ * Where the grid puts its filter controls.
+ *
+ * | Surface | Where it renders |
+ * | --- | --- |
+ * | `"popup"` | Floating over the first body rows, under the header |
+ * | `"sidebar"` | Beside the table, inside the grid frame |
+ * | `"none"` | Nowhere - the grid renders no panel of its own |
+ *
+ * Header filters are not one of these: they are a second row of controls in
+ * the header, always visible, and they coexist with any of the three. See
+ * {@link TMDataGridFiltersOptions.inHeader}.
+ */
+export type TMDataGridFilterSurface = "popup" | "sidebar" | "none";
+
+/** Which side of the table the sidebar surface renders on. */
+export type TMDataGridFilterSidebarSide = "left" | "right";
+
+/**
+ * `filters` on `useTMDataGrid` - everything about where the filter controls
+ * are, as opposed to what they do.
+ *
+ * Named for the option key, the way `editing` has `TMDataGridEditingOptions`.
+ * Not to be confused with `TMDataGridColumnFilterOptions`, which is one
+ * column's `meta.filter`.
+ *
+ * ```tsx
+ * useTMDataGrid({ data, columns, filters: { surface: "sidebar" } });
+ * ```
+ */
+export type TMDataGridFiltersOptions = {
+  /**
+   * Which surface `TMDataGrid.Table` renders and `TMDataGrid.FilterButton`
+   * toggles. Defaults to `"popup"`.
+   *
+   * Under `"none"` the table renders no panel and the filter button renders
+   * nothing. That is what a grid running header filters alone wants, and it is
+   * also what frees a hand-placed `<TMDataGrid.FilterPanel />` to be the only
+   * panel on the page - mounted, it is always visible, so drive it off
+   * `ui.state.filterPanelOpen` if it belongs behind a control of your own.
+   */
+  surface?: TMDataGridFilterSurface;
+  /** Which side the `"sidebar"` surface sits on. Defaults to `"right"`. */
+  sidebarSide?: TMDataGridFilterSidebarSide;
+  /** Width of the `"sidebar"` surface, any CSS length. Defaults to `"280px"`. */
+  sidebarWidth?: string;
+  /**
+   * Whether the popup or the sidebar starts open. Read once, at mount, like
+   * `initialState`.
+   *
+   * Defaults to `true` under `"sidebar"` and `false` everywhere else: a
+   * sidebar is a layout choice, so asking for one and getting an empty strip
+   * until the funnel is clicked is not what it reads like, while a popup that
+   * greets you open is in the way.
+   *
+   * Under `"none"` it is simply the starting value of
+   * `ui.state.filterPanelOpen`, which a control of your own can read.
+   */
+  defaultOpen?: boolean;
+  /**
+   * A second header row holding one value control per filterable column,
+   * always visible. Off by default.
+   *
+   * Independent of `surface` - a grid may have header filters and a popup at
+   * once. What it does change is the column chrome: the header's funnel
+   * indicator and the column menu's "Filter" item both come off, because
+   * their only job was to reveal a control that is now already on screen.
+   *
+   * A header cell has room for a value and an operator button, not for the
+   * panel's column / operator / value triple. Everything else about a filter
+   * is unchanged - the same operators, the same `meta.filter.control`, the
+   * same `columnFilters` state.
+   */
+  inHeader?: boolean;
+};
+
+/** {@link TMDataGridFiltersOptions} with every default filled in. */
+export type TMDataGridFiltersSettings = Required<TMDataGridFiltersOptions>;
+
+/**
+ * Fills the defaults in. Field by field rather than by spreading, so an
+ * explicit `undefined` - which is what destructuring an absent option group
+ * hands over - reads as "not set" rather than overwriting the default with it.
+ *
+ * `defaultOpen` is the one default that is not a constant: it follows the
+ * surface, so there is no flat table of defaults to export.
+ */
+export function resolveFilterOptions(
+  options: TMDataGridFiltersOptions = {},
+): TMDataGridFiltersSettings {
+  const surface = options.surface ?? "popup";
+  return {
+    surface,
+    sidebarSide: options.sidebarSide ?? "right",
+    sidebarWidth: options.sidebarWidth ?? "280px",
+    defaultOpen: options.defaultOpen ?? surface === "sidebar",
+    inHeader: options.inHeader ?? false,
+  };
+}

package/src/{tmdatagrid/core → core}/labels.ts

@@ -17,14 +17,18 @@ export type TMDataGridLabels = {
   operators: Record<TMDataGridFilterOperator, string>;
 
   // Toolbar
-  /** "Manage columns" - the burger button and the header menu item. */
-  manageColumns: string;
   /** "Filters" - the funnel button and the filter panel's title. */
   filters: string;
   searchPlaceholder: string;
   searchLabel: string;
   clearSearch: string;
 
+  // Grid menu
+  /** Tooltip and `aria-label` of `TMDataGrid.Menu`'s burger trigger. */
+  menuButton: string;
+  /** "Manage columns" - the header menu's submenu. */
+  manageColumns: string;
+
   // Columns panel
   columnsSearchPlaceholder: string;
   columnsNoMatch: (search: string) => string;
@@ -58,6 +62,8 @@ export type TMDataGridLabels = {
   clearAllFilters: string;
   closeFilters: string;
   removeFilter: string;
+  /** Names the operator button in a column's header filter control. */
+  filterOperatorFor: (column: string) => string;
 
   // Filter pills
   activeFilters: string;
@@ -85,6 +91,8 @@ export type TMDataGridLabels = {
   // Footer / pager
   rowsPerPage: string;
   pageRange: (args: { from: number; to: number; total: number }) => string;
+  /** `pageCount` is `-1` when a manual grid declares an unknown total. */
+  pageNumber: (args: { page: number; pageCount: number }) => string;
   groupedAllRows: (total: number) => string;
   pagingSuspendedHint: string;
   previousPage: string;
@@ -111,10 +119,15 @@ export type TMDataGridLabels = {
   cancelRowEdit: string;
   /** Save tooltip when field errors block the row, with no row message. */
   editRowErrors: string;
-  /** `EditActions`' Save, with the dirty-row count. */
+  /** `DraftActions`' Save, with the count of rows in the draft store. */
   saveAllEdits: (rows: number) => string;
-  /** `EditActions`' Discard. */
+  /** `DraftActions`' Discard. */
   discardAllEdits: string;
+  /**
+   * `DraftActions`' note about rows still open - edited but not committed, so
+   * not part of the save. Shown only while there are any.
+   */
+  editRowsStillOpen: (rows: number) => string;
   /** The entry row's ✓ - commit the add. */
   confirmNewRow: string;
   /** The entry row's ✕ - drop the entry. */
@@ -135,9 +148,27 @@ export type TMDataGridLabels = {
   // Cell selection menu
   cellCount: (count: number) => string;
   copy: string;
-  exportCsv: string;
+  exportCells: string;
+  /** @deprecated Use `exportCells`. Read as its fallback for one beta. */
+  exportCsv?: string;
   includeHeaders: string;
 
+  // Export
+  exportAll: string;
+  exportSelected: (count: number) => string;
+  /** Title of the column picker `columns="custom"` opens; `format` is the file extension in upper case, "CSV". */
+  exportPickerTitle: (format: string) => string;
+  /** The line under the title; `selected` is the selected row count, or `null` for an export of all rows. */
+  exportPickerHint: (selected: number | null) => string;
+  exportPickerConfirm: string;
+  exportPickerCancel: string;
+  /** The select-all row over the picker's list. */
+  exportPickerSelectAll: string;
+  /** The "3 of 12" count beside it. */
+  exportPickerCount: (checked: number, total: number) => string;
+  /** Marks a column the grid hides at the moment. */
+  exportPickerHidden: string;
+
   // Generated checkbox lane
   selectColumnLabel: string;
   selectAllRows: string;
@@ -172,16 +203,18 @@ export type TMDataGridLabelsOverride = Partial<
 export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   operators: FILTER_OPERATOR_LABELS,
 
-  manageColumns: "Manage columns",
   filters: "Filters",
   searchPlaceholder: "Search",
   searchLabel: "Search rows",
   clearSearch: "Clear search",
 
+  menuButton: "Menu",
+  manageColumns: "Manage columns",
+
   columnsSearchPlaceholder: "Search",
   columnsNoMatch: (search) => `No columns match “${search}”`,
   columnsShowHideAll: "Show/Hide All",
-  columnsReset: "RESET LAYOUT",
+  columnsReset: "Reset layout",
   columnsResetHint:
     "Resets column visibility, order, widths, pinning and grouping",
   rowNumberColumnLabel: "Row number",
@@ -200,6 +233,7 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   clearAllFilters: "Clear all",
   closeFilters: "Close filters",
   removeFilter: "Remove filter",
+  filterOperatorFor: (column) => `${column} filter operator`,
 
   activeFilters: "Active filters",
   clearFilter: (column) => `Clear ${column} filter`,
@@ -224,6 +258,8 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
 
   rowsPerPage: "Rows per page:",
   pageRange: ({ from, to, total }) => `${from}–${to} of ${total}`,
+  pageNumber: ({ page, pageCount }) =>
+    pageCount < 0 ? `Page ${page}` : `Page ${page} of ${pageCount}`,
   groupedAllRows: (total) => `Grouped · all ${total} rows`,
   pagingSuspendedHint:
     "Paging is off while the rows are grouped: the whole tree is rendered and virtualized. Ungroup to page again.",
@@ -243,6 +279,8 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   editRowErrors: "Fix the marked cells",
   saveAllEdits: (rows) => (rows === 1 ? "Save 1 row" : `Save ${rows} rows`),
   discardAllEdits: "Discard",
+  editRowsStillOpen: (rows) =>
+    rows === 1 ? "1 row still being edited" : `${rows} rows still being edited`,
   confirmNewRow: "Add row",
   discardNewRow: "Discard new row",
   deleteRow: "Delete row",
@@ -254,9 +292,25 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
 
   cellCount: (count) => (count === 1 ? "1 cell" : `${count} cells`),
   copy: "Copy",
-  exportCsv: "Export as CSV for Excel",
+  exportCells: "Export cells",
   includeHeaders: "Include headers",
 
+  exportAll: "Export all rows",
+  exportSelected: (count) =>
+    count === 1 ? "Export 1 selected row" : `Export ${count} selected rows`,
+  exportPickerTitle: (format) => `Export as ${format}`,
+  exportPickerHint: (selected) =>
+    selected === null
+      ? "Select the columns to export"
+      : selected === 1
+        ? "Select the columns to export for the selected row"
+        : `Select the columns to export for the ${selected} selected rows`,
+  exportPickerConfirm: "Export",
+  exportPickerCancel: "Cancel",
+  exportPickerSelectAll: "Select all",
+  exportPickerCount: (checked, total) => `${checked} of ${total}`,
+  exportPickerHidden: "Hidden",
+
   selectColumnLabel: "Checkbox selection",
   selectAllRows: "Select all rows",
   selectRow: "Select row",
@@ -282,6 +336,10 @@ export function mergeLabels(
   return {
     ...TMDATAGRID_LABELS_EN,
     ...override,
+    exportCells:
+      override.exportCells ??
+      override.exportCsv ??
+      TMDATAGRID_LABELS_EN.exportCells,
     operators: {
       ...TMDATAGRID_LABELS_EN.operators,
       ...override.operators,

package/src/{tmdatagrid/core → core}/labelsSv.ts

@@ -32,16 +32,18 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
     isNotEmpty: "är inte tom",
   },
 
-  manageColumns: "Hantera kolumner",
   filters: "Filter",
   searchPlaceholder: "Sök",
   searchLabel: "Sök rader",
   clearSearch: "Rensa sökningen",
 
+  menuButton: "Meny",
+  manageColumns: "Hantera kolumner",
+
   columnsSearchPlaceholder: "Sök",
   columnsNoMatch: (search) => `Inga kolumner matchar ”${search}”`,
   columnsShowHideAll: "Visa/dölj alla",
-  columnsReset: "ÅTERSTÄLL LAYOUT",
+  columnsReset: "Återställ layout",
   columnsResetHint:
     "Återställer kolumnernas synlighet, ordning, bredder, fästning och gruppering",
   rowNumberColumnLabel: "Radnummer",
@@ -60,6 +62,7 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
   clearAllFilters: "Rensa alla",
   closeFilters: "Stäng filter",
   removeFilter: "Ta bort filter",
+  filterOperatorFor: (column) => `Filteroperator för ${column}`,
 
   activeFilters: "Aktiva filter",
   clearFilter: (column) => `Rensa filtret för ${column}`,
@@ -84,6 +87,8 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
 
   rowsPerPage: "Rader per sida:",
   pageRange: ({ from, to, total }) => `${from}–${to} av ${total}`,
+  pageNumber: ({ page, pageCount }) =>
+    pageCount < 0 ? `Sida ${page}` : `Sida ${page} av ${pageCount}`,
   groupedAllRows: (total) => `Grupperad · alla ${total} rader`,
   pagingSuspendedHint:
     "Sidindelningen är avstängd medan raderna är grupperade: hela trädet renderas och virtualiseras. Avgruppera för att bläddra igen.",
@@ -103,6 +108,8 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
   editRowErrors: "Åtgärda de markerade cellerna",
   saveAllEdits: (rows) => (rows === 1 ? "Spara 1 rad" : `Spara ${rows} rader`),
   discardAllEdits: "Förkasta",
+  editRowsStillOpen: (rows) =>
+    rows === 1 ? "1 rad redigeras fortfarande" : `${rows} rader redigeras fortfarande`,
   confirmNewRow: "Lägg till rad",
   discardNewRow: "Släng ny rad",
   deleteRow: "Ta bort rad",
@@ -114,9 +121,25 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
 
   cellCount: (count) => (count === 1 ? "1 cell" : `${count} celler`),
   copy: "Kopiera",
-  exportCsv: "Exportera som CSV för Excel",
+  exportCells: "Exportera celler",
   includeHeaders: "Inkludera rubriker",
 
+  exportAll: "Exportera alla rader",
+  exportSelected: (count) =>
+    count === 1 ? "Exportera 1 vald rad" : `Exportera ${count} valda rader`,
+  exportPickerTitle: (format) => `Exportera som ${format}`,
+  exportPickerHint: (selected) =>
+    selected === null
+      ? "Välj kolumner att exportera"
+      : selected === 1
+        ? "Välj kolumner att exportera för den valda raden"
+        : `Välj kolumner att exportera för de ${selected} valda raderna`,
+  exportPickerConfirm: "Exportera",
+  exportPickerCancel: "Avbryt",
+  exportPickerSelectAll: "Markera alla",
+  exportPickerCount: (checked, total) => `${checked} av ${total}`,
+  exportPickerHidden: "Dold",
+
   selectColumnLabel: "Kryssrutemarkering",
   selectAllRows: "Markera alla rader",
   selectRow: "Markera rad",

package/src/core/pageReset.ts

@@ -0,0 +1,120 @@
+import {
+  functionalUpdate,
+  makeStateUpdater,
+  type TableState,
+  type Updater,
+} from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { sameStateValue } from "./controlledState";
+import { isFilterActive, isTMDataGridFilterValue } from "./filterOperators";
+
+/**
+ * Sends a server-paged grid back to the first page when the query changes.
+ *
+ * Under `manualPagination` the grid does not own the result set, so a column
+ * filter, the quick search or a sort leaves `pageIndex` pointing into a page
+ * range that no longer exists: the next request asks the server for page 8 of
+ * a result set that now has three, and the consumer gets an empty grid with
+ * no error.
+ *
+ * TanStack's `autoResetPageIndex` does not cover it. It defaults to
+ * `!manualPagination`, so it is off exactly when this is needed, and it fires
+ * on a data change - which server-side is the response landing, one request
+ * too late.
+ *
+ * The reset rides on the slice's own change callback rather than on an effect
+ * over table state, so both writes land in the same render and the query goes
+ * out once. From an effect the request for the stale page would leave first.
+ */
+
+/**
+ * The state a query is built from, plus grouping: paging is suspended while
+ * a column is grouped, and the page it hands back on the way out was
+ * measured over the ungrouped rows before the group was made.
+ */
+export type TMDataGridQuerySlice =
+  | "columnFilters"
+  | "globalFilter"
+  | "sorting"
+  | "grouping";
+
+/** What the reset reads and writes - the table, narrowed to that. */
+export type TMDataGridQueryTable = {
+  store: { state: TableState<TMDataGridFeatures> };
+  setPageIndex: (index: number) => void;
+};
+
+type QueryHandler = (updater: never) => void;
+
+type ColumnFilters = TableState<TMDataGridFeatures>["columnFilters"];
+
+/**
+ * The entries the server could answer differently. Only the grid's own
+ * `{ operator, value }` shape can be recognised as "still empty" - anything
+ * else, a custom filter control's raw value or state restored from a URL,
+ * narrows the grid as far as this module can know, so it always counts.
+ */
+function querySignificantFilters(filters: ColumnFilters): ColumnFilters {
+  return filters.filter(
+    (entry) =>
+      !isTMDataGridFilterValue(entry.value) || isFilterActive(entry.value),
+  );
+}
+
+/**
+ * Whether the server would answer the next state differently.
+ *
+ * A column filter with an empty value matches every row, so it is not part of
+ * the query: opening the filter panel seeds a row on the first filterable
+ * column, and the user then types into it. Neither moves the result set, and
+ * neither may throw away the page the user is on.
+ */
+function changesTheQuery(
+  slice: TMDataGridQuerySlice,
+  previous: unknown,
+  next: unknown,
+): boolean {
+  if (slice === "columnFilters") {
+    return !sameStateValue(
+      querySignificantFilters(previous as ColumnFilters),
+      querySignificantFilters(next as ColumnFilters),
+    );
+  }
+  return !sameStateValue(previous, next);
+}
+
+/**
+ * Wraps one slice's change callback. `handler` is the consumer's, where they
+ * control the slice; without one the write is the same `makeStateUpdater`
+ * TanStack would have defaulted to, which this option replaces.
+ */
+export function withPageReset(
+  slice: TMDataGridQuerySlice,
+  handler: QueryHandler | undefined,
+  getTable: () => TMDataGridQueryTable,
+): QueryHandler {
+  return (updater) => {
+    const table = getTable();
+    const previous = table.store.state[slice];
+    // Resolved here rather than read back off the table afterwards: where the
+    // consumer owns the slice the write is their `setState`, so the table
+    // still holds the old value when this returns. The updater therefore runs
+    // twice per change - once here, once in the write path - which is safe
+    // for every updater the grid and table-core produce, and a requirement on
+    // the consumer's: an updater has to be a pure derivation of the previous
+    // value. The decision is also best-effort under batching: two writes to
+    // one slice in the same tick both read the same `previous`, so the second
+    // decision is computed from a stale base. A wrong reset decision at
+    // worst, never a wrong write.
+    const next = functionalUpdate(updater as Updater<unknown>, previous);
+
+    (handler ?? (makeStateUpdater(slice, table as never) as QueryHandler))(
+      updater,
+    );
+
+    if (!changesTheQuery(slice, previous, next)) return;
+    // Already on the first page: writing anyway would publish the store and
+    // re-render the grid for a value that did not move.
+    if (table.store.state.pagination.pageIndex !== 0) table.setPageIndex(0);
+  };
+}

package/src/{tmdatagrid/core → core}/persistence.ts

@@ -188,12 +188,26 @@ const SLICE_GUARDS: Record<
     isRecordOf(value, (entry) => typeof entry === "boolean"),
   columnSizing: (value) => isRecordOf(value, isFiniteNumber),
   columnOrder: (value) => isArrayOf(value, isString),
+  // Both the current logical shape and the physical one 1.x wrote.
   columnPinning: (value) =>
-    isArrayOf(prop(value, "left"), isString) &&
-    isArrayOf(prop(value, "right"), isString),
+    (isArrayOf(prop(value, "start"), isString) &&
+      isArrayOf(prop(value, "end"), isString)) ||
+    (isArrayOf(prop(value, "left"), isString) &&
+      isArrayOf(prop(value, "right"), isString)),
   grouping: (value) => isArrayOf(value, isString),
 };
 
+/**
+ * Settings saved by 1.x used TanStack's old physical `columnPinning` keys.
+ * Rewrite them once on read, so nothing downstream sees `left` / `right`.
+ */
+function normalizeColumnPinning(value: unknown): unknown {
+  const left = prop(value, "left");
+  const right = prop(value, "right");
+  if (left === undefined || right === undefined) return value;
+  return { start: left, end: right };
+}
+
 function isValidSlice(slice: keyof GridState, value: unknown): boolean {
   const guard = SLICE_GUARDS[slice as keyof typeof SLICE_GUARDS];
   return guard === undefined || guard(value);
@@ -219,7 +233,10 @@ function readSlices(
     for (const slice of resolved.slices) {
       if (!(slice in record)) continue;
       if (!isValidSlice(slice, record[slice])) continue;
-      restored[slice] = record[slice];
+      restored[slice] =
+        slice === "columnPinning"
+          ? normalizeColumnPinning(record[slice])
+          : record[slice];
     }
     return restored as Partial<GridState>;
   } catch {
@@ -323,8 +340,8 @@ function realignToColumns(
   }
   if (restored.columnPinning) {
     realigned.columnPinning = {
-      left: keepIds(restored.columnPinning.left ?? []),
-      right: keepIds(restored.columnPinning.right ?? []),
+      start: keepIds(restored.columnPinning.start ?? []),
+      end: keepIds(restored.columnPinning.end ?? []),
     };
   }
   if (restored.sorting) realigned.sorting = keepEntries(restored.sorting);