@patterninc/pattern-ui 0.0.0-main.20260929.db2f8e8fde0d

package/src/components/DataGrid/DataGrid.tsx

@@ -0,0 +1,1411 @@
+import { useLingui } from '@lingui/react/macro'
+import { cn } from 'cn'
+import * as React from 'react'
+
+import type { RestrictedIconProps } from '../../lib/utils/icon-helpers'
+import { Checkbox } from '../Checkbox/Checkbox'
+import CalendarIcon from '../icons/CalendarIcon'
+import ChevronDownSquareIcon from '../icons/ChevronDownSquareIcon'
+import Dollar2Icon from '../icons/Dollar2Icon'
+import HashtagIcon from '../icons/HashtagIcon'
+import LinkIcon from '../icons/LinkIcon'
+import PaperclipIcon from '../icons/PaperclipIcon'
+import SquareCheckIcon from '../icons/SquareCheckIcon'
+import TagIcon from '../icons/TagIcon'
+import TextAlignLeftIcon from '../icons/TextAlignLeftIcon'
+import TextIcon from '../icons/TextIcon'
+import { DataGridCell } from './DataGridCell'
+import { DataGridCellEditor } from './DataGridCellEditor'
+import { DataGridCellValue } from './DataGridCellValue'
+import { DataGridColumnHeader } from './DataGridColumnHeader'
+import { DataGridContext } from './DataGridContext'
+import { DataGridDatePickerCell } from './DataGridDatePickerCell'
+import { DataGridFooterOptionsMenu, useColumnHeaderMenu } from './DataGridMenus'
+import { DataGridPickerCell } from './DataGridPickerCell'
+import { DataGridRow } from './DataGridRow'
+import { DataGridRowHeader } from './DataGridRowHeader'
+import { partitionDataGridChildren } from './dataGridSlots'
+import type {
+  DataGridAlign,
+  DataGridCellEdit,
+  DataGridCellRange,
+  DataGridCellValueType,
+  DataGridColumn,
+  DataGridLayout,
+  DataGridRowData,
+  DataGridRowId,
+  DataGridSelectOption,
+  DataGridSortDirection,
+  DataGridValueState,
+  DataGridVariant,
+} from './dataGridTypes'
+import { useCellRangeSelection } from './hooks/useCellRangeSelection'
+import { useColumnResize } from './hooks/useColumnResize'
+import { useDataGridFind } from './hooks/useDataGridFind'
+import { useDataGridLayout } from './hooks/useDataGridLayout'
+import { useDataGridSelection } from './hooks/useDataGridSelection'
+import { useStickyColumns } from './hooks/useStickyColumns'
+
+// ── Re-export the family's parts + shared types (barrel) ────────────────────
+export type {
+  DataGridAlign,
+  DataGridCellEdit,
+  DataGridCellEditValue,
+  DataGridCellPosition,
+  DataGridCellRange,
+  DataGridCellState,
+  DataGridColumn,
+  DataGridColumnHeaderState,
+  DataGridCellValueType,
+  DataGridDensity,
+  DataGridLayout,
+  DataGridPaginationProps,
+  DataGridPinSide,
+  DataGridRowData,
+  DataGridRowHeaderState,
+  DataGridRowId,
+  DataGridRowState,
+  DataGridSelectOption,
+  DataGridSortDirection,
+  DataGridValueState,
+  DataGridVariant,
+} from './dataGridTypes'
+export { DataGridCell, type DataGridCellProps } from './DataGridCell'
+export { DataGridCellEditor, type DataGridCellEditorProps } from './DataGridCellEditor'
+export { DataGridCellValue, type DataGridCellValueProps } from './DataGridCellValue'
+export { DataGridDatePickerCell, type DataGridDatePickerCellProps } from './DataGridDatePickerCell'
+export { DataGridPickerCell, type DataGridPickerCellProps } from './DataGridPickerCell'
+export {
+  DataGridColumnHeader,
+  type DataGridColumnHeaderHandlerProps,
+  type DataGridColumnHeaderProps,
+} from './DataGridColumnHeader'
+export { DataGridGroupHeader, type DataGridGroupHeaderProps } from './DataGridGroupHeader'
+export { DataGridRow, type DataGridRowProps } from './DataGridRow'
+export { DataGridRowHeader, type DataGridRowHeaderProps } from './DataGridRowHeader'
+export { DataGridTreeCell, type DataGridTreeCellProps } from './DataGridTreeCell'
+export { DataGridFind, type DataGridFindProps } from './DataGridFind'
+export { DataGridHeader, type DataGridSlot } from './dataGridSlots'
+export { DataGridSearchBar, type DataGridSearchBarProps } from './DataGridSearchBar'
+export { DataGridSelectionBar, type DataGridSelectionBarProps } from './DataGridSelectionBar'
+export { DataGridStatusBar, type DataGridStatusBarProps } from './DataGridStatusBar'
+export { DataGridToolbar, type DataGridToolbarProps } from './DataGridToolbar'
+export {
+  useDataGridContext,
+  useOptionalDataGridContext,
+  type DataGridContextValue,
+  type DataGridFindState,
+} from './DataGridContext'
+// Headless logic that ships with the family. The composed `DataGrid` above is built on these — it
+// uses `useColumnResize`, `useStickyColumns` and `useCellRangeSelection` internally — and they are
+// exported so apps can compose a custom table from the atoms with the same sort / selection /
+// paging / resize / sticky-column / cell-range / nesting logic instead of re-implementing it.
+export {
+  useDataGridSort,
+  type DataGridSortState,
+  type UseDataGridSortOptions,
+  type UseDataGridSortResult,
+} from './hooks/useDataGridSort'
+export {
+  useDataGridSelection,
+  type UseDataGridSelectionOptions,
+  type UseDataGridSelectionResult,
+} from './hooks/useDataGridSelection'
+export {
+  useDataGridPagination,
+  type UseDataGridPaginationOptions,
+  type UseDataGridPaginationResult,
+} from './hooks/useDataGridPagination'
+export {
+  useDataGridTree,
+  dataGridTreeRowMotion,
+  DATA_GRID_TREE_MOTION_MS,
+  type DataGridFlatRow,
+  type DataGridTreeNode,
+  type UseDataGridTreeOptions,
+  type UseDataGridTreeResult,
+} from './hooks/useDataGridTree'
+export {
+  useColumnResize,
+  type UseColumnResizeColumn,
+  type UseColumnResizeOptions,
+  type UseColumnResizeResult,
+} from './hooks/useColumnResize'
+export {
+  useDataGridLayout,
+  type UseDataGridLayoutOptions,
+  type UseDataGridLayoutResult,
+} from './hooks/useDataGridLayout'
+export {
+  useStickyColumns,
+  type UseStickyColumnsOptions,
+  type UseStickyColumnsResult,
+} from './hooks/useStickyColumns'
+export {
+  useCellRangeSelection,
+  type DataGridRangeRect,
+  type UseCellRangeSelectionOptions,
+  type UseCellRangeSelectionResult,
+} from './hooks/useCellRangeSelection'
+export {
+  useDataGridFind,
+  type DataGridFindMatch,
+  type UseDataGridFindOptions,
+  type UseDataGridFindResult,
+} from './hooks/useDataGridFind'
+
+const GUTTER_WIDTH = '48px'
+const DEFAULT_RESIZE_WIDTH = 150
+const MIN_RESIZE_WIDTH = 64
+// Placeholder rows while `isLoading`. Fixed, not a prop — matches `Table` so a loading grid fills a
+// typical viewport and column widths do not jump when data arrives.
+const SKELETON_ROW_COUNT = 20
+// The column-header row is a fixed 40px (`h-10`) band above the data rows. The sticky selection-ring
+// layer lives at the top of the scroll viewport, so it offsets each run past the header to reach the
+// rows.
+const HEADER_ROW_HEIGHT = 40
+
+// A pinned cell / sticky gutter has an OPAQUE `::before` backing (so scrolling cells slide under it),
+// which also hides any selection tint set on the cell's own background — the tint only shows through
+// the 1px borders ("peaking"). So the tint is layered onto that backing as a background-IMAGE (a flat
+// gradient of the state token) which composites over the solid backing to the SAME surface a
+// non-pinned range cell shows. (The grid has no row hover, so only the cell-range selection tint
+// needs this treatment.)
+const PIN_SELECTED_BACKING =
+  'before:bg-[image:linear-gradient(var(--color-depth-secondary-10),var(--color-depth-secondary-10))]'
+
+/**
+ * Map row `bg-*` classes onto the pinned `::before` so row tints are not hidden by opaque pin
+ * backing.
+ */
+function rowPinBackingClass(className?: string) {
+  if (!className) return undefined
+  const pinBg = className
+    .split(/\s+/)
+    .filter((token) => token.startsWith('bg-') && !token.startsWith('bg-clip-'))
+    .map((token) => `before:${token}`)
+  return pinBg.length > 0 ? pinBg.join(' ') : undefined
+}
+
+// Selection fill + ring share these classes (same rounded rect) so the fill can't poke past the
+// ring's rounded corners. ROW selection renders both together in the sticky VIEWPORT layer (over the
+// cells), so the rounded rectangle stays hugging the pinned columns while the middle scrolls. CELL-
+// RANGE selection instead keeps the fill BEHIND the rows (shows through non-pinned cells; pinned
+// range cells paint their own via `PIN_SELECTED_BACKING`) with the ring above at `z-30`, since a
+// range is tied to specific columns rather than the whole viewport.
+const SELECTION_FILL = 'rounded-xl bg-depth-secondary-10'
+const SELECTION_RING =
+  'rounded-xl shadow-[inset_0_0_0_2px_var(--color-secondary-base),inset_0_0_0_4px_var(--color-base-inverse)]'
+
+const HEADER_TYPE_ICON: Partial<
+  Record<DataGridCellValueType, React.ComponentType<RestrictedIconProps>>
+> = {
+  text: TextIcon,
+  number: HashtagIcon,
+  currency: Dollar2Icon,
+  select: ChevronDownSquareIcon,
+  tags: TagIcon,
+  checkbox: SquareCheckIcon,
+  date: CalendarIcon,
+  url: LinkIcon,
+  'long-text': TextAlignLeftIcon,
+  file: PaperclipIcon,
+}
+
+const TEXT_EDITOR_TYPES = new Set<DataGridCellValueType>([
+  'text',
+  'long-text',
+  'number',
+  'currency',
+  'url',
+])
+
+/**
+ * Resolve a column's alignment. Cell content is left-aligned by default (UX: even numbers/currency
+ * read left); an explicit `align` on the column still wins.
+ */
+function resolveAlign(col: DataGridColumn): DataGridAlign {
+  return col.align ?? 'start'
+}
+
+/**
+ * Header type-marker: an explicit `typeIcon` (including `null` to hide) wins; otherwise the icon
+ * for `type`. `??` cannot be used here — it would treat `null` as missing and fall back to
+ * TextIcon.
+ */
+function resolveTypeIcon(col: DataGridColumn) {
+  if (col.typeIcon !== undefined) return col.typeIcon
+  return HEADER_TYPE_ICON[col.type ?? 'text']
+}
+
+/**
+ * Map a column's raw value to the prop `DataGridCellValue` expects for that type, including the
+ * `valueState` that turns a blank cell into the em-dash placeholder. Without it the grid would show
+ * two different empty cells side by side: `DataGridPickerCell` and `DataGridDatePickerCell` set
+ * `valueState` themselves, so their empty cells render the dash while a plain text or currency cell
+ * rendered nothing at all.
+ */
+function cellValueProps(
+  type: DataGridCellValueType | undefined,
+  value: unknown,
+  options?: DataGridSelectOption[],
+) {
+  if (type === 'tags' || type === 'select') {
+    // oxlint-disable-next-line typescript/no-base-to-string
+    const raw = Array.isArray(value) ? value.map(String) : value != null ? [String(value)] : []
+    // Show each stored value's display label when the column defines options; fall back to the raw
+    // value (a string label defined on the option; non-string labels aren't renderable as tags).
+    const labelByValue = new Map(
+      (options ?? []).map((option) => [
+        option.value,
+        typeof option.label === 'string' ? option.label : option.value,
+      ]),
+    )
+    return { tags: raw.map((entry) => labelByValue.get(entry) ?? entry) }
+  }
+  // A checkbox has no empty face — unchecked *is* the empty value.
+  if (type === 'checkbox') return { checked: Boolean(value) }
+  const valueState: DataGridValueState = value == null || value === '' ? 'empty' : 'filled'
+  return { value: value as React.ReactNode, valueState }
+}
+
+function getGridTemplate(
+  columns: DataGridColumn[],
+  selectable: boolean,
+  widthFor: (col: DataGridColumn) => number,
+): string {
+  const tracks = columns.map((col) => {
+    // Pinned columns render at a fixed px width so the sticky offset (also from `widthFor`) matches
+    // the rendered track exactly — a CSS-string or unsized pinned column would otherwise overlap its
+    // neighbour or leave a gap because the offset wouldn't equal the rendered width.
+    if (col.resizable || col.pinned) return `${widthFor(col)}px`
+    if (col.width == null) return 'minmax(0, 1fr)'
+    return typeof col.width === 'number' ? `${col.width}px` : col.width
+  })
+  return [selectable ? GUTTER_WIDTH : null, ...tracks].filter(Boolean).join(' ')
+}
+
+export interface DataGridProps extends Omit<React.ComponentProps<'div'>, 'title'> {
+  /** Column definitions (header, value type, alignment, sortability, width). */
+  columns: DataGridColumn[]
+  /**
+   * Row data for the rows currently shown. The grid renders these as-is — the consumer supplies
+   * data already sorted / filtered / paged (this is a controlled, presentational grid; it never
+   * transforms the dataset).
+   */
+  data: DataGridRowData[]
+  /**
+   * Dataset total for the status-bar count ("179 rows") and selection readout ("12 of 179
+   * selected"). Defaults to `data.length`. A paged consumer must pass the unpaged total — otherwise
+   * the footer inherits the current page and reads as "20 rows" on a 20-row page of a 179-row
+   * table.
+   */
+  rowCount?: number
+  /** Surface treatment. Composed parts inherit it from the grid via context. */
+  variant?: DataGridVariant
+  /**
+   * Controlled column layout — which columns are hidden, where each pinned column sits, and the row
+   * height. Apply `onLayoutChange` and pass the next layout back, exactly like `selectedIds`. Omit
+   * it and the grid keeps its own layout, seeded from `defaultLayout`.
+   */
+  layout?: DataGridLayout
+  /**
+   * Starting layout when `layout` is omitted. Anything unset is empty pins / no hidden columns /
+   * `medium` density. Pin and hide live here, not on the column definition.
+   */
+  defaultLayout?: Partial<DataGridLayout>
+  /**
+   * Called with the next layout whenever a header menu or the footer's Columns / Row height menu
+   * changes it. Fires in both modes — use it alone to persist a view, or with `layout` to own one.
+   */
+  onLayoutChange?: (layout: DataGridLayout) => void
+  /** Show the leading selection gutter (row-number ↔ checkbox) and enable row selection. */
+  selectable?: boolean
+  /**
+   * Controlled selected row ids (may include ids not on the current page). Omit it and the grid
+   * tracks the selection itself, seeded from `defaultSelectedIds` — which column the checkboxes
+   * tick is the grid's own UI state, so `selectable` works on its own. Pass this only when
+   * something outside the grid needs to drive it (a saved selection, a cross-page "select all").
+   */
+  selectedIds?: DataGridRowId[]
+  /** Rows selected to begin with when `selectedIds` is omitted. */
+  defaultSelectedIds?: DataGridRowId[]
+  /** Called with the next selected row ids when the selection changes. Fires in both modes. */
+  onSelectedIdsChange?: (ids: DataGridRowId[]) => void
+  /**
+   * Enable rectangular cell-range selection (independent of row selection). Clicking a cell selects
+   * it; shift-click or drag extends the range. Like row selection, the grid owns the range unless
+   * you pass `selectedRange`.
+   */
+  cellSelectable?: boolean
+  /**
+   * Controlled cell-selection range (its two corner cells). `null` is an empty range you own;
+   * omitting the prop hands the range back to the grid.
+   */
+  selectedRange?: DataGridCellRange | null
+  /** Called with the next range as the cell selection is made / extended (`null` when cleared). */
+  onSelectedRangeChange?: (range: DataGridCellRange | null) => void
+  /** Key of the column the data is currently sorted by (drives the header indicator only). */
+  sortedColumn?: string
+  /** Direction of the active sort (drives the header indicator only). */
+  sortDirection?: DataGridSortDirection
+  /**
+   * Called from the header menu's Sort ascending / descending / Remove sort rows with the exact
+   * next direction (`null` clears the sort). Sorting changes the data, not the grid's own state, so
+   * this stays with the consumer: sort the rows and update `sortedColumn` / `sortDirection`.
+   */
+  onSortChange?: (columnKey: string, direction: DataGridSortDirection | null) => void
+  /** Called when an inline edit is committed — the consumer applies it to its own data. */
+  onCellEdit?: (edit: DataGridCellEdit) => void
+  /** Called when a column finishes resizing, with the column key and its new width in px. */
+  onColumnResize?: (columnKey: string, width: number) => void
+  /**
+   * The grid's chrome, written in the order it appears on screen — a `DataGridToolbar`, a
+   * `DataGridStatusBar`, a `DataGridSelectionBar`. Each part declares whether it belongs above or
+   * below the rows, so there is no slot to name; wrap anything the grid does not recognise in
+   * `DataGridHeader` to put it above the column headers instead of below the rows.
+   *
+   * The rows themselves are not children: `columns` + `data` drive one CSS grid whose template,
+   * sticky columns, roving tabindex and selection overlays have to be owned in one place.
+   */
+  children?: React.ReactNode
+  /** 1-based number to show for the first visible row (for paged data). Defaults to 1. */
+  rowNumberStart?: number
+  /**
+   * Custom match test for find-in-grid (default: case-insensitive substring on the stringified cell
+   * value). Return `true` when the cell value matches the lower-cased query. Highlighting runs when
+   * `DataGridFind` is mounted inside the grid and the query is non-empty.
+   */
+  findMatcher?: (value: unknown, query: string, columnKey: string) => boolean
+  /**
+   * When true, the body renders a fixed set of skeleton rows matching `columns` instead of `data`,
+   * preserving column widths so there is no layout shift when data arrives.
+   */
+  isLoading?: boolean
+  /**
+   * Shown in place of the rows when `data` is empty and the grid is not loading; the column headers
+   * stay put. Defaults to a plain "No records to display" line — pass anything (an `EmptyState`, a
+   * "clear filters" prompt) to replace it. The grid only centres what it is given.
+   */
+  emptyState?: React.ReactNode
+  /**
+   * Per-row className / style, plus selection holes. Merged onto the row after the grid's own
+   * layout classes. `selectable: false` keeps the gutter but hides the checkbox (StandardTable
+   * nested rows with parent checkboxes only). `checkboxDisabled` blocks toggling and select-all;
+   * the gutter stays a row number — no checkbox on hover.
+   */
+  getRowProps?: (
+    row: DataGridRowData,
+    index: number,
+  ) =>
+    | {
+        className?: string
+        style?: React.CSSProperties
+        selectable?: boolean
+        checkboxDisabled?: boolean
+      }
+    | undefined
+  /**
+   * Render an extra row directly before this one, inside the scroll body. With `renderAfterRow`
+   * this is the seam for anything that is not a plain data row — a group bar above a group's first
+   * row, an expanded detail panel, a subtotal. The grid owns none of it: no trigger, no open state,
+   * no styling. Drive it from your own state (typically a chevron in a `column.render`) and return
+   * content only for the rows that need it.
+   *
+   * Return a row — a `DataGridRow` (wrap free-form content in a single `role='gridcell'` child) or
+   * a `DataGridGroupHeader`. The node is placed in the grid's `role='rowgroup'` untouched, which
+   * may only own rows. Any height is fine: the selection ring and the cell-range overlay measure
+   * real row geometry rather than assuming every row is the density height.
+   */
+  renderBeforeRow?: (row: DataGridRowData, index: number) => React.ReactNode
+  /** Render an extra row directly after this one. See `renderBeforeRow`. */
+  renderAfterRow?: (row: DataGridRowData, index: number) => React.ReactNode
+  /** Optional test id rendered as the `qa-test-id` attribute for QA testing */
+  qaTestId?: string
+}
+
+export function DataGrid({
+  columns,
+  data,
+  rowCount: rowCountProp,
+  variant = 'inverse',
+  layout: layoutProp,
+  defaultLayout,
+  onLayoutChange,
+  selectable = false,
+  selectedIds: selectedIdsProp,
+  defaultSelectedIds,
+  onSelectedIdsChange,
+  cellSelectable = false,
+  selectedRange,
+  onSelectedRangeChange,
+  sortedColumn,
+  sortDirection,
+  onSortChange,
+  onCellEdit,
+  onColumnResize,
+  children,
+  rowNumberStart = 1,
+  findMatcher,
+  isLoading = false,
+  emptyState,
+  getRowProps,
+  renderBeforeRow,
+  renderAfterRow,
+  className,
+  qaTestId = 'data-grid',
+  ...props
+}: DataGridProps) {
+  const { t } = useLingui()
+  const gridRef = React.useRef<HTMLDivElement>(null)
+  const [editingCell, setEditingCell] = React.useState<{
+    rowId: string
+    columnKey: string
+  } | null>(null)
+  // Column pinning / visibility / density run on the shared headless hook, so the composed grid and
+  // a hand-built one stay on one implementation. `effectiveColumns` is what actually renders —
+  // everything below (resize, sticky, template, find, header, cells) works off it, with each
+  // column's `pinned` already resolved against the layout.
+  const {
+    columns: effectiveColumns,
+    layout,
+    setColumnPinned,
+    setColumnHidden,
+    setDensity,
+  } = useDataGridLayout({ columns, layout: layoutProp, defaultLayout, onLayoutChange })
+  const densityState = layout.density
+  const hiddenKeys = new Set(layout.hidden)
+
+  // An open editor belongs to one row and one column. If either leaves the grid — a page turn, a
+  // filter, hiding the column — nothing renders it, but the state survives and springs the editor
+  // back open the moment that row returns. Dropping it during render (the pattern the React docs
+  // call adjusting state on prop change) keeps it tied to what is actually on screen.
+  if (
+    editingCell &&
+    !(
+      data.some((row) => String(row.id) === editingCell.rowId) &&
+      effectiveColumns.some((col) => col.key === editingCell.columnKey)
+    )
+  ) {
+    setEditingCell(null)
+  }
+
+  // Both grid menus live in `DataGridMenus` — they are pure JSX factories with no stake in the
+  // render loop below, and together they were about a fifth of this function.
+  const buildColumnHeaderMenu = useColumnHeaderMenu()
+  const renderHeaderMenu = (col: DataGridColumn) =>
+    buildColumnHeaderMenu({
+      column: col,
+      sortedColumn,
+      onSortChange,
+      setColumnPinned,
+      setColumnHidden,
+    })
+
+  const footerOptionsMenu = (
+    <DataGridFooterOptionsMenu
+      columns={columns}
+      hiddenKeys={hiddenKeys}
+      density={densityState}
+      setColumnHidden={setColumnHidden}
+      setDensity={setDensity}
+    />
+  )
+
+  // Chrome is written as children in screen order; each part says which band it belongs to.
+  const chrome = partitionDataGridChildren(children)
+
+  // Column resize + sticky (pinned) columns are the grid's own state; both come from the shared
+  // headless hooks so the composed grid and standalone consumers stay on one implementation.
+  const { widthFor, isResizing, startResize } = useColumnResize({
+    columns: effectiveColumns,
+    defaultWidth: DEFAULT_RESIZE_WIDTH,
+    minWidth: MIN_RESIZE_WIDTH,
+    onColumnResize,
+  })
+  const {
+    orderedColumns,
+    hasPinned,
+    stickyGutter,
+    getPinProps,
+    // Opaque backing for the sticky selection gutter. It comes from the hook rather than being
+    // re-derived here so the gutter and the pinned cells can't drift onto different surfaces.
+    surfaceBacking,
+    scrollRef,
+    onScroll,
+  } = useStickyColumns({
+    columns: effectiveColumns,
+    widthFor,
+    selectable,
+    variant,
+    gutterWidth: Number.parseInt(GUTTER_WIDTH, 10),
+    rowCount: isLoading ? SKELETON_ROW_COUNT : data.length,
+  })
+
+  const rowHeight = densityState === 'medium' ? 56 : 40
+
+  // Find-in-grid marks and steps through matching cells; it never filters. Only visible columns are
+  // searched — a hidden column has no cell to highlight or scroll to. The hook owns the query, the
+  // expanded state and the match position; what's left here is the two DOM effects, which belong to
+  // this component because they reach into its own markup.
+  const find = useDataGridFind({
+    rows: data,
+    columnKeys: effectiveColumns.map((col) => col.key),
+    matcher: findMatcher,
+    disabled: isLoading,
+  })
+
+  // Scroll the active match into view (imperative DOM after paint — the one valid effect here).
+  React.useEffect(() => {
+    if (!find.activeMatchKey) return
+    gridRef.current
+      ?.querySelector('[data-active-match]')
+      ?.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+  }, [find.activeMatchKey])
+
+  // Focus the search field when the magnifier expands it.
+  React.useEffect(() => {
+    if (find.open) {
+      gridRef.current
+        ?.querySelector<HTMLInputElement>('[qa-test-id=data-grid-search-bar] input')
+        ?.focus()
+    }
+  }, [find.open])
+
+  // When every column is a fixed / pinned / resizable px track (no flexible `1fr` column), the tracks
+  // can sum WIDER than the scroll viewport. A block-level row is only the viewport width, so its
+  // hover / selection background would stop at the fold and the columns revealed by scrolling right
+  // would show no row fill. Size those rows to their content (`w-max`) — still at least full width
+  // (`min-w-full`) — so the fill spans every column. Grids with a `1fr` column fill the viewport
+  // exactly (no overflow), so they keep the default width to preserve `1fr` shrink-to-fit.
+  const hasFlexColumn = orderedColumns.some(
+    (col) => col.width == null && !col.resizable && col.pinned == null,
+  )
+  const rowWidthClass = hasFlexColumn ? undefined : 'w-max min-w-full'
+  const template = getGridTemplate(orderedColumns, selectable, widthFor)
+  const isEmpty = !isLoading && data.length === 0
+
+  // ── Row geometry (for the selection overlays) ───────────────────────────
+  // The selection ring and the cell-range overlay are absolutely positioned siblings of the rows —
+  // they have to be, so their rounded rectangle can stay pinned to the scroll viewport and keep
+  // hugging the frozen columns. That means their vertical offsets are computed, and `index *
+  // rowHeight` is only right while every row is exactly the density height and nothing else sits in
+  // the body. Neither holds: a tall `column.render` grows its row, and `renderBeforeRow` /
+  // `renderAfterRow` inject content between rows. So measure the rows instead — `offsetTop` is
+  // relative to the `relative` rowgroup below, which is the same box the overlays are inset to.
+  const rowgroupRef = React.useRef<HTMLDivElement>(null)
+  const [rowRects, setRowRects] = React.useState<{ top: number; height: number }[]>([])
+  // Closes over nothing but the ref and the setter — both stable — so both effects below can share
+  // one implementation without re-subscribing the observer.
+  const measureRows = () => {
+    const rowgroup = rowgroupRef.current
+    if (!rowgroup) return
+    const next = Array.from(
+      rowgroup.querySelectorAll<HTMLElement>('[data-row-index]'),
+      (element) => ({ top: element.offsetTop, height: element.offsetHeight }),
+    )
+    // Bail when nothing moved. This is also what makes measuring after *every* render safe: an
+    // unconditional set would re-render, measure again, and never settle.
+    setRowRects((prev) =>
+      prev.length === next.length &&
+      prev.every((rect, i) => rect.top === next[i]?.top && rect.height === next[i]?.height)
+        ? prev
+        : next,
+    )
+  }
+
+  // Deliberately dependency-free. A row slot can change a row's height without changing the row
+  // count, the density or the template — closing one detail panel while opening another of the
+  // same height leaves the rowgroup exactly as tall as it was — so there is no dependency list
+  // that catches every case, and a stale rect paints the selection ring at the wrong offset.
+  React.useLayoutEffect(measureRows)
+
+  // Height changes that don't come from a render of this component at all: fonts or images
+  // settling, a container resize. Deferred by a frame because measuring (and the state update it
+  // can trigger) from inside the callback re-enters the observer, which browsers report as a
+  // "ResizeObserver loop completed with undelivered notifications".
+  React.useLayoutEffect(() => {
+    const rowgroup = rowgroupRef.current
+    if (!rowgroup) return
+    let frame = 0
+    const observer = new ResizeObserver(() => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(measureRows)
+    })
+    observer.observe(rowgroup)
+    return () => {
+      cancelAnimationFrame(frame)
+      observer.disconnect()
+    }
+    // `measureRows` is intentionally omitted: it reads only the ref and the setter, so the
+    // identity it gets on mount stays correct for the observer's lifetime.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Arithmetic is the pre-measurement fallback so an overlay never paints at the wrong offset on
+  // the first frame.
+  const rowTop = (index: number) => rowRects[index]?.top ?? index * rowHeight
+  const rowBottom = (index: number) => {
+    const rect = rowRects[index]
+    return rect ? rect.top + rect.height : (index + 1) * rowHeight
+  }
+
+  // ── Cell selection — via useCellRangeSelection ─────────────────────────────
+  // The hook owns the drag lifecycle, the rect math AND the range itself unless `selectedRange` is
+  // passed. `selectedRange` is forwarded raw: the hook reads `undefined` as "uncontrolled" and
+  // `null` as "controlled, nothing selected", so a `?? null` here would pin it in controlled mode
+  // and make `cellSelectable` inert on its own. Passing the ordered columns + page ids keeps the
+  // rect's indices aligned with the grid's render order, so the reported row/column highlights and
+  // the overlay block below read straight off `cellRange.rect`.
+  const cellRange = useCellRangeSelection({
+    rowIds: data.map((row) => row.id),
+    columnKeys: orderedColumns.map((col) => col.key),
+    range: selectedRange,
+    onRangeChange: onSelectedRangeChange,
+  })
+  const rangeRect = cellRange.rect
+  const gutterOffset = selectable ? 1 : 0
+  const isColumnReported = (index: number) =>
+    rangeRect != null && index >= rangeRect.colStart && index <= rangeRect.colEnd
+  const isRowReported = (index: number) =>
+    rangeRect != null && index >= rangeRect.rowStart && index <= rangeRect.rowEnd
+
+  // ── Row selection — via useDataGridSelection ───────────────────────────────
+  // `getRowProps` is consumer code, and the render asks three separate questions about each row
+  // (can it be toggled, is it in the select-all set, what chrome does it carry). Resolve it once
+  // per row here and read from this list instead of calling it again for each question.
+  const rowPropsList = data.map((row, index) => getRowProps?.(row, index))
+  const canToggleRow = (index: number) => {
+    const rowProps = rowPropsList[index]
+    return rowProps?.selectable !== false && !rowProps?.checkboxDisabled
+  }
+  // Only the rows that can actually be ticked are in scope for select-all, so a page of disabled
+  // rows never leaves the header checkbox stuck half-selected.
+  const selectablePageIds = data.flatMap((row, index) => (canToggleRow(index) ? [row.id] : []))
+
+  // Which rows are ticked is the grid's own UI state — nothing in `data` changes when you select a
+  // row — so the grid holds it unless the consumer takes over with `selectedIds`. Same hook a
+  // hand-built table would use, in the same controlled-or-uncontrolled shape as the layout and the
+  // cell range above; `onSelectedIdsChange` fires either way.
+  const rowSelection = useDataGridSelection({
+    rowIds: selectablePageIds,
+    selectedIds: selectedIdsProp,
+    defaultSelectedIds,
+    onSelectionChange: onSelectedIdsChange,
+  })
+  const selectedIds = rowSelection.selectedIds
+  const isRowSelected = rowSelection.isSelected
+  const allPageSelected = rowSelection.allSelected
+  const somePageSelected = rowSelection.someSelected
+  const selectedCount = rowSelection.selectedCount
+
+  // Row and cell selection are mutually exclusive (UX): selecting a row replaces any active cell
+  // range, and starting a cell selection (below) clears the row selection.
+  const toggleRow = (id: DataGridRowId, checked: boolean) => {
+    if (checked) cellRange.clear()
+    rowSelection.toggle(id)
+  }
+  const toggleAllOnPage = () => {
+    if (!allPageSelected) cellRange.clear()
+    rowSelection.toggleAll()
+  }
+
+  // ── Keyboard navigation ────────────────────────────────────────────────────
+  // `role='grid'` is a promise of arrow-key cell navigation, and it can't be delegated: nothing
+  // outside this component can reach between the rows to place a roving tabindex. So the body is
+  // one tab stop holding exactly one focusable cell, and the arrows move it from there. (Header
+  // controls stay individually tabbable — they are ordinary buttons, and sort / pin / hide are
+  // reachable that way without a second roving scheme.)
+  const [focusedCell, setFocusedCell] = React.useState<{ row: number; col: number }>({
+    row: 0,
+    col: 0,
+  })
+  // Clamp rather than store out-of-range: the page can shrink under the focused cell.
+  const focusRow = Math.min(focusedCell.row, Math.max(data.length - 1, 0))
+  const focusCol = Math.min(focusedCell.col, Math.max(orderedColumns.length - 1, 0))
+  const isFocusedCell = (rowIndex: number, colIndex: number) =>
+    rowIndex === focusRow && colIndex === focusCol
+
+  // Focus is moved imperatively from the key handler rather than through an effect, so the grid
+  // never steals focus on mount or on an unrelated re-render.
+  const focusCellAt = (rowIndex: number, colIndex: number) => {
+    const col = orderedColumns[colIndex]
+    if (!col) return
+    gridRef.current
+      ?.querySelector<HTMLElement>(
+        `[data-row-index="${rowIndex}"] [data-col-key="${CSS.escape(col.key)}"]`,
+      )
+      ?.focus()
+  }
+
+  const onCellKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+    // Only when the cell itself has focus. Inside an open editor, a checkbox or a picker trigger
+    // the keystroke belongs to that control — arrows move a caret, space ticks a box.
+    const cell = event.target as HTMLElement
+    if (!cell.matches('[data-cell]')) return
+
+    // Where we are comes from the cell that actually has focus, not from `focusedCell`: a run of
+    // keystrokes can be batched into one render, and a second arrow read off stale state would
+    // move from where the first one started rather than from where it landed.
+    const originRow = Number(cell.closest<HTMLElement>('[data-row-index]')?.dataset.rowIndex ?? -1)
+    const originCol = orderedColumns.findIndex((entry) => entry.key === cell.dataset.colKey)
+    if (originRow < 0 || originCol < 0) return
+
+    const lastRow = data.length - 1
+    const lastCol = orderedColumns.length - 1
+    let { row, col } = { row: originRow, col: originCol }
+
+    switch (event.key) {
+      case 'ArrowDown':
+        row = Math.min(row + 1, lastRow)
+        break
+      case 'ArrowUp':
+        row = Math.max(row - 1, 0)
+        break
+      case 'ArrowRight':
+        col = Math.min(col + 1, lastCol)
+        break
+      case 'ArrowLeft':
+        col = Math.max(col - 1, 0)
+        break
+      // Home / End go to the ends of the row; with the modifier, to the ends of the grid.
+      case 'Home':
+        col = 0
+        if (event.ctrlKey || event.metaKey) row = 0
+        break
+      case 'End':
+        col = lastCol
+        if (event.ctrlKey || event.metaKey) row = lastRow
+        break
+      // Enter / F2 opens the editor, the keyboard equivalent of the click that opens it. Only the
+      // inline text editors: pickers and date cells are their own triggers and handle their keys.
+      case 'Enter':
+      case 'F2': {
+        const target = orderedColumns[col]
+        const targetRow = data[row]
+        if (
+          target?.editable &&
+          target.render == null &&
+          targetRow &&
+          TEXT_EDITOR_TYPES.has(target.type ?? 'text')
+        ) {
+          event.preventDefault()
+          setEditingCell({ rowId: String(targetRow.id), columnKey: target.key })
+        }
+        return
+      }
+      // Space ticks the focused row, the same thing the gutter checkbox does.
+      case ' ': {
+        const targetRow = data[row]
+        if (selectable && targetRow && canToggleRow(row)) {
+          event.preventDefault()
+          toggleRow(targetRow.id, !isRowSelected(targetRow.id))
+        }
+        return
+      }
+      case 'Escape':
+        cellRange.clear()
+        return
+      default:
+        return
+    }
+
+    event.preventDefault()
+    // Shift + arrows extend the cell range, the keyboard counterpart of shift-clicking. Without
+    // this the whole range mode would be mouse-only.
+    if (cellSelectable) {
+      const target = data[row]
+      const targetCol = orderedColumns[col]
+      const originColKey = orderedColumns[originCol]?.key
+      const originRowId = data[originRow]?.id
+      if (target && targetCol) {
+        if (selectedCount > 0) rowSelection.clear()
+        cellRange.selectCell(target.id, targetCol.key, {
+          extend: event.shiftKey,
+          // The first shift + arrow has no range yet, so it anchors on the cell being left.
+          anchorFallback:
+            originRowId != null && originColKey != null
+              ? { rowId: originRowId, columnKey: originColKey }
+              : undefined,
+        })
+      }
+    }
+    setFocusedCell({ row, col })
+    focusCellAt(row, col)
+  }
+
+  // Contiguous runs of selected rows on this page → one selection ring each.
+  const selectionRuns: { start: number; length: number }[] = []
+  data.forEach((row, index) => {
+    if (!isRowSelected(row.id)) return
+    const last = selectionRuns.at(-1)
+    if (last && last.start + last.length === index) last.length += 1
+    else selectionRuns.push({ start: index, length: 1 })
+  })
+  // Starting (or extending) a cell selection replaces the row selection — the mirror of `toggleRow`
+  // clearing the range — so the two selection modes never show at once.
+  const startCellSelect =
+    (rowId: DataGridRowId, columnKey: string) => (event: React.PointerEvent) => {
+      if (selectedCount > 0) rowSelection.clear()
+      cellRange.startCellSelect(rowId, columnKey)(event)
+    }
+
+  return (
+    <DataGridContext.Provider
+      value={{
+        variant,
+        selectedIds,
+        selectedRange: cellRange.range,
+        selectedCount,
+        rowCount: rowCountProp ?? data.length,
+        selectionActive: !isLoading && (selectedCount > 0 || rangeRect != null),
+        clearSelection: () => {
+          rowSelection.clear()
+          cellRange.clear()
+        },
+        footerOptions: footerOptionsMenu,
+        find,
+      }}
+    >
+      <div
+        ref={gridRef}
+        role='grid'
+        // A `role='grid'` is expected to report its own size so assistive tech can say "row 21 of
+        // 248" while only one page is in the DOM. Columns are exact (the gutter counts as one).
+        // Rows are not: the grid is handed one page and never learns the total, so it claims a
+        // count only for an unpaged grid and otherwise reports -1, ARIA's "total unknown". Page 1
+        // of a paged grid is indistinguishable from an unpaged one here, so it reports the page.
+        aria-rowcount={rowNumberStart === 1 ? data.length + 1 : -1}
+        aria-colcount={orderedColumns.length + gutterOffset}
+        // One handler for every cell rather than one per cell: the keydown bubbles up here, and
+        // `onCellKeyDown` bails unless the focused element is a cell — so a header button, an open
+        // editor and the gutter checkbox all keep their own keys.
+        onKeyDown={onCellKeyDown}
+        // -1, not 0: the roving tabindex lives on the cells, so the grid itself must not become a
+        // second tab stop. This only makes the container scriptable (and satisfies the a11y rule
+        // that an element with a key handler be focusable).
+        tabIndex={-1}
+        className={cn(
+          // A `flex` column that is `overflow-hidden` so the grid clips (not grows past its box). The
+          // toolbar / status bar are fixed `shrink-0` bands; the middle scroll container is `flex-1
+          // min-h-0` so it absorbs the grid's height and scrolls both axes inside its own box.
+          // `max-h-full` matches `Table`: fill a height-bounded parent so rows scroll and the footer
+          // stays put. A `max-h-*` on `className` still wins when the parent has no height.
+          'relative flex max-h-full flex-col overflow-hidden rounded-xl border border-depth-black-4',
+          // Width: a grid with a flexible (`1fr`) column fills its container (`w-full`, like `Table`).
+          // A grid of only fixed-width columns instead shrinks to exactly those columns (`w-fit`) so the
+          // border hugs the data — no dead space to the right — and `max-w-full` caps it at the container
+          // so it scrolls (rather than overflowing the page) when the columns are wider than the space.
+          hasFlexColumn ? 'w-full' : 'w-fit max-w-full',
+          variant === 'weak' ? 'bg-base-weak' : 'bg-base-inverse',
+          className,
+        )}
+        qa-test-id={qaTestId}
+        aria-busy={isLoading || undefined}
+        {...props}
+      >
+        {chrome.header}
+
+        <div
+          ref={scrollRef}
+          // The single scroll box (matches `Table`'s `flex-1 min-h-0 min-w-0 overflow-auto` container):
+          // `flex-1 min-h-0` makes it absorb the grid's bounded height so rows scroll *vertically* under
+          // the sticky header when a consumer caps the height (`max-h-*` on the root); `min-w-0
+          // overflow-auto` scrolls the columns *horizontally* when they're wider than the viewport —
+          // common on mobile, or with fixed / pinned / resizable tracks. Both `min-*-0` let the box
+          // shrink below its content so the scroll actually engages instead of the grid overflowing.
+          className='min-h-0 min-w-0 flex-1 overflow-auto'
+          onScroll={hasPinned ? onScroll : undefined}
+        >
+          {/* Row-selection FILL + RING layer: `sticky left-0` pins it horizontally to the scroll
+            viewport so its rounded rectangle keeps hugging the frozen left/right edges — the pinned
+            columns — while the middle scrolls under. It is NOT sticky vertically (no `top-0`): the
+            layer flows from the content top so its runs scroll up/down *with* their rows, and pass
+            under the sticky header (which sits above at a higher z). Keeping the fill and ring in ONE
+            rounded rect here means the fill can't poke out past the ring's rounded corners. `w-full`
+            is the viewport width (this is a scroll-container child), `h-0` keeps it out of layout,
+            and each run is offset past the header row. The fill sits over the cells (a light 10%
+            wash), the ring on top. */}
+          {!isLoading && selectionRuns.length > 0 && (
+            <div className='pointer-events-none sticky left-0 z-30 h-0 w-full'>
+              {selectionRuns.map((run) => {
+                const runStyle = {
+                  top: HEADER_ROW_HEIGHT + rowTop(run.start),
+                  height: rowBottom(run.start + run.length - 1) - rowTop(run.start),
+                }
+                return (
+                  <React.Fragment key={run.start}>
+                    <div
+                      aria-hidden
+                      className={cn('absolute inset-x-0', SELECTION_FILL)}
+                      style={runStyle}
+                    />
+                    <div
+                      aria-hidden
+                      data-slot='data-grid-selection-ring'
+                      className={cn('absolute inset-x-0', SELECTION_RING)}
+                      style={runStyle}
+                    />
+                  </React.Fragment>
+                )
+              })}
+            </div>
+          )}
+          <div
+            role='row'
+            // The header row is row 1 of the grid; data rows count on from there.
+            aria-rowindex={1}
+            // Sticky header (matches `Table`'s `sticky top-0` header cells): when the scroll box is
+            // height-bounded, the header freezes at the top while rows scroll under it. It needs its
+            // own opaque backing because the `inverse` column-header cells are transparent by default
+            // (they only tint on hover) — without it the rows would show through the header band.
+            // `z-40` sits above the selection fill/ring layer (`z-30`) so a selected row's ring slides
+            // *under* the header instead of painting over it; pinned header cells re-assert their own
+            // sticky-left `z-20` within this row's stacking context.
+            className={cn(
+              'sticky top-0 z-40 grid',
+              variant === 'weak' ? 'bg-base-weak' : 'bg-base-inverse',
+              rowWidthClass,
+            )}
+            style={{ gridTemplateColumns: template }}
+          >
+            {selectable && (
+              <div
+                role='columnheader'
+                aria-colindex={1}
+                className={cn(
+                  'flex h-10 items-center justify-center border-r border-b border-depth-black-4',
+                  'hover:[@media(hover:hover)]:bg-depth-black-4',
+                  stickyGutter && cn('sticky left-0 z-20', surfaceBacking),
+                )}
+              >
+                <Checkbox
+                  checked={allPageSelected}
+                  partialChecked={somePageSelected}
+                  aria-label={t`Select all rows`}
+                  disabled={isLoading || selectablePageIds.length === 0}
+                  onChange={toggleAllOnPage}
+                />
+              </div>
+            )}
+            {orderedColumns.map((col, index) => {
+              const sorted = sortedColumn === col.key ? sortDirection : undefined
+              const state =
+                sorted === 'asc'
+                  ? 'sorted-ascending'
+                  : sorted === 'desc'
+                    ? 'sorted-descending'
+                    : 'default'
+              const pin = getPinProps(col)
+              // Checkbox columns render an EMPTY header (req 4: no label + no type icon) — the
+              // checkboxes below speak for themselves. It stays pin-aware and keeps an accessible name.
+              if (col.type === 'checkbox') {
+                return (
+                  <div
+                    key={col.key}
+                    role='columnheader'
+                    aria-colindex={index + 1 + gutterOffset}
+                    // Empty header still needs an accessible name; fall back to the column key when the
+                    // header isn't a plain string.
+                    aria-label={typeof col.header === 'string' ? col.header : col.key}
+                    style={pin?.style}
+                    className={cn(
+                      'flex h-10 items-center border-r border-b border-depth-black-4',
+                      variant === 'weak' && 'bg-base-weak',
+                      isColumnReported(index) && 'bg-base-weak',
+                      pin?.className,
+                    )}
+                  />
+                )
+              }
+              return (
+                <DataGridColumnHeader
+                  key={col.key}
+                  role='columnheader'
+                  aria-colindex={index + 1 + gutterOffset}
+                  label={col.header}
+                  variant={variant}
+                  typeIcon={resolveTypeIcon(col)}
+                  align={resolveAlign(col)}
+                  state={state}
+                  // Sortable columns show the sort glyph (neutral double-chevron until sorted, then the
+                  // active direction) so sortability stays discoverable even with the kebab removed.
+                  showSort={col.sortable ?? false}
+                  // No kebab icon — the whole header is the click target that opens the menu.
+                  showMenu={false}
+                  // Show the pin glyph once the column is pinned (state indicator).
+                  showPin={col.pinned != null}
+                  menuContent={renderHeaderMenu(col)}
+                  resizable={col.resizable ?? false}
+                  isResizing={isResizing(col.key)}
+                  onResizeStart={col.resizable ? startResize(col.key, widthFor(col)) : undefined}
+                  style={pin?.style}
+                  className={cn(isColumnReported(index) && 'bg-base-weak', pin?.className)}
+                />
+              )
+            })}
+          </div>
+
+          {/* Match the rows' content width so the absolute selection overlays span every column (not
+            just the viewport) — the ring then tracks the true grid edges instead of stopping mid-grid
+            when scrolled. */}
+          <div
+            ref={rowgroupRef}
+            role='rowgroup'
+            // With no rows there is no data content to size to, so the body drops to the scroll
+            // VIEWPORT width and pins there (`sticky left-0 w-full`, the same trick the selection
+            // layer uses). The header row still spans the full column width, so wide columns keep
+            // scrolling horizontally while the empty message stays centred in view.
+            className={cn(
+              'relative',
+              isEmpty ? 'sticky left-0 w-full' : rowWidthClass,
+              // Outline/Secondary spreads 3px outside the cell. `overflow-auto` on the scroll box
+              // clips that ring on the last row (the footer sits just below, so there is no paint
+              // room). While the last row is being edited, make 3px of space for it.
+              editingCell != null &&
+                data.length > 0 &&
+                editingCell.rowId === String(data.at(-1)?.id) &&
+                'pb-[3px]',
+            )}
+          >
+            {isLoading ? (
+              <>
+                <div className='sr-only' role='status'>
+                  {t`Loading table data`}
+                </div>
+                {Array.from({ length: SKELETON_ROW_COUNT }, (_, index) => (
+                  <DataGridRow
+                    key={`skeleton-${index}`}
+                    state='loading'
+                    aria-hidden
+                    data-slot='data-grid-skeleton-row'
+                    className={cn('relative z-10', rowWidthClass)}
+                    style={{ gridTemplateColumns: template }}
+                    gutter={
+                      selectable ? (
+                        <DataGridRowHeader
+                          density={densityState}
+                          state='default'
+                          rowNumber={index + 1}
+                          className={
+                            stickyGutter ? cn('sticky left-0 z-20', surfaceBacking) : undefined
+                          }
+                        />
+                      ) : undefined
+                    }
+                  >
+                    {orderedColumns.map((col) => {
+                      const pin = getPinProps(col)
+                      return (
+                        <DataGridCell
+                          key={col.key}
+                          role='gridcell'
+                          density={densityState}
+                          align={resolveAlign(col)}
+                          style={pin?.style}
+                          className={pin?.className}
+                        >
+                          <DataGridCellValue type='skeleton' />
+                        </DataGridCell>
+                      )
+                    })}
+                  </DataGridRow>
+                ))}
+              </>
+            ) : isEmpty ? (
+              // Still a row holding one cell — a `role='rowgroup'` may only own rows, the same
+              // contract `renderBeforeRow` / `renderAfterRow` are held to. `role='status'` announces
+              // the change when a filter empties an already-rendered grid.
+              <DataGridRow>
+                <div
+                  role='gridcell'
+                  className='flex min-h-80 items-center justify-center px-6 py-8'
+                >
+                  <div role='status'>
+                    {emptyState ?? (
+                      <span className='pui-text-body-small text-text-soft'>
+                        {t`No records to display`}
+                      </span>
+                    )}
+                  </div>
+                </div>
+              </DataGridRow>
+            ) : (
+              data.map((row, index) => {
+                const rowProps = rowPropsList[index]
+                const rowCanToggle = canToggleRow(index)
+                const rowHasCheckbox = rowProps?.selectable !== false
+                // Selection fill / `aria-selected` follow the controlled id list even when the gutter
+                // checkbox is hidden (`selectable: false`) — e.g. a parent-selection cascade. Only the
+                // checkbox itself is gated by `rowHasCheckbox`.
+                const isSelected = isRowSelected(row.id)
+                const pinRowSurface = rowPinBackingClass(rowProps?.className)
+                const before = renderBeforeRow?.(row, index)
+                const after = renderAfterRow?.(row, index)
+                const rowElement = (
+                  <DataGridRow
+                    key={row.id}
+                    // The selection overlays measure `[data-row-index]` to place their rings, so
+                    // this marks which children of the rowgroup are real data rows.
+                    data-row-index={index}
+                    // Position in the whole dataset, not in this page: `rowNumberStart` carries
+                    // the paging offset, and the +1 is the header row above.
+                    aria-rowindex={rowNumberStart + index + 1}
+                    state='default'
+                    // No row-level hover tint by design (req: the grid is cell-based — feedback comes from
+                    // cell / drag selection, not a whole-row wash). A row-wide hover fill sat under the
+                    // translucent gridlines and darkened the borders, which read like a rendering mistake,
+                    // so it's dropped entirely. `DataGridRow` defaults to `hoverable={false}`; the sticky
+                    // gutter still reveals its selection checkbox on hover via the row's `group`.
+                    aria-selected={isSelected || undefined}
+                    className={cn(
+                      // `z-10` keeps rows under the sticky header (`z-40`) while they scroll.
+                      // An editing row has to win: the 3px Outline/Secondary ring sits outside
+                      // the cell, and Figma's editor "floats above its neighbours" — including
+                      // the header. Without this the top of the first-row ring is painted under
+                      // the opaque header band.
+                      'relative z-10',
+                      editingCell?.rowId === String(row.id) && 'z-50',
+                      rowWidthClass,
+                      rowProps?.className,
+                    )}
+                    style={{ gridTemplateColumns: template, ...rowProps?.style }}
+                    gutter={
+                      selectable ? (
+                        <DataGridRowHeader
+                          role='gridcell'
+                          aria-colindex={1}
+                          density={densityState}
+                          state='default'
+                          rowNumber={rowNumberStart + index}
+                          hoverReveal={rowHasCheckbox && !rowProps?.checkboxDisabled}
+                          checked={isSelected}
+                          disabled={rowProps?.checkboxDisabled}
+                          onCheckedChange={
+                            rowCanToggle ? (checked) => toggleRow(row.id, checked) : undefined
+                          }
+                          className={cn(
+                            isRowReported(index) && !isSelected && 'bg-base-weak',
+                            // Row selection is painted by the sticky viewport fill layer (over the
+                            // gutter), so no selection fill is needed here — and there's no row hover.
+                            stickyGutter && cn('sticky left-0 z-20', surfaceBacking, pinRowSurface),
+                          )}
+                        />
+                      ) : undefined
+                    }
+                  >
+                    {orderedColumns.map((col, colIndex) => {
+                      const type = col.type ?? 'text'
+                      const rawValue = row[col.key]
+                      const hasCustomRender = col.render != null
+                      const isEditing =
+                        !hasCustomRender &&
+                        editingCell?.rowId === String(row.id) &&
+                        editingCell.columnKey === col.key
+                      const canTextEdit =
+                        !hasCustomRender && (col.editable ?? false) && TEXT_EDITOR_TYPES.has(type)
+                      const canToggle =
+                        !hasCustomRender && (col.editable ?? false) && type === 'checkbox'
+                      // `select` / `tags` open the picker editor — but only with options to pick from.
+                      const canPickEdit =
+                        !hasCustomRender &&
+                        (col.editable ?? false) &&
+                        (type === 'select' || type === 'tags') &&
+                        (col.options?.length ?? 0) > 0
+                      // `date` is a trigger cell: it keeps its date face and opens the calendar in a
+                      // popover on click (like select/tags), rather than swapping a field into the cell.
+                      const canDateEdit =
+                        !hasCustomRender && (col.editable ?? false) && type === 'date'
+                      // Trigger cells keep their value face and open a picker on click (the cell is the
+                      // trigger); they own their padding so the whole cell is clickable.
+                      const isTriggerCell = canPickEdit || canDateEdit
+                      // The only editor that still swaps an inline field into the cell on click / Enter is
+                      // free text (text / long-text / number / currency / url) — there's no foreign
+                      // control to hide, so editing in place is the value's own representation.
+                      const canSwapEdit = canTextEdit
+                      // Any cell whose click is owned by an editor/menu or custom render — excluded
+                      // from cell-range drag-select (custom cells may contain links/buttons).
+                      const canOpenEditor = canSwapEdit || isTriggerCell || hasCustomRender
+                      const inRange = isRowReported(index) && isColumnReported(colIndex)
+                      // Skip the pin sticky/fill while editing so the floating editor frame keeps its own
+                      // positioning + white surface (editing a pinned cell mid-scroll is a rare edge).
+                      const pin = isEditing ? undefined : getPinProps(col)
+                      const openEditor = () =>
+                        setEditingCell({ rowId: String(row.id), columnKey: col.key })
+                      const isActiveMatch = find.isActiveMatch(index, col.key)
+                      const isMatch = find.isMatch(index, col.key)
+                      const matchClass = isEditing
+                        ? undefined
+                        : isActiveMatch
+                          ? 'bg-notice-light'
+                          : isMatch
+                            ? 'bg-notice-lighter'
+                            : undefined
+                      return (
+                        <DataGridCell
+                          key={col.key}
+                          role='gridcell'
+                          aria-colindex={colIndex + 1 + gutterOffset}
+                          // `data-cell` + ids let the drag hit-test the cell under the pointer.
+                          data-cell
+                          data-row-id={row.id}
+                          data-col-key={col.key}
+                          state={isEditing ? 'editing' : 'default'}
+                          aria-selected={isSelected || inRange || undefined}
+                          data-active-match={isActiveMatch || undefined}
+                          density={densityState}
+                          align={resolveAlign(col)}
+                          // Trigger cells hand their padding to the full-bleed trigger so the whole cell
+                          // opens the picker.
+                          padded={isTriggerCell ? false : undefined}
+                          // Roving tabindex: the body is a single tab stop and the arrows move
+                          // within it. Every cell takes part, not just the editable ones, so a
+                          // keyboard user can read across a row the way a mouse user scans it.
+                          tabIndex={isEditing ? undefined : isFocusedCell(index, colIndex) ? 0 : -1}
+                          // Clicking a cell (or tabbing back in) makes it the one that holds the
+                          // tab stop, so focus resumes where the user last was.
+                          onFocus={() => setFocusedCell({ row: index, col: colIndex })}
+                          onPointerDown={
+                            cellSelectable && !isEditing && !canOpenEditor
+                              ? startCellSelect(row.id, col.key)
+                              : undefined
+                          }
+                          onClick={canSwapEdit && !isEditing ? openEditor : undefined}
+                          style={pin?.style}
+                          className={cn(
+                            canTextEdit && !isEditing && 'cursor-text',
+                            isTriggerCell && 'cursor-pointer',
+                            // Drag-select shouldn't paint the native text selection over the cells.
+                            cellSelectable && !isEditing && 'select-none',
+                            matchClass,
+                            pin?.className,
+                            pin && pinRowSurface,
+                            // A pinned cell's opaque backing hides a tint set on the cell itself, so its
+                            // cell-range fill is layered onto that backing instead. (Row selection is
+                            // painted by the sticky viewport fill layer above, which sits over the pinned
+                            // cell, so it needs no backing fill here.) There is no row hover to re-apply.
+                            pin && inRange && PIN_SELECTED_BACKING,
+                          )}
+                        >
+                          {hasCustomRender && col.render ? (
+                            col.render(rawValue, row)
+                          ) : canPickEdit ? (
+                            // Cell stays its own Tags face; clicking opens the menu (no Select injected).
+                            <DataGridPickerCell
+                              multiple={type === 'tags'}
+                              options={col.options ?? []}
+                              align={resolveAlign(col)}
+                              density={densityState}
+                              value={
+                                Array.isArray(rawValue)
+                                  ? rawValue.map(String)
+                                  : rawValue == null
+                                    ? []
+                                    : // oxlint-disable-next-line typescript/no-base-to-string
+                                      [String(rawValue)]
+                              }
+                              onCommit={(value) =>
+                                onCellEdit?.({ rowId: row.id, columnKey: col.key, value })
+                              }
+                            />
+                          ) : canDateEdit ? (
+                            // Cell stays its own date face; clicking opens the calendar popover.
+                            <DataGridDatePickerCell
+                              align={resolveAlign(col)}
+                              density={densityState}
+                              // oxlint-disable-next-line typescript/no-base-to-string
+                              value={rawValue == null ? '' : String(rawValue)}
+                              onCommit={(value) =>
+                                onCellEdit?.({ rowId: row.id, columnKey: col.key, value })
+                              }
+                            />
+                          ) : isEditing ? (
+                            <DataGridCellEditor
+                              type={type}
+                              align={resolveAlign(col)}
+                              // oxlint-disable-next-line typescript/no-base-to-string
+                              initialValue={rawValue == null ? '' : String(rawValue)}
+                              onCommit={(value) => {
+                                onCellEdit?.({ rowId: row.id, columnKey: col.key, value })
+                                setEditingCell(null)
+                              }}
+                              onCancel={() => setEditingCell(null)}
+                            />
+                          ) : (
+                            <DataGridCellValue
+                              type={type}
+                              {...cellValueProps(type, rawValue, col.options)}
+                              onCheckedChange={
+                                canToggle
+                                  ? (checked) =>
+                                      onCellEdit?.({
+                                        rowId: row.id,
+                                        columnKey: col.key,
+                                        value: checked,
+                                      })
+                                  : undefined
+                              }
+                            />
+                          )}
+                        </DataGridCell>
+                      )
+                    })}
+                  </DataGridRow>
+                )
+                if (before == null && after == null) return rowElement
+                // Injected content goes into the rowgroup unwrapped: a `role='rowgroup'` may only
+                // own rows, so a layout div here would be an ARIA violation the consumer couldn't
+                // fix. It is handed straight through instead — which is also why the returned node
+                // has to be a row (`DataGridRow` / `DataGridGroupHeader`).
+                return (
+                  <React.Fragment key={row.id}>
+                    {before}
+                    {rowElement}
+                    {after}
+                  </React.Fragment>
+                )
+              })
+            )}
+
+            {rangeRect &&
+              !isLoading &&
+              (() => {
+                const gridColumn = `${rangeRect.colStart + 1 + gutterOffset} / ${rangeRect.colEnd + 2 + gutterOffset}`
+                const gridStyle = { gridTemplateColumns: template }
+                // Columns come from the shared grid template; the vertical band is measured (see
+                // `rowTop`). `self-start` + an explicit height keeps the block off the implicit
+                // row's stretch, and `marginTop` walks it down to the first row in the range.
+                const blockStyle = {
+                  gridColumn,
+                  marginTop: rowTop(rangeRect.rowStart),
+                  height: rowBottom(rangeRect.rowEnd) - rowTop(rangeRect.rowStart),
+                }
+                return (
+                  <>
+                    {/* Fill behind the rows (pinned cells fill via `PIN_SELECTED_BACKING`). */}
+                    <div
+                      aria-hidden
+                      className='pointer-events-none absolute inset-0 grid'
+                      style={gridStyle}
+                    >
+                      <div className={cn('self-start', SELECTION_FILL)} style={blockStyle} />
+                    </div>
+                    {/* Ring above the rows (z-30) so it also outlines the pinned columns. */}
+                    <div
+                      aria-hidden
+                      className='pointer-events-none absolute inset-0 z-30 grid'
+                      style={gridStyle}
+                    >
+                      <div className={cn('self-start', SELECTION_RING)} style={blockStyle} />
+                    </div>
+                  </>
+                )
+              })()}
+          </div>
+        </div>
+
+        {chrome.footer}
+      </div>
+    </DataGridContext.Provider>
+  )
+}