basalt-ui 1.30.2 → 1.32.0

package/src/data/data-table.tsx

@@ -37,8 +37,10 @@ import {
   Checkbox,
   Group,
   Pagination,
+  ScrollArea,
   Select,
   Skeleton,
+  Stack,
   Table,
   Text,
   TextInput,
@@ -48,14 +50,14 @@ import type {
   Column,
   ColumnDef,
   ColumnFiltersState,
-  ColumnPinningState,
   FilterFn,
   PaginationState,
+  Row,
   RowData,
   RowSelectionState,
   SortingState,
   Table as TanstackTable,
-  Updater,
+  VisibilityState,
 } from '@tanstack/react-table'
 import {
   flexRender,
@@ -65,16 +67,13 @@ import {
   getSortedRowModel,
   useReactTable,
 } from '@tanstack/react-table'
-import type {
-  CSSProperties,
-  KeyboardEvent as ReactKeyboardEvent,
-  ReactNode,
-  RefObject,
-} from 'react'
-import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactNode, RefObject } from 'react'
+import { Fragment, 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 { HIT_COARSE } from '../common/hit-floor'
+import { useMeasuredWidths } from '../common/use-measured-widths'
 import { assertRequiredProps, useValidateProps } from '../common/validate'
 import { FilterSet } from '../controls'
 import { ActionGroup, BarActionSlot } from '../controls/actions'
@@ -91,6 +90,13 @@ import type { EnumField, FieldHandle, MultiField } from '../state'
 import { WidgetHeader } from '../dashboard'
 import { ErrorState } from '../dashboard/query-state'
 import type { QueryStateLike } from '../dashboard/query-state'
+import {
+  activationProps,
+  EMPTY_FOLD_SET,
+  useCardProjection,
+  useDataTableState,
+  useRowDisclosure,
+} from './data-table-state'
 import { dataQueryBranch } from './query-branch'
 import { isDev } from '../common/is-dev'
 import classes from './data-table.module.css'
@@ -121,6 +127,14 @@ declare module '@tanstack/react-table' {
      * `<td>`'s mono font then overrides what the cell asked for.
      */
     numeral?: boolean
+    /**
+     * Fold priority for the measured column fold (`docs/CONTROLS-SPEC.md` §2): once the
+     * table no longer fits its wrapper, the HIGHEST-numbered priority column folds first, moving
+     * into a per-row disclosure instead of forcing the table into horizontal scroll. Unset columns
+     * fall back to their declared position, so a bare `<BasaltDataTable data columns />` folds its
+     * LAST column first — nothing regresses with no `meta.priority` set anywhere. See `foldOrder`.
+     */
+    priority?: number
   }
 }
 
@@ -315,32 +329,37 @@ 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.
+ * The select cell's `stopPropagation` (see the `<Table.Td>`) 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()}
-      />
+      // oxlint-disable-next-line jsx-a11y/label-has-associated-control -- wraps <Checkbox>, which oxlint cannot see is an input
+      <label className={classes.selectHit}>
+        <Checkbox
+          size="xs"
+          aria-label="Select all rows"
+          checked={table.getIsAllPageRowsSelected()}
+          indeterminate={table.getIsSomePageRowsSelected() && !table.getIsAllPageRowsSelected()}
+          onChange={table.getToggleAllPageRowsSelectedHandler()}
+        />
+      </label>
     ),
     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()}
-      />
+      // oxlint-disable-next-line jsx-a11y/label-has-associated-control -- wraps <Checkbox>, which oxlint cannot see is an input
+      <label className={classes.selectHit}>
+        <Checkbox
+          size="xs"
+          aria-label={`Select row ${row.index + 1}`}
+          checked={row.getIsSelected()}
+          disabled={!row.getCanSelect()}
+          onChange={row.getToggleSelectedHandler()}
+        />
+      </label>
     ),
   }
 }
@@ -370,8 +389,9 @@ function BulkActionBar({ count, actions }: { count: number; actions: BarAction[]
 
 /**
  * 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.
+ * `toolbar` is the search/facets/actions row, `table` is whichever body renders — the Mantine
+ * `Table`, or the card list's `Stack` while `renderCard` projects — and `footer` is the pagination
+ * bar.
  */
 export type BasaltDataTableSlot = 'root' | 'toolbar' | 'table' | 'footer'
 
@@ -577,6 +597,37 @@ export type BasaltDataTableProps<T> = BasaltProps &
      * <BasaltDataTable data={rows} columns={columns} onRowActivate={(row) => setSelected(row)} />
      */
     onRowActivate?: (row: T) => void
+
+    /**
+     * A compact card projection of one row, rendered INSTEAD of the table while the table's own box
+     * is narrower than the `regular` container class (`CONTAINER_CLASSES`, 480px) — keyed on the
+     * width this table actually has, never the viewport, so a table in a narrow aside or a split
+     * column swaps on a desktop too, and a full-width one does not swap early on a tablet.
+     *
+     * The cards are the SAME processed rows the table would draw — sorted, filtered and paged — so a
+     * list can never disagree with its table; a fixed card order is `initialSorting`, not a second
+     * sort. Everything around the body stays: the header (title · count · toolbar), the bulk bar,
+     * the pager, and `query` / `isLoading` / `emptyState`. `onRowActivate` makes each card
+     * activatable exactly as it does a row (click, or Enter on the focused card). The selection
+     * checkbox is not projected — a card list with a selection keeps its bulk bar but no ticks.
+     *
+     * An activatable card takes `tabIndex=0` + `data-activatable`, never `role="button"`: a card is
+     * where a row's actions and links land (argo's all do), and a `button` role makes every
+     * descendant presentational, so those nested controls would vanish from the accessibility tree.
+     * The affordance is the cursor and the focus ring, as on the row. `maxHeight` caps the card list
+     * in a `ScrollArea`; `minWidth` does not apply — it is a horizontal floor for columns, and a
+     * card list has none.
+     *
+     * Reach for it when the row carries more than the columns a phone can hold (a status + label +
+     * age header, a clamped title, a prose line). A table that only needs to shed a column or two
+     * already has that: the column fold hides the lowest-priority columns behind a per-row
+     * disclosure with no prop at all. Server render and first paint are the table.
+     *
+     * @example
+     * <BasaltDataTable data={items} columns={columns} onRowActivate={open}
+     *   renderCard={(item) => <ItemCard item={item} />} />
+     */
+    renderCard?: (row: T) => ReactNode
     /**
      * Prepends a checkbox column (header = select-all on the page) and arms TanStack's row-selection
      * feature. Selection is uncontrolled unless `rowSelection` is passed.
@@ -777,6 +828,8 @@ function SortIndicator({ direction }: { direction: 'asc' | 'desc' | false }) {
   )
 }
 
+const ARIA_SORT = { asc: 'ascending', desc: 'descending' } as const
+
 // ── Numeral cell idiom (docs/DESIGN-SPEC.md §3: "Stat/table numeral: mono, 12-12.5px, weight
 // 500, ink") — auto-detected from the cell's raw value (no column-level opt-in prop needed) so
 // every numeric column gets tabular, mono figures with zero call-site configuration.
@@ -884,6 +937,215 @@ function getPinnedCellStyle<T>(
   }
 }
 
+// ── Column fold (`meta.priority`, docs/CONTROLS-SPEC.md §2) ──────────────────
+
+/** The column id TanStack will resolve internally for this raw def — explicit `id`, else the
+ * accessor key string. Mirrors the resolution `facetColumns` already relies on above. */
+function columnDefId<T>(column: ColumnDef<T, unknown>): string | undefined {
+  if (column.id !== undefined) return column.id
+  return 'accessorKey' in column && typeof column.accessorKey === 'string'
+    ? column.accessorKey
+    : undefined
+}
+
+/**
+ * Fold order for `meta.priority` — the FIRST id in the returned list folds first. Effective
+ * priority is `meta.priority ?? declaredIndex`, so with no `meta.priority` set anywhere it is just
+ * the column's position: the LAST declared column folds first, the zero-config default a bare
+ * `<BasaltDataTable data columns />` needs. An explicit priority folds a HIGHER number before a
+ * lower one; a tie folds in reverse declared order. A column with no resolvable id (an
+ * `accessorFn` with no explicit `id`) is never a fold candidate — nothing downstream could
+ * reliably re-identify it once hidden.
+ */
+function foldOrder<T>(columns: readonly ColumnDef<T, unknown>[]): string[] {
+  return columns
+    .map((column, index) => ({
+      id: columnDefId(column),
+      priority: column.meta?.priority ?? index,
+      index,
+    }))
+    .filter((candidate): candidate is { id: string; priority: number; index: number } =>
+      Boolean(candidate.id),
+    )
+    .toSorted((a, b) => b.priority - a.priority || b.index - a.index)
+    .map((candidate) => candidate.id)
+}
+
+/** Marks a rendered data column header for `useColumnFold`'s width measurement — never read past
+ * that hook, so it carries no styling and needs no CSS-module counterpart. */
+const FOLD_ID_ATTR = 'data-basalt-fold-id'
+
+/**
+ * Pure decision: fold columns off the FRONT of `order` (already fold-first sorted) until the
+ * still-unfolded ones — plus `overhead` (the columns excluded from candidacy altogether — pinned,
+ * or `enableHiding: false` — which occupy room but can never fold) and the disclosure toggle's own
+ * width, once anything is folded — fit `room`. A candidate with no measured width yet (never
+ * rendered) is skipped rather than folded blind, since folding it would remove the one place its
+ * width could ever be read from.
+ */
+export function planColumnFold(input: {
+  room: number
+  toggleWidth: number
+  overhead: number
+  order: readonly string[]
+  widths: ReadonlyMap<string, number>
+}): ReadonlySet<string> {
+  const { room, toggleWidth, overhead, order, widths } = input
+  const known = order.filter((id) => widths.has(id))
+  let unfolded = overhead + known.reduce((sum, id) => sum + (widths.get(id) ?? 0), 0)
+  const folded = new Set<string>()
+  for (const id of known) {
+    // Never fold the last remaining data column — a table with every column folded has no row
+    // identifier left to read at all, which is worse than the horizontal scroll this exists to
+    // avoid. With no explicit `meta.priority` this is `order`'s LAST id, which `foldOrder`'s own
+    // doc pins as the FIRST declared column (the last-declared one folds first).
+    if (folded.size >= known.length - 1) break
+    const withToggle = unfolded + (folded.size > 0 ? toggleWidth : 0)
+    if (withToggle <= room) break
+    folded.add(id)
+    unfolded -= widths.get(id) ?? 0
+  }
+  return folded
+}
+
+/**
+ * The general-case measured fold. Reacting to `useMeasuredContainment`'s boolean fit directly
+ * (fold one, remeasure, maybe unfold) would oscillate, because folding changes the very box being
+ * measured. Instead this reads each candidate `<th data-basalt-fold-id>`'s width once, while it is
+ * visible, caches it, and decides analytically (`planColumnFold`). `useMeasuredWidths` owns the
+ * cache and the wrapper-vs-table observer that `controls/actions.tsx`'s fold shares.
+ */
+function useColumnFold(input: {
+  active: boolean
+  order: readonly string[]
+  /**
+   * Columns excluded from fold candidacy altogether (pinned, or `enableHiding: false`) — they are
+   * never in `order`, but they still occupy room, and their measured widths (carried in the same
+   * `[data-basalt-fold-id]` sweep as every eligible column's) become fixed overhead against the
+   * fold baseline. See `planColumnFold`'s `overhead` param.
+   */
+  fixedIds: readonly string[]
+}): {
+  wrapperRef: RefObject<HTMLDivElement | null>
+  folded: ReadonlySet<string>
+} {
+  const { active, order, fixedIds } = input
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const [folded, setFolded] = useState<ReadonlySet<string>>(EMPTY_FOLD_SET)
+  const orderRef = useRef(order)
+  orderRef.current = order
+  const fixedIdsRef = useRef(fixedIds)
+  fixedIdsRef.current = fixedIds
+  useLayoutEffect(() => {
+    if (!active || order.length === 0) {
+      setFolded((current) => (current.size === 0 ? current : EMPTY_FOLD_SET))
+    }
+  }, [active, order.length])
+
+  useMeasuredWidths({
+    resolveRoot: () => wrapperRef.current,
+    signature: `${order.join('|')}::${fixedIds.join('|')}`,
+    enabled: active && order.length > 0,
+    // The table too, not only the wrapper: a re-measured column set moves its min-content width
+    // while the wrapper's own box never changes.
+    extra: (root) => [root.querySelector('table')],
+    onMeasure: (root, boxes) => {
+      for (const cell of root.querySelectorAll<HTMLElement>(`[${FOLD_ID_ATTR}]`)) {
+        const id = cell.getAttribute(FOLD_ID_ATTR)
+        if (id !== null && cell.offsetWidth > 0) {
+          boxes.current.set(id, { width: cell.offsetWidth, height: cell.offsetHeight })
+        }
+      }
+      const room = root.clientWidth
+      // A zero reading is an un-laid-out ancestor, not a table with no room — the same guard
+      // `useMeasuredContainment` above runs against the aside animating in from 0.
+      if (room === 0) return
+      const widths = new Map([...boxes.current].map(([id, box]) => [id, box.width]))
+      const overhead = fixedIdsRef.current.reduce((sum, id) => sum + (widths.get(id) ?? 0), 0)
+      const next = planColumnFold({
+        room,
+        // The disclosure toggle is a fixed icon-button cell matched to the coarse hit floor, so it
+        // reads as one more `--vx-hit` control rather than a narrower afterthought.
+        toggleWidth: HIT_COARSE,
+        overhead,
+        order: orderRef.current,
+        widths,
+      })
+      setFolded((current) =>
+        current.size === next.size && [...current].every((id) => next.has(id)) ? current : next,
+      )
+    },
+  })
+
+  return { wrapperRef, folded: active ? folded : EMPTY_FOLD_SET }
+}
+
+/** The label half of a folded column's disclosure row — its own header when it is a plain string
+ * (the common case), else the column id, since a function/`ReactNode` header has no header
+ * CONTEXT to render with here (this is a body row, not the `<thead>`). */
+function columnLabel<T>(column: Column<T, unknown>): string {
+  const header = column.columnDef.header
+  return typeof header === 'string' ? header : column.id
+}
+
+/** One row's folded columns as label/value pairs, directly under it. `row.getAllCells()` returns
+ * every leaf cell regardless of visibility (unlike `getVisibleCells()`), so a folded column's own
+ * `cell` renderer still draws here exactly as it would in the `<td>` it no longer occupies. */
+function RowDisclosure<T>({
+  row,
+  folded,
+}: {
+  row: Row<T>
+  folded: ReadonlySet<string>
+}): ReactNode {
+  const cells = row.getAllCells().filter((cell) => folded.has(cell.column.id))
+  return (
+    <div className={classes.foldDisclosure}>
+      {cells.map((cell) => (
+        <div key={cell.id} className={classes.foldDisclosureRow}>
+          <Text className={classes.foldDisclosureLabel}>{columnLabel(cell.column)}</Text>
+          <div className={classes.foldDisclosureValue}>
+            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/** The per-row expand/collapse control the fold-disclosure column renders — a text glyph, since
+ * basalt ships no icon set (`docs/CONTROLS-SPEC.md` §2, mirrors `SortIndicator` above). */
+function FoldToggle({
+  expanded,
+  controlsId,
+  onToggle,
+}: {
+  expanded: boolean
+  controlsId: string
+  onToggle: () => void
+}): ReactNode {
+  return (
+    <button
+      type="button"
+      className={classes.foldToggle}
+      data-basalt-hit
+      aria-expanded={expanded}
+      aria-controls={controlsId}
+      aria-label={expanded ? 'Hide row details' : 'Show row details'}
+      // A row carrying `onRowActivate` reads a bubbled click as "activate the row" — the toggle
+      // would open/close its disclosure AND fire the row's own action underneath it.
+      onClick={(event) => {
+        event.stopPropagation()
+        onToggle()
+      }}
+    >
+      <Box component="span" aria-hidden>
+        {expanded ? '▾' : '▸'}
+      </Box>
+    </button>
+  )
+}
+
 // ── The manual-pagination contract ────────────────────────────────────────────
 
 /** One client-side control that `manualPagination` turns into a claim the table cannot support. */
@@ -973,38 +1235,20 @@ function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): vo
  * 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.
+ * sizes to its own min-content and would drag the page sideways. This shape cannot take that
+ * container unconditionally: an `overflow-x: auto` box also computes `overflow-y`, making it the
+ * sticky header's own scrollport with no scroll range, so the `<thead>` scrolls clean away.
  *
- * 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.
+ * So the wrapper's overflow is MEASURED. While the table FITS, the wrapper is bare and the sticky
+ * header sticks; once it is WIDER, the wrapper flips to `overflow-x: auto` and the header is inert.
+ * The trade is deliberate: a header that stops sticking is recoverable, a page that scrolls
+ * sideways is not.
  *
- * 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.
+ * Three invariants: the observer stays alive in BOTH states (no one-way latch, so the wrapper
+ * reverts when the space returns); equality counts as FITS (a `width: 100%` table reads
+ * `offsetWidth === clientWidth`, which stops oscillation); and a zero `clientWidth` is `unknown`,
+ * not overflow (the aside animates its width in from 0). `useLayoutEffect` runs before paint, so an
+ * already-measurable table resolves without a flash; the default is bare for SSR and first paint.
  */
 function useMeasuredContainment(active: boolean): {
   wrapperRef: RefObject<HTMLDivElement | null>
@@ -1013,50 +1257,26 @@ function useMeasuredContainment(active: 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 same measured-fold core `useColumnFold` uses, so this shape no longer mounts a second
+  // bespoke `ResizeObserver` on the wrapper + table.
+  useMeasuredWidths({
+    resolveRoot: () => wrapperRef.current,
+    signature: String(active),
+    enabled: active,
     // 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])
+    extra: (root) => [root.querySelector('table')],
+    onMeasure: (root) => {
+      const table = root.querySelector('table')
+      // Three answers, not two — see the docblock. A zero reading is an un-laid-out ancestor
+      // (the aside animating in from 0), not overflow, so it moves neither the state nor the
+      // observer; equality counts as FITS and stops the fit/contained oscillation.
+      if (table === null || root.clientWidth === 0 || table.offsetWidth === 0) return
+      const next = table.offsetWidth > root.clientWidth
+      setContained((current) => (current === next ? current : next))
+    },
+  })
 
   return { wrapperRef, contained: active && contained }
 }
@@ -1107,32 +1327,23 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     isLoading = false,
     query,
     skeletonRows = 5,
-    initialSorting,
-    onSortingChange,
     enableGlobalFilter = false,
     globalFilterPlaceholder = 'Search…',
     searchIcon,
-    initialGlobalFilter,
-    onGlobalFilterChange,
     facets,
-    onColumnFiltersChange,
     manualFiltering = false,
     actions,
     onRowActivate,
+    renderCard,
     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,
@@ -1145,17 +1356,8 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     style,
     classNames,
   } = props
-  const [sorting, setSorting] = useState<SortingState>(initialSorting ?? [])
-  const [globalFilter, setGlobalFilter] = useState(initialGlobalFilter ?? '')
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
-  const [pagination, setPagination] = useState<PaginationState>(
-    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
+  const tableState = useDataTableState(props, pageSizeOptions[0] ?? 10)
+  const { globalFilter, columnPinning, onGlobalFilterChange: handleGlobalFilterChange } = tableState
 
   // `stickyHeaderOffset` is DROPPED whenever the table owns a scroll container — see
   // `resolvedStickyHeaderOffset` below for why it is always wrong there. Dropping it silently is
@@ -1198,69 +1400,6 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     ],
   )
 
-  const handleSortingChange = useCallback(
-    (updater: Updater<SortingState>) => {
-      setSorting((prev) => {
-        const next = typeof updater === 'function' ? updater(prev) : updater
-        onSortingChange?.(next)
-        return next
-      })
-    },
-    [onSortingChange],
-  )
-
-  const handleGlobalFilterChange = useCallback(
-    (updater: Updater<string>) => {
-      setGlobalFilter((prev) => {
-        const next = typeof updater === 'function' ? updater(prev) : updater
-        onGlobalFilterChange?.(next)
-        return next
-      })
-    },
-    [onGlobalFilterChange],
-  )
-
-  const handleColumnFiltersChange = useCallback(
-    (updater: Updater<ColumnFiltersState>) => {
-      setColumnFilters((prev) => {
-        const next = typeof updater === 'function' ? updater(prev) : updater
-        onColumnFiltersChange?.(next)
-        return next
-      })
-    },
-    [onColumnFiltersChange],
-  )
-
-  const handlePaginationChange = useCallback(
-    (updater: Updater<PaginationState>) => {
-      setPagination((prev) => {
-        const next = typeof updater === 'function' ? updater(prev) : updater
-        onPaginationChange?.(next)
-        return next
-      })
-    },
-    [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.
@@ -1268,7 +1407,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     if (!facets || facets.length === 0) return columns
     const facetById = new Map(facets.map((facet) => [facet.columnId, facet]))
     return columns.map((column) => {
-      const id = column.id ?? (column as { accessorKey?: string }).accessorKey
+      const id = columnDefId(column)
       const facet = id === undefined ? undefined : facetById.get(id)
       if (!facet) return column
       const filterFn: FilterFn<T> = facet.multiple
@@ -1318,25 +1457,74 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   const filteringEnabled = !breaches.includes('filtering')
   const totalIsAuthoritative = !breaches.includes('total')
 
+  // A capped body or a horizontal floor both need the same native scroll node — computed here,
+  // ahead of the table, because `pageStickyHeader` (further down) needs it: `maxHeight` alone still
+  // wants its own `ScrollArea` scrollport (a sticky `<thead>` resolves against it, not the measured
+  // containment div, which offers no vertical scroll box at all), so EITHER prop rules out the
+  // measured-containment shape.
+  const scrolls = maxHeight !== undefined || minWidth !== undefined
+
+  // Fold eligibility is narrower than `scrolls`: only `minWidth` is a genuinely DECLARED horizontal
+  // floor — the caller is stating "this table is at least this wide," which folding columns out of
+  // would contradict. `maxHeight` alone is a purely VERTICAL cap and orthogonal to column width, so
+  // a `stickyHeader` + `maxHeight` table (the pairing this package's own docs recommend for a
+  // capped, sticky-header body) still folds instead of silently regressing to horizontal scroll.
+  const foldEligible = minWidth === undefined
+
+  // The fold order is computed off the caller's OWN `columns` — never `tableColumns` — so the
+  // selection checkbox (prepended below) is never a fold candidate; see `foldOrder`'s docblock for
+  // the declared-order default and the explicit-priority rule. `enableHiding: false` and a PINNED
+  // column are excluded outright, not merely de-prioritized — both are the caller stating this
+  // column must stay visible, the same declaration a fold candidate has no way to override.
+  const { columnFoldOrder, columnFoldFixedIds } = useMemo(() => {
+    const pinnedIds = new Set([...(columnPinning.left ?? []), ...(columnPinning.right ?? [])])
+    const excluded = new Set(
+      columns.flatMap((column) => {
+        const id = columnDefId(column)
+        if (id === undefined) return []
+        return column.enableHiding === false || pinnedIds.has(id) ? [id] : []
+      }),
+    )
+    return {
+      columnFoldOrder: foldOrder(columns).filter((id) => !excluded.has(id)),
+      columnFoldFixedIds: [...excluded],
+    }
+  }, [columns, columnPinning])
+  // The card projection unmounts the table, so the fold and the containment wrapper go inactive with
+  // it — their measuring effects re-attach to the remounted table when the width returns.
+  const projection = useCardProjection(renderCard !== undefined)
+  const columnFold = useColumnFold({
+    active: foldEligible && !projection.cards,
+    order: columnFoldOrder,
+    fixedIds: columnFoldFixedIds,
+  })
+  const columnVisibility: VisibilityState = useMemo(
+    () => Object.fromEntries([...columnFold.folded].map((id) => [id, false])),
+    [columnFold.folded],
+  )
+  const hasFolded = columnFold.folded.size > 0
+  const foldRows = useRowDisclosure({ data, getRowId })
+
   const table = useReactTable<T>({
     data,
     columns: tableColumns,
     state: {
-      sorting,
+      sorting: tableState.sorting,
       globalFilter,
-      columnFilters,
+      columnFilters: tableState.columnFilters,
       columnPinning,
-      ...(enablePagination && { pagination }),
-      ...(enableRowSelection && { rowSelection: rowSelectionState }),
+      columnVisibility,
+      ...(enablePagination && { pagination: tableState.pagination }),
+      ...(enableRowSelection && { rowSelection: tableState.rowSelection }),
     },
-    onSortingChange: handleSortingChange,
+    onSortingChange: tableState.onSortingChange,
     onGlobalFilterChange: handleGlobalFilterChange,
-    onColumnFiltersChange: handleColumnFiltersChange,
-    onColumnPinningChange: setColumnPinning,
-    ...(enablePagination && { onPaginationChange: handlePaginationChange }),
+    onColumnFiltersChange: tableState.onColumnFiltersChange,
+    onColumnPinningChange: tableState.onColumnPinningChange,
+    ...(enablePagination && { onPaginationChange: tableState.onPaginationChange }),
     ...(enableRowSelection && {
       enableRowSelection: true,
-      onRowSelectionChange: handleRowSelectionChange,
+      onRowSelectionChange: tableState.onRowSelectionChange,
     }),
     ...(getRowId !== undefined && { getRowId }),
     getCoreRowModel: getCoreRowModel(),
@@ -1371,10 +1559,11 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   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)
+  // Every colSpan and every skeleton row counts the RENDERED columns: one more than `columns` for
+  // the prepended checkbox column, one more again for the fold-disclosure toggle once anything has
+  // folded — a stale count left the empty state and the error row short of the header.
+  const columnCount =
+    columns.length + (enableRowSelection ? 1 : 0) + (hasFolded ? 1 : 0) - columnFold.folded.size
 
   // `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.
@@ -1398,10 +1587,6 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   // `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>`
@@ -1420,9 +1605,27 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   // `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 containment = useMeasuredContainment(pageStickyHeader && !projection.cards)
   const resolvedStickyHeaderOffset = scrolls ? undefined : stickyHeaderOffset
 
+  // The error branch the table did not have (components audit #3) carries the query's OWN `refetch`
+  // behind Retry, so the failure is reported where the rows would have been — in a row spanning
+  // every rendered column, or in place of the card list.
+  const errorNode = queryError !== undefined && (
+    <ErrorState
+      error={queryError.error}
+      title="Could not load"
+      tier="section"
+      retrying={queryError.fetchStatus === 'fetching'}
+      onRetry={() => void queryError.refetch()}
+    />
+  )
+  const emptyNode = emptyState ?? (
+    <Text c="dimmed" ta="center" size="sm" py="sm">
+      No data to display.
+    </Text>
+  )
+
   const tableNode = (
     <Table
       className={cx(classNames?.table)}
@@ -1440,6 +1643,9 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       <Table.Thead>
         {headerGroups.map((headerGroup) => (
           <Table.Tr key={headerGroup.id}>
+            {/* The disclosure toggle column has no header of its own — nothing is "sorted" or
+                "selected all" across it, only revealed per row. */}
+            {hasFolded && <Table.Th className={classes.foldToggleCell} aria-hidden />}
             {headerGroup.headers.map((header) => {
               const canSort = sortingEnabled && header.column.getCanSort()
               const sorted = header.column.getIsSorted()
@@ -1448,9 +1654,14 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                 ? getPinnedCellStyle(table, header.column)
                 : undefined
               const align = resolveAlign(header.column)
+              const isSelectColumn = header.column.id === SELECT_COLUMN_ID
               return (
                 <Table.Th
                   key={header.id}
+                  {...(isSelectColumn && { className: classes.selectCell })}
+                  // The measured fold's own read (`useColumnFold`) — never present on the
+                  // selection column, which is never a fold candidate.
+                  {...(!isSelectColumn && { [FOLD_ID_ATTR]: header.column.id })}
                   onClick={canSort ? toggleSorting : undefined}
                   onKeyDown={
                     canSort
@@ -1462,15 +1673,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                       : undefined
                   }
                   tabIndex={canSort ? 0 : undefined}
-                  aria-sort={
-                    canSort
-                      ? sorted === 'asc'
-                        ? 'ascending'
-                        : sorted === 'desc'
-                          ? 'descending'
-                          : 'none'
-                      : undefined
-                  }
+                  aria-sort={canSort ? (sorted ? ARIA_SORT[sorted] : 'none') : undefined}
                   style={{
                     ...(canSort ? { cursor: 'pointer', userSelect: 'none' } : undefined),
                     ...(align !== undefined && { textAlign: align }),
@@ -1489,19 +1692,8 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       </Table.Thead>
       <Table.Tbody>
         {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.Td colSpan={columnCount}>{errorNode}</Table.Td>
           </Table.Tr>
         ) : showSkeleton ? (
           Array.from({ length: skeletonRows }, (_, rowIndex) => (
@@ -1515,13 +1707,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
           ))
         ) : rows.length === 0 ? (
           <Table.Tr>
-            <Table.Td colSpan={columnCount}>
-              {emptyState ?? (
-                <Text c="dimmed" ta="center" size="sm" py="sm">
-                  No data to display.
-                </Text>
-              )}
-            </Table.Td>
+            <Table.Td colSpan={columnCount}>{emptyNode}</Table.Td>
           </Table.Tr>
         ) : (
           rows.map((row) => {
@@ -1532,51 +1718,60 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                   ...row.getRightVisibleCells(),
                 ]
               : row.getVisibleCells()
+            const rowExpanded = hasFolded && foldRows.expanded.has(row.id)
             return (
-              <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)
-                    : undefined
-                  const align = resolveAlign(cell.column)
-                  return (
-                    <Table.Td
-                      key={cell.id}
-                      style={{
-                        ...(typeof cell.getValue() === 'number' &&
-                        cell.column.columnDef.meta?.numeral !== false
-                          ? NUMERIC_CELL_STYLE
-                          : undefined),
-                        ...(align !== undefined && { textAlign: align }),
-                        ...pinnedStyle,
-                      }}
-                    >
-                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              <Fragment key={row.id}>
+                <Table.Tr
+                  {...(enableRowSelection && row.getIsSelected() && { 'data-selected': true })}
+                  {...activationProps(onRowActivate, row.original)}
+                >
+                  {hasFolded && (
+                    <Table.Td className={classes.foldToggleCell}>
+                      <FoldToggle
+                        expanded={rowExpanded}
+                        controlsId={`${row.id}-fold`}
+                        onToggle={() => foldRows.toggle(row.id)}
+                      />
+                    </Table.Td>
+                  )}
+                  {cells.map((cell) => {
+                    const pinnedStyle = enablePinning
+                      ? getPinnedCellStyle(table, cell.column)
+                      : undefined
+                    const align = resolveAlign(cell.column)
+                    return (
+                      <Table.Td
+                        key={cell.id}
+                        {...(cell.column.id === SELECT_COLUMN_ID && {
+                          className: classes.selectCell,
+                          // The label's ::after fills the cell, so a tap on it bubbles to the row —
+                          // stop it only where a tick is possible; a disabled row's tap is a row tap.
+                          ...(cell.row.getCanSelect() && {
+                            onClick: (event: ReactMouseEvent) => event.stopPropagation(),
+                          }),
+                        })}
+                        style={{
+                          ...(typeof cell.getValue() === 'number' &&
+                          cell.column.columnDef.meta?.numeral !== false
+                            ? NUMERIC_CELL_STYLE
+                            : undefined),
+                          ...(align !== undefined && { textAlign: align }),
+                          ...pinnedStyle,
+                        }}
+                      >
+                        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                      </Table.Td>
+                    )
+                  })}
+                </Table.Tr>
+                {rowExpanded && (
+                  <Table.Tr id={`${row.id}-fold`} className={classes.foldDisclosureRowTr}>
+                    <Table.Td colSpan={columnCount} className={classes.foldDisclosureCell}>
+                      <RowDisclosure row={row} folded={columnFold.folded} />
                     </Table.Td>
-                  )
-                })}
-              </Table.Tr>
+                  </Table.Tr>
+                )}
+              </Fragment>
             )
           })
         )}
@@ -1584,6 +1779,25 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     </Table>
   )
 
+  // The `renderCard` body — the same processed rows, states and activation as the table's.
+  const renderCardList = () => (
+    <Stack gap="xs" className={cx(classNames?.table)}>
+      {queryError !== undefined
+        ? errorNode
+        : showSkeleton
+          ? Array.from({ length: skeletonRows }, (_, index) => (
+              <Skeleton key={`skeleton-${index}`} height={48} radius="md" />
+            ))
+          : rows.length === 0
+            ? emptyNode
+            : rows.map((row) => (
+                <Box key={row.id} {...activationProps(onRowActivate, row.original)}>
+                  {renderCard?.(row.original)}
+                </Box>
+              ))}
+    </Stack>
+  )
+
   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
@@ -1597,7 +1811,11 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   const rangeEnd = Math.min((paginationState.pageIndex + 1) * paginationState.pageSize, total)
 
   return (
-    <div className={cx(classNames?.root, className)} {...(style !== undefined && { style })}>
+    <div
+      ref={projection.rootRef}
+      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
@@ -1671,25 +1889,47 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       {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}
-          {...(maxHeight !== undefined && { maxHeight })}
-        >
+      {projection.cards ? (
+        maxHeight === undefined ? (
+          renderCardList()
+        ) : (
+          <ScrollArea.Autosize mah={maxHeight} type="hover" scrollbars="y">
+            {renderCardList()}
+          </ScrollArea.Autosize>
+        )
+      ) : !foldEligible ? (
+        // An explicit `minWidth` is the one genuinely DECLARED horizontal floor — the column fold
+        // never engages here (see `foldEligible`, above), so this shape keeps its exact
+        // pre-existing DOM: no extra measuring wrapper for a table nothing folds.
+        <Table.ScrollContainer type="native" minWidth={minWidth ?? 0} maxHeight={maxHeight}>
           {tableNode}
         </Table.ScrollContainer>
+      ) : (
+        // The column fold's own measuring box (`useColumnFold`) — wraps every remaining shape,
+        // `maxHeight`-only included: a vertical cap is orthogonal to column width, so a
+        // `stickyHeader` + `maxHeight` table (the pairing this package's own docs recommend) still
+        // folds instead of silently regressing to horizontal scroll. A plain block box, so it
+        // constrains nothing on its own; `columnFold.wrapperRef` only reads it.
+        <div ref={columnFold.wrapperRef} className={classes.foldWrapper}>
+          {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>
+          ) : (
+            // `pageStickyHeader` is false whenever `maxHeight` is set (`scrolls` above), so a vertical
+            // cap lands here — its own `ScrollArea` scrollport, just with no `minWidth` floor.
+            <Table.ScrollContainer type="native" minWidth={0} maxHeight={maxHeight}>
+              {tableNode}
+            </Table.ScrollContainer>
+          )}
+        </div>
       )}
       {enablePagination && (
         <Group
@@ -1705,6 +1945,8 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
             {totalIsAuthoritative ? ` of ${total}` : ''}
           </Text>
           <Group gap="xs" align="center">
+            {/* theme-allow control-outside-home — the table's own page-size setting, not a page
+                filter: its state is the table's pagination, owned inside this component. */}
             <Select
               size="ctl"
               radius="md"
@@ -1714,13 +1956,19 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
               onChange={(value) => value && table.setPageSize(Number(value))}
               allowDeselect={false}
             />
-            <Pagination
-              size="sm"
-              radius="md"
-              total={Math.max(table.getPageCount(), 1)}
-              value={paginationState.pageIndex + 1}
-              onChange={(page) => table.setPageIndex(page - 1)}
-            />
+            <CtlSlot>
+              {/* `Pagination` carries no `ctl`-tier entry in `CTL_THEME` (its own controls resolve
+                  the 44px coarse hit floor through `PaginationControl`'s theme-level
+                  `data-basalt-hit`, not through the `ctl` size), so `CtlSlot` cannot restore this
+                  size on its own — an explicit `size="sm"` is the visual this footer always had. */}
+              <Pagination
+                size="sm"
+                radius="md"
+                total={Math.max(table.getPageCount(), 1)}
+                value={paginationState.pageIndex + 1}
+                onChange={(page) => table.setPageIndex(page - 1)}
+              />
+            </CtlSlot>
           </Group>
         </Group>
       )}