@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

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}/grouping.ts

@@ -19,3 +19,24 @@ export function getGroupDataRows<TData extends RowData>(
   if (row.subRows.length === 0) return [row];
   return row.getLeafRows().filter((leaf) => leaf.subRows.length === 0);
 }
+
+/** Shown for a group whose value is empty - `String(null)` would read as "null". */
+const BLANK_GROUP_LABEL = "(Blank)";
+
+/**
+ * How a grouping value is written into the tree cell.
+ *
+ * Deliberately not the grouped column's own `cell` renderer: that renderer is
+ * written for a data row and is free to reach into `row.original`, which on a
+ * group row is the first leaf's record rather than anything about the group.
+ */
+export function formatGroupValue(
+  value: unknown,
+  blankLabel = BLANK_GROUP_LABEL,
+): string {
+  if (value === null || value === undefined || value === "") {
+    return blankLabel;
+  }
+  if (value instanceof Date) return value.toLocaleDateString();
+  return String(value);
+}

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;
@@ -140,9 +148,25 @@ export type TMDataGridLabels = {
   // Cell selection menu
   cellCount: (count: number) => string;
   copy: string;
-  exportCsv: string;
+  exportCells: 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;
@@ -177,16 +201,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",
@@ -205,6 +231,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`,
@@ -229,6 +256,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.",
@@ -261,9 +290,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",

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.",
@@ -116,13 +121,29 @@ 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: "Välj alla",
+  exportPickerCount: (checked, total) => `${checked} av ${total}`,
+  exportPickerHidden: "Dold",
+
   selectColumnLabel: "Kryssrutemarkering",
-  selectAllRows: "Markera alla rader",
-  selectRow: "Markera rad",
-  selectGroup: "Markera grupp",
+  selectAllRows: "Välj alla rader",
+  selectRow: "Välj rad",
+  selectGroup: "Välj grupp",
 
   detailsColumnLabel: "Detaljer",
   showDetails: "Visa detaljer",

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/core/pagination.ts

@@ -0,0 +1,81 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/** What the pager is showing. The read half of {@link TMDataGridPaginationApi}. */
+export type TMDataGridPaginationState = {
+  pageIndex: number;
+  pageSize: number;
+  /** `-1` when a manual grid declares `pageCount: -1` (unknown total). */
+  pageCount: number;
+  rowCount: number;
+  canPreviousPage: boolean;
+  canNextPage: boolean;
+  /**
+   * Whether the pager is slicing anything right now. `false` while a grouping
+   * is active, which suspends paging - see `isPagingActive`.
+   */
+  isPagingActive: boolean;
+  /** First and last row number on this page, 1-based, for a range label. */
+  from: number;
+  to: number;
+};
+
+/** What the pager can do. The write half of {@link TMDataGridPaginationApi}. */
+export type TMDataGridPaginationActions = {
+  setPageIndex: (pageIndex: number) => void;
+  setPageSize: (pageSize: number) => void;
+  previousPage: () => void;
+  nextPage: () => void;
+  firstPage: () => void;
+  lastPage: () => void;
+};
+
+/**
+ * Pagination state and actions, split into the half you read and the half you
+ * call.
+ *
+ * The split is what makes a partial override possible: a consumer replacing
+ * only the range label reads `state` and never touches `actions`, and one
+ * replacing only the buttons does the opposite.
+ */
+export type TMDataGridPaginationApi = {
+  state: TMDataGridPaginationState;
+  actions: TMDataGridPaginationActions;
+};
+
+/**
+ * Reads {@link TMDataGridPaginationApi} off a table. The Footer feeds it to the
+ * `renderPagination` slot; a pager living outside the Footer can call it with
+ * the table from `useTMDataGrid` directly.
+ *
+ * `Controls` are not here: they are components bound to the grid context, and
+ * this function takes only a table.
+ */
+export function getTMDataGridPaginationApi<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  isPaging = true,
+): TMDataGridPaginationApi {
+  const { pageIndex, pageSize } = table.store.state.pagination;
+  const rowCount = table.getRowCount();
+  return {
+    state: {
+      pageIndex,
+      pageSize,
+      pageCount: table.getPageCount(),
+      rowCount,
+      canPreviousPage: table.getCanPreviousPage(),
+      canNextPage: table.getCanNextPage(),
+      isPagingActive: isPaging,
+      from: rowCount === 0 ? 0 : pageIndex * pageSize + 1,
+      to: Math.min(rowCount, (pageIndex + 1) * pageSize),
+    },
+    actions: {
+      setPageIndex: (index) => table.setPageIndex(index),
+      setPageSize: (size) => table.setPageSize(size),
+      previousPage: () => table.previousPage(),
+      nextPage: () => table.nextPage(),
+      firstPage: () => table.firstPage(),
+      lastPage: () => table.lastPage(),
+    },
+  };
+}