basalt-ui 1.31.0 → 1.32.0

package/src/charts/primitives/legend-disclosure.tsx

@@ -0,0 +1,177 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { alpha, VX } from '../../tokens'
+import { useDismissOnOutside } from '../cursor/touch-pin'
+import { LEGEND_ROW_GAP } from './chart-frame-layout'
+
+const DISCLOSURE_PANEL: CSSProperties = {
+  position: 'fixed',
+  zIndex: VX.zIndexFloating,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: LEGEND_ROW_GAP,
+  // theme-allow raw-scroll-container — a fixed floating panel of one legend, not app chrome
+  overflowY: 'auto',
+  // `<dialog open>` brings UA chrome (centring margin, border, fit-content box) this resets.
+  margin: 0,
+  border: 'none',
+  width: 'auto',
+  height: 'auto',
+  padding: 10,
+  boxSizing: 'border-box',
+  backgroundColor: VX.surface.overlay,
+  boxShadow: VX.shadowOverlay,
+  color: VX.muted,
+  borderRadius: VX.radiusCard,
+}
+
+/** A popover never collapses below one usable row, however little room the chip leaves. */
+const DISCLOSURE_MIN_HEIGHT = 96
+
+/** A popover hangs off its chip (flipping above when there is no room below); a sheet is docked. */
+function disclosurePlacement(chip: DOMRect, coarse: boolean): CSSProperties {
+  if (coarse) {
+    return {
+      left: 0,
+      right: 0,
+      bottom: 0,
+      maxHeight: '60dvh',
+      borderBottomLeftRadius: 0,
+      borderBottomRightRadius: 0,
+      padding: '12px 16px calc(12px + env(safe-area-inset-bottom, 0px))',
+    }
+  }
+  const below = window.innerHeight - chip.bottom
+  const left = Math.max(8, Math.min(chip.left, window.innerWidth - 248))
+  const base = { left, right: 'auto', minWidth: 200, maxWidth: 'calc(100vw - 16px)' }
+  return below >= 200 || below >= chip.top
+    ? { ...base, top: chip.bottom + 4, maxHeight: Math.max(below - 12, DISCLOSURE_MIN_HEIGHT) }
+    : {
+        ...base,
+        bottom: window.innerHeight - chip.top + 4,
+        maxHeight: Math.max(chip.top - 12, DISCLOSURE_MIN_HEIGHT),
+      }
+}
+
+/**
+ * `ChartLegend`'s `All N` disclosure state: which button opened it (the chip, or a dots-mode entry)
+ * and where the fixed panel sits. Focus moves into the panel on open and back to that trigger on
+ * EVERY close path; a scroll outside the panel or a resize closes it, since it is fixed to where the
+ * trigger WAS.
+ */
+export function useLegendDisclosure(coarse: boolean) {
+  const [placement, setPlacement] = useState<CSSProperties | null>(null)
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const panelRef = useRef<HTMLDialogElement>(null)
+  const panelId = useId()
+  const wasOpen = useRef(false)
+  const open = placement !== null
+  const close = useCallback(() => setPlacement(null), [])
+  const openFrom = (trigger: HTMLButtonElement) => {
+    triggerRef.current = trigger
+    setPlacement(disclosurePlacement(trigger.getBoundingClientRect(), coarse))
+  }
+
+  useEffect(() => {
+    if (open) panelRef.current?.focus()
+    else if (wasOpen.current) triggerRef.current?.focus()
+    wasOpen.current = open
+  }, [open])
+
+  // Shared with the chart cursors' own outside-dismiss (`useChartCursor`/`useDiscreteCursor`, see
+  // `touch-pin.ts`); the panel's own scroll is not an outside one.
+  const isInsidePanel = useCallback(
+    (target: Node): boolean =>
+      panelRef.current?.contains(target) === true || triggerRef.current?.contains(target) === true,
+    [],
+  )
+  useDismissOnOutside({
+    enabled: open,
+    isInside: isInsidePanel,
+    onDismiss: close,
+    dismissOnResize: true,
+    scrollExemptInside: true,
+  })
+
+  // The coarse sheet claims `aria-modal` (below), which is a claim that Tab cannot leave it — a
+  // native `<dialog open>` (no `showModal()`) does not enforce that on its own (B14). Wrap Tab at
+  // the panel's own first/last focusable rather than the fine popover, which is dismissed by an
+  // outside click/Escape just as easily and never claimed to be modal in the first place.
+  useEffect(() => {
+    if (!open || !coarse) return
+    const panel = panelRef.current
+    if (panel === null) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const focusable = panel.querySelectorAll<HTMLElement>(
+        'button, [tabindex]:not([tabindex="-1"])',
+      )
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      if (first === undefined || last === undefined) return
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    panel.addEventListener('keydown', onKeyDown)
+    return () => panel.removeEventListener('keydown', onKeyDown)
+  }, [open, coarse])
+
+  return { open, panelId, openFrom, close, panel: { panelRef, panelId, coarse, placement, close } }
+}
+
+/** The portalled panel itself — a popover under the chip on a fine pointer, a docked sheet (over a
+ * scrim) on a coarse one. Fixed-position, so opening it never grows the legend band. */
+export function LegendDisclosure({
+  panelRef,
+  panelId,
+  coarse,
+  placement,
+  close,
+  fontSize,
+  children,
+}: ReturnType<typeof useLegendDisclosure>['panel'] & {
+  fontSize: number
+  children: ReactNode
+}) {
+  if (placement === null) return null
+  return createPortal(
+    <>
+      {coarse && (
+        <div
+          aria-hidden
+          onPointerDown={(e) => {
+            e.stopPropagation()
+            close()
+          }}
+          style={{
+            position: 'fixed',
+            inset: 0,
+            // One below the panel it sits behind — still `VX.zIndexFloating`-derived, never a
+            // second unrelated literal (B14).
+            zIndex: VX.zIndexFloating - 1,
+            backgroundColor: alpha(VX.neutral, 0.35),
+          }}
+        />
+      )}
+      <dialog
+        ref={panelRef}
+        id={panelId}
+        open
+        tabIndex={-1}
+        aria-label="Legend"
+        {...(coarse && { 'aria-modal': true })}
+        data-basalt-legend-disclosure={coarse ? 'sheet' : 'popover'}
+        style={{ ...DISCLOSURE_PANEL, fontSize, ...placement }}
+      >
+        {children}
+      </dialog>
+    </>,
+    document.body,
+  )
+}

package/src/controls/controls.module.css

@@ -49,6 +49,11 @@
   flex-shrink: 0;
 }
 
+/* theme-allow-file raw-media-query — the ControlRow's own C9 swap (pills inline, the rest in a
+   sheet) keys on the SIZE CLASS by design: the sheet is compact-class chrome, the same axis the
+   shell's bottom bar reads. Every width query here is `SIZE_CLASSES.medium`, pinned by
+   `breakpoint-literals.test.ts`. */
+
 /* Below `sm` only the first `inline` slots are pills; the rest live in the sheet. */
 @media (max-width: 52.49375em) {
   .pillSlot:not([data-inline]) {

package/src/controls/sync-button.module.css

@@ -45,6 +45,7 @@
  * width itself, pinned to the `ctl` height so the box is square. This module is unlayered, so it
  * outranks `@layer mantine` regardless of specificity.
  */
+/* theme-allow raw-media-query — the control's own C9 icon-only swap at the compact size class */
 @media (max-width: 52.49375em) {
   .label,
   .age {

package/src/dashboard/stat-group.module.css

@@ -15,24 +15,24 @@
  * one: a query with no container resolves to false, so a shell-only context would have silently
  * pinned every non-shell consumer to the base count.
  *
- * The `@supports not` block below it is the pre-2023 fallback and the ONLY place the old viewport
- * law survives. It is written as an exclusive alternative rather than as a base the container
- * queries override, because the rail's `:nth-child` suppressors are MORE specific than the rule
- * that draws the border: two overlapping laws would each suppress a different set of leading cells
- * and the rail would lose hairlines in the middle of a row. One law at a time, chosen by support.
+ * The literals are the container-class law (`CONTAINER_CLASSES`, `tokens/size-classes.ts`): the
+ * `sm` count opens at `wide` (800px), not at the viewport-era 768. Two are StatGroup's own and say
+ * so: 260px (one column, below) and 1200px, where the full `cols` count opens. The class table
+ * stops at 800, and 800 is too early for a full KPI row — four cells of ~190px clamp a value a real
+ * dashboard prints (`tests/layout/page-aside.layout.test.ts` measures ~195px against the 844px row
+ * a claimed aside leaves). Conditions are px, never `em`: `em` inside a `@container` condition
+ * resolves against the CONTAINER's font-size, so a consumer panel with smaller text would silently
+ * move the boundary. A condition cannot read a custom property, so the numbers are written; the
+ * COUNTS are custom properties the component sets per instance.
  *
- * The literals: `@container` conditions are stated in px, `@media` ones in Mantine's own `em`
- * (`--mantine-breakpoint-sm` 48em, `--mantine-breakpoint-lg` 75em). Both spellings name the same
- * boundary at the 16px initial font size — 768px and 1200px — but `em` inside a `@container`
- * condition resolves against the CONTAINER's font-size rather than the root's, so a consumer panel
- * with smaller text would silently move the breakpoint. px is the only spelling that cannot drift.
- * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`.) A condition still cannot read a custom property either way, so the numbers are written;
- * the COUNTS are custom properties the component sets per instance.
+ * No viewport fallback: basalt's own CSS already requires `color-mix()` (Safari 16.2, Chrome 111,
+ * Firefox 113), and every one of those parses `@container` — a `@supports not (container-type)`
+ * block is unreachable in any browser that renders basalt at all.
  */
 
 .container {
   container-type: inline-size;
-  container-name: basalt-stat-group;
+  container-name: basalt-grid;
 }
 
 .root {
@@ -45,7 +45,7 @@
 
 /* 260px is StatGroup's own literal (docs/DESIGN-CORE.md § Layout, elevation, shapes), not a container class: one column below it,
  * so every cell leads a row and the rail draws no leading hairline at all. */
-@container basalt-stat-group (max-width: 259.9px) {
+@container basalt-grid (max-width: 259.9px) {
   .root {
     grid-template-columns: minmax(0, 1fr);
   }
@@ -56,13 +56,13 @@
   }
 }
 
-@container basalt-stat-group (min-width: 768px) {
+@container basalt-grid (min-width: 800px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
   }
 }
 
-@container basalt-stat-group (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
   }
@@ -83,14 +83,14 @@
   padding-inline-start: var(--vx-space-stack-md);
 }
 
-@container basalt-stat-group (max-width: 767.9px) {
+@container basalt-grid (max-width: 799.9px) {
   .root[data-divided] > *:nth-child(2n + 1) {
     border-inline-start: 0;
     padding-inline-start: 0;
   }
 }
 
-@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px) {
+@container basalt-grid (min-width: 800px) and (max-width: 1199.9px) {
   .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
     border-inline-start: 0;
@@ -98,7 +98,7 @@
   }
 }
 
-@container basalt-stat-group (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
   .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
@@ -107,48 +107,3 @@
     padding-inline-start: 0;
   }
 }
-
-/*
- * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
- * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not.
- * A browser that cannot parse `container-type` also cannot parse the `@container` blocks above, so
- * the two sets are never live at once.
- */
-@supports not (container-type: inline-size) {
-  @media (min-width: 48em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
-    }
-  }
-
-  @media (max-width: 47.99375em) {
-    .root[data-divided] > *:nth-child(2n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-
-  @media (min-width: 48em) and (max-width: 74.99375em) {
-    .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
-    .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
-    .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
-    .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
-    .root[data-divided][data-cols='5'] > *:nth-child(5n + 1) {
-      border-inline-start: 0;
-      padding-inline-start: 0;
-    }
-  }
-}

package/src/dashboard/widget-grid.module.css

@@ -15,18 +15,19 @@
  * container. A span resolved against the viewport while the tracks follow the container is exactly
  * the phantom-track defect `WidgetGrid.Item`'s context clamp exists to prevent.
  *
- * The literals: px in `@container`, Mantine's own `em` in the `@supports not` fallback — same
- * boundary (768px / 1200px at the 16px initial font size), but `em` inside a `@container`
- * condition resolves against the CONTAINER's font-size, so px is the only spelling that cannot
- * drift. A condition cannot read a custom property either way, so the numbers are written; the
- * COUNTS are custom properties, set once per instance by the component — three hand-written
- * `repeat()` blocks would have to enumerate every `cols` value, and the whole point of this
- * primitive is that a consumer states one desktop number and basalt owns the rest.
+ * The literals are the container-class law, as in `stat-group.module.css`: the `sm` count opens
+ * at `wide` (800px); 1200px, where the full `cols` count opens, is the grid's own boundary above
+ * the class table's top step. px, never `em` (an `em` condition resolves against the container's
+ * font-size). A condition cannot read a custom property, so the numbers are written; the COUNTS
+ * are custom properties, set once per instance by the component — three hand-written `repeat()`
+ * blocks would have to enumerate every `cols` value, and the whole point of this primitive is that
+ * a consumer states one desktop number and basalt owns the rest. No viewport fallback, for the
+ * reason `stat-group.module.css` states: nothing that renders basalt lacks `@container`.
  */
 
 .container {
   container-type: inline-size;
-  container-name: basalt-widget-grid;
+  container-name: basalt-grid;
 }
 
 .root {
@@ -47,7 +48,7 @@
   min-width: 0;
 }
 
-@container basalt-widget-grid (min-width: 768px) {
+@container basalt-grid (min-width: 800px) {
   .root {
     grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
   }
@@ -57,7 +58,7 @@
   }
 }
 
-@container basalt-widget-grid (min-width: 1200px) {
+@container basalt-grid (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
   }
@@ -66,31 +67,3 @@
     grid-column: span var(--basalt-widget-grid-span-lg);
   }
 }
-
-/*
- * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
- * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not: a
- * browser that cannot parse `container-type` cannot parse the blocks above either, so the two sets
- * are never live at once.
- */
-@supports not (container-type: inline-size) {
-  @media (min-width: 48em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
-    }
-
-    .item {
-      grid-column: span var(--basalt-widget-grid-span-sm);
-    }
-  }
-
-  @media (min-width: 75em) {
-    .root {
-      grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
-    }
-
-    .item {
-      grid-column: span var(--basalt-widget-grid-span-lg);
-    }
-  }
-}

package/src/data/data-table-state.ts

@@ -0,0 +1,218 @@
+/**
+ * `BasaltDataTable`'s state hooks — the table's own interactive state, the fold row disclosure, the
+ * card projection and the row/card activation props. Internal to `./data/table`; nothing here is on a
+ * published subpath.
+ */
+import type {
+  ColumnFiltersState,
+  ColumnPinningState,
+  PaginationState,
+  RowSelectionState,
+  SortingState,
+  Updater,
+} from '@tanstack/react-table'
+import { functionalUpdate } from '@tanstack/react-table'
+import type { KeyboardEvent as ReactKeyboardEvent, RefObject } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { useMeasuredWidths } from '../common/use-measured-widths'
+import { CONTAINER_CLASSES } from '../tokens/size-classes'
+import classes from './data-table.module.css'
+
+export const EMPTY_FOLD_SET: ReadonlySet<string> = new Set()
+
+/**
+ * Which rows have their fold disclosure open. `row.id` defaults to the row's index in `data` (no
+ * `getRowId`) — stable across a client-side sort/filter/pagination, which 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 a different record.
+ * Keeping an expanded index across THAT would silently attach the old disclosure to a stranger's
+ * row. So the index-id lane 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.
+ */
+export function useRowDisclosure<T>({
+  data,
+  getRowId,
+}: {
+  data: readonly T[]
+  getRowId: ((row: T, index: number) => string) | undefined
+}): { expanded: ReadonlySet<string>; toggle: (rowId: string) => void } {
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(EMPTY_FOLD_SET)
+  const toggle = useCallback((rowId: string) => {
+    setExpanded((current) => {
+      const next = new Set(current)
+      if (next.has(rowId)) next.delete(rowId)
+      else next.add(rowId)
+      return next
+    })
+  }, [])
+  const prevDataRef = useRef(data)
+  useEffect(() => {
+    const prevData = prevDataRef.current
+    prevDataRef.current = data
+    setExpanded((current) => {
+      if (current.size === 0) return current
+      const liveIds = getRowId && new Set(data.map((row, index) => getRowId(row, index)))
+      const isLive = (id: string) => {
+        if (liveIds) return liveIds.has(id)
+        const index = Number(id)
+        return data[index] !== undefined && data[index] === prevData[index]
+      }
+      const next = new Set([...current].filter(isLive))
+      return next.size === current.size ? current : next
+    })
+  }, [data, getRowId])
+  return { expanded, toggle }
+}
+
+/** `useState` whose every write also reports the settled value — the one shape sorting, the global
+ * filter, the column filters and pagination all share. The callback runs inside the updater, so it
+ * sees exactly the value TanStack applied. */
+function useReportedState<S>(
+  initial: S,
+  onChange: ((next: S) => void) | undefined,
+): [S, (updater: Updater<S>) => void] {
+  const [value, setValue] = useState(initial)
+  const update = useCallback(
+    (updater: Updater<S>) => {
+      setValue((prev) => {
+        const next = functionalUpdate(updater, prev)
+        onChange?.(next)
+        return next
+      })
+    },
+    [onChange],
+  )
+  return [value, update]
+}
+
+/** The `BasaltDataTableProps` fields `useDataTableState` reads — declared here rather than picked
+ * off the props type, so the hook owns its contract and this module never imports the component. */
+export type DataTableStateProps = {
+  initialSorting?: SortingState | undefined
+  onSortingChange?: ((sorting: SortingState) => void) | undefined
+  initialGlobalFilter?: string | undefined
+  onGlobalFilterChange?: ((value: string) => void) | undefined
+  onColumnFiltersChange?: ((filters: ColumnFiltersState) => void) | undefined
+  initialPagination?: PaginationState | undefined
+  onPaginationChange?: ((pagination: PaginationState) => void) | undefined
+  initialColumnPinning?: ColumnPinningState | undefined
+  rowSelection?: RowSelectionState | undefined
+  onRowSelectionChange?: ((selection: RowSelectionState) => void) | undefined
+}
+
+/** The table's own interactive state and the TanStack `on*Change` handlers that write it — every
+ * piece uncontrolled with an optional change callback, except row selection, which is controlled
+ * whenever `rowSelection` is passed. */
+export function useDataTableState(props: DataTableStateProps, defaultPageSize: number) {
+  const { rowSelection, onRowSelectionChange } = props
+  const [sorting, onSortingChange] = useReportedState(
+    props.initialSorting ?? [],
+    props.onSortingChange,
+  )
+  const [globalFilter, onGlobalFilterChange] = useReportedState(
+    props.initialGlobalFilter ?? '',
+    props.onGlobalFilterChange,
+  )
+  const [columnFilters, onColumnFiltersChange] = useReportedState<ColumnFiltersState>(
+    [],
+    props.onColumnFiltersChange,
+  )
+  const [pagination, onPaginationChange] = useReportedState(
+    props.initialPagination ?? { pageIndex: 0, pageSize: defaultPageSize },
+    props.onPaginationChange,
+  )
+  const [columnPinning, setColumnPinning] = useState<ColumnPinningState>(
+    props.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 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?.(functionalUpdate(updater, rowSelection))
+        return
+      }
+      setInternalRowSelection((prev) => {
+        const next = functionalUpdate(updater, prev)
+        onRowSelectionChange?.(next)
+        return next
+      })
+    },
+    [rowSelection, onRowSelectionChange],
+  )
+
+  return {
+    sorting,
+    onSortingChange,
+    globalFilter,
+    onGlobalFilterChange,
+    columnFilters,
+    onColumnFiltersChange,
+    pagination,
+    onPaginationChange,
+    columnPinning,
+    onColumnPinningChange: setColumnPinning,
+    rowSelection: rowSelection ?? internalRowSelection,
+    onRowSelectionChange: handleRowSelectionChange,
+  }
+}
+
+/** Whether the table renders as `renderCard` projections: its own root measured below the `regular`
+ * container class. A zero width is an un-laid-out ancestor, not a narrow table, so it moves nothing
+ * — the default (and the SSR answer) is the table. The root's width never depends on which body it
+ * holds, so the swap cannot oscillate. */
+export function useCardProjection(enabled: boolean): {
+  rootRef: RefObject<HTMLDivElement | null>
+  cards: boolean
+} {
+  const rootRef = useRef<HTMLDivElement>(null)
+  const [narrow, setNarrow] = useState(false)
+  useMeasuredWidths({
+    resolveRoot: () => rootRef.current,
+    signature: '',
+    enabled,
+    onMeasure: (root) => {
+      if (root.clientWidth === 0) return
+      const next = root.clientWidth < CONTAINER_CLASSES.regular
+      setNarrow((current) => (current === next ? current : next))
+    },
+  })
+  return { rootRef, cards: enabled && narrow }
+}
+
+/** Click + Enter activation, shared by a row and its card. 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. */
+export function activationProps<T>(onRowActivate: ((row: T) => void) | undefined, row: T) {
+  if (onRowActivate === undefined) return undefined
+  return {
+    className: classes.activatable,
+    'data-activatable': true,
+    tabIndex: 0,
+    onClick: () => onRowActivate(row),
+    onKeyDown: (event: ReactKeyboardEvent<HTMLElement>) => {
+      if (event.key !== 'Enter') return
+      // Only the element's own Enter. A cell or card 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)
+    },
+  }
+}