basalt-ui 1.30.2 → 1.31.0

package/src/data/data-table.tsx

@@ -51,11 +51,13 @@ import type {
   ColumnPinningState,
   FilterFn,
   PaginationState,
+  Row,
   RowData,
   RowSelectionState,
   SortingState,
   Table as TanstackTable,
   Updater,
+  VisibilityState,
 } from '@tanstack/react-table'
 import {
   flexRender,
@@ -68,13 +70,16 @@ import {
 import type {
   CSSProperties,
   KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
   ReactNode,
   RefObject,
 } from 'react'
-import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { Fragment, useCallback, useEffect, 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'
@@ -121,6 +126,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 +328,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>
     ),
   }
 }
@@ -884,6 +902,217 @@ 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'
+
+const EMPTY_FOLD_SET: ReadonlySet<string> = new Set()
+
+/**
+ * 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 +1202,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.
- *
- * 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:
+ * 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.
  *
- * - **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.
+ * 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.
  *
- * `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 +1224,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 }
 }
@@ -1268,7 +1455,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,6 +1505,97 @@ 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])
+  const columnFold = useColumnFold({
+    active: foldEligible,
+    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 [expandedFoldRows, setExpandedFoldRows] = useState<ReadonlySet<string>>(EMPTY_FOLD_SET)
+  const toggleFoldRow = useCallback((rowId: string) => {
+    setExpandedFoldRows((current) => {
+      const next = new Set(current)
+      if (next.has(rowId)) next.delete(rowId)
+      else next.add(rowId)
+      return next
+    })
+  }, [])
+  // `row.id` defaults to the row's index in `data` (no `getRowId` passed) — stable across a
+  // client-side sort/filter/pagination (they reorder or subset the SAME core rows). PRUNED rather
+  // than cleared on every `data` change: a non-memoized `data` prop (an inline `.map()`, an
+  // unstable query result) hands a brand-new array of the SAME rows on every parent re-render, and
+  // clearing on that reference alone collapsed every open disclosure the instant anything upstream
+  // re-rendered.
+  //
+  // Pruning by ID ALONE is only safe with `getRowId` — a caller-declared identity that genuinely
+  // survives a page turn or a refetch, so an id no longer present (a manual-pagination page turn, a
+  // delete) still has to go, or a differently-shaped record seated at a reused id would silently
+  // read as pre-expanded. Without `getRowId` the id IS the array index, and an index survives a
+  // refetch trivially — it is still "0", "1", … even when every object behind it is now a
+  // completely different record. Keeping an expanded index across THAT would silently attach the
+  // old disclosure to a stranger's row. So the index-id lane instead keeps a `prevData` snapshot and
+  // asks the narrower, correct question: is the object AT this index still the same reference as
+  // last time? A non-memoized array of the SAME rows answers yes at every index (the case above);
+  // a page turn or a refetch answers no.
+  const prevDataRef = useRef(data)
+  useEffect(() => {
+    const prevData = prevDataRef.current
+    prevDataRef.current = data
+    setExpandedFoldRows((current) => {
+      if (current.size === 0) return current
+      let next: ReadonlySet<string>
+      if (getRowId === undefined) {
+        next = new Set(
+          [...current].filter((id) => {
+            const index = Number(id)
+            return data[index] !== undefined && data[index] === prevData[index]
+          }),
+        )
+      } else {
+        const liveIds = new Set(data.map((row, index) => getRowId(row, index)))
+        next = new Set([...current].filter((id) => liveIds.has(id)))
+      }
+      return next.size === current.size ? current : next
+    })
+  }, [data, getRowId])
+
   const table = useReactTable<T>({
     data,
     columns: tableColumns,
@@ -1326,6 +1604,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       globalFilter,
       columnFilters,
       columnPinning,
+      columnVisibility,
       ...(enablePagination && { pagination }),
       ...(enableRowSelection && { rowSelection: rowSelectionState }),
     },
@@ -1371,10 +1650,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.
@@ -1400,8 +1680,8 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
 
   // 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
+  // measured wrapper below; there is no third overflow box. (`scrolls` itself is computed earlier,
+  // ahead of the table, because the column fold above needs it too.)
   // `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>`
@@ -1440,6 +1720,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 +1731,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
@@ -1532,51 +1820,77 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                   ...row.getRightVisibleCells(),
                 ]
               : row.getVisibleCells()
+            const rowExpanded = hasFolded && expandedFoldRows.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 })}
+                  {...(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)
+                    },
+                  })}
+                >
+                  {hasFolded && (
+                    <Table.Td className={classes.foldToggleCell}>
+                      <FoldToggle
+                        expanded={rowExpanded}
+                        controlsId={`${row.id}-fold`}
+                        onToggle={() => toggleFoldRow(row.id)}
+                      />
                     </Table.Td>
-                  )
-                })}
-              </Table.Tr>
+                  )}
+                  {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>
+                )}
+              </Fragment>
             )
           })
         )}
@@ -1671,25 +1985,44 @@ 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 })}
-        >
+      {!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>
+          ) : maxHeight !== undefined ? (
+            // `pageStickyHeader` is already false whenever `maxHeight` is set (`scrolls` above), so
+            // this is the ONE remaining case: a vertical cap with no sticky header to measure —
+            // still wants its own `ScrollArea` scrollport, just with no `minWidth` floor.
+            <Table.ScrollContainer type="native" minWidth={0} maxHeight={maxHeight}>
+              {tableNode}
+            </Table.ScrollContainer>
+          ) : (
+            <Table.ScrollContainer type="native" minWidth={0}>
+              {tableNode}
+            </Table.ScrollContainer>
+          )}
+        </div>
       )}
       {enablePagination && (
         <Group
@@ -1714,13 +2047,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>
       )}