@jielga/tmdatagrid 0.3.0 → 0.5.0

package/src/tmdatagrid/core/summary.ts

@@ -0,0 +1,35 @@
+import { aggregationFns, type RowData } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/** The registered aggregation names — the same set `aggregationFn` accepts. */
+export type TMDataGridAggregationName = keyof typeof aggregationFns;
+
+/**
+ * One column aggregated over every filtered row — the number a summary-row
+ * `footer` wants:
+ *
+ * ```tsx
+ * columnHelper.accessor("salary", {
+ *   footer: ({ table }) => sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+ * });
+ * ```
+ *
+ * Filtered rather than paginated rows, so the total covers everything the
+ * filters left — all pages — and follows the filters as they change. Reuses
+ * TanStack's registered aggregation functions; `fn` defaults to `"sum"`.
+ */
+export function aggregateColumn<TData extends RowData>({
+  table,
+  columnId,
+  fn = "sum",
+}: {
+  table: TMDataGridTable<TData>;
+  columnId: string;
+  fn?: TMDataGridAggregationName;
+}): unknown {
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
+  const rows = erased.getFilteredRowModel().rows;
+  // Leaf and child rows are the same set here: the filtered model is flat.
+  return aggregationFns[fn](columnId, rows, rows);
+}

package/src/tmdatagrid/index.ts

@@ -1,10 +1,12 @@
 export { TMDataGrid, type TMDataGridProps } from "./components/TMDataGrid";
 export {
+  useCellControlTabIndex,
   useTMDataGridContext,
   type TMDataGridContextValue,
   type TMDataGridRowData,
 } from "./TMDataGridContext";
 export { SELECT_COLUMN_ID } from "./components/TMDataGridSelectColumn";
+export { DETAILS_COLUMN_ID } from "./components/TMDataGridDetailsColumn";
 export {
   formatGroupValue,
   GROUP_COLUMN_ID,
@@ -15,6 +17,8 @@ export {
   tmDataGridFeatures,
   type TMDataGridApi,
   type TMDataGridColumnMeta,
+  type TMDataGridDetailsArgs,
+  type TMDataGridDetailsRenderer,
   type TMDataGridFeatures,
   type TMDataGridTable,
   type TMDataGridTableMeta,
@@ -28,20 +32,84 @@ export {
   TMDataGridFilterPills,
   type TMDataGridFilterPillsProps,
 } from "./components/TMDataGridFilterPills";
+export {
+  TMDataGridSearch,
+  type TMDataGridSearchProps,
+} from "./components/TMDataGridSearch";
 export {
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
   FILTER_OPERATOR_LABELS,
   formatFilterLabel,
+  getDefaultOperator,
+  getOperatorsForType,
   isFilterActive,
+  operatorNeedsValue,
+  operatorTakesArrayValue,
 } from "./core/filterOperators";
+export {
+  optionsToComboboxData,
+  resolveColumnOptions,
+  type TMDataGridOption,
+  type TMDataGridOptionsArgs,
+  type TMDataGridOptionsSource,
+} from "./core/columnOptions";
+export {
+  mergeLabels,
+  TMDATAGRID_LABELS_EN,
+  type TMDataGridLabels,
+  type TMDataGridLabelsOverride,
+} from "./core/labels";
+export { TMDATAGRID_LABELS_SV } from "./core/labelsSv";
 export {
   getColumnLabel,
   getColumnType,
   isColumnReorderable,
+  isControlColumn,
 } from "./core/columnUtils";
 export { getGroupDataRows } from "./core/grouping";
+export {
+  aggregateColumn,
+  type TMDataGridAggregationName,
+} from "./core/summary";
+export { autosizeColumn, measureColumnContentWidth } from "./core/autosize";
+export {
+  isSameCell,
+  resolveCellMove,
+  type ResolveCellMoveArgs,
+  type TMDataGridCellCoords,
+  type TMDataGridCellPosition,
+} from "./core/cellNavigation";
+export {
+  boundsCellCount,
+  boundsEdges,
+  isWithinBounds,
+  resolveRangeBounds,
+  type ResolveRangeBoundsArgs,
+  type TMDataGridCellRange,
+  type TMDataGridRangeBounds,
+} from "./core/cellRange";
+export {
+  buildCellMatrix,
+  buildGridCellMatrix,
+  DEFAULT_CELL_EXPORT_OPTIONS,
+  downloadTextFile,
+  exportGridToCsv,
+  formatExportValue,
+  toClipboardText,
+  toExcelCsv,
+  writeClipboardText,
+  type BuildCellMatrixArgs,
+  type TMDataGridCellExportOptions,
+  type TMDataGridCellMatrix,
+} from "./core/cellExport";
+export {
+  areAllRowsExpanded,
+  resolveExpandAll,
+  type TMDataGridExpandAllArgs,
+  type TMDataGridExpandTarget,
+} from "./core/expanding";
 export {
   getColumnRegion,
   getStepTargetColumn,
@@ -56,6 +124,7 @@ export {
   getColumnCapabilities,
   getGridCapabilities,
   readFeatureFlags,
+  type TMDataGridCellSelectionMode,
   type TMDataGridCapabilities,
   type TMDataGridColumnCapabilities,
   type TMDataGridFeatureFlags,
@@ -86,6 +155,7 @@ export {
   type TMDataGridStorageMode,
 } from "./core/persistence";
 export type {
+  TMDataGridCellNav,
   TMDataGridColumnLayout,
   TMDataGridRowContextMenu,
   TMDataGridRowContextMenuArgs,

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -22,6 +22,7 @@ import {
   filterFns,
   globalFilteringFeature,
   metaHelper,
+  type Row,
   type RowData,
   rowExpandingFeature,
   rowPaginationFeature,
@@ -35,12 +36,18 @@ import {
   useTable,
 } from "@tanstack/react-table";
 import type { Store } from "@tanstack/store";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import type { TMDataGridOptionsSource } from "./core/columnOptions";
 import {
   type TMDataGridColumnType,
   tmDataGridFilterFn,
   getDefaultOperator,
 } from "./core/filterOperators";
+import {
+  mergeLabels,
+  type TMDataGridLabels,
+  type TMDataGridLabelsOverride,
+} from "./core/labels";
 import {
   hasPersistenceKeys,
   readPersistedState,
@@ -49,9 +56,15 @@ import {
 } from "./core/persistence";
 import {
   readFeatureFlags,
+  type TMDataGridCellSelectionMode,
   type TMDataGridFeatureFlags,
   type TMDataGridSelectionMode,
 } from "./core/capabilities";
+import {
+  isSameCell,
+  type TMDataGridCellPosition,
+} from "./core/cellNavigation";
+import type { TMDataGridCellRange } from "./core/cellRange";
 import {
   createSelectColumn,
   SELECT_COLUMN_ID,
@@ -60,6 +73,10 @@ import {
   createGroupColumn,
   GROUP_COLUMN_ID,
 } from "./components/TMDataGridGroupColumn";
+import {
+  createDetailsColumn,
+  DETAILS_COLUMN_ID,
+} from "./components/TMDataGridDetailsColumn";
 
 /**
  * How long the grid waits after the last state change before writing to
@@ -72,11 +89,28 @@ const PERSIST_DEBOUNCE_MS = 200;
 export type TMDataGridColumnMeta = {
   /** Name shown in menus and the column manager. Falls back to a string header. */
   label?: string;
-  /** Drives which filter operators are offered. Defaults to `"string"`. */
+  /**
+   * Drives which filter operators are offered and, once editing is on, which
+   * editor the cell opens. Defaults to `"string"`.
+   */
   type?: TMDataGridColumnType;
+  /**
+   * The choices of a `select` / `multiSelect` column — one declaration feeding
+   * the filter panel's value control and the cell editor alike. A static
+   * array, `"faceted"` (the distinct values present in the data), or a
+   * function of the table, column and — for editors — the row. See
+   * {@link TMDataGridOptionsSource}.
+   */
+  options?: TMDataGridOptionsSource;
   /** Share of the leftover width this column claims. Defaults to `1`. */
   flex?: number;
   align?: "left" | "right" | "center";
+  /**
+   * Size the column to its widest mounted content once, after the first rows
+   * render — unless a persisted or user-set width already covers it. The same
+   * measurement as double-clicking the resize divider; see `autosizeColumn`.
+   */
+  autoSize?: boolean;
   /**
    * `false` keeps the column where it is: no header dragging, no move items.
    * Column ordering is the one feature TanStack defines no column option for,
@@ -151,6 +185,26 @@ export function createTMDataGridColumnHelper<TData extends RowData>() {
   return createColumnHelper<TMDataGridFeatures, TData>();
 }
 
+/** What the `renderDetails` render prop is handed for an expanded row. */
+export type TMDataGridDetailsArgs<TData extends RowData> = {
+  row: Row<TMDataGridFeatures, TData>;
+  table: TMDataGridTable<TData>;
+};
+
+/** Builds the panel shown underneath an expanded row. See `renderDetails`. */
+export type TMDataGridDetailsRenderer<TData extends RowData> = (
+  args: TMDataGridDetailsArgs<TData>,
+) => ReactNode;
+
+/**
+ * What the virtualizer assumes a detail panel it has not measured yet is worth.
+ * Only a seed — every mounted row is measured, so the real height replaces it.
+ */
+const DEFAULT_DETAILS_EST_HEIGHT = 160;
+
+/** Rows kept mounted on each side of the viewport. See `overscan`. */
+const DEFAULT_OVERSCAN = 6;
+
 /**
  * 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
@@ -180,6 +234,25 @@ export type TMDataGridUiState = {
   highlightedRowId: string | null;
   /** The pivot a shift-click extends from. See resolveRowSelectionClick. */
   selectionAnchorRowId: string | null;
+  /**
+   * The cell the keyboard is on, under `enableCellSelection`. `null` until the
+   * grid is first entered — and again whenever a consumer clears it.
+   *
+   * The state is the source of truth and DOM focus follows it, not the other
+   * way around: under virtualization the cell it names is often not mounted,
+   * which is exactly what a coordinate has to survive. Held as ids for the
+   * same reason — see {@link TMDataGridCellPosition}.
+   */
+  focusedCell: TMDataGridCellPosition | null;
+  /**
+   * The selected rectangle, under `cellSelection: "range"`. Held as the two
+   * cells that span it — see {@link TMDataGridCellRange}.
+   *
+   * Always covers the focused cell: every gesture that moves the focus either
+   * extends the rectangle or collapses it onto the new cell, so the two never
+   * describe different places.
+   */
+  cellRange: TMDataGridCellRange | null;
 };
 
 export type TMDataGridUiActions = {
@@ -195,6 +268,19 @@ export type TMDataGridUiActions = {
    */
   setHighlightedRow: (rowId: string | null) => void;
   setSelectionAnchor: (rowId: string | null) => void;
+  /**
+   * Moves the focused cell, or clears it with `null`. DOM focus follows while
+   * the grid holds it — so this both moves the keyboard and, when the row is
+   * off screen, scrolls it into view. Called for every arrow key, and available
+   * for a consumer putting the keyboard somewhere itself.
+   */
+  setFocusedCell: (cell: TMDataGridCellPosition | null) => void;
+  /**
+   * Sets the selected rectangle, or clears it with `null`. Does not move the
+   * focused cell — the two are set together by the gestures that change both,
+   * which is what keeps "extend the selection" and "move the cursor" separable.
+   */
+  setCellRange: (range: TMDataGridCellRange | null) => void;
 };
 
 export type TMDataGridUiStore = Store<TMDataGridUiState, TMDataGridUiActions>;
@@ -205,6 +291,14 @@ export type TMDataGridApi<TData extends RowData> = {
   ui: TMDataGridUiStore;
   /** Table-level feature switches, re-read from options on every render. */
   features: TMDataGridFeatureFlags;
+  /** Every string the chrome renders, `labels` merged over the English defaults. */
+  labels: TMDataGridLabels;
+  /** The detail renderer, when row details are on. See `renderDetails`. */
+  renderDetails?: TMDataGridDetailsRenderer<TData>;
+  /** Detail estimate in px: the option, or {@link DEFAULT_DETAILS_EST_HEIGHT}. */
+  renderDetailsEstHeight: number;
+  /** Virtualizer overscan: the option, or {@link DEFAULT_OVERSCAN}. */
+  overscan: number;
 };
 
 export type UseTMDataGridOptions<TData extends RowData> = Omit<
@@ -219,6 +313,20 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * dependency of the subscription that writes back.
    */
   persist?: TMDataGridPersistence;
+  /**
+   * Overrides for the grid's strings — menu items, panels, the pager, and
+   * every `aria-label`. Any subset, merged over the English defaults; a full
+   * Swedish dictionary ships as `TMDATAGRID_LABELS_SV`.
+   *
+   * ```tsx
+   * useTMDataGrid({ data, columns, labels: TMDATAGRID_LABELS_SV });
+   * useTMDataGrid({ data, columns, labels: { noResults: "Inga rader" } });
+   * ```
+   *
+   * Keep the object referentially stable (module scope or `useMemo`) — the
+   * chrome re-renders when its identity changes.
+   */
+  labels?: TMDataGridLabelsOverride;
   /**
    * Header drag-and-drop and the move items in the column menu. Defaults to
    * `true`.
@@ -301,6 +409,113 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * Fires for `ui.actions.setHighlightedRow` too, not only for clicks.
    */
   onHighlightedRowChange?: (rowId: string | null) => void;
+  /**
+   * How cells are selected. Defaults to `"none"`.
+   *
+   * | Mode | What it gives |
+   * | ---- | ------------- |
+   * | `"none"` | nothing; the body's tab stop stays on the row |
+   * | `"single"` | one focused cell, moved with the arrow keys |
+   * | `"range"` | as `"single"`, plus a rectangle of cells |
+   *
+   * Under either live mode:
+   *
+   * | Key | Moves to |
+   * | --- | --- |
+   * | Arrows | the neighbouring cell, clamped at the edges |
+   * | PageUp / PageDown | one viewport of rows |
+   * | Home / End | first / last cell of the row |
+   * | Ctrl+Home / Ctrl+End | first / last cell of the grid |
+   * | Enter or F2 | into the cell — the checkbox, link or button it holds |
+   * | Escape | back out to the cell |
+   * | Space | selects the row, as it does in row-selection mode |
+   *
+   * And under `"range"`, additionally:
+   *
+   * | Gesture | Does |
+   * | ------- | ---- |
+   * | Drag across cells | selects the rectangle they span |
+   * | Shift+click, Shift+arrows | extends the rectangle from its anchor |
+   * | Ctrl+C | copies it as tab-separated text — paste lands in Excel's cells |
+   * | Right-click inside it | offers the CSV export, headers optional |
+   *
+   * Off, nothing about the body changes. On, three things do: the body's tab
+   * stop moves from the row to a cell, so the whole grid is one Tab stop; the
+   * grid reports itself as a `grid` of `gridcell`s rather than a `table` of
+   * `cell`s, which is what tells a screen reader the arrow keys are live; and
+   * the cells take `data-focused` / `data-selected` for the ring and the tint.
+   *
+   * The state is `ui.state.focusedCell` and `ui.state.cellRange`, and moving it
+   * is `ui.actions.setFocusedCell` / `setCellRange` — so a consumer can put the
+   * keyboard on a cell, or follow it:
+   *
+   * ```tsx
+   * const grid = useTMDataGrid({
+   *   data,
+   *   columns,
+   *   cellSelection: "range",
+   *   onFocusedCellChange: (cell) => setStatus(cell?.columnId ?? ""),
+   * });
+   * ```
+   *
+   * Ids rather than a row/column index pair, so sorting, filtering and column
+   * reordering move the selection with the cells instead of leaving it over
+   * whatever slid into those positions.
+   */
+  cellSelection?: TMDataGridCellSelectionMode;
+  /**
+   * Called with the newly focused cell, or `null` when it is cleared. Fires for
+   * `ui.actions.setFocusedCell` too, not only for keys and clicks.
+   */
+  onFocusedCellChange?: (cell: TMDataGridCellPosition | null) => void;
+  /**
+   * Renders a panel underneath an expanded row, spanning every column. Setting
+   * it is what turns row details on.
+   *
+   * Which rows are open is TanStack's own `expanded` state, so opening one is
+   * `row.toggleExpanded()` from wherever suits — a chevron in a cell, a button
+   * in the context menu, a double-click:
+   *
+   * ```tsx
+   * const grid = useTMDataGrid({
+   *   data,
+   *   columns,
+   *   renderDetails: ({ row }) => <EmployeeCard employee={row.original} />,
+   * });
+   * ```
+   *
+   * The panel is as tall as what it renders — see {@link renderDetailsEstHeight}
+   * for what the virtualizer assumes before it has measured one.
+   *
+   * Group rows are left out: expanding one opens its children, and a panel there
+   * would be about an arbitrary one of them. The same reason they sit out
+   * `onRowClick`.
+   *
+   * Row details and `selectionMode: "highlight"` are two answers to the same
+   * question. Details keep the record in place and in context, which suits a few
+   * fields or an action strip; a highlight-driven side panel has room for more
+   * and survives scrolling. Nothing stops a grid from doing both.
+   */
+  renderDetails?: TMDataGridDetailsRenderer<TData>;
+  /**
+   * What the virtualizer assumes an unmeasured detail panel is worth, in px.
+   * Defaults to 160.
+   *
+   * An estimate, not a height: every mounted row is measured, so the real one
+   * takes over as soon as the panel is on screen. It keeps the scrollbar honest
+   * for panels that open off screen — restored `expanded` state, say — and being
+   * roughly right is enough.
+   */
+  renderDetailsEstHeight?: number;
+  /**
+   * Rows the virtualizer keeps mounted above and below the viewport. Defaults
+   * to 6.
+   *
+   * Raise it to trade memory for a scroll that stays painted — fast wheel or
+   * touch flings can outrun the virtualizer and flash blank rows, and a larger
+   * buffer covers the gap. Lower it when rows are expensive to render.
+   */
+  overscan?: number;
 };
 
 type TMDataGridColumnDef<TData extends RowData> = ColumnDef<
@@ -355,12 +570,18 @@ function withTMDataGridDefaults<TData extends RowData>(
 export function useTMDataGrid<TData extends RowData>({
   persist,
   // Not TanStack options, so they are kept out of what `useTable` receives.
+  labels: labelsOverride,
   enableColumnOrdering,
   enablePagination,
   selectionMode,
   showSelectedBackground,
   defaultHighlightedRowId,
   onHighlightedRowChange,
+  cellSelection,
+  onFocusedCellChange,
+  renderDetails,
+  renderDetailsEstHeight = DEFAULT_DETAILS_EST_HEIGHT,
+  overscan = DEFAULT_OVERSCAN,
   ...options
 }: UseTMDataGridOptions<TData>): TMDataGridApi<TData> {
   // Derived up here, rather than just before the return, because the rest of the
@@ -375,27 +596,60 @@ export function useTMDataGrid<TData extends RowData>({
     enablePagination,
     selectionMode,
     showSelectedBackground,
+    cellSelection,
   });
 
+  // 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]);
+
   const pinningEnabled = options.enableColumnPinning !== false;
   const selectColumnEnabled = features.selectColumn;
   const groupColumnEnabled = features.grouping;
+  // The lane that opens the panels. Nothing to switch on: a grid with no
+  // `renderDetails` has nothing for it to open.
+  const detailsColumnEnabled = renderDetails !== undefined;
+
+  // The generated lanes bake `meta.label` into their definitions, so the memo
+  // depends on the three strings rather than on the labels object — a fresh
+  // inline `labels` must not rebuild the table's columns.
+  const selectColumnLabel = labels.selectColumnLabel;
+  const groupColumnLabel = labels.groupColumnLabel;
+  const detailsColumnLabel = labels.detailsColumnLabel;
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
       options.columns as ReadonlyArray<TMDataGridColumnDef<TData>>,
     );
-    // Both generated columns are always present when their feature is on, and
-    // the tree column hides itself while nothing is grouped. Adding it to the
-    // array only once a column is grouped would make the column list depend on
-    // table state, which is the one thing that cannot be a `useMemo` dependency
-    // here — the table is built from these columns.
+    // Every generated column is present whenever its feature is on, and the
+    // tree column hides itself while nothing is grouped. Adding it to the array
+    // only once a column is grouped would make the column list depend on table
+    // state, which is the one thing that cannot be a `useMemo` dependency here
+    // — the table is built from these columns.
+    //
+    // The order is the order they are pinned in, and it follows what each one
+    // is about: tick a row, find it in the tree the user grouped it into, then
+    // open it. The details chevron sits last because it acts on the record the
+    // lanes to its left have narrowed down to.
     return [
-      ...(selectColumnEnabled ? [createSelectColumn<TData>()] : []),
-      ...(groupColumnEnabled ? [createGroupColumn<TData>()] : []),
+      ...(selectColumnEnabled
+        ? [createSelectColumn<TData>(selectColumnLabel)]
+        : []),
+      ...(groupColumnEnabled ? [createGroupColumn<TData>(groupColumnLabel)] : []),
+      ...(detailsColumnEnabled
+        ? [createDetailsColumn<TData>(detailsColumnLabel)]
+        : []),
       ...base,
     ];
-  }, [options.columns, selectColumnEnabled, groupColumnEnabled]);
+  }, [
+    options.columns,
+    selectColumnEnabled,
+    detailsColumnEnabled,
+    groupColumnEnabled,
+    selectColumnLabel,
+    groupColumnLabel,
+    detailsColumnLabel,
+  ]);
 
   // Read once on mount: `initialState` is only consumed on the first render,
   // and re-reading later would fight the user's live edits.
@@ -417,6 +671,14 @@ export function useTMDataGrid<TData extends RowData>({
     // `"reorder"` to keep the column and have it moved to the front instead.
     groupedColumnMode: "remove",
     ...options,
+    // 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
+    // too, so nothing here has to tell the two apart, and a consumer passing
+    // their own predicate still wins.
+    ...(renderDetails !== undefined
+      ? { getRowCanExpand: options.getRowCanExpand ?? (() => true) }
+      : {}),
     features: tmDataGridFeatures,
     columns: columns as TableOptions<TMDataGridFeatures, TData>["columns"],
     initialState: {
@@ -437,11 +699,17 @@ export function useTMDataGrid<TData extends RowData>({
         left: [
           ...(selectColumnEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
           ...(groupColumnEnabled && pinningEnabled ? [GROUP_COLUMN_ID] : []),
+          ...(detailsColumnEnabled && pinningEnabled ? [DETAILS_COLUMN_ID] : []),
           ...(
             persistedState.columnPinning?.left ??
             options.initialState?.columnPinning?.left ??
             []
-          ).filter((id) => id !== SELECT_COLUMN_ID && id !== GROUP_COLUMN_ID),
+          ).filter(
+            (id) =>
+              id !== SELECT_COLUMN_ID &&
+              id !== DETAILS_COLUMN_ID &&
+              id !== GROUP_COLUMN_ID,
+          ),
         ],
         right:
           persistedState.columnPinning?.right ??
@@ -557,6 +825,8 @@ export function useTMDataGrid<TData extends RowData>({
       // default rather than a value that would fight later clicks.
       highlightedRowId: defaultHighlightedRowId ?? null,
       selectionAnchorRowId: null,
+      focusedCell: null,
+      cellRange: null,
     },
     ({ setState }) => ({
       openFilterPanel: (columnId = null) =>
@@ -583,6 +853,25 @@ export function useTMDataGrid<TData extends RowData>({
         setState((prev) => ({ ...prev, highlightedRowId: rowId })),
       setSelectionAnchor: (rowId) =>
         setState((prev) => ({ ...prev, selectionAnchorRowId: rowId })),
+      setFocusedCell: (cell) =>
+        setState((prev) =>
+          // Same cell, same object: the body re-renders on every scroll frame
+          // and mouse events land on the cell that already has the focus, so a
+          // fresh identity here would republish the store for nothing.
+          isSameCell(prev.focusedCell, cell)
+            ? prev
+            : { ...prev, focusedCell: cell },
+        ),
+      setCellRange: (range) =>
+        setState((prev) =>
+          // Same guard as above, and it earns more here: a drag publishes a new
+          // corner on every mouse move, and most of those land on the cell the
+          // range already ends at.
+          isSameCell(prev.cellRange?.anchor ?? null, range?.anchor ?? null) &&
+          isSameCell(prev.cellRange?.focus ?? null, range?.focus ?? null)
+            ? prev
+            : { ...prev, cellRange: range },
+        ),
     }),
   );
 
@@ -608,7 +897,34 @@ export function useTMDataGrid<TData extends RowData>({
     return () => subscription.unsubscribe();
   }, [ui]);
 
-  return { table, ui, features };
+  // Same shape for the focused cell, and for the same reason: arrow keys, a
+  // click and `setFocusedCell` all have to report through one place.
+  const onFocusedCellChangeRef = useRef(onFocusedCellChange);
+  useEffect(() => {
+    onFocusedCellChangeRef.current = onFocusedCellChange;
+  }, [onFocusedCellChange]);
+
+  useEffect(() => {
+    let previous = ui.state.focusedCell;
+    const subscription = ui.subscribe((state) => {
+      // Identity is enough: `setFocusedCell` keeps the previous object when the
+      // cell has not changed, so a new one always means a new cell.
+      if (state.focusedCell === previous) return;
+      previous = state.focusedCell;
+      onFocusedCellChangeRef.current?.(state.focusedCell);
+    });
+    return () => subscription.unsubscribe();
+  }, [ui]);
+
+  return {
+    table,
+    ui,
+    features,
+    labels,
+    renderDetails,
+    renderDetailsEstHeight,
+    overscan,
+  };
 }
 
 /**