basalt-ui 1.26.0 → 1.28.0

package/src/data/data-table.tsx

@@ -32,7 +32,17 @@
  *   enablePagination
  * />
  */
-import { Box, Group, Pagination, Select, Skeleton, Table, Text, TextInput } from '@mantine/core'
+import {
+  Box,
+  Checkbox,
+  Group,
+  Pagination,
+  Select,
+  Skeleton,
+  Table,
+  Text,
+  TextInput,
+} from '@mantine/core'
 import type { MantineSpacing } from '@mantine/core'
 import type {
   Column,
@@ -42,6 +52,7 @@ import type {
   FilterFn,
   PaginationState,
   RowData,
+  RowSelectionState,
   SortingState,
   Table as TanstackTable,
   Updater,
@@ -54,9 +65,20 @@ import {
   getSortedRowModel,
   useReactTable,
 } from '@tanstack/react-table'
-import type { CSSProperties, ReactNode } from 'react'
-import { useCallback, useMemo, useState } from 'react'
+import type {
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+  RefObject,
+} from 'react'
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { BASALT_PREFIX } from '../common/errors'
+import { assertRequiredProps, useValidateProps } from '../common/validate'
 import { FilterSet } from '../controls'
+import { ActionGroup, BarActionSlot } from '../controls/actions'
+import type { BarAction, SlotActions } from '../controls/actions'
 // `EnumFilter` is deliberately NOT on the `./controls` barrel (`docs/CONTROLS-SPEC.md` §3 —
 // reaching for it directly is hand-rolling a filter, `basalt/hand-rolled-filter`); a facet column
 // is the one place inside the framework itself that legitimately builds a `FieldHandle` over
@@ -67,6 +89,11 @@ import { CtlSlot } from '../theme'
 import { alpha, VX } from '../tokens'
 import type { EnumField, FieldHandle, MultiField } from '../state'
 import { WidgetHeader } from '../widget-header'
+import { ErrorState } from '../dashboard/query-state'
+import type { QueryStateLike } from '../dashboard/query-state'
+import { dataQueryBranch } from './query-branch'
+import { isDev } from '../utils/is-dev'
+import classes from './data-table.module.css'
 
 // ── Column alignment ──────────────────────────────────────────────────────────
 
@@ -122,20 +149,30 @@ export type DataTableFacetOption = {
   label: string
 }
 
+/**
+ * A TanStack column id typed off the row shape `T` where `accessor`/manual `id` inference allows
+ * it — `Extract<keyof T, string>` for a real field name, widened by `(string & {})` so a
+ * synthetic/derived column id (no matching key on `T`) still type-checks. Defaults to `unknown` so
+ * a bare `DataTableFacet[]` / `DataTableColumnPinning` (no type argument) keeps working exactly as
+ * before. Shared by {@link DataTableFacet}'s `columnId` and {@link DataTableColumnPinning}'s
+ * `left`/`right`.
+ */
+export type DataTableColumnId<T = unknown> = Extract<keyof T, string> | (string & {})
+
 /**
  * Declares one faceted column filter, rendered as an `EnumFilter` pill (or `MultiSelectFilter`
  * when `multiple` is set) inside a `FilterSet` in the toolbar (`docs/CONTROLS-SPEC.md` §3).
  *
  * @example
- * const facets: DataTableFacet[] = [
+ * const facets: DataTableFacet<Employee>[] = [
  *   { columnId: 'department', label: 'Department', options: [{ value: 'Engineering', label: 'Engineering' }] },
  *   { columnId: 'role', label: 'Role', multiple: true, options: roleOptions },
  * ]
  * <BasaltDataTable data={rows} columns={columns} facets={facets} />
  */
-export type DataTableFacet = {
+export type DataTableFacet<T = unknown> = {
   /** The TanStack column id — the column's manual `id`, or its `accessorKey` string. */
-  columnId: string
+  columnId: DataTableColumnId<T>
   /** The pill's label — read at rest (single-select) and as the `Filters`/count fallback (multi). */
   label: string
   /** Selectable options for this facet. */
@@ -144,6 +181,17 @@ export type DataTableFacet = {
   multiple?: boolean
 }
 
+/**
+ * Column ids pinned to each edge — the same `T`-derived id union as {@link DataTableFacet}'s
+ * `columnId`, applied to TanStack's own `ColumnPinningState` shape (`{ left, right }`, each a bare
+ * `string[]` unrelated to any row type). Structurally assignable to `ColumnPinningState`, so no
+ * cast is needed where this flows into `useState<ColumnPinningState>`.
+ */
+export type DataTableColumnPinning<T = unknown> = {
+  left?: DataTableColumnId<T>[]
+  right?: DataTableColumnId<T>[]
+}
+
 /**
  * The "no filter" member of a single-select facet's `FieldHandle`. A closed enum field always has
  * a real member as its fallback (C4) — there is no "unset" — so a facet, whose underlying
@@ -161,7 +209,7 @@ export type DataTableFacet = {
 const FACET_ALL_VALUE = '__basalt_facet_all__'
 
 /** The synthetic row's label — see {@link FACET_ALL_VALUE}. */
-function facetAllLabel(facet: DataTableFacet): string {
+function facetAllLabel<T>(facet: DataTableFacet<T>): string {
   return `Any ${facet.label.toLowerCase()}`
 }
 
@@ -174,7 +222,7 @@ function facetAllLabel(facet: DataTableFacet): string {
  */
 function facetEnumHandle<T>(
   column: Column<T, unknown>,
-  facet: DataTableFacet,
+  facet: DataTableFacet<T>,
 ): FieldHandle<EnumField<string>> {
   return {
     kind: 'enum',
@@ -189,6 +237,10 @@ function facetEnumHandle<T>(
         },
       ] as const
     },
+    // A facet column has no lane to unset: clearing the column filter IS its fallback state.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
     isDefault: (value) => value === FACET_ALL_VALUE,
   }
 }
@@ -200,7 +252,7 @@ function facetEnumHandle<T>(
  */
 function facetMultiHandle<T>(
   column: Column<T, unknown>,
-  facet: DataTableFacet,
+  facet: DataTableFacet<T>,
 ): FieldHandle<MultiField<string>> {
   return {
     kind: 'multi',
@@ -215,12 +267,114 @@ function facetMultiHandle<T>(
         },
       ] as const
     },
+    // Same as the single-select facet: an empty column filter is this handle's fallback.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
     isDefault: (value) => value.length === 0,
   }
 }
 
+/**
+ * Resolves a facet's `columnId` against the table. A mistyped id used to fall through to
+ * `if (!column) return null` — the facet pill silently vanished from the toolbar, the same class
+ * of defect the sibling `meta.align` lane and `manualPagination` both treat as a dev-time throw.
+ * Mirrors `resolveAlign`'s dev-throw shape: throw naming the id in dev
+ * (`basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle constant-folds this
+ * away), degrade to "no pill for this facet" in production.
+ */
+function resolveFacetColumn<T>(
+  table: TanstackTable<T>,
+  facet: DataTableFacet<T>,
+): Column<T, unknown> | undefined {
+  const column = table.getColumn(facet.columnId)
+  if (column) return column
+  if (isDev()) {
+    const knownIds = table
+      .getAllColumns()
+      .map((known) => known.id)
+      .join(', ')
+    throw new Error(
+      `BasaltDataTable: facet columnId "${facet.columnId}" matches no column — known column ids: ` +
+        `${knownIds}.`,
+    )
+  }
+  return undefined
+}
+
+// ── Row selection ─────────────────────────────────────────────────────────────
+
+/**
+ * The synthetic checkbox column `enableRowSelection` prepends. Its id is namespaced so it can never
+ * collide with a real accessor key, and it is excluded from sorting — a checkbox column sorts by
+ * selection state, which is a reordering nobody asked for.
+ */
+const SELECT_COLUMN_ID = '__basalt_select__'
+
+/**
+ * Built per render inside a `useMemo`, not hoisted as a constant: `ColumnDef` is generic in `T`, and
+ * a single shared instance would have to be cast at every call site.
+ *
+ * `onClick`'s `stopPropagation` is the load-bearing line. The checkbox lives inside the row, and a
+ * row carrying `onRowActivate` opens a detail from a click — so without it, ticking the box also
+ * navigated away from the table the tick was meant to act on.
+ */
+function selectionColumn<T>(): ColumnDef<T, unknown> {
+  return {
+    id: SELECT_COLUMN_ID,
+    enableSorting: false,
+    header: ({ table }) => (
+      <Checkbox
+        size="xs"
+        aria-label="Select all rows"
+        checked={table.getIsAllPageRowsSelected()}
+        indeterminate={table.getIsSomePageRowsSelected() && !table.getIsAllPageRowsSelected()}
+        onChange={table.getToggleAllPageRowsSelectedHandler()}
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        size="xs"
+        aria-label={`Select row ${row.index + 1}`}
+        checked={row.getIsSelected()}
+        disabled={!row.getCanSelect()}
+        onChange={row.getToggleSelectedHandler()}
+        onClick={(event) => event.stopPropagation()}
+      />
+    ),
+  }
+}
+
+/**
+ * The bar a selection raises, above the table and below its header — the count, then the actions,
+ * through the SAME `BarAction[]` vocabulary `PageBar` uses, so the ≤3-inline fold and the mobile
+ * kebab are basalt's here too (law C7/C15) instead of a hand-rolled `Group` of buttons.
+ *
+ * It renders only while at least one row is selected. A bar reserved at zero is a row of page
+ * furniture that says nothing, and a table that changes height when the first box is ticked is the
+ * price of not reserving it — the cheaper of the two, because the selection is what the reader just
+ * caused.
+ */
+function BulkActionBar({ count, actions }: { count: number; actions: BarAction[] }) {
+  return (
+    <Group className={classes.bulkBar} gap="xs" align="center" wrap="wrap" mb="xs">
+      <Text className={classes.bulkCount}>{count} selected</Text>
+      <CtlSlot>
+        <ActionGroup secondary={actions} />
+      </CtlSlot>
+    </Group>
+  )
+}
+
 // ── Props ─────────────────────────────────────────────────────────────────────
 
+/**
+ * The four boxes `BasaltDataTable` paints: `root` is the outer fragment's replacement wrapper,
+ * `toolbar` is the search/facets/actions row, `table` is the Mantine `Table` itself, `footer` is
+ * the pagination bar.
+ */
+export type BasaltDataTableSlot = 'root' | 'toolbar' | 'table' | 'footer'
+
 /**
  * Props for {@link BasaltDataTable}.
  *
@@ -234,268 +388,383 @@ function facetMultiHandle<T>(
  *   emptyState: <Text c="dimmed">No results found.</Text>,
  * }
  */
-export type BasaltDataTableProps<T> = {
-  // ── Header (WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────
-
-  /**
-   * Optional heading rendered above the toolbar via `WidgetHeader tier="widget"`. `count` always
-   * reads `table.getRowCount()` (C11) — never a raw `data.length` — so it tracks the row model
-   * (post-filter/-pagination) rather than the unfiltered input.
-   */
-  title?: string
-  /** Optional leading icon, forwarded to `WidgetHeader`. */
-  icon?: ReactNode
-  /** Optional muted line rendered below the title row. */
-  subtitle?: string
-
-  /** Row data array. */
-  data: T[]
-  /**
-   * Column definitions. Use `createColumnHelper<T>()` from `@tanstack/react-table`
-   * for a typed accessor builder — `col.accessor('field', …)` columns sort by value.
-   */
-  // The cell-value type varies per column, so the array is heterogeneous in TValue. `any` here
-  // is the TanStack-idiomatic escape (accessor columns infer their own TValue); row typing stays
-  // exact via the `T` data generic.
-  // oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
-  columns: ColumnDef<T, any>[]
-  /**
-   * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
-   * reordered.
-   *
-   * Under `manualPagination` that is one page, so leaving this on without also passing
-   * `manualSorting` is a contract violation and throws in dev — see `manualPagination`.
-   * @default true
-   */
-  enableSorting?: boolean
-  /**
-   * Hand sorting to the server: the table stops reordering `data` locally and renders it in the
-   * order given, while the headers keep toggling `SortingState` and reporting it through
-   * `onSortingChange` — which is where you re-request the sorted page.
-   *
-   * This is the required companion to `manualPagination` whenever sort headers are live; without
-   * it a server-paginated table sorts one page and the "of N" bar presents that as a sort of all N.
-   * @default false
-   * @example
-   * <BasaltDataTable
-   *   data={page.rows}
-   *   columns={columns}
-   *   enablePagination
-   *   manualPagination
-   *   manualSorting
-   *   rowCount={page.total}
-   *   onSortingChange={(s) => refetch({ sort: s[0] })}
-   * />
-   */
-  manualSorting?: boolean
-  /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
-  striped?: boolean | 'odd' | 'even'
-  /** Highlight hovered rows. Forwarded to Mantine `Table`. */
-  highlightOnHover?: boolean
-  /**
-   * Rendered when no rows are VISIBLE — `data` is empty, or a filter/page matches none of it.
-   * Falls back to a simple message when omitted. (Before 1.25.0 this tracked `data.length` alone,
-   * so a search matching nothing rendered a blank `<tbody>` with no message at all.)
-   */
-  emptyState?: ReactNode
-  /**
-   * When true, renders skeleton placeholder rows instead of the empty-state branch.
-   * The header remains visible. Use while async data is loading.
-   */
-  isLoading?: boolean
-  /**
-   * Number of skeleton rows to render when `isLoading` is true.
-   * @default 5
-   */
-  skeletonRows?: number
-  /**
-   * Initial sorting state. Drives `useState` initial value — useful for restoring
-   * sort order from URL search params (e.g. `initialSorting={Route.useSearch().sorting}`).
-   * @example
-   * // URL-sync pattern with TanStack Router
-   * const { sorting } = Route.useSearch()
-   * <BasaltDataTable initialSorting={sorting} onSortingChange={(s) => navigate({ search: { sorting: s } })} … />
-   */
-  initialSorting?: SortingState
-  /**
-   * Called whenever the internal sorting state changes. Receives the new `SortingState`.
-   * The table continues to manage sorting internally (uncontrolled) when this is omitted.
-   */
-  onSortingChange?: (sorting: SortingState) => void
-
-  // ── Toolbar (search + facets + actions) ──────────────────────────────────────
-
-  /**
-   * Shows a global search `TextInput` above the table, wired to TanStack's `globalFilter` state
-   * (substring match against every column's stringified cell value).
-   * @default false
-   * @example
-   * <BasaltDataTable data={rows} columns={columns} enableGlobalFilter searchIcon={<IconSearch size={14} />} />
-   */
-  enableGlobalFilter?: boolean
-  /**
-   * Placeholder for the global search input.
-   * @default 'Search…'
-   */
-  globalFilterPlaceholder?: string
-  /**
-   * Leading icon rendered inside the global search input (Mantine `leftSection`). basalt-ui ships
-   * no icon set — pass any `ReactNode` (e.g. `<IconSearch size={14} />`).
-   */
-  searchIcon?: ReactNode
-  /**
-   * Initial global filter value. Drives `useState` initial value — mirrors `initialSorting` for
-   * restoring the search term from a URL search param.
-   */
-  initialGlobalFilter?: string
-  /** Called whenever the internal global filter value changes. */
-  onGlobalFilterChange?: (value: string) => void
-  /**
-   * Faceted column filters, rendered in the toolbar as `EnumFilter`/`MultiSelectFilter` pills
-   * inside a `FilterSet`, wired to TanStack's per-column `columnFilters` state. The toolbar
-   * renders whenever this array is non-empty, `enableGlobalFilter` is set, or `actions` is passed.
-   * @example
-   * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
-   */
-  facets?: DataTableFacet[]
-  /** Called whenever the faceted column filters change — the seam for server-side faceting. */
-  onColumnFiltersChange?: (filters: ColumnFiltersState) => void
-  /**
-   * Hand filtering to the server: the table stops narrowing `data` locally and renders every row
-   * given, while the search input and facets keep reporting through `onGlobalFilterChange` /
-   * `onColumnFiltersChange` — which is where you re-request the filtered page.
-   *
-   * Required alongside `manualPagination` whenever `enableGlobalFilter` or `facets` is set;
-   * without it the controls narrow one page while "of N" keeps counting the whole set.
-   * @default false
-   */
-  manualFiltering?: boolean
-  /**
-   * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
-   * search input or facets are configured. Renamed from `toolbarActions` — the toolbar (search +
-   * facets + this slot) is wrapped in `CtlSlot` (C1/C5), so its controls resolve to the `ctl` tier.
-   */
-  actions?: ReactNode
-
-  // ── Pagination ────────────────────────────────────────────────────────────────
-
-  /**
-   * Enables the bottom pagination bar ("Showing X–Y of N", rows-per-page `Select`, Mantine
-   * `Pagination`) wired to TanStack's `pagination` state. Client-side by default — see
-   * `manualPagination` for server-driven pagination.
-   * @default false
-   */
-  enablePagination?: boolean
-  /**
-   * Rows-per-page choices offered in the pagination bar's Select.
-   * @default [10, 25, 50, 100]
-   */
-  pageSizeOptions?: number[]
-  /**
-   * Initial pagination state. Drives `useState` initial value — mirrors `initialSorting` for
-   * restoring the page/size from a URL search param.
-   */
-  initialPagination?: PaginationState
-  /** Called whenever the internal pagination state changes. */
-  onPaginationChange?: (pagination: PaginationState) => void
-  /**
-   * Disables local pagination slicing — pass the already-paginated page of `data` plus `rowCount`
-   * (and optionally `pageCount`) for server-driven pagination. `onPaginationChange` is where you
-   * fetch the next page.
-   *
-   * **It imposes a contract, enforced at render.** `data` is now one page, but the pagination bar
-   * says "Showing 1–25 of 412" — so every OTHER client-side control becomes a claim about 412 rows
-   * that it can only make about 25. Each has to be resolved explicitly, because only the call site
-   * knows whether the server does the work:
-   *
-   * - `rowCount` (or `pageCount`) must be given, or "of N" counts the page and the pager collapses
-   *   to a single page nobody can leave;
-   * - sorting must be handed over with `manualSorting`, or switched off with `enableSorting={false}`;
-   * - `enableGlobalFilter` / `facets`, if used, must be handed over with `manualFiltering`;
-   * - `enablePagination` must be on, or `manualPagination` is inert and the page renders as if it
-   *   were the whole table.
-   *
-   * Unresolved, each throws in dev and degrades to the honest render in production (no sort
-   * headers, no filter controls, no "of N") — never to the plausible wrong answer.
-   * @default false
-   * @example
-   * <BasaltDataTable
-   *   data={page.rows}
-   *   columns={columns}
-   *   enablePagination
-   *   manualPagination
-   *   rowCount={page.total}
-   *   initialPagination={{ pageIndex: page.index, pageSize: page.size }}
-   *   onPaginationChange={(p) => fetchPage(p)}
-   * />
-   */
-  manualPagination?: boolean
-  /** Total row count across all pages. Required for `manualPagination` to render "of N" and compute page count. */
-  rowCount?: number
-  /** Total page count, when known. Only consulted under `manualPagination`; omit to derive it from `rowCount`/`pageSize`. */
-  pageCount?: number
-
-  // ── Column pinning ────────────────────────────────────────────────────────────
-
-  /**
-   * Enables sticky left/right column pinning — pinned columns stick to the edge with a panel
-   * background and a hairline shadow separator while the table scrolls horizontally. Pin columns
-   * via `initialColumnPinning` (`{ left: string[], right: string[] }`).
-   * @default false
-   * @example
-   * <BasaltDataTable data={rows} columns={columns} enablePinning initialColumnPinning={{ left: ['name'] }} />
-   */
-  enablePinning?: boolean
-  /** Initial column-pinning state — which column ids stick to the left/right edge. */
-  initialColumnPinning?: ColumnPinningState
-
-  // ── Body chrome ─────────────────────────────────────────────────────────────
-
-  /**
-   * Caps the scrolling body (px number or CSS length) so a long table cannot blow a card out
-   * vertically — the header stays put and the rows scroll under it. Renders Mantine's
-   * `Table.ScrollContainer type="native"`, which is the same node the docs sanction as the raw
-   * escape for a bespoke table: the blessed lane and the escape hatch produce identical DOM, so
-   * adopting one does not contradict the other.
-   *
-   * `type="native"` is required rather than preferred: `ScrollArea`'s custom viewport is the
-   * positioning context a sticky `<thead>` resolves against, so the default `'scrollarea'` type
-   * pins the header to the page viewport instead of the table's box.
-   */
-  maxHeight?: number | string
-  /**
-   * `min-width` below which the body scrolls horizontally. Setting either this or `maxHeight`
-   * turns on the scroll container; `maxHeight` alone implies `minWidth: 0`.
-   */
-  minWidth?: number | string
-  /** Sticky header row. Pair with `maxHeight` to stick within the table rather than the page. */
-  stickyHeader?: boolean
-  /** Offset for a sticky header sitting under a fixed app header (px number or CSS length). */
-  stickyHeaderOffset?: number | string
-  /** Vertical cell padding. Forwarded to Mantine `Table`. */
-  verticalSpacing?: MantineSpacing
-  /** Horizontal cell padding. Forwarded to Mantine `Table`. */
-  horizontalSpacing?: MantineSpacing
-  /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
-  withRowBorders?: boolean
-  /**
-   * Outer table border — a full box around the table.
-   *
-   * **`false` by default since this minor** (it was `true`). Three separate faults, all visible on
-   * the playground's `Controls (mobile)` page at 390px: its TOP edge sat directly under the table's
-   * own `WidgetHeader`, separating a header from its own content; its BOTTOM edge landed on the last
-   * row's own hairline, two rules at zero distance; and its left/right edges carried no information
-   * at all on a table that fills the page (`docs/DESIGN-SPEC.md` §8 — a border is a layout divider,
-   * and there is nothing here to divide). The head-row rule and the between-row rules stay, so the
-   * table still reads as a table.
-   *
-   * Pass `true` for a table that genuinely needs a frame — a small table floating in whitespace
-   * beside other content, where the box IS the grouping.
-   *
-   * @default false
-   */
-  withTableBorder?: boolean
-}
+export type BasaltDataTableProps<T> = BasaltProps &
+  SlotStylesProps<BasaltDataTableSlot> & {
+    // ── Header (WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────
+
+    /**
+     * Optional heading rendered above the toolbar via `WidgetHeader tier="widget"`. `count` always
+     * reads `table.getRowCount()` (C11) — never a raw `data.length` — so it tracks the row model
+     * (post-filter/-pagination) rather than the unfiltered input.
+     */
+    title?: string
+    /** Optional leading icon, forwarded to `WidgetHeader`. */
+    icon?: ReactNode
+    /** Optional muted line rendered below the title row. */
+    subtitle?: string
+
+    /** Row data array. */
+    data: T[]
+    /**
+     * Column definitions. Use `createColumnHelper<T>()` from `@tanstack/react-table`
+     * for a typed accessor builder — `col.accessor('field', …)` columns sort by value.
+     */
+    // The cell-value type varies per column, so the array is heterogeneous in TValue. `any` here
+    // is the TanStack-idiomatic escape (accessor columns infer their own TValue); row typing stays
+    // exact via the `T` data generic.
+    // oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
+    columns: ColumnDef<T, any>[]
+    /**
+     * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
+     * reordered.
+     *
+     * Under `manualPagination` that is one page, so leaving this on without also passing
+     * `manualSorting` is a contract violation and throws in dev — see `manualPagination`.
+     * @default true
+     */
+    enableSorting?: boolean
+    /**
+     * Hand sorting to the server: the table stops reordering `data` locally and renders it in the
+     * order given, while the headers keep toggling `SortingState` and reporting it through
+     * `onSortingChange` — which is where you re-request the sorted page.
+     *
+     * This is the required companion to `manualPagination` whenever sort headers are live; without
+     * it a server-paginated table sorts one page and the "of N" bar presents that as a sort of all N.
+     * @default false
+     * @example
+     * <BasaltDataTable
+     *   data={page.rows}
+     *   columns={columns}
+     *   enablePagination
+     *   manualPagination
+     *   manualSorting
+     *   rowCount={page.total}
+     *   onSortingChange={(s) => refetch({ sort: s[0] })}
+     * />
+     */
+    manualSorting?: boolean
+    /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
+    striped?: boolean | 'odd' | 'even'
+    /** Highlight hovered rows. Forwarded to Mantine `Table`. */
+    highlightOnHover?: boolean
+    /**
+     * Rendered when no rows are VISIBLE — `data` is empty, or a filter/page matches none of it.
+     * Falls back to a simple message when omitted. (Before 1.25.0 this tracked `data.length` alone,
+     * so a search matching nothing rendered a blank `<tbody>` with no message at all.)
+     */
+    emptyState?: ReactNode
+    /**
+     * When true, renders skeleton placeholder rows instead of the empty-state branch.
+     * The header remains visible. Use while async data is loading.
+     *
+     * Superseded by `query`, which resolves this branch AND the two this prop cannot express — pass
+     * both and `query` wins, with a dev warning.
+     */
+    isLoading?: boolean
+    /**
+     * The result behind `data`, resolved into a body: pending → the skeleton rows below, error with
+     * no data → an `ErrorState` row spanning the table (with the query's own `refetch` behind
+     * Retry), anything else → the rows, or `emptyState` when none are visible.
+     *
+     * This is law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1). The table had NO
+     * error branch at all (components audit #3), so a 500 rendered *No data to display.* — the
+     * exact false claim `QueryState` was built to delete, one container over.
+     *
+     * The header, toolbar, `<thead>` and pagination bar stay drawn through every branch: only the
+     * `<tbody>` swaps, which is why this is not `QueryState` wrapped around the table. A refetch
+     * that fails while rows are already on screen keeps the rows — compose `QueryState` AROUND the
+     * table when you want its cached-data banner too.
+     *
+     * @example
+     * const q = useQuery({ queryKey: ['rows'], queryFn: () => api.rows() })
+     * <BasaltDataTable data={q.data ?? []} columns={columns} query={q} />
+     */
+    query?: QueryStateLike<unknown>
+    /**
+     * Number of skeleton rows to render when `isLoading` is true.
+     * @default 5
+     */
+    skeletonRows?: number
+    /**
+     * Initial sorting state. Drives `useState` initial value — useful for restoring
+     * sort order from URL search params (e.g. `initialSorting={Route.useSearch().sorting}`).
+     * @example
+     * // URL-sync pattern with TanStack Router
+     * const { sorting } = Route.useSearch()
+     * <BasaltDataTable initialSorting={sorting} onSortingChange={(s) => navigate({ search: { sorting: s } })} … />
+     */
+    initialSorting?: SortingState
+    /**
+     * Called whenever the internal sorting state changes. Receives the new `SortingState`.
+     * The table continues to manage sorting internally (uncontrolled) when this is omitted.
+     */
+    onSortingChange?: (sorting: SortingState) => void
+
+    // ── Toolbar (search + facets + actions) ──────────────────────────────────────
+
+    /**
+     * Shows a global search `TextInput` above the table, wired to TanStack's `globalFilter` state
+     * (substring match against every column's stringified cell value).
+     * @default false
+     * @example
+     * <BasaltDataTable data={rows} columns={columns} enableGlobalFilter searchIcon={<IconSearch size={14} />} />
+     */
+    enableGlobalFilter?: boolean
+    /**
+     * Placeholder for the global search input.
+     * @default 'Search…'
+     */
+    globalFilterPlaceholder?: string
+    /**
+     * Leading icon rendered inside the global search input (Mantine `leftSection`). basalt-ui ships
+     * no icon set — pass any `ReactNode` (e.g. `<IconSearch size={14} />`).
+     */
+    searchIcon?: ReactNode
+    /**
+     * Initial global filter value. Drives `useState` initial value — mirrors `initialSorting` for
+     * restoring the search term from a URL search param.
+     */
+    initialGlobalFilter?: string
+    /** Called whenever the internal global filter value changes. */
+    onGlobalFilterChange?: (value: string) => void
+    /**
+     * Faceted column filters, rendered in the toolbar as `EnumFilter`/`MultiSelectFilter` pills
+     * inside a `FilterSet`, wired to TanStack's per-column `columnFilters` state. The toolbar
+     * renders whenever this array is non-empty, `enableGlobalFilter` is set, or `actions` is passed.
+     * @example
+     * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
+     */
+    facets?: DataTableFacet<T>[]
+    /** Called whenever the faceted column filters change — the seam for server-side faceting. */
+    onColumnFiltersChange?: (filters: ColumnFiltersState) => void
+    /**
+     * Hand filtering to the server: the table stops narrowing `data` locally and renders every row
+     * given, while the search input and facets keep reporting through `onGlobalFilterChange` /
+     * `onColumnFiltersChange` — which is where you re-request the filtered page.
+     *
+     * Required alongside `manualPagination` whenever `enableGlobalFilter` or `facets` is set;
+     * without it the controls narrow one page while "of N" keeps counting the whole set.
+     * @default false
+     */
+    manualFiltering?: boolean
+    /**
+     * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
+     * search input or facets are configured. Renamed from `toolbarActions` — the toolbar (search +
+     * facets + this slot) is wrapped in `CtlSlot` (C1/C5), so its controls resolve to the `ctl` tier.
+     *
+     * Two accepted forms (law C15): a typed `BarAction[]`, projected through the same row `PageBar`
+     * and `ActionGroup` use — ≤3 inline, the rest folded into `More`, one kebab below `sm` — or an
+     * opaque `ReactNode`, rendered verbatim exactly as before.
+     */
+    actions?: SlotActions
+
+    // ── Row activation + selection ────────────────────────────────────────────────
+
+    /**
+     * Makes each row openable — click, or Enter on a focused row — with the ROW's original datum.
+     * The hook that pairs a table with `PageAside`: row → detail, without the caller adding an
+     * `onClick` to every cell renderer.
+     *
+     * The row keeps its native `<tr>` semantics and takes `tabIndex=0` plus `data-activatable`,
+     * never `role="button"`: a role swap takes the row out of the table's row/cell semantics, so a
+     * screen reader stops announcing each cell's column header — which is the reason the data is in
+     * a table. Cursor and focus ring come from the module class.
+     *
+     * A click that originates inside the selection checkbox does NOT activate (the checkbox stops
+     * the event); a click on a control your own `cell` renders should do the same.
+     *
+     * @example
+     * <BasaltDataTable data={rows} columns={columns} onRowActivate={(row) => setSelected(row)} />
+     */
+    onRowActivate?: (row: T) => void
+    /**
+     * Prepends a checkbox column (header = select-all on the page) and arms TanStack's row-selection
+     * feature. Selection is uncontrolled unless `rowSelection` is passed.
+     * @default false
+     */
+    enableRowSelection?: boolean
+    /**
+     * Controlled selection — TanStack's own `RowSelectionState` (`Record<rowId, boolean>`), keyed by
+     * `getRowId` (row index by default). Omit for uncontrolled selection held by the table.
+     */
+    rowSelection?: RowSelectionState
+    /** Called with the next `RowSelectionState` on every selection change, controlled or not. */
+    onRowSelectionChange?: (selection: RowSelectionState) => void
+    /**
+     * Stable row id, handed to TanStack. Pass one whenever the selection must survive a re-sort, a
+     * page change or a refetch — the default id is the row's INDEX, so row 3 stays "selected" when a
+     * different record moves into position 3.
+     */
+    getRowId?: (row: T, index: number) => string
+    /**
+     * The actions a selection offers, rendered in a bar above the table while at least one row is
+     * selected — and nothing at all while none is.
+     *
+     * A FUNCTION of the selected rows, not a bare array, and that is the whole signature decision:
+     * `BarActionItem.onClick` is `() => void` (the one vocabulary every home shares, unforked), so
+     * the rows have to reach the handler through the closure the caller writes here. It also means
+     * an UNCONTROLLED table can offer bulk actions at all — the selection lives inside the table,
+     * and this is how it gets out.
+     *
+     * @example
+     * bulkActions={(rows) => [
+     *   { key: 'export', label: `Export ${rows.length}`, onClick: () => exportCsv(rows) },
+     *   { key: 'delete', label: 'Delete', danger: true, onClick: () => remove(rows) },
+     * ]}
+     */
+    bulkActions?: (rows: T[]) => BarAction[]
+
+    // ── Pagination ────────────────────────────────────────────────────────────────
+
+    /**
+     * Enables the bottom pagination bar ("Showing X–Y of N", rows-per-page `Select`, Mantine
+     * `Pagination`) wired to TanStack's `pagination` state. Client-side by default — see
+     * `manualPagination` for server-driven pagination.
+     * @default false
+     */
+    enablePagination?: boolean
+    /**
+     * Rows-per-page choices offered in the pagination bar's Select.
+     * @default [10, 25, 50, 100]
+     */
+    pageSizeOptions?: number[]
+    /**
+     * Initial pagination state. Drives `useState` initial value — mirrors `initialSorting` for
+     * restoring the page/size from a URL search param.
+     */
+    initialPagination?: PaginationState
+    /** Called whenever the internal pagination state changes. */
+    onPaginationChange?: (pagination: PaginationState) => void
+    /**
+     * Disables local pagination slicing — pass the already-paginated page of `data` plus `rowCount`
+     * (and optionally `pageCount`) for server-driven pagination. `onPaginationChange` is where you
+     * fetch the next page.
+     *
+     * **It imposes a contract, enforced at render.** `data` is now one page, but the pagination bar
+     * says "Showing 1–25 of 412" — so every OTHER client-side control becomes a claim about 412 rows
+     * that it can only make about 25. Each has to be resolved explicitly, because only the call site
+     * knows whether the server does the work:
+     *
+     * - `rowCount` (or `pageCount`) must be given, or "of N" counts the page and the pager collapses
+     *   to a single page nobody can leave;
+     * - sorting must be handed over with `manualSorting`, or switched off with `enableSorting={false}`;
+     * - `enableGlobalFilter` / `facets`, if used, must be handed over with `manualFiltering`;
+     * - `enablePagination` must be on, or `manualPagination` is inert and the page renders as if it
+     *   were the whole table.
+     *
+     * Unresolved, each throws in dev and degrades to the honest render in production (no sort
+     * headers, no filter controls, no "of N") — never to the plausible wrong answer.
+     * @default false
+     * @example
+     * <BasaltDataTable
+     *   data={page.rows}
+     *   columns={columns}
+     *   enablePagination
+     *   manualPagination
+     *   rowCount={page.total}
+     *   initialPagination={{ pageIndex: page.index, pageSize: page.size }}
+     *   onPaginationChange={(p) => fetchPage(p)}
+     * />
+     */
+    manualPagination?: boolean
+    /** Total row count across all pages. Required for `manualPagination` to render "of N" and compute page count. */
+    rowCount?: number
+    /** Total page count, when known. Only consulted under `manualPagination`; omit to derive it from `rowCount`/`pageSize`. */
+    pageCount?: number
+
+    // ── Column pinning ────────────────────────────────────────────────────────────
+
+    /**
+     * Enables sticky left/right column pinning — pinned columns stick to the edge with a panel
+     * background and a hairline shadow separator while the table scrolls horizontally. Pin columns
+     * via `initialColumnPinning` (`{ left: string[], right: string[] }`).
+     * @default false
+     * @example
+     * <BasaltDataTable data={rows} columns={columns} enablePinning initialColumnPinning={{ left: ['name'] }} />
+     */
+    enablePinning?: boolean
+    /** Initial column-pinning state — which column ids stick to the left/right edge. */
+    initialColumnPinning?: DataTableColumnPinning<T>
+
+    // ── Body chrome ─────────────────────────────────────────────────────────────
+
+    /**
+     * Caps the scrolling body (px number or CSS length) so a long table cannot blow a card out
+     * vertically — the header stays put and the rows scroll under it. Renders Mantine's
+     * `Table.ScrollContainer type="native"`, which is the same node the docs sanction as the raw
+     * escape for a bespoke table: the blessed lane and the escape hatch produce identical DOM, so
+     * adopting one does not contradict the other.
+     *
+     * `type="native"` is required rather than preferred: `ScrollArea`'s custom viewport is the
+     * positioning context a sticky `<thead>` resolves against, so the default `'scrollarea'` type
+     * pins the header to the page viewport instead of the table's box.
+     */
+    maxHeight?: number | string
+    /**
+     * `min-width` below which the body scrolls horizontally. Setting either this or `maxHeight`
+     * turns on the CAPPED scroll container; `maxHeight` alone implies `minWidth: 0`.
+     *
+     * It is a FLOOR, not the containment switch — since the shell made `AppShell.Main` the
+     * scrollport, every table renders inside a `Table.ScrollContainer type="native"` whether or not
+     * this is set (`minWidth: 0` when it is not), so a table wider than its column scrolls inside
+     * its own card instead of widening the page. Reach for this only to hold a MINIMUM table width
+     * — e.g. so eight columns keep their readable widths and scroll rather than compress.
+     *
+     * The one table whose wrapper is MEASURED rather than declared is `stickyHeader` with neither
+     * this nor `maxHeight`; see that prop and `useMeasuredContainment` in the implementation for
+     * why, and pair it with `maxHeight` if the table must both scroll and stick.
+     */
+    minWidth?: number | string
+    /**
+     * Sticky header row. Pair with `maxHeight` to stick within the table rather than the page.
+     *
+     * On its own — no `maxHeight`, no `minWidth` — the header sticks against the page's scrollport
+     * (`AppShell.Main`) only while the table FITS its container, and basalt measures that: the
+     * wrapper declares no overflow while it fits and flips to `overflow-x: auto` once the table is
+     * wider, publishing `data-contained`. The columns stay reachable either way and the page never
+     * scrolls sideways, but a sticky header cannot stick inside an uncapped overflow box — it has
+     * no scroll range — so it is inert at that width. A dev warning states the trade; pair this
+     * with `maxHeight` for a table that must both scroll and stick at every width.
+     */
+    stickyHeader?: boolean
+    /**
+     * Offset for a sticky header sitting under whatever chrome scrolls above it (px number or CSS
+     * length).
+     *
+     * PAGE-scroll only, and IGNORED whenever `maxHeight`/`minWidth` turn on the scroll container:
+     * that box is then the header's own scrollport, so an offset would park the `<thead>` that many
+     * pixels down inside the body — painting it over the rows instead of above them. Inside the
+     * container the header sticks to the scroller's own top edge.
+     *
+     * Inside `BasaltShell` the page's scrollport is `AppShell.Main`, and the app header sits
+     * OUTSIDE it — so the only chrome left to clear is `PageBar` row 2's band:
+     * `var(--basalt-page-bar-h, 0px)`, not the header height plus it.
+     */
+    stickyHeaderOffset?: number | string
+    /** Vertical cell padding. Forwarded to Mantine `Table`. */
+    verticalSpacing?: MantineSpacing
+    /** Horizontal cell padding. Forwarded to Mantine `Table`. */
+    horizontalSpacing?: MantineSpacing
+    /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
+    withRowBorders?: boolean
+    /**
+     * Outer table border — a full box around the table.
+     *
+     * **`false` by default since this minor** (it was `true`). Three separate faults, all visible on
+     * the playground's `Controls (mobile)` page at 390px: its TOP edge sat directly under the table's
+     * own `WidgetHeader`, separating a header from its own content; its BOTTOM edge landed on the last
+     * row's own hairline, two rules at zero distance; and its left/right edges carried no information
+     * at all on a table that fills the page (`docs/DESIGN-SPEC.md` §8 — a border is a layout divider,
+     * and there is nothing here to divide). The head-row rule and the between-row rules stay, so the
+     * table still reads as a table.
+     *
+     * Pass `true` for a table that genuinely needs a frame — a small table floating in whitespace
+     * beside other content, where the box IS the grouping.
+     *
+     * @default false
+     */
+    withTableBorder?: boolean
+  }
 
 // ── Sort indicator ────────────────────────────────────────────────────────────
 
@@ -530,19 +799,38 @@ const RANGE_LABEL_STYLE: CSSProperties = {
 const DEFAULT_PAGE_SIZE_OPTIONS = [10, 25, 50, 100]
 
 /**
- * The header row's two halves. The lead SHRINKS and the toolbar does not — a title can ellipsize, a
- * 220px search field with a facet pill beside it cannot, and when both were shrinkable flex split
- * the overflow between them and clipped the search's placeholder mid-word.
+ * The header row's two halves. The lead GROWS and the toolbar does not — a title can ellipsize into
+ * whatever is left, and a search field that grew with it was 600px on a wide table.
+ *
+ * Both SHRINK, and that half is not a preference. `CtlSlot` between the header row and the toolbar
+ * is `display: contents`, so the toolbar `Group` IS the row's flex item — and with the
+ * `flex: 0 0 auto` it used to carry (plus flex's default `min-width: auto`) it could not give up a
+ * pixel. MEASURED at 390x844 on `/data`: a 220px search beside a 230px facet pill row, gap 11, is a
+ * 461px item in a 302px column, and `AppShell.Main` read `scrollWidth` 505 against `clientWidth`
+ * 390 — the whole app draggable sideways over a table header. `0 1 auto` + `min-width: 0` lets the
+ * item shrink to the column, and `wrap="wrap"` then does the rest: the search takes one line and
+ * the pills the next. Nothing here is width-gated, so it holds in a narrow grid cell at any
+ * viewport, the same way the chart tier resolves.
  */
 const TABLE_HEADER_LEAD_STYLE: CSSProperties = { flex: '1 1 auto', minWidth: 0 }
-const TABLE_TOOLBAR_STYLE: CSSProperties = { flex: '0 0 auto' }
+const TABLE_TOOLBAR_STYLE: CSSProperties = { flex: '0 1 auto', minWidth: 0 }
 /**
  * The toolbar search's width. Mantine's Input grows to its container, which in a `justify:
  * space-between` row means "whatever is left" — so the field was 600px on a wide table and 180px on a
  * narrow one, for the same one-word query. A stated width also makes the toolbar's own minimum width
  * knowable, which is what lets it wrap under the title below `sm` with no media query.
+ *
+ * It is a BASIS, not a `width`: `flex: 0 1 <SEARCH_WIDTH>px` holds the field at 220px wherever 220
+ * is available and lets it shrink where it is not, floored at `12ch` (a legible query plus the
+ * search glyph) and capped at `100%` so it can never be the box that outgrows its column. A literal
+ * `w={220}` in a 302px column was half of the overflow above.
  */
 const SEARCH_WIDTH = 220
+const TABLE_SEARCH_STYLE: CSSProperties = {
+  flex: `0 1 ${SEARCH_WIDTH}px`,
+  minWidth: '12ch',
+  maxWidth: '100%',
+}
 /** The rows-per-page Select's width — see `SEARCH_WIDTH` for why a toolbar field states one. */
 const PAGE_SIZE_WIDTH = 116
 
@@ -598,13 +886,6 @@ function getPinnedCellStyle<T>(
 
 // ── The manual-pagination contract ────────────────────────────────────────────
 
-/** The house dev gate (`src/provider`, `src/charts/kinds/BandStrip` use the same expression):
- * `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle constant-folds this to
- * `false` and drops the throw. Read per call, never hoisted, so a test can flip it. */
-function isDev(): boolean {
-  return process.env['NODE_ENV'] !== 'production'
-}
-
 /** One client-side control that `manualPagination` turns into a claim the table cannot support. */
 type ManualPaginationBreach = 'inert' | 'total' | 'sorting' | 'filtering'
 
@@ -687,6 +968,99 @@ function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): vo
   console.error(message)
 }
 
+/**
+ * MEASURED CONTAINMENT — the wrapper for the ONE table shape whose overflow mode cannot be decided
+ * statically: `stickyHeader` with neither `maxHeight` nor `minWidth`.
+ *
+ * Every other table renders inside `Table.ScrollContainer type="native"`, because a bare `<table>`
+ * sizes to its own min-content and a five-column one measured 448px inside a 390px viewport,
+ * dragging the whole page sideways (`tests/layout/no-horizontal-overflow.layout.test.ts`). This
+ * shape cannot take that container unconditionally: an `overflow-x: auto` box computes `overflow-y`
+ * to `auto` as well, which makes it the sticky header's own scrollport — and with no height cap
+ * that box has no scroll range at all, so the `<thead>` scrolls clean away (MEASURED in Chrome:
+ * top 10.5 → −389.5 across a 400px scroll). Containing it unconditionally deletes the feature;
+ * leaving it bare unconditionally widens the page.
+ *
+ * So the wrapper's overflow is decided by MEASUREMENT, the same fit-check `useTrackFits`
+ * (`controls/panel-row.tsx`) runs for a segmented track. While the table FITS its wrapper the
+ * wrapper is `overflow: visible` — bare, and the page-sticky header sticks against `AppShell.Main`
+ * exactly as it did before. Once the table is WIDER the wrapper flips to `overflow-x: auto`, the
+ * columns stay reachable by horizontal scroll, and the header is necessarily inert at that width.
+ * That is the honest trade: a header that stops sticking is recoverable, a page that scrolls
+ * sideways takes every fixed and sticky element on it with it.
+ *
+ * Three properties that are easy to lose:
+ *
+ * - **The observer stays alive in BOTH states** — no one-way latch, unlike `useTrackFits`. The
+ *   wrapper must revert to bare when the space comes back (the window widened, the sidebar
+ *   collapsed, the aside closed), and a contained table's `offsetWidth` is still its min-content
+ *   width, so the same comparison keeps answering correctly from inside the contained state.
+ * - **Equality counts as FITS**, which is what stops the two states oscillating: a contained
+ *   wrapper that grows past the table reads `offsetWidth === clientWidth` (the `width: 100%` table
+ *   resolves against the container) and flips back exactly once.
+ * - **A zero `clientWidth` is `unknown`, not overflow** — the ancestor chain has not been laid out
+ *   yet (the aside animates its width in from 0, `docs/ASIDE-SPEC.md` §0). Committing to contained
+ *   on that reading would wrap a table that was never too wide.
+ *
+ * `useLayoutEffect` runs before paint, so a table that is already measurable resolves without a
+ * flash of the wrong mode. SSR reaches neither the effect nor a `window`, and the default state is
+ * bare — the same node the server and the first client paint both render.
+ */
+function useMeasuredContainment(active: boolean): {
+  wrapperRef: RefObject<HTMLDivElement | null>
+  contained: boolean
+} {
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const [contained, setContained] = useState(false)
+
+  useLayoutEffect(() => {
+    if (!active) return
+    const wrapper = wrapperRef.current
+    if (wrapper === null) return
+
+    // Three answers, not two — see the docblock. `unknown` moves neither the state nor the
+    // observer; it is simply not an answer yet.
+    const checkFit = (): 'fits' | 'contained' | 'unknown' => {
+      const table = wrapper.querySelector('table')
+      if (table === null) return 'unknown'
+      if (wrapper.clientWidth === 0 || table.offsetWidth === 0) return 'unknown'
+      return table.offsetWidth <= wrapper.clientWidth ? 'fits' : 'contained'
+    }
+
+    const apply = (): void => {
+      const result = checkFit()
+      if (result === 'unknown') return
+      const next = result === 'contained'
+      setContained((current) => (current === next ? current : next))
+    }
+
+    if (typeof ResizeObserver === 'undefined') {
+      // No recovery path without an observer, so the one same-tick read is this environment's
+      // only chance. `unknown` stays bare, which is the pre-measurement default anyway.
+      apply()
+      return
+    }
+
+    const observer = new ResizeObserver(apply)
+    observer.observe(wrapper)
+    const table = wrapper.querySelector('table')
+    // The TABLE too, not only the wrapper: a column set that re-measures (a facet filter changing
+    // the widest cell, a font settling) moves the table's min-content width while the wrapper's
+    // box never changes at all.
+    if (table !== null) observer.observe(table)
+
+    // Same check once, synchronously, so an already-settled table resolves before paint rather
+    // than waiting for the observer's first async tick.
+    apply()
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [active])
+
+  return { wrapperRef, contained: active && contained }
+}
+
 // ── Component ─────────────────────────────────────────────────────────────────
 
 /**
@@ -714,48 +1088,63 @@ function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): vo
  *   emptyState={<Text c="dimmed">No users found.</Text>}
  * />
  */
-export function BasaltDataTable<T>({
-  title,
-  icon,
-  subtitle,
-  data,
-  columns,
-  enableSorting = true,
-  manualSorting = false,
-  striped,
-  highlightOnHover,
-  emptyState,
-  isLoading = false,
-  skeletonRows = 5,
-  initialSorting,
-  onSortingChange,
-  enableGlobalFilter = false,
-  globalFilterPlaceholder = 'Search…',
-  searchIcon,
-  initialGlobalFilter,
-  onGlobalFilterChange,
-  facets,
-  onColumnFiltersChange,
-  manualFiltering = false,
-  actions,
-  enablePagination = false,
-  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
-  initialPagination,
-  onPaginationChange,
-  manualPagination = false,
-  rowCount,
-  pageCount,
-  enablePinning = false,
-  initialColumnPinning,
-  maxHeight,
-  minWidth,
-  stickyHeader,
-  stickyHeaderOffset,
-  verticalSpacing,
-  horizontalSpacing,
-  withRowBorders,
-  withTableBorder = false,
-}: BasaltDataTableProps<T>) {
+export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
+  // F-ERR-1: without this, a table missing `data`/`columns` fails deep inside `useReactTable` as a
+  // raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no message naming either
+  // prop.
+  assertRequiredProps('BasaltDataTable', props, ['data', 'columns'])
+  const {
+    title,
+    icon,
+    subtitle,
+    data,
+    columns,
+    enableSorting = true,
+    manualSorting = false,
+    striped,
+    highlightOnHover,
+    emptyState,
+    isLoading = false,
+    query,
+    skeletonRows = 5,
+    initialSorting,
+    onSortingChange,
+    enableGlobalFilter = false,
+    globalFilterPlaceholder = 'Search…',
+    searchIcon,
+    initialGlobalFilter,
+    onGlobalFilterChange,
+    facets,
+    onColumnFiltersChange,
+    manualFiltering = false,
+    actions,
+    onRowActivate,
+    enableRowSelection = false,
+    rowSelection,
+    onRowSelectionChange,
+    getRowId,
+    bulkActions,
+    enablePagination = false,
+    pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+    initialPagination,
+    onPaginationChange,
+    manualPagination = false,
+    rowCount,
+    pageCount,
+    enablePinning = false,
+    initialColumnPinning,
+    maxHeight,
+    minWidth,
+    stickyHeader,
+    stickyHeaderOffset,
+    verticalSpacing,
+    horizontalSpacing,
+    withRowBorders,
+    withTableBorder = false,
+    className,
+    style,
+    classNames,
+  } = props
   const [sorting, setSorting] = useState<SortingState>(initialSorting ?? [])
   const [globalFilter, setGlobalFilter] = useState(initialGlobalFilter ?? '')
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
@@ -763,6 +1152,51 @@ export function BasaltDataTable<T>({
     initialPagination ?? { pageIndex: 0, pageSize: pageSizeOptions[0] ?? 10 },
   )
   const [columnPinning, setColumnPinning] = useState<ColumnPinningState>(initialColumnPinning ?? {})
+  // Uncontrolled by default; `rowSelection`, when passed, is the truth and this only mirrors it so
+  // the updater below has a base to apply against.
+  const [internalRowSelection, setInternalRowSelection] = useState<RowSelectionState>({})
+  const rowSelectionState = rowSelection ?? internalRowSelection
+
+  // `stickyHeaderOffset` is DROPPED whenever the table owns a scroll container — see
+  // `resolvedStickyHeaderOffset` below for why it is always wrong there. Dropping it silently is
+  // the part worth a message: the header still sticks, so the table looks right until it overlaps
+  // the page chrome the offset was measured against, and nothing anywhere says the prop was ignored.
+  //
+  // The second check is `query` beside `isLoading`: `query` resolves the pending branch AND the two
+  // `isLoading` cannot express, so it wins outright. Silently, that reads as the boolean having no
+  // effect — which is indistinguishable from a bug in the caller's own loading flag.
+  useValidateProps(
+    'BasaltDataTable',
+    () => [
+      stickyHeaderOffset === undefined || (maxHeight === undefined && minWidth === undefined)
+        ? null
+        : `${BASALT_PREFIX} BasaltDataTable: prop "stickyHeaderOffset" is ignored beside ` +
+          '"maxHeight"/"minWidth" — those render a scroll container, and the sticky `<thead>` then ' +
+          "anchors to that box's own top edge rather than to the window. Drop the offset, or drop " +
+          'the cap and let the page scroll.',
+      query === undefined || props.isLoading === undefined
+        ? null
+        : `${BASALT_PREFIX} BasaltDataTable: props "query" and "isLoading" are both set — "query" ` +
+          'wins and "isLoading" is ignored. `query` already resolves the pending branch, plus the ' +
+          'error and empty ones the boolean cannot express. Drop "isLoading".',
+      stickyHeader !== true || maxHeight !== undefined || minWidth !== undefined
+        ? null
+        : `${BASALT_PREFIX} BasaltDataTable: prop "stickyHeader" with neither "maxHeight" nor ` +
+          '"minWidth" sticks only while the table FITS its container. basalt measures it: a table ' +
+          'wider than the space it has flips its wrapper to `overflow-x: auto` so the columns ' +
+          'stay reachable and the page never scrolls sideways, and a sticky header cannot stick ' +
+          'inside that box — it has no scroll range. Pair it with "maxHeight" for a table that ' +
+          'must both scroll and stick.',
+    ],
+    [
+      stickyHeaderOffset,
+      maxHeight,
+      minWidth,
+      stickyHeader,
+      query === undefined,
+      props.isLoading === undefined,
+    ],
+  )
 
   const handleSortingChange = useCallback(
     (updater: Updater<SortingState>) => {
@@ -808,10 +1242,29 @@ export function BasaltDataTable<T>({
     [onPaginationChange],
   )
 
+  const handleRowSelectionChange = useCallback(
+    (updater: Updater<RowSelectionState>) => {
+      // CONTROLLED: the caller's map is the base AND the only writer. Mirroring it into state too
+      // would leave a copy that the caller never moves, and that stale copy becomes the selection
+      // the moment `rowSelection` goes back to `undefined` — plus every tick would render twice for
+      // one change. Report the next map and let the caller own it.
+      if (rowSelection !== undefined) {
+        onRowSelectionChange?.(typeof updater === 'function' ? updater(rowSelection) : updater)
+        return
+      }
+      setInternalRowSelection((prev) => {
+        const next = typeof updater === 'function' ? updater(prev) : updater
+        onRowSelectionChange?.(next)
+        return next
+      })
+    },
+    [rowSelection, onRowSelectionChange],
+  )
+
   // Facets are TanStack `columnFilters` entries under the hood — inject an exact-match (or
   // any-of, for `multiple`) filterFn onto the matching column so the built-in `includesString`
   // auto-filter (substring match) never misfires against a Select's exact option value.
-  const tableColumns = useMemo(() => {
+  const facetColumns = useMemo(() => {
     if (!facets || facets.length === 0) return columns
     const facetById = new Map(facets.map((facet) => [facet.columnId, facet]))
     return columns.map((column) => {
@@ -836,6 +1289,14 @@ export function BasaltDataTable<T>({
     })
   }, [columns, facets])
 
+  // The checkbox column is PREPENDED here rather than asked of the caller, so `columns` stays the
+  // caller's own data columns and `meta.align` / `numeral` never have to reason about a synthetic
+  // one. Everything counting columns downstream reads `columnCount`, below.
+  const tableColumns = useMemo(
+    () => (enableRowSelection ? [selectionColumn<T>(), ...facetColumns] : facetColumns),
+    [facetColumns, enableRowSelection],
+  )
+
   // Enforced before the table is built, so the degraded options below are the ones TanStack gets —
   // a degraded table must not merely hide a control, it must not compute the answer either.
   const hasFacets = Boolean(facets && facets.length > 0)
@@ -866,12 +1327,18 @@ export function BasaltDataTable<T>({
       columnFilters,
       columnPinning,
       ...(enablePagination && { pagination }),
+      ...(enableRowSelection && { rowSelection: rowSelectionState }),
     },
     onSortingChange: handleSortingChange,
     onGlobalFilterChange: handleGlobalFilterChange,
     onColumnFiltersChange: handleColumnFiltersChange,
     onColumnPinningChange: setColumnPinning,
     ...(enablePagination && { onPaginationChange: handlePaginationChange }),
+    ...(enableRowSelection && {
+      enableRowSelection: true,
+      onRowSelectionChange: handleRowSelectionChange,
+    }),
+    ...(getRowId !== undefined && { getRowId }),
     getCoreRowModel: getCoreRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
@@ -895,17 +1362,76 @@ export function BasaltDataTable<T>({
   const showSearch = enableGlobalFilter && filteringEnabled
   const showFacets = hasFacets && filteringEnabled
   const showToolbar = showSearch || showFacets || Boolean(actions)
+
+  // ── The query branch (law C3) ───────────────────────────────────────────────
+  // `query`, when given, owns the body: it resolves the pending branch `isLoading` used to own,
+  // plus the error branch the table had none of. `isLoading` stays live for every caller who never
+  // had a query result to hand — the dev warning above covers the pair.
+  const branch = query === undefined ? undefined : dataQueryBranch('BasaltDataTable', query)
+  const showSkeleton = branch === undefined ? isLoading : branch === 'pending'
+  const queryError = branch === 'error' && query !== undefined ? query : undefined
+
+  // Every colSpan and every skeleton row counts the RENDERED columns, which is one more than
+  // `columns` once the checkbox column is prepended — a stale count left the empty state and the
+  // error row one cell short of the header.
+  const columnCount = columns.length + (enableRowSelection ? 1 : 0)
+
+  // `getSelectedRowModel()` is TanStack's own memo, so its `rows` array keeps its identity until
+  // the selection or the row model actually moves — which is what makes both memos below hold.
+  const selectedModelRows = enableRowSelection ? table.getSelectedRowModel().rows : undefined
+  const selectedRows = useMemo(
+    () => selectedModelRows?.map((row) => row.original) ?? [],
+    [selectedModelRows],
+  )
+  // `bulkActions` is the caller's function of the selection, and calling it inline rebuilt every
+  // action object on every render of the table — new `onClick` identities into the whole bar, for a
+  // selection that had not changed.
+  const bulkBarActions = useMemo(
+    () =>
+      bulkActions === undefined || selectedRows.length === 0
+        ? undefined
+        : bulkActions(selectedRows),
+    [bulkActions, selectedRows],
+  )
   const headerGroups = enablePinning ? getOrderedHeaderGroups(table) : table.getHeaderGroups()
   // The rows actually rendered, not `data` — a filter or a page index that matches nothing leaves
   // `data` non-empty while the body has nothing in it, and a blank body reads as a broken table.
   const rows = table.getRowModel().rows
 
+  // A capped body or a horizontal floor both need the same native scroll node. Everything else —
+  // pinning included — either takes that same container (the uncapped, non-sticky default) or the
+  // measured wrapper below; there is no third overflow box.
+  const scrolls = maxHeight !== undefined || minWidth !== undefined
+  // `stickyHeaderOffset` is a WINDOW-scroll concept — the height of whatever fixed chrome the page
+  // scrolls under (the AppShell header plus `PageBar` row 2). Inside the scroll container it is
+  // always wrong: that box is the sticky header's own scrollport, so the offset parks the `<thead>`
+  // that many pixels DOWN INSIDE the body rather than above it. MEASURED on `/data-stress`
+  // (`stickyHeader` + `minWidth`, no `maxHeight`): `calc(48px + 46px)` put the header at y=339 with
+  // row 1 at y=284 and row 2 at y=327 — the header painted over row 2 at initial scroll, at 1440x900
+  // and 390x844 alike. `overflow-x: auto` computes `overflow-y` to `auto` too, so the container is a
+  // scrollport even with no `maxHeight` and the header never scrolls back into place. The scroller's
+  // own top edge is the only correct anchor here, so the offset is dropped rather than honoured.
+  //
+  // THE ONE SHAPE WHOSE OVERFLOW IS MEASURED, NOT DECLARED. Every other table renders inside a
+  // `Table.ScrollContainer` (see the render branch below), because a bare `<table>` sizes to its
+  // own min-content and a 5-column table is ~450px wide — it widened the whole page at 390px, which
+  // is the defect `tests/layout/no-horizontal-overflow.layout.test.ts` guards. A page-scrolled
+  // sticky header cannot take that container unconditionally, so it takes the wrapper
+  // `useMeasuredContainment` drives instead: bare while the table fits, `overflow-x: auto` once it
+  // does not. Its docblock carries the full accounting.
+  const pageStickyHeader = !scrolls && stickyHeader === true
+  const containment = useMeasuredContainment(pageStickyHeader)
+  const resolvedStickyHeaderOffset = scrolls ? undefined : stickyHeaderOffset
+
   const tableNode = (
     <Table
+      className={cx(classNames?.table)}
       {...(striped !== undefined && { striped })}
       {...(highlightOnHover !== undefined && { highlightOnHover })}
       {...(stickyHeader !== undefined && { stickyHeader })}
-      {...(stickyHeaderOffset !== undefined && { stickyHeaderOffset })}
+      {...(resolvedStickyHeaderOffset !== undefined && {
+        stickyHeaderOffset: resolvedStickyHeaderOffset,
+      })}
       {...(verticalSpacing !== undefined && { verticalSpacing })}
       {...(horizontalSpacing !== undefined && { horizontalSpacing })}
       {...(withRowBorders !== undefined && { withRowBorders })}
@@ -962,10 +1488,25 @@ export function BasaltDataTable<T>({
         ))}
       </Table.Thead>
       <Table.Tbody>
-        {isLoading ? (
+        {queryError !== undefined ? (
+          // The branch the table did not have (components audit #3). It spans every rendered
+          // column and carries the query's OWN `refetch` behind Retry, so the failure is reported
+          // where the rows would have been — not as an empty table saying nothing failed.
+          <Table.Tr>
+            <Table.Td colSpan={columnCount}>
+              <ErrorState
+                error={queryError.error}
+                title="Could not load"
+                tier="section"
+                retrying={queryError.fetchStatus === 'fetching'}
+                onRetry={() => void queryError.refetch()}
+              />
+            </Table.Td>
+          </Table.Tr>
+        ) : showSkeleton ? (
           Array.from({ length: skeletonRows }, (_, rowIndex) => (
             <Table.Tr key={`skeleton-${rowIndex}`}>
-              {columns.map((_, colIndex) => (
+              {Array.from({ length: columnCount }, (__, colIndex) => (
                 <Table.Td key={`skeleton-${rowIndex}-${colIndex}`}>
                   <Skeleton height={16} radius="sm" />
                 </Table.Td>
@@ -974,7 +1515,7 @@ export function BasaltDataTable<T>({
           ))
         ) : rows.length === 0 ? (
           <Table.Tr>
-            <Table.Td colSpan={columns.length}>
+            <Table.Td colSpan={columnCount}>
               {emptyState ?? (
                 <Text c="dimmed" ta="center" size="sm" py="sm">
                   No data to display.
@@ -992,7 +1533,28 @@ export function BasaltDataTable<T>({
                 ]
               : row.getVisibleCells()
             return (
-              <Table.Tr key={row.id}>
+              <Table.Tr
+                key={row.id}
+                {...(enableRowSelection && row.getIsSelected() && { 'data-selected': true })}
+                {...(onRowActivate !== undefined && {
+                  className: classes.activatable,
+                  'data-activatable': true,
+                  tabIndex: 0,
+                  onClick: () => onRowActivate(row.original),
+                  // Enter only. Space is the browser's own page-scroll on a focused non-button, and
+                  // stealing it from a keyboard reader moving down a long table costs more than the
+                  // second activation key buys.
+                  onKeyDown: (event: ReactKeyboardEvent<HTMLTableRowElement>) => {
+                    if (event.key !== 'Enter') return
+                    // Only the ROW's own Enter. A cell may hold a button, a link or the selection
+                    // checkbox, and keydown bubbles — so without this an Enter on a nested control
+                    // fired that control AND opened the row's detail behind it.
+                    if (event.target !== event.currentTarget) return
+                    event.preventDefault()
+                    onRowActivate(row.original)
+                  },
+                })}
+              >
                 {cells.map((cell) => {
                   const pinnedStyle = enablePinning
                     ? getPinnedCellStyle(table, cell.column)
@@ -1022,10 +1584,6 @@ export function BasaltDataTable<T>({
     </Table>
   )
 
-  // A capped body or a horizontal floor both need the same native scroll node; pinning keeps its
-  // simpler overflow-x Box when neither is set.
-  const scrolls = maxHeight !== undefined || minWidth !== undefined
-
   const paginationState = table.getState().pagination
   // The CURRENT page size is always an option, even when it is not in `pageSizeOptions`. Mantine's
   // Select renders EMPTY when its `value` matches no row, so a table opened at
@@ -1039,7 +1597,7 @@ export function BasaltDataTable<T>({
   const rangeEnd = Math.min((paginationState.pageIndex + 1) * paginationState.pageSize, total)
 
   return (
-    <>
+    <div className={cx(classNames?.root, className)} {...(style !== undefined && { style })}>
       {/*
        * ONE header row: the `WidgetHeader` (title · count) on the left, the toolbar right-aligned in
        * the SAME row. It was two stacked rows with `mb="xs"` on each, so a titled table with search
@@ -1066,11 +1624,17 @@ export function BasaltDataTable<T>({
           ) : null}
           {showToolbar && (
             <CtlSlot>
-              <Group gap="xs" wrap="wrap" align="center" style={TABLE_TOOLBAR_STYLE}>
+              <Group
+                className={cx(classNames?.toolbar)}
+                gap="xs"
+                wrap="wrap"
+                align="center"
+                style={TABLE_TOOLBAR_STYLE}
+              >
                 {showSearch && (
                   <TextInput
                     radius="md"
-                    w={SEARCH_WIDTH}
+                    style={TABLE_SEARCH_STYLE}
                     placeholder={globalFilterPlaceholder}
                     leftSection={searchIcon}
                     value={globalFilter}
@@ -1080,7 +1644,7 @@ export function BasaltDataTable<T>({
                 {showFacets && (
                   <FilterSet>
                     {facets?.map((facet) => {
-                      const column = table.getColumn(facet.columnId)
+                      const column = resolveFacetColumn(table, facet)
                       if (!column) return null
                       return facet.multiple ? (
                         <MultiSelectFilter
@@ -1098,13 +1662,27 @@ export function BasaltDataTable<T>({
                     })}
                   </FilterSet>
                 )}
-                {actions}
+                {actions !== undefined && <BarActionSlot actions={actions} />}
               </Group>
             </CtlSlot>
           )}
         </Group>
       )}
-      {scrolls ? (
+      {bulkBarActions !== undefined && (
+        <BulkActionBar count={selectedRows.length} actions={bulkBarActions} />
+      )}
+      {pageStickyHeader ? (
+        // Pinning takes this wrapper too — a pinned column's offsets are `position: sticky` on the
+        // cells and need no overflow box of their own, so the `overflow-x: auto` Box that used to
+        // sit here was the exact inert-sticky defect this shape exists to avoid.
+        <div
+          ref={containment.wrapperRef}
+          className={classes.containment}
+          data-contained={containment.contained ? 'true' : 'false'}
+        >
+          {tableNode}
+        </div>
+      ) : (
         <Table.ScrollContainer
           type="native"
           minWidth={minWidth ?? 0}
@@ -1112,13 +1690,16 @@ export function BasaltDataTable<T>({
         >
           {tableNode}
         </Table.ScrollContainer>
-      ) : enablePinning ? (
-        <Box style={{ overflowX: 'auto' }}>{tableNode}</Box>
-      ) : (
-        tableNode
       )}
       {enablePagination && (
-        <Group justify="space-between" mt="xs" wrap="wrap" gap="xs" align="center">
+        <Group
+          className={cx(classNames?.footer)}
+          justify="space-between"
+          mt="xs"
+          wrap="wrap"
+          gap="xs"
+          align="center"
+        >
           <Text style={RANGE_LABEL_STYLE}>
             Showing {rangeStart}–{rangeEnd}
             {totalIsAuthoritative ? ` of ${total}` : ''}
@@ -1143,6 +1724,6 @@ export function BasaltDataTable<T>({
           </Group>
         </Group>
       )}
-    </>
+    </div>
   )
 }