@jielga/tmdatagrid 2.0.0-beta.11 → 2.0.0-beta.13

package/src/tmdatagrid/components/filters/filterControlFor.ts

@@ -0,0 +1,65 @@
+import type { Column } from "@tanstack/react-table";
+import { resolveColumnOptions, type TMDataGridOption } from "../../core/columnOptions";
+import { getColumnFilterControl, getColumnType } from "../../core/columnUtils";
+import type { TMDataGridFilterControlComponent } from "../../core/filterControls";
+import type { TMDataGridRowData } from "../../TMDataGridContext";
+import type { TMDataGridFeatures, TMDataGridTable } from "../../useTMDataGrid";
+import { TMDataGridFilterValueInput } from "./TMDataGridFilterValueInput";
+
+type FilterColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+
+/** One array, so "this column has no options" never changes identity. */
+const NO_OPTIONS: ReadonlyArray<TMDataGridOption> = [];
+
+/**
+ * Whether resolving this column's options would read the faceted index -
+ * which is what makes the resolution worth memoizing, and what it goes stale
+ * against.
+ */
+export function filterOptionsUseFacets(column: FilterColumn): boolean {
+  const declared = column.columnDef.meta?.options;
+  return (
+    columnNeedsFilterOptions(column) &&
+    (declared === undefined || declared === "faceted")
+  );
+}
+
+/**
+ * Whether a column's filter control is offered a list of options at all.
+ *
+ * Only where options mean something out of the box - a declared set, or a
+ * select-shaped column's faceted values. A custom control wanting faceted
+ * values on some other column resolves them itself; resolving here would build
+ * the faceted index for every filtered column.
+ */
+function columnNeedsFilterOptions(column: FilterColumn): boolean {
+  const type = getColumnType(column);
+  return (
+    column.columnDef.meta?.options !== undefined ||
+    type === "select" ||
+    type === "multiSelect"
+  );
+}
+
+/**
+ * What a column's filter control is, and what options it is handed - the one
+ * decision the panel row and the header cell make identically.
+ *
+ * Not a hook: the panel resolves this inside a `map` over its rows, where a
+ * hook cannot go. The header row memoizes the call itself, because it
+ * re-renders with the table on every scroll frame.
+ */
+export function filterControlFor(
+  table: TMDataGridTable<TMDataGridRowData>,
+  column: FilterColumn,
+): {
+  options: ReadonlyArray<TMDataGridOption>;
+  ValueControl: TMDataGridFilterControlComponent;
+} {
+  return {
+    options: columnNeedsFilterOptions(column)
+      ? resolveColumnOptions({ table, column, fallback: "faceted" })
+      : NO_OPTIONS,
+    ValueControl: getColumnFilterControl(column) ?? TMDataGridFilterValueInput,
+  };
+}

package/src/tmdatagrid/components/sticky.module.css

@@ -104,3 +104,47 @@
     opacity: 0;
   }
 }
+
+/* The scrolled-under shadow: a soft band under the header, only while body
+   rows are actually beneath it. Worn by the last header row - the header/body
+   boundary - which is the filter row under `filters.inHeader` and the last
+   group row otherwise. Lives here rather than in either row's own module
+   because the two are in different modules and the boundary moves between
+   them.
+
+   A scroll-driven animation, like the pinned-lane gradients: the shadow tracks
+   the scroll on the compositor with no listener and no render, and an inactive
+   timeline (nothing to scroll) leaves `opacity: 0` standing, so a grid that
+   fits shows nothing. Where unsupported there is simply no shadow - the
+   header's border already draws the boundary. */
+.headerBoundary::after {
+  content: "";
+  position: absolute;
+  inset: 100% 0 auto 0;
+  height: 6px;
+  pointer-events: none;
+  background: linear-gradient(
+    to bottom,
+    var(--dg-header-shadow-color, rgba(0, 0, 0, 0.14)),
+    transparent
+  );
+  opacity: 0;
+}
+
+@supports (animation-timeline: scroll()) {
+  .headerBoundary::after {
+    animation: dgHeaderShadow linear both;
+    animation-timeline: scroll(nearest block);
+    /* Arrives over the first rows leaving, reads as depth not as a fade. */
+    animation-range: 0px 24px;
+  }
+}
+
+@keyframes dgHeaderShadow {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}

package/src/tmdatagrid/core/columnOptions.ts

@@ -45,6 +45,51 @@ export type TMDataGridOptionsSource =
   | "faceted"
   | ((args: TMDataGridOptionsArgs) => ReadonlyArray<TMDataGridOption | string>);
 
+/**
+ * Columns already warned about, per grid - so a warning fires once and a
+ * test's grid is not silenced by another test's. Keyed on `table.store`, not
+ * on the table: `useTable` returns a fresh table object every render, while
+ * the store is created once and shared by every render's copy.
+ */
+const warnedFaceted = new WeakMap<object, Set<string>>();
+
+/**
+ * Faceted options read the distinct values in `data`, which under
+ * `manualFiltering` or `manualPagination` is whatever the server sent for the
+ * current page. The dropdown then offers the values that happen to be on the
+ * page the user is looking at, and looks correct while being wrong - so it is
+ * said out loud, once per column.
+ *
+ * Fires from render, unlike the library's other warnings: the fallback form
+ * of `"faceted"` only exists at resolve time, which is render. The guard
+ * makes it once per grid regardless - a StrictMode double render or a
+ * discarded concurrent render marks the set the same way a committed one
+ * does. H3 in the backlog folds it into the diagnostics mechanism with the
+ * rest.
+ */
+function warnFacetedUnderManualMode(
+  table: TMDataGridTable<TMDataGridRowData>,
+  columnId: string,
+): void {
+  if (
+    table.options.manualFiltering !== true &&
+    table.options.manualPagination !== true
+  ) {
+    return;
+  }
+  const store = table.store as object;
+  let warned = warnedFaceted.get(store);
+  if (warned === undefined) {
+    warned = new Set();
+    warnedFaceted.set(store, warned);
+  }
+  if (warned.has(columnId)) return;
+  warned.add(columnId);
+  console.warn(
+    `TMDataGrid: column "${columnId}" resolves faceted options while the server owns the rows - the distinct values of one page are not the distinct values of the result set. Pass meta.options as a list or a function instead.`,
+  );
+}
+
 function addFacetValue(target: Set<string>, value: unknown): void {
   if (value === null || value === undefined || value === "") return;
   target.add(String(value));
@@ -68,6 +113,7 @@ export function resolveColumnOptions({
   if (!source) return [];
 
   if (source === "faceted") {
+    warnFacetedUnderManualMode(table, column.id);
     const values = new Set<string>();
     for (const key of column.getFacetedUniqueValues().keys()) {
       if (Array.isArray(key)) {

package/src/tmdatagrid/core/controlledStateSync.ts

@@ -0,0 +1,108 @@
+import type { ReadonlyStore, Store } from "@tanstack/store";
+
+/**
+ * Timing repair for TanStack's controlled-state sync.
+ *
+ * `useTable` calls `table.setOptions` from its render body, and that syncs
+ * `options.state` into the table's atoms. An atom write publishes the store
+ * synchronously, so every component subscribed to `table.store` schedules a
+ * setState while the consumer's component is still rendering - which React
+ * reports as "Cannot update a component (X) while rendering a different
+ * component (Y)", pointing at the consumer's component rather than at the
+ * grid.
+ *
+ * The write has to stay where it is: the atoms must hold the controlled value
+ * before the table builds its row models for that render. Only the
+ * notification is early, so it moves to a microtask. `getSnapshot` already
+ * returns the new value, so a component reads the same state either way; the
+ * subscription is only what schedules a re-render for the components the
+ * consumer's own render does not reach.
+ *
+ * Scope and assumptions. Only `table.store` is patched: a subscription made
+ * on `table.atoms.*` or `table.baseAtoms.*` keeps the synchronous timing.
+ * The patch leans on three table-core 9.0.0-beta.21 internals - the store is
+ * created once in `constructTable`, `useTable` returns a shallow copy that
+ * shares it, and the sync runs inside `setOptions` during render. The
+ * publish test in controlledState.test.tsx fails loudly if any of them
+ * moves; it is the guard for this module, not a redundant check. The
+ * intended end state - owning the controlled slices through `options.atoms`,
+ * which removes the render-time sync entirely - is in the backlog.
+ */
+
+type Observer = ((value: unknown) => void) | { next?: (value: unknown) => void };
+
+type Subscribe = (observer: Observer) => { unsubscribe: () => void };
+
+/**
+ * True while `useTable` is syncing controlled state inside a render pass.
+ * Process-global, so while one grid is inside its `useTable` call a publish
+ * on any patched store is deferred too - harmless, since nothing else runs
+ * during a synchronous render pass.
+ */
+let syncing = false;
+
+/**
+ * Called immediately before the `useTable` call that performs the sync.
+ *
+ * The microtask is the backstop that bounds the flag to the current task: if
+ * `useTable` throws and an error boundary unmounts the grid, nothing after
+ * the call runs, and without it every patched store would keep deferring its
+ * notifications for the life of the page.
+ */
+export function beginControlledStateSync(): void {
+  syncing = true;
+  queueMicrotask(() => {
+    syncing = false;
+  });
+}
+
+/**
+ * Called immediately after it - the prompt clear; correctness rests on the
+ * backstop above. Not a `finally` around the call, because hooks inside
+ * `try` opt the whole hook out of the React Compiler.
+ */
+export function endControlledStateSync(): void {
+  syncing = false;
+}
+
+const patched = new WeakSet<object>();
+
+/**
+ * Wraps a table store's `subscribe` so notifications raised during the sync
+ * are delivered in a microtask. Idempotent, and installed on the store object
+ * itself rather than on a copy of the table - rows hold the original, so
+ * `row.table.store` has to be the patched one.
+ */
+export function deferControlledStateSyncPublishes<TState>(
+  store: Store<TState> | ReadonlyStore<TState>,
+): void {
+  if (patched.has(store)) return;
+  patched.add(store);
+
+  const subscribe = store.subscribe.bind(store) as Subscribe;
+
+  (store as unknown as { subscribe: Subscribe }).subscribe = (observer) => {
+    const next =
+      typeof observer === "function" ? observer : observer.next?.bind(observer);
+    if (next === undefined) return subscribe(observer);
+
+    let live = true;
+    const subscription = subscribe((value) => {
+      if (!syncing) {
+        next(value);
+        return;
+      }
+      queueMicrotask(() => {
+        // The subscriber may have unmounted between the write and the flush.
+        if (live) next(value);
+      });
+    });
+
+    return {
+      unsubscribe: () => {
+        live = false;
+        subscription.unsubscribe();
+      },
+    };
+  };
+}

package/src/tmdatagrid/core/editEngine.ts

@@ -707,11 +707,26 @@ export type TMDataGridEditApi<
   ) => Promise<TMDataGridAddRowsResult>;
   /**
    * Deletes a row: `onRowDelete` straight away, or under `editing.draft` a
-   * toggle of the id in `deletedRowIds` - the row renders struck through
-   * until `saveDrafts` reports it. On an uncommitted entry row it just
-   * discards the entry.
+   * mark in `deletedRowIds` - the row renders struck through until
+   * `saveDrafts` reports it. Idempotent: deleting a marked row again leaves
+   * it marked, and {@link restoreRow} is the undo. On an entry row,
+   * committed or not, it just discards the entry; an id the grid does not
+   * know is a no-op.
    */
   deleteRow: (rowId: string) => void;
+  /**
+   * {@link deleteRow} for several rows in one call - one notification for
+   * the batch, for a bulk action over a selection. Because `deleteRow` is
+   * idempotent and ignores unknown ids, the list may be passed exactly as
+   * the selection stands - already-marked rows stay marked, duplicates and
+   * stale ids do nothing.
+   */
+  deleteRows: (rowIds: ReadonlyArray<string>) => void;
+  /**
+   * Removes a row's deletion mark - the lane's Restore. A no-op on a row
+   * that is not marked, and outside `editing.draft`, where no marks exist.
+   */
+  restoreRow: (rowId: string) => void;
   /** Whether delete chrome makes sense - the lane's trash gate. */
   canDeleteRows: () => boolean;
 };
@@ -875,6 +890,7 @@ export function createEditEngine(
   };
   const forms = new Map<string, FormEntry>();
   let newRowCounter = 0;
+  const NEW_ROW_ID_PREFIX = "__new__";
   /** Lets `commit` tell a `saveDrafts` flush apart from a lone commit. */
   let savingDrafts = false;
 
@@ -1428,6 +1444,11 @@ export function createEditEngine(
       } finally {
         entry.pendingCommit = null;
       }
+      // Dropped while the submit was in flight - cancel or deleteRow won the
+      // race. The form is gone, so there is nothing to park or drop; marking
+      // the row committed now would plant an id in `committedRowIds` that no
+      // save or discard could ever clear.
+      if (forms.get(rowId) !== entry) return true;
       if (!entry.lastSubmitOk) {
         // Snapshot before the caller closes the editor: the field errors go
         // with it, and the row is about to be left carrying them.
@@ -1532,7 +1553,7 @@ export function createEditEngine(
 
   const addRow = (values?: TMDataGridRowData): string => {
     newRowCounter += 1;
-    const tempId = `__new__${newRowCounter}`;
+    const tempId = `${NEW_ROW_ID_PREFIX}${newRowCounter}`;
     createForm(tempId, seedNewRow(values), true);
     store.setState((prev) => ({
       ...prev,
@@ -1564,7 +1585,7 @@ export function createEditEngine(
     batch(() => {
       for (const values of rows) {
         newRowCounter += 1;
-        const tempId = `__new__${newRowCounter}`;
+        const tempId = `${NEW_ROW_ID_PREFIX}${newRowCounter}`;
         createForm(tempId, seedNewRow(values), true);
         tempIds.push(tempId);
       }
@@ -1599,13 +1620,26 @@ export function createEditEngine(
     }
     const context = getContext();
     if (context.draft) {
-      // A toggle: the second press unmarks - the mark is a draft too.
-      store.setState((prev) => ({
-        ...prev,
-        deletedRowIds: prev.deletedRowIds.includes(rowId)
-          ? prev.deletedRowIds.filter((id) => id !== rowId)
-          : [...prev.deletedRowIds, rowId],
-      }));
+      // Idempotent: a marked row stays marked - `restoreRow` is the undo.
+      store.setState((prev) => {
+        if (prev.deletedRowIds.includes(rowId)) return prev;
+        // Only a consumer row can be marked. A deletion mark is what
+        // `saveDrafts` reports to the server, so an id it cannot act on -
+        // an engine temp id, a record gone from `data`, an id the grid
+        // never knew - must not live on as a mark inflating the draft
+        // count. Entry rows are dropped above, never marked; the prefix
+        // check also catches one already dropped that a stale selection or
+        // a double-fired handler names again, while the table's data still
+        // shows it for one render. The core model, so a filtered-out row
+        // still takes its mark.
+        if (
+          rowId.startsWith(NEW_ROW_ID_PREFIX) ||
+          !(rowId in context.table.getCoreRowModel().rowsById)
+        ) {
+          return prev;
+        }
+        return { ...prev, deletedRowIds: [...prev.deletedRowIds, rowId] };
+      });
       return;
     }
     const row = getRow(rowId);
@@ -1614,6 +1648,26 @@ export function createEditEngine(
     void context.onRowDelete?.({ rowId, row });
   };
 
+  const deleteRows = (rowIds: ReadonlyArray<string>) => {
+    // One notification for the batch - each id still goes through
+    // `deleteRow`, so entry rows drop and everything else marks or no-ops
+    // by the same rules.
+    batch(() => {
+      for (const rowId of rowIds) deleteRow(rowId);
+    });
+  };
+
+  const restoreRow = (rowId: string) => {
+    store.setState((prev) =>
+      prev.deletedRowIds.includes(rowId)
+        ? {
+            ...prev,
+            deletedRowIds: prev.deletedRowIds.filter((id) => id !== rowId),
+          }
+        : prev,
+    );
+  };
+
   const canDeleteRows = (): boolean => {
     const context = getContext();
     if (context.draft) {
@@ -1903,6 +1957,8 @@ export function createEditEngine(
     addRow,
     addRows,
     deleteRow,
+    deleteRows,
+    restoreRow,
     canDeleteRows,
   };
 }

package/src/tmdatagrid/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

package/src/tmdatagrid/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/tmdatagrid/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/labels.ts

@@ -62,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;
@@ -89,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;
@@ -211,6 +215,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`,
@@ -235,6 +240,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.",