basalt-ui 1.30.2 → 1.32.0

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)
+    },
+  }
+}

package/src/data/data-table.module.css

@@ -62,3 +62,97 @@
 .containment[data-contained='true'] {
   overflow-x: auto;
 }
+
+/*
+ * The selection column's hit area is the WHOLE cell (`docs/CONTROLS-SPEC.md` §2): the
+ * cell is the positioning box and the wrapping <label>'s ::after stretches over it, so a tap
+ * anywhere in the cell toggles the checkbox. Not `data-basalt-hit` — that primitive centres a
+ * `--vx-hit` square on its element; this one must fill a cell of any width.
+ */
+.selectCell {
+  position: relative;
+}
+
+.selectHit {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.selectHit::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+}
+
+/*
+ * The column-fold measuring box (`useColumnFold` in `data-table.tsx`) — a plain block wrapper
+ * around whichever overflow shape the table already picks (the measured containment div, or
+ * `Table.ScrollContainer`). `min-width: 0` is the same flex/grid floor `.containment` needs: a
+ * wrapper sized by its own min-content would never read a shrunken `clientWidth` back.
+ */
+.foldWrapper {
+  min-width: 0;
+}
+
+/*
+ * The fold-disclosure toggle column (`docs/CONTROLS-SPEC.md` §2) — a narrow, centred cell
+ * matching `HIT_COARSE` in `common/hit-floor.ts`, so the header's empty cell and every row's
+ * button cell line up under one another regardless of how many columns folded.
+ */
+.foldToggleCell {
+  width: 2.75rem;
+  text-align: center;
+}
+
+.foldToggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: none;
+  padding: 0;
+  color: var(--vx-muted);
+  cursor: pointer;
+}
+
+.foldToggle:hover {
+  color: var(--vx-ink);
+}
+
+/* The disclosure row itself carries no border of its own — it reads as part of the row above it,
+   not a new one. */
+.foldDisclosureRowTr {
+  border-top: none;
+}
+
+.foldDisclosureCell {
+  padding-top: 0;
+  background: var(--vx-surface-subtle);
+}
+
+.foldDisclosure {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-row-inset-y, 0.375rem);
+  padding: var(--vx-space-row-inset-y, 0.375rem) 0;
+}
+
+.foldDisclosureRow {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--vx-space-row-inset-x, 0.5rem);
+}
+
+.foldDisclosureLabel {
+  font-size: var(--vx-text-xs);
+  color: var(--vx-muted);
+}
+
+.foldDisclosureValue {
+  font-size: var(--vx-text-sm);
+  color: var(--vx-ink);
+  text-align: right;
+}

package/src/data/data-table.module.css.d.ts

@@ -7,5 +7,16 @@ declare const classes: {
   readonly bulkBar: string
   readonly bulkCount: string
   readonly containment: string
+  readonly foldDisclosure: string
+  readonly foldDisclosureCell: string
+  readonly foldDisclosureLabel: string
+  readonly foldDisclosureRow: string
+  readonly foldDisclosureRowTr: string
+  readonly foldDisclosureValue: string
+  readonly foldToggle: string
+  readonly foldToggleCell: string
+  readonly foldWrapper: string
+  readonly selectCell: string
+  readonly selectHit: string
 }
 export default classes