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

package/src/{tmdatagrid/useTMDataGrid.tsx → useTMDataGrid.tsx}

@@ -1,4 +1,5 @@
-import { useCreateStore } from "@tanstack/react-store";
+import { useCreateStore, useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
 import {
   aggregationFns,
   type ColumnDef,
@@ -23,6 +24,7 @@ import {
   metaHelper,
   type Row,
   type RowData,
+  rowAggregationFeature,
   rowExpandingFeature,
   rowPaginationFeature,
   rowPinningFeature,
@@ -51,13 +53,15 @@ import {
   createEditEngine,
   type TMDataGridEditApi,
   type TMDataGridEditCommitArgs,
-  type TMDataGridEditCommitDraftsArgs,
+  type TMDataGridSaveDraftsArgs,
+  type TMDataGridSaveDraftsResult,
   type TMDataGridEditEngineContext,
   type TMDataGridColumnEditOptions,
   type TMDataGridEditMode,
   type TMDataGridRowAddArgs,
   type TMDataGridRowDeleteArgs,
   type TMDataGridRowValidators,
+  type TMDataGridTableValidators,
 } from "./core/editEngine";
 import {
   emptyValueForOperator,
@@ -66,6 +70,11 @@ import {
 } from "./core/filterOperators";
 import { getColumnDefaultOperator, isControlColumn } from "./core/columnUtils";
 import type { TMDataGridColumnFilterOptions } from "./core/filterControls";
+import {
+  resolveFilterOptions,
+  type TMDataGridFiltersOptions,
+  type TMDataGridFiltersSettings,
+} from "./core/filterSurface";
 import {
   createFuzzyRankedSortedRowModel,
   fuzzyGlobalFilterFn,
@@ -93,7 +102,29 @@ import {
   isSameCell,
   type TMDataGridCellPosition,
 } from "./core/cellNavigation";
+import {
+  findFrozenStateSlices,
+  stabilizeControlledState,
+  withoutUndefinedSlices,
+} from "./core/controlledState";
+import {
+  beginControlledStateSync,
+  deferControlledStateSyncPublishes,
+  endControlledStateSync,
+} from "./core/controlledStateSync";
+import { registerDeletedRows } from "./core/deletedRows";
+import {
+  withPageReset,
+  type TMDataGridQueryTable,
+} from "./core/pageReset";
 import type { TMDataGridCellRange } from "./core/cellRange";
+import {
+  resolveExportOptions,
+  type TMDataGridExportOptions,
+  type TMDataGridExportPickerRequest,
+  type TMDataGridExportSettings,
+  type TMDataGridExportValueGetter,
+} from "./core/export";
 import {
   createSelectColumn,
   SELECT_COLUMN_ID,
@@ -164,8 +195,8 @@ export type TMDataGridColumnMeta = {
    */
   enableOrdering?: boolean;
   /**
-   * How this column filters: the operator a fresh filter starts with, and the
-   * value control the filter panel renders for it.
+   * How this column filters: which operators it offers, the operator a fresh
+   * filter starts with, and the value control the filter panel renders for it.
    *
    * ```tsx
    * meta: {
@@ -192,6 +223,25 @@ export type TMDataGridColumnMeta = {
    * See {@link TMDataGridColumnEditOptions}.
    */
   edit?: TMDataGridColumnEditOptions;
+  /**
+   * `false` leaves the column out of every export and out of Ctrl+C - for a
+   * column of buttons, or one whose value means nothing outside the grid.
+   * Defaults to `true`.
+   */
+  enableExport?: boolean;
+  /**
+   * The value an export writes for this column, in place of
+   * `row.getValue(column.id)`. The export otherwise writes the value, never
+   * what the cell renders, so this is where a status code becomes its label
+   * or a nested object becomes one field.
+   *
+   * ```tsx
+   * meta: {
+   *   exportValue: ({ value }) => STATUS_LABELS[value as Status],
+   * }
+   * ```
+   */
+  exportValue?: TMDataGridExportValueGetter;
 };
 
 /** Grid-wide configuration passed through `options.meta`. */
@@ -224,6 +274,7 @@ export const tmDataGridFeatures = tableFeatures({
   columnResizingFeature,
   columnFacetingFeature,
   columnGroupingFeature,
+  rowAggregationFeature,
   // Registered for grouping's sake rather than for tree data: the grouped row
   // model builds the parent rows, and this is what flattens the expanded ones
   // back into the flat list the body virtualizes.
@@ -287,6 +338,9 @@ const DEFAULT_DETAILS_EST_HEIGHT = 160;
 /** Rows kept mounted on each side of the viewport. See `overscan`. */
 const DEFAULT_OVERSCAN = 6;
 
+/** One empty array, so a selector answering "none" never changes identity. */
+const EMPTY_IDS: ReadonlyArray<string> = [];
+
 /**
  * Chrome state that is *not* table state: which panels are open, and which
  * column opened the filter panel. Kept in a TanStack Store so consumers can
@@ -294,9 +348,20 @@ const DEFAULT_OVERSCAN = 6;
  */
 export type TMDataGridUiState = {
   filterPanelOpen: boolean;
-  columnsPanelOpen: boolean;
-  /** Column whose filter row should be focused when the panel opens. */
+  /**
+   * Column whose *panel* row should take the focus. Cleared once the row has
+   * taken it, so pointing at the same column twice focuses twice.
+   */
   filterPanelColumnId: string | null;
+  /**
+   * Column whose *header filter* control should take the focus, under
+   * `filters.inHeader`. Cleared once taken, like the one above.
+   *
+   * Its own slot rather than a second reader of `filterPanelColumnId`: a grid
+   * can have header filters and a panel at once, and two controls racing to
+   * answer one id means whichever mounted last wins the caret.
+   */
+  headerFilterColumnId: string | null;
   /**
    * Column being dragged by its header, if any. Held here rather than read from
    * `dataTransfer`, which browsers keep unreadable until the drop.
@@ -335,13 +400,33 @@ export type TMDataGridUiState = {
    * describe different places.
    */
   cellRange: TMDataGridCellRange | null;
+  /**
+   * The export column picker, while it is open: which rows it exports and the
+   * options of the item that opened it. `null` while closed. Held here rather
+   * than in the menu item, which unmounts with the dropdown the moment it is
+   * clicked.
+   */
+  exportPicker: TMDataGridExportPickerRequest | null;
 };
 
 export type TMDataGridUiActions = {
   openFilterPanel: (columnId?: string | null) => void;
   closeFilterPanel: () => void;
-  setColumnsPanelOpen: (open: boolean) => void;
-  toggleColumnsPanel: () => void;
+  /** Opens the export column picker for `request`. See `TMDataGrid.Menu.Export`'s `columns="custom"`. */
+  openExportPicker: (request: TMDataGridExportPickerRequest) => void;
+  closeExportPicker: () => void;
+  /**
+   * Points at a column's row in the filter panel without opening anything.
+   * `openFilterPanel` does this as well as opening; this is the half a panel
+   * that is already showing needs.
+   */
+  focusPanelFilter: (columnId: string | null) => void;
+  /**
+   * Points at a column's header filter control - what `openColumnFilter` does
+   * under `filters.inHeader`, where there is no panel to open. The header row
+   * scrolls the column into view and focuses it.
+   */
+  focusHeaderFilter: (columnId: string | null) => void;
   startColumnDrag: (columnId: string) => void;
   endColumnDrag: () => void;
   /**
@@ -387,12 +472,27 @@ export type TMDataGridApi<TData extends RowData> = {
   /**
    * The edit engine - open forms, dirty/error projections, and the verbs
    * (`begin`, `commit`, `cancel`, `submitAll`). `edit.getForm(rowId)` hands
-   * out the same TanStack Form the inline editors write through, so a drawer
-   * or detail panel can share a row's draft. Inert until `editing` is set.
+   * out the same TanStack Form the inline editors write through while a row
+   * is open, so a drawer or detail panel can share a row's draft; a
+   * committed row has no form until `begin` reopens it. Inert until
+   * `editing` is set.
    */
-  edit: TMDataGridEditApi;
+  edit: TMDataGridEditApi<TData>;
   /** Table-level feature switches, re-read from options on every render. */
   features: TMDataGridFeatureFlags;
+  /**
+   * Where the filter controls live, the `filters` option with its defaults
+   * filled in. On the api rather than in a component's props because the
+   * pills, the column menu and `openColumnFilter` all have to agree with the
+   * table about which surface is on.
+   */
+  filters: TMDataGridFiltersSettings;
+  /**
+   * How the grid exports, the `exportOptions` option with its defaults filled
+   * in. Read by `useTMDataGridExport`, the `TMDataGrid.Menu.Export*` items and
+   * the cell-range menu, so every export of the grid agrees on the format.
+   */
+  exportOptions: TMDataGridExportSettings;
   /** Every string the chrome renders, `labels` merged over the English defaults. */
   labels: TMDataGridLabels;
   /** The detail renderer, when row details are on. See `renderDetails`. */
@@ -455,6 +555,27 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
    * Pathed issues land on the matching columns; pathless ones on the row.
    */
   rowValidators?: TMDataGridRowValidators;
+  /**
+   * Rules that need the other rows - no duplicate keys, no overlapping
+   * ranges, allocations summing to a total. Handed the committing row and
+   * `rows`, the collection as it would stand if the commit landed: every
+   * draft overlaid, entry rows appended, deletion-marked rows removed.
+   *
+   * ```tsx
+   * tableValidators: {
+   *   onSubmit: ({ value, rowId, rows }) =>
+   *     rows.some((r) => r.rowId !== rowId && r.value.code === value.code)
+   *       ? { fields: { code: "Duplicate code" } }
+   *       : undefined,
+   * }
+   * ```
+   *
+   * Runs at every commit, after the row's own validators, and again per
+   * parked row during `saveDrafts` - a draft another edit has invalidated
+   * blocks the save. Pathed issues land on the committing row's cells,
+   * pathless ones on the row.
+   */
+  tableValidators?: TMDataGridTableValidators<TData>;
   /** Rows the pencil skips - `false` keeps a row read-only in every mode. */
   isRowEditable?: (row: Row<TMDataGridFeatures, TData>) => boolean;
   /**
@@ -471,39 +592,48 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
   /**
    * Seed values for `edit.addRow()` - the entry row's starting point. A
    * function is called per added row (fresh timestamps, empty arrays).
+   * `edit.addRow(values)` overrides this key by key for that one row.
    */
   newRowDefaults?: TData | (() => TData);
   /**
-   * Called when an entry row commits: `Enter` or the lane's ✓ under the
-   * immediate modes, `submitAll` under draft. Create the record and let it
-   * arrive back through `data`; the engine's `tempId` never leaves the grid.
+   * Called when an entry row commits: `Enter` or the lane's ✓, or
+   * `saveDrafts` under `editing.draft`. Create the record and let it arrive
+   * back through `data`; the engine's `tempId` never leaves the grid.
    */
   onRowAdd?: (args: TMDataGridRowAddArgs<TData>) => void | Promise<void>;
   /**
-   * Called by `edit.deleteRow` under the immediate modes - confirmation, if
-   * any, belongs in here. Under draft, deletions accumulate in
-   * `edit.state.deletedRowIds` instead and are reported by `submitAll`.
-   * Setting this also puts the trash can in the edit lane.
+   * Called by `edit.deleteRow` - confirmation, if any, belongs in here. Under
+   * `editing.draft` deletions accumulate in `edit.state.deletedRowIds`
+   * instead and are reported by `saveDrafts`. Setting this also puts the
+   * trash can in the edit lane.
    */
   onRowDelete?: (args: TMDataGridRowDeleteArgs<TData>) => void | Promise<void>;
 };
 
 /**
  * The `editing` option: one object that turns editing on and holds
- * everything about it. `mode` picks what counts as a commit and which
- * controls trigger it; the other members act within that mode.
+ * everything about it. Two axes, and they are independent: `mode` picks what
+ * counts as a commit, `draft` picks where that commit goes.
+ *
+ * | Mode | Commit | Cancel | Controls |
+ * | ---- | ------ | ------ | -------- |
+ * | `"cell"` | Enter, Tab, blur - Sheets | Escape | none |
+ * | `"cellConfirm"` | ✓ or Enter; Tab and blur keep the draft | ✕ or Escape | ✓ / ✕ beside the input |
+ * | `"row"` | Save in the edit lane, or Enter | Cancel, or Escape | generated edit lane |
+ *
+ * | `draft` | Where a commit goes |
+ * | ------- | ------------------- |
+ * | `false` (default) | Out as it happens - `onCommit`, `onRowAdd`, `onRowDelete` |
+ * | `true` | Into the grid's draft store; `edit.saveDrafts()` sends the lot |
  *
- * | Mode | Commit | Cancel |
- * | ---- | ------ | ------ |
- * | `"cell"` | Enter, Tab, blur - Sheets | Escape |
- * | `"cellConfirm"` | ✓ or Enter only; blur keeps the draft | ✕ or Escape |
- * | `"row"` | Save in the edit lane, or Ctrl+Enter | Cancel, or Escape |
- * | `"draft"` | `edit.submitAll()` | `edit.cancelAll()` |
+ * So `{ mode: "row", draft: true }` is "edit a row, the lane's ✓ parks it,
+ * the toolbar's Save sends every parked row at once", and
+ * `{ mode: "cell", draft: true }` is the same store filled cell by cell.
  *
  * Setting `editing` makes `getRowId` required - drafts are keyed by row id,
  * and the index fallback would name a different record after any sort - and
- * `onCommitDrafts` exists only under `mode: "draft"`, the one mode whose
- * `submitAll` calls it.
+ * `onSaveDrafts` exists only under `draft: true`, the one configuration with
+ * a draft store to save.
  *
  * The object may be written inline: the callbacks are read through a ref
  * every render, so its identity does not matter.
@@ -515,33 +645,79 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * override the rest.
  */
 export type TMDataGridEditingOptions<TData extends RowData> =
-  TMDataGridEditingCallbacks<TData> &
-    (
+  TMDataGridEditingCallbacks<TData> & {
+    /** What counts as a commit. See the table above. */
+    mode: TMDataGridEditMode;
+    /**
+     * The column ids that take edits, by id. Unset - the default - every
+     * column mapping to a data path is editable, which is what a grid whose
+     * columns are mostly the record itself wants.
+     *
+     * Set it for the other shape: a grid of reference data with one or two
+     * columns the user maintains, where naming those is shorter and harder to
+     * get wrong than switching every other column off one by one.
+     *
+     * This gates before `meta.edit`, never past it: a column left out takes no
+     * edits whatever its own meta says, and a column listed here still answers
+     * to its `meta.edit.enabled`.
+     */
+    columns?: ReadonlyArray<string>;
+  } & (
       | {
-          mode: "draft";
           /**
-           * Draft mode's save, called once by `edit.submitAll()` with every
-           * valid dirty row. Without it, `submitAll` falls back to the per-row
-           * {@link TMDataGridEditingCallbacks.onCommit} loop. Rows failing
-           * validation stay open either way; a rejection keeps every draft.
+           * Commits park in the grid's draft store instead of reaching the
+           * consumer, and leave together through `edit.saveDrafts()`. The
+           * edit lane gains the change markers and the per-row revert, the
+           * trash marks a row for deletion rather than deleting it, and
+           * `TMDataGrid.DraftActions` gets something to save.
+           */
+          draft: true;
+          /**
+           * The bulk save: called once by `edit.saveDrafts()` with the
+           * whole draft store - committed edits, added rows and deletion
+           * marks - so a server can apply it as one transaction. Without it,
+           * `saveDrafts` falls back to the per-row
+           * {@link TMDataGridEditingCallbacks.onCommit} loop.
+           *
+           * Rows still open are not in the payload and stay open. Returning
+           * nothing saves the whole store and throwing saves none of it;
+           * return a {@link TMDataGridSaveDraftsResult} to save part of it.
+           */
+          onSaveDrafts?: (
+            args: TMDataGridSaveDraftsArgs<TData>,
+          ) =>
+            | void
+            | TMDataGridSaveDraftsResult
+            | Promise<void | TMDataGridSaveDraftsResult>;
+          /**
+           * @deprecated Renamed to {@link onSaveDrafts} - it fires when the
+           * draft store is saved, not when a row commits into it. Still
+           * honoured; removed in a later beta.
            */
           onCommitDrafts?: (
-            args: TMDataGridEditCommitDraftsArgs<TData>,
-          ) => void | Promise<void>;
+            args: TMDataGridSaveDraftsArgs<TData>,
+          ) =>
+            | void
+            | TMDataGridSaveDraftsResult
+            | Promise<void | TMDataGridSaveDraftsResult>;
           /**
-           * Keep confirmed entry rows pinned in the sticky entry block until
-           * Save all. Off by default: a confirmed row joins the scrolling
-           * flow above the body rows instead - the block a row is *typed*
-           * into is always sticky, but entered rows scroll, so entering many
-           * cannot fill the viewport with sticky chrome.
+           * Keep committed entry rows pinned in the sticky entry block until
+           * the draft store is saved, out of the body's sort. Off by default:
+           * a committed row joins the body rows instead, sorted and filtered
+           * with them - the block a row is *typed* into is always sticky, but
+           * committed rows scroll, so entering many cannot fill the viewport
+           * with sticky chrome.
            */
           newRowsSticky?: boolean;
         }
       | {
-          mode: Exclude<TMDataGridEditMode, "draft">;
-          /** Only `"draft"`'s `submitAll` ever calls it - see the other branch. */
+          /** Every commit reaches the consumer as it happens. The default. */
+          draft?: false;
+          /** Only `draft: true` has a store to save - see the other branch. */
+          onSaveDrafts?: never;
+          /** @deprecated See {@link onSaveDrafts}. */
           onCommitDrafts?: never;
-          /** Confirmed entry rows exist only under `"draft"` - see there. */
+          /** Parked entry rows exist only under `draft: true` - see there. */
           newRowsSticky?: never;
         }
     );
@@ -606,12 +782,55 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * no extra flag.
    */
   enablePagination?: boolean;
+  /**
+   * Sends the grid back to the first page whenever the query changes - a
+   * column filter, the quick search, the sort or the grouping. On by
+   * default. TanStack's own `autoResetPageIndex` is switched off by the
+   * grid: it fires on any change to the `data` array, which under
+   * `editing.draft` is every commit.
+   *
+   * Server-side, `pageIndex` is a position in a result set the grid does not
+   * own: narrowing the query leaves it pointing past the last page, and the
+   * next request comes back empty. The reset is applied in the same event as
+   * the change, so one request goes out, for the first page of the new query.
+   */
+  resetPageOnQueryChange?: boolean;
   /**
    * The row-number gutter: a generated lane, outermost left, numbering the
    * rows of the current view - sorted, filtered, continuing across pages,
    * with group rows unnumbered. Off by default.
    */
   enableRowNumbers?: boolean;
+  /**
+   * Where the grid puts its filter controls - a popup over the rows, a sidebar
+   * beside them, controls in the header row, or nowhere at all so you place
+   * `TMDataGrid.FilterPanel` yourself.
+   *
+   * ```tsx
+   * useTMDataGrid({ data, columns, filters: { surface: "sidebar", inHeader: true } });
+   * ```
+   *
+   * Defaults to `{ surface: "popup" }` - the floating panel the grid has
+   * always shown. See {@link TMDataGridFiltersOptions}.
+   *
+   * Read field by field, so a literal is fine here - unlike `labels` or
+   * `persist`, this one does not have to be referentially stable.
+   */
+  filters?: TMDataGridFiltersOptions;
+  /**
+   * How the grid exports: the file format, the file name and whether the
+   * column labels go in as the first row. Defaults to `csvExcelFormat()`,
+   * `"export"` and `true`. See {@link TMDataGridExportOptions}.
+   *
+   * ```tsx
+   * useTMDataGrid({ data, columns, exportOptions: { format: csvFormat(), fileName: "employees" } });
+   * ```
+   *
+   * Read field by field like `filters`, so a literal is fine. A `format`
+   * built inline is rebuilt every render, which costs nothing but a small
+   * object; keep it at module scope when that bothers you.
+   */
+  exportOptions?: TMDataGridExportOptions;
   /**
    * How the quick search (`TMDataGrid.Search`) matches. `"fuzzy"` - the
    * default - forgives typos and skipped characters, and while it is the
@@ -875,6 +1094,7 @@ export function useTMDataGrid<TData extends RowData>({
   labels: labelsOverride,
   enableColumnOrdering,
   enablePagination,
+  resetPageOnQueryChange,
   enableRowNumbers,
   selectionMode,
   showSelectedBackground,
@@ -882,6 +1102,8 @@ export function useTMDataGrid<TData extends RowData>({
   onHighlightedRowChange,
   cellSelection,
   onFocusedCellChange,
+  filters: filterOptions,
+  exportOptions: exportOptionsOverride,
   editing,
   renderDetails,
   renderDetailsEstHeight = DEFAULT_DETAILS_EST_HEIGHT,
@@ -891,6 +1113,7 @@ export function useTMDataGrid<TData extends RowData>({
   // The one place `editing` is unpacked - the engine and the flags keep their
   // own vocabulary (`editMode`, `onEditCommit`), so the mapping lives here.
   const editMode = editing?.mode;
+  const editDraft = editing?.draft === true;
 
   // Derived up here, rather than just before the return, because the rest of the
   // hook needs `selectColumn` - one place decides what each mode means.
@@ -912,6 +1135,50 @@ export function useTMDataGrid<TData extends RowData>({
   // Resolved on the override's identity, so a module-scope dictionary costs one
   // merge for the lifetime of the grid.
   const labels = useMemo(() => mergeLabels(labelsOverride), [labelsOverride]);
+  // Field by field for the same reason as `filters` below.
+  const {
+    format: exportFormat,
+    fileName: exportFileName,
+    includeHeaders: exportIncludeHeaders,
+    columns: exportColumns,
+  } = exportOptionsOverride ?? {};
+  const exportOptions = useMemo(
+    () =>
+      resolveExportOptions({
+        format: exportFormat,
+        fileName: exportFileName,
+        includeHeaders: exportIncludeHeaders,
+        columns: exportColumns,
+      }),
+    [exportFormat, exportFileName, exportIncludeHeaders, exportColumns],
+  );
+  // Unpacked before the memo, so the api is keyed on the five fields rather
+  // than on the object's identity - which is what lets `filters` be written as
+  // a literal, the way it reads best, without republishing every render.
+  const {
+    surface: filterSurface,
+    sidebarSide: filterSidebarSide,
+    sidebarWidth: filterSidebarWidth,
+    defaultOpen: filtersDefaultOpen,
+    inHeader: filtersInHeader,
+  } = filterOptions ?? {};
+  const filters = useMemo(
+    () =>
+      resolveFilterOptions({
+        surface: filterSurface,
+        sidebarSide: filterSidebarSide,
+        sidebarWidth: filterSidebarWidth,
+        defaultOpen: filtersDefaultOpen,
+        inHeader: filtersInHeader,
+      }),
+    [
+      filterSurface,
+      filterSidebarSide,
+      filterSidebarWidth,
+      filtersDefaultOpen,
+      filtersInHeader,
+    ],
+  );
 
   const pinningEnabled = options.enableColumnPinning !== false;
   const selectColumnEnabled = features.selectColumn;
@@ -921,14 +1188,12 @@ export function useTMDataGrid<TData extends RowData>({
   const detailsColumnEnabled = renderDetails !== undefined;
   // Row mode's Save sits at the end of the row - the lane is its chrome. It
   // also appears wherever the trash can has somewhere to report to, and
-  // always under draft mode, where it is the change marker and the per-row
-  // revert - with or without `onCommitDrafts`, since the per-row `submitAll`
-  // fallback is a first-class configuration.
+  // always under `draft`, where it is the change marker and the per-row
+  // revert - with or without `onSaveDrafts`, since the per-row fallback is a
+  // first-class configuration.
   const editColumnEnabled =
     editing !== undefined &&
-    (editing.mode === "row" ||
-      editing.mode === "draft" ||
-      editing.onRowDelete !== undefined);
+    (editing.mode === "row" || editDraft || editing.onRowDelete !== undefined);
 
   // The generated lanes bake `meta.label` into their definitions, so the memo
   // depends on the strings rather than on the labels object - a fresh
@@ -939,9 +1204,9 @@ export function useTMDataGrid<TData extends RowData>({
   const editColumnLabel = labels.editColumnLabel;
   const rowNumberColumnLabel = labels.rowNumberColumnLabel;
   const rowNumbersEnabled = features.rowNumbers;
-  // Draft mode's lane holds three controls (state icon, undo, trash) where
-  // the other modes hold two - it gets the wider track.
-  const editIsDraftMode = editing?.mode === "draft";
+  // A draft lane holds three controls (state icon, undo, trash) where the
+  // rest hold two - it gets the wider track.
+  const editWideLane = editDraft;
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
@@ -972,7 +1237,7 @@ export function useTMDataGrid<TData extends RowData>({
       ...base,
       // Last and pinned right - the row's Save belongs at the end of the row.
       ...(editColumnEnabled
-        ? [createEditColumn<TData>(editColumnLabel, editIsDraftMode)]
+        ? [createEditColumn<TData>(editColumnLabel, editWideLane)]
         : []),
     ];
   }, [
@@ -982,7 +1247,7 @@ export function useTMDataGrid<TData extends RowData>({
     detailsColumnEnabled,
     groupColumnEnabled,
     editColumnEnabled,
-    editIsDraftMode,
+    editWideLane,
     rowNumberColumnLabel,
     selectColumnLabel,
     groupColumnLabel,
@@ -1004,8 +1269,213 @@ export function useTMDataGrid<TData extends RowData>({
   const initialGrouping =
     persistedState.grouping ?? options.initialState?.grouping ?? [];
 
+  // Current grouping state, feeding the tree column's entry in a controlled
+  // `columnVisibility` (below). A ref, not state: it is only read while
+  // building the options, and the store change that updates it re-renders the
+  // hook anyway. A controlled `grouping` takes precedence over the persisted
+  // one; grouping held in an external atom is not readable here and is
+  // corrected by the effect below with one extra write on mount.
+  const groupingActiveRef = useRef(
+    (options.state?.grouping ?? initialGrouping).length > 0,
+  );
+
+  // Removes keys set to `undefined` before TanStack writes them into the
+  // slice atoms; such a key means the slice is not controlled.
+  const consumerState = withoutUndefinedSlices(options.state);
+
+  // A controlled `columnVisibility` replaces the whole map on every options
+  // sync, including the grid's own entries, so the tree column's entry must be
+  // re-applied here. Entries for the control columns are removed, as they are
+  // for `initialState`: their visibility follows the feature options, not the
+  // visibility map.
+  const controlledColumnVisibility = consumerState?.columnVisibility;
+  const requestedState =
+    consumerState !== undefined && controlledColumnVisibility !== undefined
+      ? {
+          ...consumerState,
+          columnVisibility: {
+            ...withoutControlColumnVisibility(controlledColumnVisibility),
+            ...(groupColumnEnabled
+              ? { [GROUP_COLUMN_ID]: groupingActiveRef.current }
+              : {}),
+          },
+        }
+      : consumerState;
+
+  // Controlled state is synced to the table on every render and compared by
+  // identity, so a `state` object built in the consumer's render body would
+  // cause an infinite render loop. Unchanged slices are forwarded with the
+  // previous render's identity instead - see controlledState.ts.
+  const controlledStateRef = useRef<Partial<TableState<TMDataGridFeatures>>>(
+    undefined,
+  );
+  // Exception: the grouping workaround below republishes `columnOrder` and
+  // `columnVisibility` with unchanged contents and a new identity to repair
+  // table-core's missing memo deps - the exact write stabilization cancels.
+  // After it runs, one render forwards the controlled state unstabilized so
+  // the new identities reach the atoms. A single render cannot loop.
+  const republishControlledStateRef = useRef(false);
+  const controlledState = republishControlledStateRef.current
+    ? requestedState
+    : stabilizeControlledState(requestedState, controlledStateRef.current);
+  republishControlledStateRef.current = false;
+  controlledStateRef.current = controlledState;
+
+  /**
+   * What the hook's own subscription watches.
+   *
+   * `useTable` re-renders whoever called it whenever a state slice changes
+   * identity, and `columnResizing` publishes a new delta on every pointer move
+   * of a resize drag - so without this the consumer's component, and the whole
+   * grid under it, would re-render for each of those moves. The slice is
+   * pinned to the identity it had when the drag started: a drag starting and a
+   * drag ending still publish, the deltas in between do not.
+   *
+   * The live deltas stay on `table.store.state`, which is where the grid reads
+   * them - see the resize preview in TMDataGridTable.
+   */
+  const pinnedResizingRef = useRef<
+    TableState<TMDataGridFeatures>["columnResizing"] | null
+  >(null);
+  const selectSettledState = useCallback(
+    (state: TableState<TMDataGridFeatures>) => {
+      const resizing = state.columnResizing;
+      const pinned = pinnedResizingRef.current;
+      if (
+        pinned === null ||
+        pinned.isResizingColumn !== resizing.isResizingColumn
+      ) {
+        pinnedResizingRef.current = resizing;
+        return state;
+      }
+      return { ...state, columnResizing: pinned };
+    },
+    [],
+  );
+
+  // The edit engine. Built once per mount; everything it needs later - the
+  // table, the mode, the consumer's callbacks - is read through a ref updated
+  // every render, so forms created at `begin()` always call the latest
+  // `onEditCommit` (the onHighlightedRowChangeRef pattern, applied wholesale).
+  // Created ahead of the table because the table's `data` reads its store;
+  // the ref is filled in once the table exists, and the engine only reads it
+  // inside verbs, never while being built.
+  const editContextRef = useRef<TMDataGridEditEngineContext>(null as never);
+  // The engine is erased; the row type comes back on the way out, which is
+  // what makes `edit.addRow(values)` check against `TData`.
+  const [engine] = useState(() =>
+    createEditEngine(() => editContextRef.current),
+  );
+  const edit = engine as unknown as TMDataGridEditApi<TData>;
+
+  // The rows as shown. Under `editing.draft` a committed row is a row like any
+  // other to the table: its draft replaces the consumer's record and a
+  // committed entry row is prepended, so sorting, filtering, grouping and
+  // aggregates all read the draft store's values. Rows still being typed
+  // into are not here - their values are undecided, and re-sorting under a
+  // caret is not something anyone wants. `newRowsSticky` keeps committed
+  // entry rows in the entry block, so those stay out too.
+  //
+  // Everything is keyed on identities the engine keeps stable while nothing
+  // is decided, so a keystroke in an open editor never rebuilds the model.
+  // `committedValues` rather than `committedRowIds`: the snapshot outlives a
+  // reopen, so a parked row being edited again keeps its place until the
+  // next commit or a cancel decides otherwise.
+  const editCommittedValues = useSelector(
+    edit.store,
+    (state) => state.committedValues,
+  );
+  const newRowsSticky = features.editNewRowsSticky;
+  const editCreatedIds = useSelector(
+    edit.store,
+    (state) =>
+      newRowsSticky
+        ? EMPTY_IDS
+        : state.newRows
+            .filter((newRow) => newRow.committed)
+            .map((newRow) => newRow.tempId),
+    { compare: shallow },
+  );
+  // Read through a ref, not listed as a dependency: an inline `getRowId` is
+  // a fresh function every render, and the merged array must keep its
+  // identity across renders or the table rebuilds its row models on each.
+  const consumerGetRowIdRef = useRef(options.getRowId);
+  consumerGetRowIdRef.current = options.getRowId;
+  const shown = useMemo(() => {
+    const consumerGetRowId = consumerGetRowIdRef.current;
+    const idOf = new Map<object, string>();
+    const created: Array<TData> = [];
+    for (const tempId of editCreatedIds) {
+      const values = editCommittedValues[tempId];
+      if (values === undefined) continue;
+      idOf.set(values, tempId);
+      created.push(values as TData);
+    }
+    const snapshots = Object.keys(editCommittedValues).length;
+    if (snapshots === 0) return { rows: options.data, idOf };
+    // Every snapshot may stand in for a record; only the created ones are
+    // known not to. The rest are looked up by the record's own id.
+    const rows =
+      snapshots === created.length
+        ? options.data
+        : options.data.map((record, index) => {
+            const rowId =
+              consumerGetRowId?.(record, index, undefined) ?? String(index);
+            const values = editCommittedValues[rowId];
+            if (values === undefined) return record;
+            idOf.set(values, rowId);
+            return values as TData;
+          });
+    return {
+      rows: created.length === 0 ? rows : [...created, ...rows],
+      idOf,
+    };
+  }, [options.data, editCommittedValues, editCreatedIds]);
+  const shownIdOfRef = useRef(shown.idOf);
+  shownIdOfRef.current = shown.idOf;
+  // A stable id resolver over the merged rows. A draft answers the id of the
+  // record it stands in for - the consumer's `getRowId` never sees a draft
+  // object, so an editable id field cannot rename the row - and a created
+  // row answers its temp id. Everything else is the consumer's own, or
+  // TanStack's index fallback.
+  const shownGetRowId = useCallback(
+    (record: TData, index: number, parent?: Row<TMDataGridFeatures, TData>) =>
+      shownIdOfRef.current.get(record) ??
+      consumerGetRowIdRef.current?.(record, index, parent) ??
+      (parent !== undefined ? `${parent.id}.${index}` : String(index)),
+    [],
+  );
+
+  // Filled immediately after the call below. The query-change wrappers close
+  // over it rather than over `table`, since they are built as part of the
+  // options the table is constructed from.
+  const tableRef = useRef<TMDataGridTable<TData>>(null as never);
+  // A narrower query invalidates the page the grid is on - see pageReset.ts.
+  // On by default everywhere: TanStack's own `autoResetPageIndex` is switched
+  // off below, since it also fires on every draft commit.
+  const resetPage = resetPageOnQueryChange ?? true;
+  const getQueryTable = useCallback(
+    () => tableRef.current as unknown as TMDataGridQueryTable,
+    [],
+  );
+
+  // The sync of `state` into the table's atoms happens inside this call, in
+  // the render body, and publishing from there makes React warn about the
+  // consumer's component - see controlledStateSync.ts.
+  beginControlledStateSync();
   const table = useTable({
-    columnResizeMode: "onChange",
+    // The grid paints a running drag itself, one style write per frame - see
+    // the resize preview in TMDataGridTable - and takes the width into state
+    // once, when the pointer is released. `"onChange"` publishes a width on
+    // every pointer move instead, which re-renders the grid for each of them.
+    columnResizeMode: "onEnd",
+    // TanStack resets both whenever the `data` array's identity changes, and
+    // the rows as shown are a new array on every draft commit (see `shown`),
+    // so a commit on page 3 would land on page 1 with every details panel
+    // closed. Off here; the page reset the grid does want - on a query
+    // change - is its own, below. A consumer's explicit option still wins.
+    autoResetExpanded: false,
+    autoResetPageIndex: false,
     enableSorting: true,
     enableColumnResizing: true,
     // The quick search's matcher. Fuzzy by default (Q4); `"contains"` keeps
@@ -1022,6 +1492,41 @@ export function useTMDataGrid<TData extends RowData>({
     // `"reorder"` to keep the column and have it moved to the front instead.
     groupedColumnMode: "remove",
     ...options,
+    // The query slices, wrapped so a change also takes the grid back to the
+    // first page - see pageReset.ts. Spread conditionally: the keys carry a
+    // `makeStateUpdater` default, and an explicit `undefined` would overwrite
+    // it and leave the slice unwritable.
+    ...(resetPage
+      ? {
+          onColumnFiltersChange: withPageReset(
+            "columnFilters",
+            options.onColumnFiltersChange as never,
+            getQueryTable,
+          ) as TableOptions<
+            TMDataGridFeatures,
+            TData
+          >["onColumnFiltersChange"],
+          onGlobalFilterChange: withPageReset(
+            "globalFilter",
+            options.onGlobalFilterChange as never,
+            getQueryTable,
+          ) as TableOptions<TMDataGridFeatures, TData>["onGlobalFilterChange"],
+          onSortingChange: withPageReset(
+            "sorting",
+            options.onSortingChange as never,
+            getQueryTable,
+          ) as TableOptions<TMDataGridFeatures, TData>["onSortingChange"],
+          onGroupingChange: withPageReset(
+            "grouping",
+            options.onGroupingChange as never,
+            getQueryTable,
+          ) as TableOptions<TMDataGridFeatures, TData>["onGroupingChange"],
+        }
+      : {}),
+    // The rows as shown - see `shown` above. The consumer's own array passes
+    // through untouched while nothing is committed.
+    data: shown.rows,
+    getRowId: shownGetRowId,
     // Row details ride on `expanded`, the same state the tree uses - but a data
     // row answers `getCanExpand()` false, since TanStack's fallback is
     // `subRows.length > 0`. `() => true` is the right answer for a group row
@@ -1040,8 +1545,24 @@ export function useTMDataGrid<TData extends RowData>({
       (typeof options.enableRowPinning === "function"
         ? options.enableRowPinning(row)
         : options.enableRowPinning === true),
+    // A deletion-marked row is not selectable: it is on its way out, and a
+    // bulk action over the selection must not see it. TanStack reads the
+    // predicate on every call, so the mark is checked live against the
+    // engine. Only under `editing.draft`, the one place marks exist; the
+    // consumer's own option keeps the final say, predicate form included.
+    ...(editDraft
+      ? {
+          enableRowSelection: (row: Row<TMDataGridFeatures, TData>) =>
+            !engine.isRowDeleted(row.id) &&
+            (typeof options.enableRowSelection === "function"
+              ? options.enableRowSelection(row)
+              : options.enableRowSelection !== false),
+        }
+      : {}),
     features: tmDataGridFeatures,
     columns: columns as TableOptions<TMDataGridFeatures, TData>["columns"],
+    // The stabilized controlled state; `undefined` when nothing is controlled.
+    state: controlledState,
     initialState: {
       ...options.initialState,
       ...persistedState,
@@ -1059,14 +1580,14 @@ export function useTMDataGrid<TData extends RowData>({
       columnPinning: {
         // The generated columns are structurally pinned, so they are re-applied
         // on top of anything restored from storage.
-        left: [
+        start: [
           ...(rowNumbersEnabled && pinningEnabled ? [ROW_NUMBER_COLUMN_ID] : []),
           ...(selectColumnEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
           ...(groupColumnEnabled && pinningEnabled ? [GROUP_COLUMN_ID] : []),
           ...(detailsColumnEnabled && pinningEnabled ? [DETAILS_COLUMN_ID] : []),
           ...(
-            persistedState.columnPinning?.left ??
-            options.initialState?.columnPinning?.left ??
+            persistedState.columnPinning?.start ??
+            options.initialState?.columnPinning?.start ??
             []
           ).filter(
             (id) =>
@@ -1078,10 +1599,10 @@ export function useTMDataGrid<TData extends RowData>({
         ],
         // The edit lane mirrors the generated columns on the left: structurally
         // pinned, outermost, re-applied over anything restored.
-        right: [
+        end: [
           ...(
-            persistedState.columnPinning?.right ??
-            options.initialState?.columnPinning?.right ??
+            persistedState.columnPinning?.end ??
+            options.initialState?.columnPinning?.end ??
             []
           ).filter((id) => id !== EDIT_COLUMN_ID),
           ...(editColumnEnabled && pinningEnabled ? [EDIT_COLUMN_ID] : []),
@@ -1094,42 +1615,69 @@ export function useTMDataGrid<TData extends RowData>({
         ...persistedState.pagination,
       },
     },
-  });
+  }, selectSettledState);
+  endControlledStateSync();
+  tableRef.current = table as unknown as TMDataGridTable<TData>;
+  deferControlledStateSyncPublishes(table.store);
 
-  // The edit engine. Built once per mount; everything it needs later - the
-  // table, the mode, the consumer's callbacks - is read through a ref updated
-  // every render, so forms created at `begin()` always call the latest
-  // `onEditCommit` (the onHighlightedRowChangeRef pattern, applied wholesale).
-  const editContextRef = useRef<TMDataGridEditEngineContext>(null as never);
+  // The engine's view of this render - see the engine's creation above.
   editContextRef.current = {
     table: table as unknown as TMDataGridTable<TMDataGridRowData>,
     editMode: editMode ?? "cell",
+    draft: editDraft,
     rowValidators: editing?.rowValidators,
+    tableValidators: editing?.tableValidators as
+      TMDataGridEditEngineContext["tableValidators"],
+    editableColumnIds: editing?.columns,
     isRowEditable:
       editing?.isRowEditable as TMDataGridEditEngineContext["isRowEditable"],
     onEditCommit:
       editing?.onCommit as TMDataGridEditEngineContext["onEditCommit"],
-    onEditCommitDrafts:
-      editing?.onCommitDrafts as TMDataGridEditEngineContext["onEditCommitDrafts"],
+    // The deprecated name still works; the new one wins if both are set.
+    onSaveDrafts: (editing?.onSaveDrafts ??
+      editing?.onCommitDrafts) as TMDataGridEditEngineContext["onSaveDrafts"],
     newRowDefaults:
       editing?.newRowDefaults as TMDataGridEditEngineContext["newRowDefaults"],
     onRowAdd: editing?.onRowAdd as TMDataGridEditEngineContext["onRowAdd"],
     onRowDelete:
       editing?.onRowDelete as TMDataGridEditEngineContext["onRowDelete"],
   };
-  const [edit] = useState(() =>
-    createEditEngine(() => editContextRef.current),
-  );
 
-  // Switching modes mid-flight drops every draft: the policies disagree about
-  // what an open form means, and carrying one across is how a draft parked
-  // under "draft" silently commits under "cell".
-  const previousEditModeRef = useRef(editMode);
+  // Switching either axis mid-flight drops every draft: the policies disagree
+  // about what an open form means, and carrying one across is how a row
+  // parked for `saveDrafts` silently commits to the consumer instead.
+  const previousEditPolicyRef = useRef({ editMode, editDraft });
   useEffect(() => {
-    if (previousEditModeRef.current === editMode) return;
-    previousEditModeRef.current = editMode;
+    const previous = previousEditPolicyRef.current;
+    if (previous.editMode === editMode && previous.editDraft === editDraft) {
+      return;
+    }
+    previousEditPolicyRef.current = { editMode, editDraft };
     edit.cancelAll();
-  }, [editMode, edit]);
+  }, [editMode, editDraft, edit]);
+
+  // A refetch that drops a record takes the engine's state for it along -
+  // see forgetMissingRows. Not where the grid does not own the result set:
+  // there a row missing from `data` is on another page or filtered away
+  // server-side, not gone, and its draft has to wait for Save. Keyed on the
+  // rows as shown, which is what the core row model is built from.
+  // Through the ref, not `table`: `useTable` hands out a fresh copy of the
+  // table every render, and listing it would run this on every one.
+  const editingOn = editing !== undefined;
+  const serverSideRows =
+    options.manualPagination === true || options.manualFiltering === true;
+  useEffect(() => {
+    if (!editingOn || serverSideRows) return;
+    engine.forgetMissingRows(tableRef.current.getCoreRowModel().rowsById);
+  }, [shown.rows, editingOn, serverSideRows, engine]);
+
+  // Readers that hold the table and nothing else - `exportGrid`,
+  // `buildGridCellMatrix` - still leave a deletion-marked row out. Keyed on
+  // the store, which every copy of the table shares, so once is enough.
+  useEffect(
+    () => registerDeletedRows(tableRef.current, engine.isRowDeleted),
+    [engine],
+  );
 
   // Editing without stable ids points every draft at whatever record slides
   // into that index after a sort. Loud, once, in development.
@@ -1143,55 +1691,72 @@ export function useTMDataGrid<TData extends RowData>({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // Two things have to happen whenever `grouping` changes.
-  //
-  // One: the tree column appears with the first grouped column and goes away
-  // with the last, so an ungrouped grid looks exactly as it did before grouping
+  // A controlled slice without its `onXChange` cannot change: TanStack routes
+  // every write through the callback, and the next options sync restores the
+  // consumer's value. Warned once in development; `initialState` is the option
+  // for a starting value.
+  useEffect(() => {
+    for (const { slice, handler } of findFrozenStateSlices(options)) {
+      console.warn(
+        `TMDataGrid: state.${slice} is controlled but no ${handler} was passed - the slice cannot change. Add ${handler}, or use initialState.${slice} for a starting value.`,
+      );
+    }
+    // A mount-time contract, like the check above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // The tree column appears with the first grouped column and goes away with
+  // the last, so an ungrouped grid looks exactly as it did before grouping
   // existed. Driven from a subscription rather than by rebuilding the column
   // array, because the array is what the table is built from - deriving it from
   // table state would close the loop. Visibility is the one column property
   // that can be changed after the fact without touching the definitions.
   //
-  // Two, and this one is a workaround. In table-core 9.0.0-beta.21 the
-  // per-region column APIs do not list `grouping` among their memo
-  // dependencies, even though they all derive from `getAllLeafColumns()`, which
-  // does:
-  //
-  // | API | Declares |
-  // | --- | --- |
-  // | `getLeft/Center/RightVisibleLeafColumns` | columns, columnPinning, columnVisibility, columnOrder |
-  // | `getLeft/Center/RightHeaderGroups` | columnPinning, columnOrder |
-  // | `row.getLeft/Center/RightVisibleCells` | columnPinning, columnVisibility |
-  //
-  // So grouping a *second* column leaves every one of them returning the
-  // previous list: the column TanStack removed keeps its header and its grid
-  // track, and the row cells no longer line up with them. The first grouping
-  // appears to work only because the visibility write above happens to touch a
-  // dependency they share.
-  //
-  // Re-publishing `columnVisibility` and `columnOrder` - same contents, new
-  // identity - invalidates all three families. `columnOrder` is the only
-  // dependency the header groups declare, and `columnVisibility` the only one
-  // the cells do, so both are needed. Remove this once the deps are fixed
-  // upstream; the test that fails without it groups two columns and asserts the
-  // second one leaves the grid.
-  //
   // Writing back into the store from its own subscriber is safe: the guard is
-  // on `grouping`'s identity, and neither write touches it, so the callback
-  // these writes trigger short-circuits.
+  // on `grouping`'s identity, and the write does not touch it, so the callback
+  // it triggers short-circuits.
   useEffect(() => {
     if (!groupColumnEnabled) return;
     let previousGrouping = table.store.state.grouping;
+    // Update the ref before any write: it feeds the visibility injection
+    // above, and a write below re-renders the hook. With a stale ref the
+    // injection would restore the old value on every render. This also
+    // corrects the mount value when an external atom owns `grouping`, which
+    // the ref's initializer cannot read.
+    groupingActiveRef.current = previousGrouping.length > 0;
+
+    // The tree column's entry in `initialState` only reaches a slice the
+    // table owns. With `columnVisibility` in an external atom the entry is
+    // missing, and a missing entry means visible: the tree column would
+    // render in an ungrouped grid. The entry is seeded here through the table
+    // API instead, so the write reaches whichever store owns the slice. No-op
+    // when the entry is already correct. `?.`: an external atom can hold
+    // `undefined`.
+    if (
+      table.store.state.columnVisibility?.[GROUP_COLUMN_ID] !==
+      (previousGrouping.length > 0)
+    ) {
+      table.setColumnVisibility((old) => ({
+        ...old,
+        [GROUP_COLUMN_ID]: previousGrouping.length > 0,
+      }));
+    }
 
     const subscription = table.store.subscribe((state) => {
       if (state.grouping === previousGrouping) return;
       previousGrouping = state.grouping;
+      // Keeps the entry injected into a controlled `columnVisibility` (see
+      // requestedState) in sync with grouping.
+      groupingActiveRef.current = state.grouping.length > 0;
+      // On a controlled slice the write below round-trips through the
+      // consumer's handler; the next render must forward it unstabilized.
+      // See republishControlledStateRef.
+      republishControlledStateRef.current = true;
 
       table.setColumnVisibility((old) => ({
         ...old,
         [GROUP_COLUMN_ID]: state.grouping.length > 0,
       }));
-      table.setColumnOrder((old) => [...old]);
     });
 
     return () => subscription.unsubscribe();
@@ -1201,10 +1766,11 @@ export function useTMDataGrid<TData extends RowData>({
   // from an effect on a state snapshot) means nothing is missed, including
   // changes made straight through the table API by the consumer.
   //
-  // Writes are debounced because `columnResizeMode: "onChange"` publishes a new
-  // state on every pointer move of a resize drag, and `setItem` serialises
-  // synchronously on the main thread. The trailing edge is enough: storage only
-  // has to agree with the table once the user stops.
+  // Writes are debounced because a state change can arrive on every pointer
+  // move - a resize drag under `columnResizeMode: "onChange"`, a range
+  // selection - and `setItem` serialises synchronously on the main thread. The
+  // trailing edge is enough: storage only has to agree with the table once the
+  // user stops.
   useEffect(() => {
     if (!hasPersistenceKeys(persist)) return;
     writePersistedState(table.store.state, persist);
@@ -1235,9 +1801,11 @@ export function useTMDataGrid<TData extends RowData>({
 
   const ui = useCreateStore<TMDataGridUiState, TMDataGridUiActions>(
     {
-      filterPanelOpen: false,
-      columnsPanelOpen: false,
+      // `useCreateStore` builds the store once per mount, so `defaultOpen` is
+      // read the way `initialState` is - a starting point, not a controller.
+      filterPanelOpen: filters.defaultOpen,
       filterPanelColumnId: null,
+      headerFilterColumnId: null,
       draggedColumnId: null,
       // `useCreateStore` builds the store once per mount, so this is a genuine
       // default rather than a value that would fight later clicks.
@@ -1245,6 +1813,7 @@ export function useTMDataGrid<TData extends RowData>({
       selectionAnchorRowId: null,
       focusedCell: null,
       cellRange: null,
+      exportPicker: null,
     },
     ({ setState }) => ({
       openFilterPanel: (columnId = null) =>
@@ -1259,10 +1828,14 @@ export function useTMDataGrid<TData extends RowData>({
           filterPanelOpen: false,
           filterPanelColumnId: null,
         })),
-      setColumnsPanelOpen: (open) =>
-        setState((prev) => ({ ...prev, columnsPanelOpen: open })),
-      toggleColumnsPanel: () =>
-        setState((prev) => ({ ...prev, columnsPanelOpen: !prev.columnsPanelOpen })),
+      openExportPicker: (request) =>
+        setState((prev) => ({ ...prev, exportPicker: request })),
+      closeExportPicker: () =>
+        setState((prev) => ({ ...prev, exportPicker: null })),
+      focusPanelFilter: (columnId) =>
+        setState((prev) => ({ ...prev, filterPanelColumnId: columnId })),
+      focusHeaderFilter: (columnId) =>
+        setState((prev) => ({ ...prev, headerFilterColumnId: columnId })),
       startColumnDrag: (columnId) =>
         setState((prev) => ({ ...prev, draggedColumnId: columnId })),
       endColumnDrag: () =>
@@ -1351,12 +1924,12 @@ export function useTMDataGrid<TData extends RowData>({
     table.setColumnSizing({ ...initial?.columnSizing });
     table.setColumnOrder([...(initial?.columnOrder ?? [])]);
     table.setColumnPinning({
-      left: [
+      start: [
         ...(rowNumbersEnabled && pinningEnabled ? [ROW_NUMBER_COLUMN_ID] : []),
         ...(selectColumnEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
         ...(groupColumnEnabled && pinningEnabled ? [GROUP_COLUMN_ID] : []),
         ...(detailsColumnEnabled && pinningEnabled ? [DETAILS_COLUMN_ID] : []),
-        ...(initial?.columnPinning?.left ?? []).filter(
+        ...(initial?.columnPinning?.start ?? []).filter(
           (id) =>
             id !== ROW_NUMBER_COLUMN_ID &&
             id !== SELECT_COLUMN_ID &&
@@ -1364,8 +1937,8 @@ export function useTMDataGrid<TData extends RowData>({
             id !== GROUP_COLUMN_ID,
         ),
       ],
-      right: [
-        ...(initial?.columnPinning?.right ?? []).filter(
+      end: [
+        ...(initial?.columnPinning?.end ?? []).filter(
           (id) => id !== EDIT_COLUMN_ID,
         ),
         ...(editColumnEnabled && pinningEnabled ? [EDIT_COLUMN_ID] : []),
@@ -1388,6 +1961,8 @@ export function useTMDataGrid<TData extends RowData>({
     ui,
     edit,
     features,
+    filters,
+    exportOptions,
     labels,
     renderDetails,
     renderDetailsEstHeight,
@@ -1399,20 +1974,44 @@ export function useTMDataGrid<TData extends RowData>({
 }
 
 /**
- * Opens the filter panel for a column, seeding an empty filter row when the
- * column has none yet - mirrors "Filter" in the column header menu.
+ * Gives a column an empty filter of its default operator, unless it already
+ * has one - which is what makes a surface open on a row rather than on
+ * nothing.
+ *
+ * @internal Shared by `openColumnFilter` and the toolbar's filter button.
  */
-export function openColumnFilter<TData extends RowData>(
+export function seedColumnFilter<TData extends RowData>(
   api: TMDataGridApi<TData>,
   columnId: string,
 ): void {
   const column = api.table.getColumn(columnId);
-  if (column && column.getFilterValue() === undefined) {
-    const operator = getColumnDefaultOperator(column);
-    column.setFilterValue({
-      operator,
-      value: emptyValueForOperator(operator),
-    });
+  if (column === undefined || column.getFilterValue() !== undefined) return;
+  const operator = getColumnDefaultOperator(column);
+  column.setFilterValue({ operator, value: emptyValueForOperator(operator) });
+}
+
+/**
+ * Sends the user to a column's filter control, seeding an empty filter when
+ * the column has none yet - what "Filter" in the column menu and a click on a
+ * filter pill both do.
+ *
+ * Which control that is follows the grid's `filters` option. Under
+ * `inHeader` it is the column's header control, which is already on screen, so
+ * the call focuses it and leaves the popup or sidebar closed. Otherwise it is
+ * the panel's row for that column, and the call opens the surface on it.
+ */
+export function openColumnFilter<TData extends RowData>(
+  api: TMDataGridApi<TData>,
+  columnId: string,
+): void {
+  seedColumnFilter(api, columnId);
+  if (api.filters.inHeader) {
+    // The header control is always visible, so there is nothing to open -
+    // only a column to point at. The header row watching this focuses it and
+    // scrolls it into view. The panel, if one is also showing, is left alone:
+    // it reads the other slot.
+    api.ui.actions.focusHeaderFilter(columnId);
+    return;
   }
   api.ui.actions.openFilterPanel(columnId);
 }