basalt-ui 1.31.0 → 1.32.1

package/src/data/data-table.tsx

@@ -37,8 +37,10 @@ import {
   Checkbox,
   Group,
   Pagination,
+  ScrollArea,
   Select,
   Skeleton,
+  Stack,
   Table,
   Text,
   TextInput,
@@ -48,7 +50,6 @@ import type {
   Column,
   ColumnDef,
   ColumnFiltersState,
-  ColumnPinningState,
   FilterFn,
   PaginationState,
   Row,
@@ -56,7 +57,6 @@ import type {
   RowSelectionState,
   SortingState,
   Table as TanstackTable,
-  Updater,
   VisibilityState,
 } from '@tanstack/react-table'
 import {
@@ -67,14 +67,8 @@ import {
   getSortedRowModel,
   useReactTable,
 } from '@tanstack/react-table'
-import type {
-  CSSProperties,
-  KeyboardEvent as ReactKeyboardEvent,
-  MouseEvent as ReactMouseEvent,
-  ReactNode,
-  RefObject,
-} from 'react'
-import { Fragment, useCallback, useEffect, 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'
@@ -96,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'
@@ -388,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'
 
@@ -595,6 +597,40 @@ 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 — never Space, the
+     * browser's own page scroll on a focused non-button). 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. `stickyHeader` has nothing to stick while the cards render. A card order
+     * with no user sort is `data`'s own order — sort it there (or `initialSorting`) for a domain
+     * order.
+     *
+     * 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.
@@ -728,6 +764,10 @@ export type BasaltDataTableProps<T> = BasaltProps &
      * its own card instead of widening the page. Reach for this only to hold a MINIMUM table width
      * — e.g. so eight columns keep their readable widths and scroll rather than compress.
      *
+     * Setting it also switches the column fold OFF (a declared floor is the caller saying "this
+     * table is at least this wide", which folding columns out would contradict), so a `minWidth`
+     * table scrolls where the same table without it folds. `maxHeight` alone keeps the fold.
+     *
      * The one table whose wrapper is MEASURED rather than declared is `stickyHeader` with neither
      * this nor `maxHeight`; see that prop and `useMeasuredContainment` in the implementation for
      * why, and pair it with `maxHeight` if the table must both scroll and stick.
@@ -795,6 +835,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.
@@ -940,8 +982,6 @@ function foldOrder<T>(columns: readonly ColumnDef<T, unknown>[]): string[] {
  * 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,
@@ -1294,32 +1334,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,
@@ -1332,17 +1363,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
@@ -1385,69 +1407,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.
@@ -1538,8 +1497,11 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       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,
+    active: foldEligible && !projection.cards,
     order: columnFoldOrder,
     fixedIds: columnFoldFixedIds,
   })
@@ -1548,74 +1510,28 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     [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 foldRows = useRowDisclosure({ data, getRowId })
 
   const table = useReactTable<T>({
     data,
     columns: tableColumns,
     state: {
-      sorting,
+      sorting: tableState.sorting,
       globalFilter,
-      columnFilters,
+      columnFilters: tableState.columnFilters,
       columnPinning,
       columnVisibility,
-      ...(enablePagination && { pagination }),
-      ...(enableRowSelection && { rowSelection: rowSelectionState }),
+      ...(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(),
@@ -1678,10 +1594,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. (`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>`
@@ -1700,9 +1612,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)}
@@ -1750,15 +1680,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 }),
@@ -1777,19 +1699,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) => (
@@ -1803,13 +1714,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) => {
@@ -1820,36 +1725,19 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                   ...row.getRightVisibleCells(),
                 ]
               : row.getVisibleCells()
-            const rowExpanded = hasFolded && expandedFoldRows.has(row.id)
+            const rowExpanded = hasFolded && foldRows.expanded.has(row.id)
             return (
               <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)
-                    },
-                  })}
+                  {...activationProps(onRowActivate, row.original)}
                 >
                   {hasFolded && (
                     <Table.Td className={classes.foldToggleCell}>
                       <FoldToggle
                         expanded={rowExpanded}
                         controlsId={`${row.id}-fold`}
-                        onToggle={() => toggleFoldRow(row.id)}
+                        onToggle={() => foldRows.toggle(row.id)}
                       />
                     </Table.Td>
                   )}
@@ -1898,6 +1786,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
@@ -1911,7 +1818,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
@@ -1985,7 +1896,15 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       {bulkBarActions !== undefined && (
         <BulkActionBar count={selectedRows.length} actions={bulkBarActions} />
       )}
-      {!foldEligible ? (
+      {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.
@@ -2010,15 +1929,10 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
             >
               {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}>
+            // `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>
           )}
@@ -2038,6 +1952,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"

package/src/forms/form-layout.module.css

@@ -14,9 +14,10 @@
  * containment and `.grid` is the queried child, the same split `StatGroup`'s `.container`/`.root`
  * uses — a container cannot reliably query ITSELF for a layout-affecting property (measured here:
  * Chrome silently keeps the un-queried value even once the container's own width crosses the
- * condition), only a descendant. The `599.9px`/`47.99375em` literals: 600px is roughly the point
+ * condition), only a descendant. The `599.9px` literal: 600px is roughly the point
  * two ~250px+ cells stop feeling cramped; `@container`/`@media` conditions cannot read a custom
- * property, so both are written numbers, not `--vx-*` refs.
+ * property, so it is a written number, not a `--vx-*` ref. No viewport fallback — see
+ * `stat-group.module.css`: nothing that renders basalt lacks `@container`.
  */
 
 /* ── FormSection ─────────────────────────────────────────────────────────────────────────────── */
@@ -102,17 +103,6 @@
   }
 }
 
-/* Pre-container-query fallback (Safari < 16, Chrome < 106, Firefox < 110) — the old viewport law,
- * reachable only where `@container` itself cannot parse (same reasoning as `stat-group.module.css`). */
-@supports not (container-type: inline-size) {
-  @media (max-width: 47.99375em) {
-    .grid {
-      grid-template-columns: minmax(0, 1fr);
-      gap: var(--vx-space-stack-xs);
-    }
-  }
-}
-
 /* ── FormGroup ───────────────────────────────────────────────────────────────────────────────── */
 
 /* Same UA reset as `.control`, same reason. */
@@ -148,9 +138,12 @@
   gap: var(--vx-space-stack-xs);
 }
 
+/* Bottom-aligned, not stretched: a trailing button beside a labelled FormRow keeps its own height
+   and lines up with the input, not with the label above it. */
 .groupControls[data-direction='row'] {
   flex-direction: row;
   flex-wrap: wrap;
+  align-items: flex-end;
   gap: var(--vx-space-control-gap);
 }
 

package/src/forms/form-layout.tsx

@@ -213,7 +213,12 @@ export type FormGroupProps = BasaltProps & {
   error?: ReactNode
   /** Marks the group required — same two-channel treatment as `FormRow`. */
   required?: boolean
-  /** `column` stacks the options; `row` lays them out inline and wraps. @default 'column' */
+  /**
+   * `column` stacks the options; `row` lays them out inline, wraps, and bottom-aligns them, so a
+   * trailing button sits level with the inputs instead of stretching to the tallest child. Give a
+   * `FormRow` inside a `row` group (or any flex row) a definite width — it is an inline-size
+   * container, so its intrinsic width is zero and it collapses otherwise. @default 'column'
+   */
   direction?: 'row' | 'column'
   /** The cluster — checkboxes, radios, chips. */
   children: ReactNode