basalt-ui 1.31.0 → 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,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,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.
@@ -795,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.
@@ -940,8 +975,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 +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,
@@ -1332,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
@@ -1385,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.
@@ -1538,8 +1490,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 +1503,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 +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. (`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 +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)}
@@ -1750,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 }),
@@ -1777,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) => (
@@ -1803,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) => {
@@ -1820,36 +1718,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 +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
@@ -1911,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
@@ -1985,7 +1889,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 +1922,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 +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"

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. */

package/src/guard/index.ts

@@ -152,7 +152,7 @@ const CSS_WIDTH_MEDIA_QUERY = new RegExp(
  * An `@container` condition — the declared NAME (optional: `@container (min-width: …)` with no
  * name is legal CSS, scoping to the nearest ancestor container regardless of its name) plus every
  * raw boundary across the WHOLE at-rule, chained `and (...)` clauses included
- * (`@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px)` —
+ * (`@container basalt-grid (min-width: 800px) and (max-width: 1199.9px)` —
  * `stat-group.module.css` ships exactly this shape). Capturing only the first parenthesized clause
  * would silently skip every boundary after the first `and`; group 2 here is the full run of
  * `(...)`/`and` text so `CSS_CONTAINER_LITERAL`'s own `matchAll` below finds all of them.
@@ -180,11 +180,8 @@ const CSS_NON_COARSE_POINTER_QUERY =
  * `basalt-form`/`basalt-main`/`basalt-grid` are the declared remaining three, reserved here so a
  * consumer adopting one ahead of the framework does not immediately trip this guard.
  *
- * Two container names already shipped ahead of this table — `basalt-stat-group` and
- * `basalt-widget-grid` (`src/tokens/breakpoint-literals.test.ts`'s own `LEGACY_CONTAINER_LITERALS`
- * names them) — predate the declared table and are deliberately NOT in this set: they surface as
- * `warn` findings against basalt's own source the same way any other kind's incumbent violations do
- * at grace time, rather than being silently grandfathered into a shipped rule's allowlist.
+ * `basalt-grid` is also what `StatGroup`/`WidgetGrid` declare (`src/dashboard/*.module.css`) —
+ * they shipped as `basalt-stat-group`/`basalt-widget-grid` until 1.32.0 moved them onto this table.
  */
 const DECLARED_CONTAINER_NAMES = new Set([
   'basalt-card',
@@ -229,7 +226,14 @@ function isSanctionedShellMediaQuery(relPath: string, query: string): boolean {
   // the comparison/chained spellings too, with no shape-specific regex of its own. All four units
   // are captured (not `em` only) so a `px` width — never a `SIZE_CLASS_LITERALS` member — correctly
   // fails the check below, rather than `.every()` vacuously passing on an empty match.
-  const widths = query.match(new RegExp(CSS_WIDTH_NUM, 'g')) ?? []
+  //
+  // But `query` is the whole at-rule prelude up to the width condition, so it can also carry a
+  // NON-width clause — the shell's own landscape rule is `(max-height: 480px) and (orientation:
+  // landscape) and (max-width: 52.49375em)`, and reading its `480px` height as an off-table width
+  // flagged the framework's own sanctioned implementation. Only the parenthesized clauses that name
+  // `width` are read.
+  const widthClauses = query.match(/\([^()]*\bwidth\b[^()]*\)/g) ?? []
+  const widths = widthClauses.flatMap((c) => c.match(new RegExp(CSS_WIDTH_NUM, 'g')) ?? [])
   return widths.length > 0 && widths.every((w) => SIZE_CLASS_LITERALS.has(w))
 }
 
@@ -860,8 +864,9 @@ export type GraceEntry = { since: string; promote: string; why: string }
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'raw-selection-control': {
     since: '1.26.0',
-    promote: '1.32.0',
+    promote: '1.33.0',
     why:
+      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
       'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
       'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
       'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
@@ -880,15 +885,15 @@ export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   },
   'raw-media-query': {
     since: '1.31.0',
-    promote: '1.32.0',
+    promote: '1.33.0',
     why:
-      'new in the wave-11 responsive/touch guards — the CSS-text ' +
-      "twin of the oxlint plugin's `basalt/raw-breakpoint`. Reaching CSS is a NEW file type for this " +
-      "check, same reasoning as `css-raw-surface`, and basalt's own `src/dashboard/stat-group.module" +
-      '.css` / `widget-grid.module.css` already declare `@container` names (`basalt-stat-group`, ' +
-      "`basalt-widget-grid`) outside the declared four-name table, plus `shell/**`'s own " +
-      "legitimate width `@media` rules — real incumbents in basalt's own tree at ship time, so this " +
-      'ships warn rather than error from the start. Promotes with its AST twin at 1.32.0.',
+      "The CSS-text twin of the oxlint plugin's `basalt/raw-breakpoint` — ONE LAW, TWO LANES, ONE " +
+      'PROMOTION, so it moves with that rule and never alone (`configs/oxlint-plugin.test.ts` › twin lanes share one promotion pins the pair). New in ' +
+      'the wave-11 responsive/touch guards; reaching CSS is a NEW file type for this check, same ' +
+      "reasoning as `css-raw-surface`, with incumbents in basalt's own tree at ship time, so it " +
+      'shipped warn. Extended 1.32.0 -> 1.33.0 with its twin: 1.31.0 named ' +
+      'no reachable container primitive, and 1.32.0 is the first minor that documents one ' +
+      '(`CONTAINER_CLASSES` + the declared `@container` names, MIGRATING § `basalt/raw-breakpoint`).',
   },
 }