@jielga/tmdatagrid 0.5.0 → 1.0.0

package/src/tmdatagrid/components/TMDataGridTable.tsx

@@ -1,6 +1,7 @@
 import { Checkbox, Loader, Menu, type MenuProps, Text } from "@mantine/core";
 import {
   type Cell,
+  type Column,
   flexRender,
   type Row,
   type RowData,
@@ -9,9 +10,11 @@ import {
 import { useSelector } from "@tanstack/react-store";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import {
+  type CSSProperties,
   type KeyboardEvent,
   type MouseEvent,
   type ReactNode,
+  type UIEvent,
   useCallback,
   useEffect,
   useRef,
@@ -22,8 +25,15 @@ import sticky from "./sticky.module.css";
 import { type TMDataGridRowData, useTMDataGridContext } from "../TMDataGridContext";
 import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
 import { TMDataGridHeaderCell } from "./TMDataGridHeaderCell";
+import {
+  TMDataGridCellEditor,
+  type TMDataGridCellEditorClose,
+} from "./TMDataGridCellEditor";
+import { TMDataGridEntryRows } from "./TMDataGridEntryRows";
 import { getColumnAlign, isControlColumn } from "../core/columnUtils";
+import { getEditFieldName } from "../core/editEngine";
 import {
+  getNextEditableCell,
   resolveCellMove,
   type TMDataGridCellPosition,
 } from "../core/cellNavigation";
@@ -46,8 +56,12 @@ import { autosizeColumn } from "../core/autosize";
 import {
   getDisplayedRows,
   getSelectableRowIds,
+  isPagingActive,
   resolveRowSelectionClick,
 } from "../core/rowSelection";
+import { readPinnedRows } from "../core/rowPinning";
+import { buildMatchNeedles, findMatchRanges } from "../core/matchHighlight";
+import { ROW_NUMBER_COLUMN_ID } from "./TMDataGridRowNumberColumn";
 import { SearchIcon } from "./icons";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
 
@@ -187,25 +201,87 @@ export type TMDataGridCellNav = {
   edges: { top: boolean; bottom: boolean; left: boolean; right: boolean } | null;
 };
 
+/**
+ * The text with its matched slices wrapped in `<mark>` — or handed back
+ * whole when nothing matches. Only ever called on string output; a renderer
+ * returning its own elements never reaches this.
+ */
+function withMatchHighlights(
+  text: string,
+  needles: ReadonlyArray<string>,
+): ReactNode {
+  const ranges = findMatchRanges(text, needles);
+  if (ranges === null) return text;
+  const parts: Array<ReactNode> = [];
+  let cursor = 0;
+  for (const range of ranges) {
+    if (range.start > cursor) parts.push(text.slice(cursor, range.start));
+    parts.push(
+      <mark key={range.start} className={classes.matchHighlight}>
+        {text.slice(range.start, range.end)}
+      </mark>,
+    );
+    cursor = range.end;
+  }
+  if (cursor < text.length) parts.push(text.slice(cursor));
+  return parts;
+}
+
 function TMDataGridBodyCell({
   cell,
   rowHeight,
   layout,
   nav,
+  editor,
+  contentOverride,
+  highlightNeedles,
   onFocus,
+  onClick,
   onMouseDown,
   onMouseEnter,
+  onDoubleClick,
   onContextMenu,
 }: {
   cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>;
   rowHeight: number;
   layout: TMDataGridColumnLayout;
   nav?: TMDataGridCellNav;
+  /** The mounted editor, when this is the cell being edited. */
+  editor?: ReactNode;
+  /**
+   * Replaces the column renderer's output — the row-number gutter, whose
+   * value only the body knows. `undefined` means "render normally".
+   */
+  contentOverride?: ReactNode;
+  /**
+   * Needles to highlight in string output — see `enableMatchHighlighting`.
+   * `undefined` almost always: only set while a highlightable filter is
+   * active for this column.
+   */
+  highlightNeedles?: ReadonlyArray<string>;
   onFocus?: () => void;
+  onClick?: (event: MouseEvent<HTMLDivElement>) => void;
   onMouseDown?: (event: MouseEvent<HTMLDivElement>) => void;
   onMouseEnter?: () => void;
+  onDoubleClick?: (event: MouseEvent<HTMLDivElement>) => void;
   onContextMenu?: (event: MouseEvent<HTMLDivElement>) => void;
 }) {
+  // The edit markers subscribe here, per cell, all to the one projection
+  // store — so typing in an editor repaints the edited row's cells and
+  // nothing else. Constant `false` everywhere while editing is off.
+  const { table, edit } = useTMDataGridContext();
+  const fieldName = getEditFieldName(cell.column);
+  const cellRowId = cell.row.id;
+  const isDirty = useSelector(edit.store, (state) => {
+    if (fieldName === null) return false;
+    const projection = state.rows[cellRowId];
+    return projection !== undefined && projection.dirtyFields.includes(fieldName);
+  });
+  const isInvalid = useSelector(edit.store, (state) => {
+    if (fieldName === null) return false;
+    const projection = state.rows[cellRowId];
+    return projection !== undefined && projection.errorFields.includes(fieldName);
+  });
   return (
     <div
       // `gridcell` rather than `cell` is the whole promise of cell selection:
@@ -218,10 +294,12 @@ function TMDataGridBodyCell({
       // a cell is the grid's, one from inside a cell belongs to whatever holds
       // the focus in there.
       data-cell={nav ? true : undefined}
-      data-row-id={nav?.rowId}
-      // Always present, not only under cell selection: autosize finds a
-      // column's mounted cells by it. The cell-navigation selectors also
-      // require `data-cell`, so they are unaffected.
+      // Both coordinates are always present, not only under cell selection:
+      // autosize finds a column's mounted cells by the column id, and the pair
+      // is how a test addresses one cell —
+      // `[data-row-id="42"][data-column-id="name"]`. The cell-navigation
+      // selectors also require `data-cell`, so they are unaffected.
+      data-row-id={cell.row.id}
       data-column-id={cell.column.id}
       data-focused={nav?.focused}
       aria-selected={nav?.selected}
@@ -237,8 +315,13 @@ function TMDataGridBodyCell({
       // landing on the cell — the ring follows the user into the checkbox
       // rather than being left behind on whichever cell they came from.
       onFocus={onFocus}
+      onClick={onClick}
       onMouseDown={onMouseDown}
       onMouseEnter={onMouseEnter}
+      onDoubleClick={onDoubleClick}
+      data-editing={editor !== undefined || undefined}
+      data-dirty={isDirty || undefined}
+      data-invalid={isInvalid || undefined}
       data-align={getColumnAlign(cell.column)}
       // A control lane is a fixed track, so it cannot take the cell padding the
       // scale grows for text. See isControlColumn.
@@ -274,7 +357,29 @@ function TMDataGridBodyCell({
             : undefined,
       }}
     >
-      <span className={classes.cellContent}>{renderCellContent(cell)}</span>
+      {editor ?? (
+        <span className={classes.cellContent}>
+          {(() => {
+            // Highlighting replicates the *default* renderer — value, then
+            // `toString` — with the matched slices marked. A column with its
+            // own `cell` opts out by existing: its renderer's identity is not
+            // the default's, and the grid will not rummage inside its output.
+            if (
+              highlightNeedles !== undefined &&
+              contentOverride === undefined &&
+              !cell.getIsPlaceholder() &&
+              !cell.getIsAggregated() &&
+              cell.column.columnDef.cell === table.getDefaultColumnDef().cell
+            ) {
+              const value = cell.renderValue();
+              if (typeof value === "string" || typeof value === "number") {
+                return withMatchHighlights(String(value), highlightNeedles);
+              }
+            }
+            return contentOverride ?? renderCellContent(cell);
+          })()}
+        </span>
+      )}
     </div>
   );
 }
@@ -368,12 +473,101 @@ export type TMDataGridRowContextMenu<TData extends RowData> = (
   args: TMDataGridRowContextMenuArgs<TData>,
 ) => ReactNode;
 
+/**
+ * What the `onCellClick` family receives — the cell with its row and column,
+ * in the consumer's own row type, plus the pointer event.
+ */
+export type TMDataGridCellEventArgs<TData extends RowData> = {
+  cell: Cell<TMDataGridFeatures, TData, unknown>;
+  row: Row<TMDataGridFeatures, TData>;
+  column: Column<TMDataGridFeatures, TData, unknown>;
+  event: MouseEvent<HTMLElement>;
+};
+
+/**
+ * Inline styles for a row. Widened to accept CSS variables, because setting
+ * `--row-bg` is the supported way to colour a row — see {@link
+ * TMDataGridTableProps.rowStyle}.
+ */
+export type TMDataGridRowStyle =
+  | CSSProperties
+  | (CSSProperties & Record<`--${string}`, string | number>);
+
 export type TMDataGridTableProps<TData extends RowData> = {
   /**
    * Called when a body row is clicked. Runs in addition to row selection under
    * `selectionMode: "row"`, not instead of it.
    */
   onRowClick?: (row: Row<TMDataGridFeatures, TData>) => void;
+  /**
+   * Called when a body cell is clicked. Composes, never suppresses: whatever
+   * the click already does — selecting, highlighting, moving the cell cursor
+   * — still happens. Group rows sit out the cell handlers the way they sit
+   * out `onRowClick`, and for the same reason.
+   */
+  onCellClick?: (args: TMDataGridCellEventArgs<TData>) => void;
+  /** As {@link onCellClick}; a double-click that opens an editor still does. */
+  onCellDoubleClick?: (args: TMDataGridCellEventArgs<TData>) => void;
+  /**
+   * As {@link onCellClick}; `rowContextMenu` and the cell-selection menu still
+   * open. To suppress the browser's own menu on a grid with neither, call
+   * `event.preventDefault()` here.
+   */
+  onCellContextMenu?: (args: TMDataGridCellEventArgs<TData>) => void;
+  /**
+   * Class for a body row — a string, or a function of the row (group rows
+   * included; test `row.getIsGrouped()` to skip them). Added after the grid's
+   * own row class.
+   */
+  rowClassName?:
+    | string
+    | ((row: Row<TMDataGridFeatures, TData>) => string | undefined);
+  /**
+   * Inline style for a body row. To colour a row, set `--row-bg` rather than
+   * `background`: the row's own background, its sticky pinned cells and the
+   * cell-range tint all read that variable, and hover/selection/highlight
+   * keep working on top of it — a raw `background` bypasses all of them.
+   *
+   * ```tsx
+   * rowStyle={(row) =>
+   *   row.original.overdue ? { "--row-bg": "var(--mantine-color-red-0)" } : undefined
+   * }
+   * ```
+   */
+  rowStyle?:
+    | TMDataGridRowStyle
+    | ((row: Row<TMDataGridFeatures, TData>) => TMDataGridRowStyle | undefined);
+  /**
+   * Every second row takes `--dg-row-striped-bg`. Computed from the row's
+   * position in the view — sorting and filtering restripe, and the stripes
+   * stay put while the virtualizer mounts and unmounts rows.
+   */
+  striped?: boolean;
+  /**
+   * Called when the scroll *arrives* at an edge — once per arrival, not per
+   * scroll event, and not on mount (the grid starts at the top-left edge).
+   * For loading more rows as the end approaches, `onReachEnd` is the better
+   * hook: it fires rows-early and latches per row count.
+   */
+  onScrollToTop?: () => void;
+  /** As {@link onScrollToTop}, for the bottom edge. */
+  onScrollToBottom?: () => void;
+  /** As {@link onScrollToTop}, for the left edge. */
+  onScrollToLeft?: () => void;
+  /** As {@link onScrollToTop}, for the right edge. */
+  onScrollToRight?: () => void;
+  /**
+   * Rendered centred in the body when the view is empty — the branded blank
+   * slate. It takes over states 3 and 4 of the empty matrix (see the docs):
+   * loading still shows the loader, and open entry rows still show only
+   * themselves. `hasActiveFilters` says which emptiness this is — a filter
+   * that matched nothing wants a "clear filters" invitation, a grid with no
+   * data wants a "create the first one".
+   */
+  renderEmptyState?: (args: {
+    hasActiveFilters: boolean;
+    table: Table<TMDataGridFeatures, TData>;
+  }) => ReactNode;
   /**
    * Contents of the menu a right-click on a row opens, at the pointer. Return
    * `null` to leave a row without one — the browser's own menu stays suppressed
@@ -428,6 +622,14 @@ export type TMDataGridTableProps<TData extends RowData> = {
    * How many rows before the end {@link onReachEnd} fires at. Defaults to 10.
    */
   reachEndThreshold?: number;
+  /**
+   * Accessible name for the grid — what a screen reader announces on entry,
+   * and what `getByRole("grid", { name })` matches. Worth setting on any page
+   * holding more than one grid; without it they are all just "grid".
+   */
+  "aria-label"?: string;
+  /** As {@link "aria-label"}, pointing at an element that already names it. */
+  "aria-labelledby"?: string;
 };
 
 /**
@@ -438,15 +640,29 @@ export type TMDataGridTableProps<TData extends RowData> = {
  */
 export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   onRowClick,
+  onCellClick,
+  onCellDoubleClick,
+  onCellContextMenu,
+  rowClassName,
+  rowStyle,
+  striped = false,
+  onScrollToTop,
+  onScrollToBottom,
+  onScrollToLeft,
+  onScrollToRight,
+  renderEmptyState,
   rowContextMenu,
   rowContextMenuProps,
   cellExport,
   onReachEnd,
   reachEndThreshold = 10,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
 }: TMDataGridTableProps<TData>) {
   const {
     table,
     ui,
+    edit,
     features,
     labels,
     rowHeight,
@@ -454,6 +670,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     renderDetails,
     renderDetailsEstHeight,
     overscan,
+    scrollerRef,
   } = useTMDataGridContext();
 
   // The body depends on every state slice (sorting, filters, paging, sizing,
@@ -465,6 +682,11 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   // with cell selection off never re-renders for it.
   const focusedCell = useSelector(ui, (state) => state.focusedCell);
   const cellRange = useSelector(ui, (state) => state.cellRange);
+  // Which cell has an editor open. The projection (dirty/error markers) is
+  // subscribed per cell instead — see TMDataGridBodyCell.
+  const editActive = useSelector(edit.store, (state) => state.active);
+  const newRowCount = useSelector(edit.store, (state) => state.newRows.length);
+  const deletedRowIds = useSelector(edit.store, (state) => state.deletedRowIds);
 
   const { loading, noResultsLabel = labels.noResults } =
     table.options.meta ?? {};
@@ -475,6 +697,37 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   // the rows as delivered, so the same branch serves server paging.
   const rows = getDisplayedRows(table, features);
 
+  // Per-column highlight needles, or `null` while off or nothing is active —
+  // the common case, costing one flag check per render.
+  const matchNeedles = features.matchHighlighting
+    ? buildMatchNeedles(table)
+    : null;
+
+  // The edge blocks. `getDisplayedRows` above has already taken these out of
+  // the scrolling order; stale ids resolve to nothing — see readPinnedRows.
+  const pinnedTopRows = features.rowPinning ? readPinnedRows(table, "top") : [];
+  const pinnedBottomRows = features.rowPinning
+    ? readPinnedRows(table, "bottom")
+    : [];
+  const pinnedRowCount = pinnedTopRows.length + pinnedBottomRows.length;
+
+  // The row-number gutter's numbers: one pass over the view per render, only
+  // while the lane exists. A cell cannot know its display position, so the
+  // body hands each row its number — group rows get none (they are headings
+  // over the rows being counted), and paging continues the count across
+  // pages rather than restarting every page at 1.
+  let rowNumberById: Map<string, number> | null = null;
+  if (features.rowNumbers) {
+    rowNumberById = new Map();
+    let n = isPagingActive(table, features)
+      ? table.store.state.pagination.pageIndex *
+        table.store.state.pagination.pageSize
+      : 0;
+    for (const viewRow of rows) {
+      if (!viewRow.getIsGrouped()) rowNumberById.set(viewRow.id, ++n);
+    }
+  }
+
   /**
    * Whether this row opens a detail panel underneath it.
    *
@@ -505,6 +758,79 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     }
   });
 
+  /**
+   * The header's height, published as `--dg-header-height` for the entry
+   * block to stick under — never measured otherwise (`top: 0` needs no
+   * number). A ResizeObserver, mounted only while the block is in use: the
+   * same discipline `renderDetails` applies to `measureElement`.
+   */
+  const gridElementRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (newRowCount === 0 && pinnedTopRows.length === 0) return;
+    const grid = gridElementRef.current;
+    if (grid === null) return;
+    const headerRows = grid.querySelectorAll<HTMLElement>(
+      "[data-dg-header-row]",
+    );
+    const measure = () => {
+      let total = 0;
+      for (const headerRow of headerRows) total += headerRow.offsetHeight;
+      grid.style.setProperty("--dg-header-height", `${total}px`);
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    for (const headerRow of headerRows) observer.observe(headerRow);
+    return () => observer.disconnect();
+  }, [newRowCount, pinnedTopRows.length]);
+
+  /**
+   * The entry block's height, published as `--dg-entry-height` so the pinned
+   * top block can stack under it — measured only while both blocks exist,
+   * which is the only time the offset is anything but 0.
+   */
+  useEffect(() => {
+    if (newRowCount === 0 || pinnedTopRows.length === 0) return;
+    const grid = gridElementRef.current;
+    if (grid === null) return;
+    const entryBlock = grid.querySelector<HTMLElement>("[data-dg-entry-block]");
+    if (entryBlock === null) return;
+    const measure = () =>
+      grid.style.setProperty("--dg-entry-height", `${entryBlock.offsetHeight}px`);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(entryBlock);
+    return () => {
+      observer.disconnect();
+      grid.style.removeProperty("--dg-entry-height");
+    };
+  }, [newRowCount, pinnedTopRows.length]);
+
+  /**
+   * The summary row's height, published as `--dg-summary-height` so the
+   * pinned bottom block sticks above it rather than underneath it.
+   */
+  useEffect(() => {
+    if (pinnedBottomRows.length === 0) return;
+    const grid = gridElementRef.current;
+    if (grid === null) return;
+    const summaryRow = grid.querySelector<HTMLElement>(
+      '[data-dg-part="summary-row"]',
+    );
+    if (summaryRow === null) return;
+    const measure = () =>
+      grid.style.setProperty(
+        "--dg-summary-height",
+        `${summaryRow.offsetHeight}px`,
+      );
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(summaryRow);
+    return () => {
+      observer.disconnect();
+      grid.style.removeProperty("--dg-summary-height");
+    };
+  }, [pinnedBottomRows.length]);
+
   // A persisted pageIndex can outlive the data that produced it; TanStack only
   // auto-resets on live filter/sort/data changes, not on restored state. The
   // guard makes the dependency-free effect idempotent.
@@ -556,6 +882,35 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   const paddingBottom =
     virtualizer.getTotalSize() - (virtualItems.at(-1)?.end ?? 0);
 
+  /**
+   * `api.scrollToRow`, implemented where the virtualizer is.
+   *
+   * Registered in an effect rather than during render, and with no dependency
+   * array so it re-registers on every one: the closure has to see this render's
+   * `rows`, which sorting, filtering and paging all change. A grid whose Table
+   * has unmounted leaves the hook's default behind, which answers `false`.
+   */
+  useEffect(() => {
+    scrollerRef.current = ({ rowId, align = "auto" }) => {
+      // Already parked at an edge, and outside the scrolling order — see
+      // `getDisplayedRows`. Nothing to scroll, but the row *is* on screen, so
+      // reporting failure would be the wrong answer.
+      if (
+        pinnedTopRows.some((row) => row.id === rowId) ||
+        pinnedBottomRows.some((row) => row.id === rowId)
+      ) {
+        return true;
+      }
+      const index = rows.findIndex((row) => row.id === rowId);
+      if (index < 0) return false;
+      virtualizer.scrollToIndex(index, { align });
+      return true;
+    };
+    return () => {
+      scrollerRef.current = () => false;
+    };
+  });
+
   /**
    * Infinite scroll. Latched on the row count rather than debounced: one call
    * per count means a pending fetch is never asked twice, and the append that
@@ -679,7 +1034,17 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   const layoutFor = (columnId: string) =>
     columnLayout.get(columnId) ?? UNPINNED_LAYOUT;
 
-  const isEmpty = rows.length === 0;
+  // Pinned rows count as content: with every visible row pinned to an edge,
+  // an empty-state message beside them would contradict what is on screen.
+  const isEmpty = rows.length === 0 && pinnedRowCount === 0;
+  // Which emptiness this is. The body already subscribes to the whole table
+  // store, so these reads are reactive.
+  const emptyGlobalFilter = table.store.state.globalFilter;
+  const hasActiveFilters =
+    table.store.state.columnFilters.length > 0 ||
+    (typeof emptyGlobalFilter === "string"
+      ? emptyGlobalFilter.trim() !== ""
+      : emptyGlobalFilter != null);
 
   /**
    * The summary row exists by declaration, not by flag: it renders exactly
@@ -738,6 +1103,35 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     onRowClick?.(row as unknown as Row<TMDataGridFeatures, TData>);
   };
 
+  // The value-or-function pair resolved per row, across the same erasure
+  // crossing `onRowClick` makes.
+  const rowClassNameFor = (
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+  ): string | undefined =>
+    typeof rowClassName === "function"
+      ? rowClassName(row as unknown as Row<TMDataGridFeatures, TData>)
+      : rowClassName;
+  const rowStyleFor = (
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+  ): CSSProperties | undefined =>
+    typeof rowStyle === "function"
+      ? rowStyle(row as unknown as Row<TMDataGridFeatures, TData>)
+      : rowStyle;
+
+  // The same erasure crossing `onRowClick` makes, once for all three cell
+  // handlers.
+  const cellEventArgs = (
+    cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>,
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+    event: MouseEvent<HTMLElement>,
+  ): TMDataGridCellEventArgs<TData> =>
+    ({
+      cell,
+      row,
+      column: cell.column,
+      event,
+    }) as unknown as TMDataGridCellEventArgs<TData>;
+
   // ---------------------------------------------------------------------------
   // Cell selection
   //
@@ -956,6 +1350,92 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     setRangeTo(cell, { extend });
   };
 
+  // ---------------------------------------------------------------------------
+  // Cell editing — the gestures. The engine owns the forms; this component
+  // owns where the editor opens from (keys, double-click) and where the
+  // focus lands when it closes.
+  // ---------------------------------------------------------------------------
+
+  /** The pending type-to-edit seed, consumed by the editor host on mount. */
+  const editSeedRef = useRef<string | undefined>(undefined);
+  const takeEditSeed = () => {
+    const seed = editSeedRef.current;
+    editSeedRef.current = undefined;
+    return seed;
+  };
+
+  /** DOM focus back onto a cell — after Escape, or a commit with nowhere to go. */
+  const refocusCell = (position: TMDataGridCellPosition) => {
+    const container = scrollContainerRef.current;
+    if (container === null) return;
+    wantsCellFocusRef.current = true;
+    findCellElement(container, position)?.focus();
+  };
+
+  const openEditor = (position: TMDataGridCellPosition) => {
+    if (cellSelection) ui.actions.setFocusedCell(position);
+    // Row mode edits whole rows: any editable cell's open gesture opens the
+    // row, exactly as the lane's pencil does.
+    edit.begin({
+      rowId: position.rowId,
+      columnId: features.editMode === "row" ? null : position.columnId,
+    });
+  };
+
+  const handleEditorClose = (
+    position: TMDataGridCellPosition,
+    close: TMDataGridCellEditorClose,
+  ) => {
+    // Where the keyboard goes: Enter moves down, Tab to the next editable
+    // cell (the deferring batch variants move the same way, draft in tow) —
+    // everything else, and a saved row, goes back to where the edit was.
+    const move =
+      close.via === "enter"
+        ? "down"
+        : close.via === "tab" || close.via === "defer-tab"
+          ? 1
+          : close.via === "shift-tab" || close.via === "defer-shift-tab"
+            ? -1
+            : null;
+    if (move === null || features.editMode === "row") {
+      refocusCell(position);
+      return;
+    }
+    const rowIndex = rows.findIndex((row) => row.id === position.rowId);
+    const columnIndex = orderedColumns.findIndex(
+      (column) => column.id === position.columnId,
+    );
+    if (rowIndex < 0 || columnIndex < 0) {
+      refocusCell(position);
+      return;
+    }
+    if (move === "down") {
+      if (rowIndex + 1 < rows.length) {
+        moveFocusedCell({ rowIndex: rowIndex + 1, columnIndex });
+      } else {
+        refocusCell(position);
+      }
+      return;
+    }
+    const next = getNextEditableCell({
+      from: { rowIndex, columnIndex },
+      direction: move,
+      rowCount: rows.length,
+      columnCount: orderedColumns.length,
+      isEditable: (coords) => {
+        const row = rows[coords.rowIndex];
+        const column = orderedColumns[coords.columnIndex];
+        return (
+          row !== undefined &&
+          column !== undefined &&
+          edit.canEditCell(row, column)
+        );
+      },
+    });
+    if (next !== null) moveFocusedCell(next);
+    else refocusCell(position);
+  };
+
   /**
    * Space, from a cell. Checkbox semantics rather than click semantics: it adds
    * to the selection instead of replacing it, so a keyboard user builds one the
@@ -1031,6 +1511,51 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       return;
     }
 
+    // Editing keys, ahead of the step-into pair — an editable cell's Enter
+    // opens its editor, and only a non-editable cell's falls through to the
+    // control it holds.
+    const keyRow = rows[rowIndex];
+    const keyColumn = orderedColumns[columnIndex];
+    if (
+      features.editing &&
+      keyRow !== undefined &&
+      keyColumn !== undefined &&
+      edit.canEditCell(keyRow, keyColumn)
+    ) {
+      if (event.key === "Enter" || event.key === "F2") {
+        event.preventDefault();
+        openEditor({ rowId, columnId });
+        return;
+      }
+      // The quick single-cell gestures — Delete-to-clear and type-to-edit —
+      // sit out row mode, whose whole point is that nothing commits until
+      // the row's explicit save.
+      if (features.editMode !== "row") {
+        // Clear-and-commit, without opening anything — the spreadsheet Delete.
+        if (event.key === "Delete" || event.key === "Backspace") {
+          event.preventDefault();
+          void edit
+            .clearCell(rowId, columnId)
+            .then(() => refocusCell({ rowId, columnId }));
+          return;
+        }
+        // Type-to-edit: a printable character opens the editor seeded with
+        // itself. Space stays the row-selection key, modifiers stay shortcuts.
+        if (
+          event.key.length === 1 &&
+          event.key !== " " &&
+          !event.ctrlKey &&
+          !event.metaKey &&
+          !event.altKey
+        ) {
+          event.preventDefault();
+          editSeedRef.current = event.key;
+          openEditor({ rowId, columnId });
+          return;
+        }
+      }
+    }
+
     // Step into the cell. The pair Excel and AG Grid both use, and the pair the
     // editor will take over: F2 has never meant anything else, and Enter is
     // what a keyboard user reaches for. Nothing to step into leaves the key
@@ -1269,12 +1794,52 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     );
 
   /**
-   * The dropdown is anchored to a fixed viewport point, so it does not travel
-   * with the row when the body scrolls — and under virtualization the row it
-   * belongs to may unmount entirely. Closing is the honest answer, and matches
-   * what every desktop context menu does.
+   * Which edges the scroll position is currently at. Seeded "at top-left",
+   * which is where a grid mounts — so the callbacks report *arrivals*, and
+   * mounting fires nothing.
    */
-  const handleScroll = contextMenuTarget ? closeContextMenu : undefined;
+  const scrollEdgesRef = useRef({
+    top: true,
+    bottom: false,
+    left: true,
+    right: false,
+  });
+  const hasEdgeCallbacks =
+    onScrollToTop !== undefined ||
+    onScrollToBottom !== undefined ||
+    onScrollToLeft !== undefined ||
+    onScrollToRight !== undefined;
+
+  /**
+   * The context menu's dropdown is anchored to a fixed viewport point, so it
+   * does not travel with the row when the body scrolls — and under
+   * virtualization the row it belongs to may unmount entirely. Closing is
+   * the honest answer, and matches what every desktop context menu does.
+   *
+   * The edge callbacks share the handler. Reading scroll offsets here costs
+   * no layout; the 1px tolerance absorbs fractional offsets under browser
+   * zoom, where a "fully scrolled" position can land at 799.5 of 800.
+   */
+  const handleScroll =
+    contextMenuTarget || hasEdgeCallbacks
+      ? (event: UIEvent<HTMLDivElement>) => {
+          if (contextMenuTarget) closeContextMenu();
+          if (!hasEdgeCallbacks) return;
+          const el = event.currentTarget;
+          const next = {
+            top: el.scrollTop <= 1,
+            bottom: el.scrollTop + el.clientHeight >= el.scrollHeight - 1,
+            left: el.scrollLeft <= 1,
+            right: el.scrollLeft + el.clientWidth >= el.scrollWidth - 1,
+          };
+          const previous = scrollEdgesRef.current;
+          scrollEdgesRef.current = next;
+          if (next.top && !previous.top) onScrollToTop?.();
+          if (next.bottom && !previous.bottom) onScrollToBottom?.();
+          if (next.left && !previous.left) onScrollToLeft?.();
+          if (next.right && !previous.right) onScrollToRight?.();
+        }
+      : undefined;
 
   return (
     <div className={classes.tableWrapper}>
@@ -1286,11 +1851,18 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
         onScroll={handleScroll}
       >
         <div
+          ref={gridElementRef}
           // A `table` is content; a `grid` is a widget with a keyboard cursor
           // in it. Which one this is depends on whether cell selection is on,
           // and saying `grid` without one would promise arrow keys that do
           // nothing.
           role={cellSelection ? "grid" : "table"}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          // Set while `meta.loading` is, whether or not the body has rows to
+          // show — a refetch over existing rows is still a fetch, and a test
+          // waiting for the grid to settle has nothing else to wait on.
+          aria-busy={loading === true ? true : undefined}
           aria-multiselectable={
             cellSelection && features.rowSelection && features.multiRowSelection
               ? true
@@ -1306,9 +1878,17 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
           // have to be stated rather than inferred from what is rendered. Every
           // row carries its aria-rowindex for the same reason.
           aria-rowcount={
-            rows.length + headerGroups.length + (hasSummaryRow ? 1 : 0)
+            rows.length +
+            pinnedRowCount +
+            headerGroups.length +
+            (hasSummaryRow ? 1 : 0)
           }
           aria-colcount={orderedColumns.length}
+          // Body rows the grid is currently showing — the page under
+          // pagination, everything the filters left otherwise, edge blocks
+          // included. Most of them are not in the DOM, so this is what a test
+          // waits on rather than counting nodes.
+          data-dg-row-count={rows.length + pinnedRowCount}
           style={{ gridTemplateColumns, minWidth: gridMinWidth }}
         >
           <div role="rowgroup" style={{ display: "contents" }}>
@@ -1317,6 +1897,13 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                 key={headerGroup.id}
                 role="row"
                 aria-rowindex={groupIndex + 1}
+                data-dg-header-row
+                // The scrolled-under shadow belongs to the boundary between
+                // header and body — the last header row, not every stacked
+                // group row above it. See the stylesheet.
+                data-dg-header-last={
+                  groupIndex === headerGroups.length - 1 || undefined
+                }
                 className={classes.headerRow}
               >
                 {headerGroup.headers.map((header) => (
@@ -1330,8 +1917,14 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
             ))}
           </div>
 
-          {paddingTop > 0 && (
-            <div aria-hidden style={{ gridColumn: "1/-1", height: paddingTop }} />
+          {/* The entry block — new rows being typed, stuck under the header.
+              Present only while `edit.addRow()` has open entries. */}
+          {features.editing && newRowCount > 0 && (
+            <TMDataGridEntryRows
+              orderedColumns={orderedColumns}
+              layoutFor={layoutFor}
+              rowHeight={rowHeight}
+            />
           )}
 
           <TMDataGridBodyRowGroup
@@ -1343,11 +1936,40 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
             onContextMenu={handleContextMenu}
             onClose={closeContextMenu}
           >
-            {virtualItems.map((virtualItem) => {
-              const row = rows[virtualItem.index];
-              if (!row) return null;
+            {(() => {
+              /**
+               * One renderer for every body row, wherever it sits: the
+               * virtualized centre, or a pinned edge block. `viewIndex` is the
+               * row's index in the scrolling view — `-1` for a pinned row,
+               * which takes it out of striping, row measurement and the cell
+               * range, all of which are statements about the scrolling order.
+               * Scoped here rather than a component so the row keeps closing
+               * over the body's handlers without threading them as props.
+               */
+              const renderBodyRow = (
+                row: Row<TMDataGridFeatures, TMDataGridRowData>,
+                viewIndex: number,
+                ariaRowIndex: number,
+                pinnedAt?: "top" | "bottom",
+              ) => {
               const isGroupRow = row.getIsGrouped();
               const isInteractive = rowGesturesFor(row);
+              const rowCells = [
+                ...row.getLeftVisibleCells(),
+                ...row.getCenterVisibleCells(),
+                ...row.getRightVisibleCells(),
+              ];
+              // Row mode opens every editable cell of the row at once;
+              // exactly one of them may take the focus.
+              const rowEditing =
+                editActive !== null &&
+                editActive.rowId === row.id &&
+                editActive.columnId === null;
+              const firstEditableColumnId = rowEditing
+                ? (rowCells.find((cell) =>
+                    edit.canEditCell(row, cell.column),
+                  )?.column.id ?? null)
+                : null;
               // Cell selection takes the body's tab stop off the row and puts
               // it on a cell — two stops per row would make Tab a way of
               // walking the grid, which is what the arrow keys are for. Space
@@ -1358,10 +1980,11 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                 (selectsOnRowClick || features.highlightRow);
               return (
                 <div
-                  key={virtualItem.key}
+                  key={row.id}
                   role="row"
-                  aria-rowindex={virtualItem.index + headerGroups.length + 1}
-                  data-testid={`dg-row-${row.id}`}
+                  aria-rowindex={ariaRowIndex}
+                  data-dg-part="row"
+                  data-row-id={row.id}
                   // Only measured when details are on: without them every row
                   // is exactly `rowHeight`, and the estimate above is already
                   // the answer — so a plain grid keeps its ResizeObserver-free
@@ -1372,13 +1995,21 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                   // element back to its item. The panel is inside this element,
                   // so what gets measured is the row *and* its detail — which
                   // is the whole reason no second virtual item is needed.
-                  data-index={renderDetails ? virtualItem.index : undefined}
-                  ref={renderDetails ? virtualizer.measureElement : undefined}
+                  data-index={
+                    renderDetails && viewIndex >= 0 ? viewIndex : undefined
+                  }
+                  ref={
+                    renderDetails && viewIndex >= 0
+                      ? virtualizer.measureElement
+                      : undefined
+                  }
                   // The tree's own rows. `data-grouped` rather than a class, to
                   // match how the rest of the row's state is published — and so
                   // a consumer can restyle them without reaching into modules.
                   data-grouped={isGroupRow}
                   data-depth={row.depth}
+                  // Which edge block the row sits in, for styling hooks.
+                  data-pinned={pinnedAt}
                   // Gated on the flag, not just on `getIsSelected()`: under
                   // `"highlight"` there is no selection, but `rowSelection` may
                   // still hold ids from before the mode changed — TanStack never
@@ -1404,6 +2035,11 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                   data-highlighted={
                     features.highlightRow && row.id === highlightedRowId
                   }
+                  // Marked deleted under batch: struck through and inert
+                  // until submitAll reports it, or the mark is toggled back.
+                  data-deleted={
+                    deletedRowIds.length > 0 && deletedRowIds.includes(row.id)
+                  }
                   // The menu is anchored to the rowgroup, so Mantine's own
                   // `data-expanded` lands there rather than on a row. This is
                   // what says which row the open menu is about.
@@ -1420,10 +2056,18 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                       ? true
                       : undefined
                   }
-                  className={classes.bodyRow}
+                  // From the row's position in the whole view, so the stripes
+                  // survive the virtualizer's moving window — see the prop.
+                  data-striped={
+                    striped && viewIndex >= 0 ? viewIndex % 2 === 1 : undefined
+                  }
+                  className={[classes.bodyRow, rowClassNameFor(row)]
+                    .filter(Boolean)
+                    .join(" ")}
                   style={{
                     minHeight: rowHeight,
                     cursor: isInteractive ? "pointer" : undefined,
+                    ...rowStyleFor(row),
                   }}
                   // Keyboard parity with the checkbox the row replaces.
                   tabIndex={takesKeyboard ? 0 : undefined}
@@ -1480,16 +2124,65 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                       : undefined
                   }
                 >
-                  {[
-                    ...row.getLeftVisibleCells(),
-                    ...row.getCenterVisibleCells(),
-                    ...row.getRightVisibleCells(),
-                  ].map((cell, cellIndex) => (
+                  {rowCells.map((cell, cellIndex) => {
+                    const isEditingCell =
+                      (editActive !== null &&
+                        editActive.rowId === row.id &&
+                        editActive.columnId === cell.column.id) ||
+                      (rowEditing && edit.canEditCell(row, cell.column));
+                    return (
                     <TMDataGridBodyCell
                       key={cell.id}
                       cell={cell}
                       rowHeight={rowHeight}
                       layout={layoutFor(cell.column.id)}
+                      contentOverride={
+                        rowNumberById !== null &&
+                        cell.column.id === ROW_NUMBER_COLUMN_ID
+                          ? rowNumberById.get(row.id)
+                          : undefined
+                      }
+                      highlightNeedles={matchNeedles?.get(cell.column.id)}
+                      editor={
+                        isEditingCell ? (
+                          <TMDataGridCellEditor
+                            cell={cell}
+                            row={row}
+                            takeSeedText={takeEditSeed}
+                            autoFocus={
+                              !rowEditing ||
+                              cell.column.id === firstEditableColumnId
+                            }
+                            onClose={(close) =>
+                              handleEditorClose(
+                                { rowId: row.id, columnId: cell.column.id },
+                                close,
+                              )
+                            }
+                          />
+                        ) : undefined
+                      }
+                      onClick={
+                        onCellClick && !isGroupRow
+                          ? (event) =>
+                              onCellClick(cellEventArgs(cell, row, event))
+                          : undefined
+                      }
+                      onDoubleClick={
+                        (features.editing || onCellDoubleClick) && !isGroupRow
+                          ? (event) => {
+                              onCellDoubleClick?.(
+                                cellEventArgs(cell, row, event),
+                              );
+                              if (!features.editing) return;
+                              if (!edit.canEditCell(row, cell.column)) return;
+                              openEditor({
+                                rowId: row.id,
+                                columnId: cell.column.id,
+                              });
+                            }
+                          : undefined
+                      }
                       // The cells come out in the same left → centre → right
                       // order as `orderedColumns`, which is what lets the index
                       // here stand for the column index everywhere else.
@@ -1514,17 +2207,9 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                               // take" — which under `"single"` is the one cell
                               // the user is standing on.
                               selected: cellRangeSelection
-                                ? isWithinBounds(
-                                    rangeBounds,
-                                    virtualItem.index,
-                                    cellIndex,
-                                  )
+                                ? isWithinBounds(rangeBounds, viewIndex, cellIndex)
                                 : isCellAt(focusedCell, row.id, cell.column.id),
-                              edges: boundsEdges(
-                                rangeBounds,
-                                virtualItem.index,
-                                cellIndex,
-                              ),
+                              edges: boundsEdges(rangeBounds, viewIndex, cellIndex),
                             }
                           : undefined
                       }
@@ -1567,14 +2252,19 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                           : undefined
                       }
                       onContextMenu={
-                        rowContextMenu || cellRangeSelection
-                          ? () => {
+                        rowContextMenu || cellRangeSelection || onCellContextMenu
+                          ? (event) => {
                               contextMenuColumnRef.current = cell.column.id;
+                              if (isGroupRow) return;
+                              onCellContextMenu?.(
+                                cellEventArgs(cell, row, event),
+                              );
                             }
                           : undefined
                       }
                     />
-                  ))}
+                    );
+                  })}
 
                   {/* A second grid row inside the row element, on the same
                       subgrid tracks — which is what lets one measurement cover
@@ -1585,7 +2275,8 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                     <div
                       role="cell"
                       aria-colspan={orderedColumns.length}
-                      data-testid={`dg-details-${row.id}`}
+                      data-dg-part="details"
+                      data-row-id={row.id}
                       className={classes.detailsCell}
                       // The row underneath may select, highlight or open a
                       // context menu. A panel is content, not part of that
@@ -1604,39 +2295,132 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                   )}
                 </div>
               );
-            })}
+              };
+
+              return (
+                <>
+                  {/* The pinned edge blocks. Same sticky mechanics as the
+                      entry block — the *block* is the sticky element, its rows
+                      flow normally inside it. `role="presentation"` keeps the
+                      wrapper out of the accessibility tree, so the rows stay
+                      direct children of the rowgroup. Inside the rowgroup so
+                      a right-click on a pinned row still opens the menu. */}
+                  {pinnedTopRows.length > 0 && (
+                    <div
+                      role="presentation"
+                      data-dg-part="pinned-top"
+                      className={classes.pinnedTopBlock}
+                    >
+                      {pinnedTopRows.map((row, index) =>
+                        renderBodyRow(
+                          row,
+                          -1,
+                          headerGroups.length + index + 1,
+                          "top",
+                        ),
+                      )}
+                    </div>
+                  )}
+
+                  {paddingTop > 0 && (
+                    <div
+                      aria-hidden
+                      style={{ gridColumn: "1/-1", height: paddingTop }}
+                    />
+                  )}
+
+                  {virtualItems.map((virtualItem) => {
+                    const row = rows[virtualItem.index];
+                    if (!row) return null;
+                    return renderBodyRow(
+                      row,
+                      virtualItem.index,
+                      virtualItem.index +
+                        headerGroups.length +
+                        pinnedTopRows.length +
+                        1,
+                    );
+                  })}
+
+                  {paddingBottom > 0 && (
+                    <div
+                      aria-hidden
+                      style={{ gridColumn: "1/-1", height: paddingBottom }}
+                    />
+                  )}
+
+                  {pinnedBottomRows.length > 0 && (
+                    <div
+                      role="presentation"
+                      data-dg-part="pinned-bottom"
+                      className={classes.pinnedBottomBlock}
+                    >
+                      {pinnedBottomRows.map((row, index) =>
+                        renderBodyRow(
+                          row,
+                          -1,
+                          headerGroups.length +
+                            pinnedTopRows.length +
+                            rows.length +
+                            index +
+                            1,
+                          "bottom",
+                        ),
+                      )}
+                    </div>
+                  )}
+                </>
+              );
+            })()}
           </TMDataGridBodyRowGroup>
 
+          {/* The empty matrix, one state at a time: loading wins (data is on
+              its way, "empty" would be a lie), open entry rows show only
+              themselves (a "no rows" under the row being typed reads as a
+              contradiction), then the consumer's blank slate, then the two
+              defaults — filtered-empty with its search icon, truly-empty as
+              plain text, because only one of them is the user's own doing. */}
           {isEmpty && loading === true && (
             <div role="row" className={classes.messageRow}>
               <Loader size="lg" aria-label={labels.loading} />
             </div>
           )}
 
-          {isEmpty && loading !== true && (
+          {isEmpty && loading !== true && newRowCount === 0 && (
             <div role="row" className={classes.messageRow}>
-              <SearchIcon size={40} stroke={1.4} opacity={0.4} />
-              <Text size={controlSize} c="dimmed">
-                {noResultsLabel}
-              </Text>
+              {renderEmptyState !== undefined ? (
+                renderEmptyState({
+                  hasActiveFilters,
+                  table: table as unknown as Table<TMDataGridFeatures, TData>,
+                })
+              ) : hasActiveFilters ? (
+                <>
+                  <SearchIcon size={40} stroke={1.4} opacity={0.4} />
+                  <Text size={controlSize} c="dimmed">
+                    {noResultsLabel}
+                  </Text>
+                </>
+              ) : (
+                <Text size={controlSize} c="dimmed">
+                  {labels.noRows}
+                </Text>
+              )}
             </div>
           )}
 
-          {paddingBottom > 0 && (
-            <div
-              aria-hidden
-              style={{ gridColumn: "1/-1", height: paddingBottom }}
-            />
-          )}
-
           {/* Sticky along the bottom edge, the way the header is along the
               top. `flexRender` with the header context, which is what a
               TanStack `footer` renderer is written against. */}
           {hasSummaryRow && (
             <div
               role="row"
-              aria-rowindex={rows.length + headerGroups.length + 1}
-              data-testid="dg-summary-row"
+              aria-rowindex={
+                rows.length + pinnedRowCount + headerGroups.length + 1
+              }
+              // Also what the height measurement above looks for. One
+              // attribute serves both now that the part name *is* the
+              // published contract rather than a testing-only alias.
+              data-dg-part="summary-row"
               className={classes.summaryRow}
             >
               {leafHeaders.map((header) => {