basalt-ui 1.41.0 → 2.0.0

package/src/{data → table}/data-table.tsx

@@ -1,6 +1,6 @@
 /**
- * ./data — BasaltDataTable: a sortable data table over @tanstack/react-table, rendered with Mantine.
- * Optional peer: @tanstack/react-table >=8 <9.
+ * ./table — BasaltDataTable: a sortable data table over @tanstack/react-table v9, rendered with
+ * Mantine. Optional peer: @tanstack/react-table 9.2.8 (exact).
  *
  * Ships with opt-in chrome layered on top of the base sortable table: a filter/search toolbar
  * (global search + faceted column Selects + an actions slot), a pagination bar ("Showing X–Y of N"
@@ -9,8 +9,7 @@
  * exactly as before.
  *
  * @example
- * import { BasaltDataTable } from 'basalt-ui/data/table'
- * import { createColumnHelper } from '@tanstack/react-table'
+ * import { BasaltDataTable, createColumnHelper } from 'basalt-ui/table'
  *
  * type Row = { name: string; age: number }
  * const col = createColumnHelper<Row>()
@@ -50,6 +49,7 @@ import type {
   Column,
   ColumnDef,
   ColumnFiltersState,
+  ColumnVisibilityState,
   FilterFn,
   PaginationState,
   Row,
@@ -57,18 +57,11 @@ import type {
   RowSelectionState,
   SortingState,
   Table as TanstackTable,
-  VisibilityState,
-} from '@tanstack/react-table'
-import {
-  flexRender,
-  getCoreRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
-  useReactTable,
 } from '@tanstack/react-table'
+import { constructFilterFn, FlexRender, useTable } from '@tanstack/react-table'
 import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactNode, RefObject } from 'react'
 import { Fragment, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { useDebouncedCallback } from '@mantine/hooks'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { BASALT_PREFIX } from '../common/errors'
@@ -86,7 +79,7 @@ import { EnumFilter } from '../controls/enum-filter'
 import { MultiSelectFilter } from '../controls/multi-select-filter'
 import { CtlSlot } from '../theme'
 import { alpha, VX } from '../tokens'
-import type { EnumField, FieldHandle, MultiField } from '../state'
+import type { EnumField, FieldHandle, MultiField } from '../state/fields'
 import { WidgetHeader } from '../dashboard'
 import { ErrorState } from '../dashboard/query-state'
 import type { QueryStateLike } from '../dashboard/query-state'
@@ -98,49 +91,24 @@ import {
   useRowDisclosure,
 } from './data-table-state'
 import { dataQueryBranch } from './query-branch'
+import { basaltTableFeatures } from './table-features'
+import type { BasaltColumnDef, BasaltTableFeatures, DataTableAlign } from './table-features'
 import classes from './data-table.module.css'
 
 // ── Column alignment ──────────────────────────────────────────────────────────
 
-/** Horizontal alignment of a column's header AND its cells. */
-export type DataTableAlign = 'left' | 'center' | 'right'
-
-/**
- * Alignment lives on the column def's `meta`, not on a parallel prop array, so it travels with the
- * column it describes and survives reordering.
- *
- * Declared as a module augmentation of TanStack's own `ColumnMeta` so `meta: { aling: 'right' }` is
- * a TYPE error (excess-property check on the object literal) rather than a silently ignored key —
- * and a wrong VALUE (`'end'`, `'centre'`) throws at render. A misspelled alignment that quietly
- * left-aligns a money column is the class of defect that looks correct in review.
- */
-declare module '@tanstack/react-table' {
-  // TData/TValue are TanStack's own parameters — required to match its declaration, unused here.
-  // oxlint-disable-next-line no-unused-vars
-  interface ColumnMeta<TData extends RowData, TValue> {
-    align?: DataTableAlign
-    /**
-     * Opt OUT of the automatic mono-numeral cell style. The table applies it whenever the cell's
-     * raw value is a number — which is right for a plain figure and wrong for a numeric accessor
-     * whose `cell` renders its own chrome (a coloured `Text`, a `Badge`, a sparkline), because the
-     * `<td>`'s mono font then overrides what the cell asked for.
-     */
-    numeral?: boolean
-    /**
-     * Fold priority for the measured column fold (`docs/CONTROLS-SPEC.md` §2): once the
-     * table no longer fits its wrapper, the HIGHEST-numbered priority column folds first, moving
-     * into a per-row disclosure instead of forcing the table into horizontal scroll. Unset columns
-     * fall back to their declared position, so a bare `<BasaltDataTable data columns />` folds its
-     * LAST column first — nothing regresses with no `meta.priority` set anywhere. See `foldOrder`.
-     */
-    priority?: number
-  }
-}
+// `meta.align` is typed by `BasaltColumnMeta` (`table-features.ts`); only the VALUE check lives here.
 
 const ALIGNMENTS: ReadonlySet<string> = new Set<DataTableAlign>(['left', 'center', 'right'])
 
-/** Reads `meta.align` off a column, throwing on a value that is not one of the three. */
-function resolveAlign<T>(column: Column<T, unknown>): DataTableAlign | undefined {
+/**
+ * Reads `meta.align` off a column, throwing on a value that is not one of the three — the one
+ * check a type cannot make once a value arrives from an untyped caller. A misspelled alignment that
+ * quietly left-aligns a money column looks correct in review.
+ */
+function resolveAlign<T extends RowData>(
+  column: Column<BasaltTableFeatures, T, unknown>,
+): DataTableAlign | undefined {
   const align = column.columnDef.meta?.align
   if (align === undefined) return undefined
   if (!ALIGNMENTS.has(align)) {
@@ -168,7 +136,7 @@ export type DataTableFacetOption = {
  * synthetic/derived column id (no matching key on `T`) still type-checks. Defaults to `unknown` so
  * a bare `DataTableFacet[]` / `DataTableColumnPinning` (no type argument) keeps working exactly as
  * before. Shared by {@link DataTableFacet}'s `columnId` and {@link DataTableColumnPinning}'s
- * `left`/`right`.
+ * `start`/`end`.
  */
 export type DataTableColumnId<T = unknown> = Extract<keyof T, string> | (string & {})
 
@@ -196,13 +164,12 @@ export type DataTableFacet<T = unknown> = {
 
 /**
  * Column ids pinned to each edge — the same `T`-derived id union as {@link DataTableFacet}'s
- * `columnId`, applied to TanStack's own `ColumnPinningState` shape (`{ left, right }`, each a bare
- * `string[]` unrelated to any row type). Structurally assignable to `ColumnPinningState`, so no
- * cast is needed where this flows into `useState<ColumnPinningState>`.
+ * `columnId`, applied to the `{ start, end }` shape. Not itself a TanStack `ColumnPinningState`: both edges are
+ * optional here, and `useDataTableState` normalises a missing edge to `[]` before the table sees it.
  */
 export type DataTableColumnPinning<T = unknown> = {
-  left?: DataTableColumnId<T>[]
-  right?: DataTableColumnId<T>[]
+  start?: DataTableColumnId<T>[]
+  end?: DataTableColumnId<T>[]
 }
 
 /**
@@ -233,8 +200,8 @@ function facetAllLabel<T>(facet: DataTableFacet<T>): string {
  * subscription needed, since the enclosing `BasaltDataTable` already re-renders on every
  * `columnFilters` change and this handle is rebuilt fresh each render alongside its column.
  */
-function facetEnumHandle<T>(
-  column: Column<T, unknown>,
+function facetEnumHandle<T extends RowData>(
+  column: Column<BasaltTableFeatures, T, unknown>,
   facet: DataTableFacet<T>,
 ): FieldHandle<EnumField<string>> {
   return {
@@ -263,8 +230,8 @@ function facetEnumHandle<T>(
  * single-select case, `MultiField`'s own fallback — an empty selection — already means "no
  * constraint", so no synthetic option is needed here.
  */
-function facetMultiHandle<T>(
-  column: Column<T, unknown>,
+function facetMultiHandle<T extends RowData>(
+  column: Column<BasaltTableFeatures, T, unknown>,
   facet: DataTableFacet<T>,
 ): FieldHandle<MultiField<string>> {
   return {
@@ -296,10 +263,10 @@ function facetMultiHandle<T>(
  * (`basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle constant-folds this
  * away), degrade to "no pill for this facet" in production.
  */
-function resolveFacetColumn<T>(
-  table: TanstackTable<T>,
+function resolveFacetColumn<T extends RowData>(
+  table: TanstackTable<BasaltTableFeatures, T>,
   facet: DataTableFacet<T>,
-): Column<T, unknown> | undefined {
+): Column<BasaltTableFeatures, T, unknown> | undefined {
   const column = table.getColumn(facet.columnId)
   if (column) return column
   if (process.env.NODE_ENV !== 'production') {
@@ -315,6 +282,34 @@ function resolveFacetColumn<T>(
   return undefined
 }
 
+/**
+ * The facet filters, built with `constructFilterFn` so `autoRemove` is part of the typed definition:
+ * a facet with nothing selected is dropped from `columnFilters` rather than kept as a no-op. They
+ * match the column value's STRING form exactly (a Select's option values are strings), which is why
+ * the built-in `includesString` auto-filter (substring) is never allowed to run on a facet column.
+ */
+const facetAutoRemove = (value: unknown): boolean =>
+  value === null ||
+  value === undefined ||
+  value === '' ||
+  (Array.isArray(value) && value.length === 0)
+
+const facetExact = constructFilterFn({
+  filter: (dataValue, filterValue: string | null | undefined) =>
+    filterValue === null || filterValue === undefined || filterValue === ''
+      ? true
+      : String(dataValue) === filterValue,
+  autoRemove: facetAutoRemove,
+})
+
+const facetAnyOf = constructFilterFn({
+  filter: (dataValue, filterValue: string[]) =>
+    !Array.isArray(filterValue) || filterValue.length === 0
+      ? true
+      : filterValue.includes(String(dataValue)),
+  autoRemove: facetAutoRemove,
+})
+
 // ── Row selection ─────────────────────────────────────────────────────────────
 
 /**
@@ -332,7 +327,7 @@ const SELECT_COLUMN_ID = '__basalt_select__'
  * lives inside the row, and a row carrying `onRowActivate` opens a detail from a click — so without
  * it, ticking the box also navigated away from the table the tick was meant to act on.
  */
-function selectionColumn<T>(): ColumnDef<T, unknown> {
+function selectionColumn<T extends RowData>(): ColumnDef<BasaltTableFeatures, T, unknown> {
   return {
     id: SELECT_COLUMN_ID,
     enableSorting: false,
@@ -407,14 +402,15 @@ export type BasaltDataTableSlot = 'root' | 'toolbar' | 'table' | 'footer'
  *   emptyState: <Text c="dimmed">No results found.</Text>,
  * }
  */
-export type BasaltDataTableProps<T> = BasaltProps &
+export type BasaltDataTableProps<T extends RowData> = BasaltProps &
   SlotStylesProps<BasaltDataTableSlot> & {
     // ── Header (WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────
 
     /**
-     * Optional heading rendered above the toolbar via `WidgetHeader tier="widget"`. `count` always
-     * reads `table.getRowCount()` (C11) — never a raw `data.length` — so it tracks the row model
-     * (post-filter/-pagination) rather than the unfiltered input.
+     * Optional heading rendered above the toolbar via `WidgetHeader tier="widget"`. The count tag
+     * beside it is automatic, not a prop (there is no `count`): it reads `table.getRowCount()` (C11)
+     * — never a raw `data.length` — so it tracks the row model (post-filter/-pagination) rather
+     * than the unfiltered input.
      */
     title?: string
     /** Optional leading icon, forwarded to `WidgetHeader`. */
@@ -425,14 +421,12 @@ export type BasaltDataTableProps<T> = BasaltProps &
     /** Row data array. */
     data: T[]
     /**
-     * Column definitions. Use `createColumnHelper<T>()` from `@tanstack/react-table`
+     * Column definitions. Use `createColumnHelper<T>()` from `basalt-ui/table`
      * for a typed accessor builder — `col.accessor('field', …)` columns sort by value.
      */
-    // The cell-value type varies per column, so the array is heterogeneous in TValue. `any` here
-    // is the TanStack-idiomatic escape (accessor columns infer their own TValue); row typing stays
-    // exact via the `T` data generic.
-    // oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
-    columns: ColumnDef<T, any>[]
+    // The cell-value type varies per column, so the array is heterogeneous in TValue
+    // (`BasaltColumnDef` carries the `any`); row typing stays exact via the `T` data generic.
+    columns: BasaltColumnDef<T>[]
     /**
      * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
      * reordered.
@@ -728,15 +722,15 @@ export type BasaltDataTableProps<T> = BasaltProps &
     // ── Column pinning ────────────────────────────────────────────────────────────
 
     /**
-     * Enables sticky left/right column pinning — pinned columns stick to the edge with a panel
+     * Enables sticky start/end column pinning — pinned columns stick to the edge with a panel
      * background and a hairline shadow separator while the table scrolls horizontally. Pin columns
-     * via `initialColumnPinning` (`{ left: string[], right: string[] }`).
+     * via `initialColumnPinning` (`{ start: string[], end: string[] }`).
      * @default false
      * @example
-     * <BasaltDataTable data={rows} columns={columns} enablePinning initialColumnPinning={{ left: ['name'] }} />
+     * <BasaltDataTable data={rows} columns={columns} enablePinning initialColumnPinning={{ start: ['name'] }} />
      */
     enablePinning?: boolean
-    /** Initial column-pinning state — which column ids stick to the left/right edge. */
+    /** Initial column-pinning state — which column ids stick to the start/end edge. */
     initialColumnPinning?: DataTableColumnPinning<T>
 
     // ── Body chrome ─────────────────────────────────────────────────────────────
@@ -885,6 +879,8 @@ const TABLE_TOOLBAR_STYLE: CSSProperties = { flex: '0 1 auto', minWidth: 0 }
  * `w={220}` in a 302px column was half of the overflow above.
  */
 const SEARCH_WIDTH = 220
+/** How long the global search waits after the last keystroke before filtering. */
+const SEARCH_DEBOUNCE_MS = 250
 const TABLE_SEARCH_STYLE: CSSProperties = {
   flex: `0 1 ${SEARCH_WIDTH}px`,
   minWidth: '12ch',
@@ -895,26 +891,27 @@ const PAGE_SIZE_WIDTH = 116
 
 // ── Column pinning helpers ────────────────────────────────────────────────────
 
-// Merges the left/center/right header-group triad TanStack exposes for pinning into the single
-// render order (left → center → right) the header row needs — depth-indexed so grouped headers
+// Merges the start/center/end header-group triad TanStack exposes for pinning into the single
+// render order (start → center → end) the header row needs — depth-indexed so grouped headers
 // (multi-row) still line up.
-function getOrderedHeaderGroups<T>(table: TanstackTable<T>) {
-  const left = table.getLeftHeaderGroups()
+function getOrderedHeaderGroups<T extends RowData>(table: TanstackTable<BasaltTableFeatures, T>) {
+  const start = table.getStartHeaderGroups()
   const center = table.getCenterHeaderGroups()
-  const right = table.getRightHeaderGroups()
+  const end = table.getEndHeaderGroups()
   return center.map((group, index) => ({
     ...group,
-    headers: [...(left[index]?.headers ?? []), ...group.headers, ...(right[index]?.headers ?? [])],
+    headers: [...(start[index]?.headers ?? []), ...group.headers, ...(end[index]?.headers ?? [])],
   }))
 }
 
-// Sticky offset math (column.getStart('left') / getAfter('right')) is computed purely from the
+// Sticky offset math (column.getStart('start') / getAfter('end')) is computed purely from the
 // pinned columns' own `getSize()`, so only pinned cells need an explicit width to keep the offsets
 // accurate — center columns stay naturally sized. The hairline shadow marks the edge column
-// touching the unpinned center (first right-pinned index 0 / last left-pinned index).
-function getPinnedCellStyle<T>(
-  table: TanstackTable<T>,
-  column: Column<T, unknown>,
+// touching the unpinned center (first end-pinned index 0 / last start-pinned index). Offsets are
+// logical insets, so `dir=rtl` mirrors them; the hairline shadow is a physical offset and does not.
+function getPinnedCellStyle<T extends RowData>(
+  table: TanstackTable<BasaltTableFeatures, T>,
+  column: Column<BasaltTableFeatures, T, unknown>,
 ): CSSProperties | undefined {
   const pinned = column.getIsPinned()
   if (!pinned) return undefined
@@ -927,18 +924,18 @@ function getPinnedCellStyle<T>(
     maxWidth: size,
     backgroundColor: VX.surface.panel,
   }
-  if (pinned === 'left') {
-    const isEdge = column.getPinnedIndex() === table.getLeftLeafColumns().length - 1
+  if (pinned === 'start') {
+    const isEdge = column.getPinnedIndex() === table.getStartLeafColumns().length - 1
     return {
       ...shared,
-      left: column.getStart('left'),
+      insetInlineStart: column.getStart('start'),
       boxShadow: isEdge ? `4px 0 6px -4px ${alpha(VX.ink, 0.18)}` : undefined,
     }
   }
   const isEdge = column.getPinnedIndex() === 0
   return {
     ...shared,
-    right: column.getAfter('right'),
+    insetInlineEnd: column.getAfter('end'),
     boxShadow: isEdge ? `-4px 0 6px -4px ${alpha(VX.ink, 0.18)}` : undefined,
   }
 }
@@ -947,7 +944,9 @@ function getPinnedCellStyle<T>(
 
 /** The column id TanStack will resolve internally for this raw def — explicit `id`, else the
  * accessor key string. Mirrors the resolution `facetColumns` already relies on above. */
-function columnDefId<T>(column: ColumnDef<T, unknown>): string | undefined {
+function columnDefId<T extends RowData>(
+  column: ColumnDef<BasaltTableFeatures, T, unknown>,
+): string | undefined {
   if (column.id !== undefined) return column.id
   return 'accessorKey' in column && typeof column.accessorKey === 'string'
     ? column.accessorKey
@@ -963,7 +962,9 @@ function columnDefId<T>(column: ColumnDef<T, unknown>): string | undefined {
  * `accessorFn` with no explicit `id`) is never a fold candidate — nothing downstream could
  * reliably re-identify it once hidden.
  */
-function foldOrder<T>(columns: readonly ColumnDef<T, unknown>[]): string[] {
+function foldOrder<T extends RowData>(
+  columns: readonly ColumnDef<BasaltTableFeatures, T, unknown>[],
+): string[] {
   return columns
     .map((column, index) => ({
       id: columnDefId(column),
@@ -988,16 +989,26 @@ const FOLD_ID_ATTR = 'data-basalt-fold-id'
  * width, once anything is folded — fit `room`. A candidate with no measured width yet (never
  * rendered) is skipped rather than folded blind, since folding it would remove the one place its
  * width could ever be read from.
+ *
+ * Every width is a rounded integer (`offsetWidth`, `clientWidth`), and a table that fills its
+ * wrapper stretches its columns to sum to `room` exactly — so the rounded sum lands up to half a
+ * pixel per column over it, and a table that fits folded a column on hydration (a server-painted
+ * table whose cells then moved). The fit check forgives that rounding and nothing more: half a
+ * pixel for each measured width (the foldable columns AND `fixedCount`, the pinned / non-hiding
+ * ones `overhead` sums), plus half a pixel for `room`'s own rounding (the `+ 1` in the slack).
  */
 export function planColumnFold(input: {
   room: number
   toggleWidth: number
   overhead: number
+  /** How many columns `overhead` sums, for the rounding slack. */
+  fixedCount?: number
   order: readonly string[]
   widths: ReadonlyMap<string, number>
 }): ReadonlySet<string> {
-  const { room, toggleWidth, overhead, order, widths } = input
+  const { room, toggleWidth, overhead, fixedCount = 0, order, widths } = input
   const known = order.filter((id) => widths.has(id))
+  const roundingSlack = (known.length + fixedCount + 1) / 2
   let unfolded = overhead + known.reduce((sum, id) => sum + (widths.get(id) ?? 0), 0)
   const folded = new Set<string>()
   for (const id of known) {
@@ -1007,7 +1018,7 @@ export function planColumnFold(input: {
     // doc pins as the FIRST declared column (the last-declared one folds first).
     if (folded.size >= known.length - 1) break
     const withToggle = unfolded + (folded.size > 0 ? toggleWidth : 0)
-    if (withToggle <= room) break
+    if (withToggle <= room + roundingSlack) break
     folded.add(id)
     unfolded -= widths.get(id) ?? 0
   }
@@ -1039,14 +1050,12 @@ function useColumnFold(input: {
   const wrapperRef = useRef<HTMLDivElement>(null)
   const [folded, setFolded] = useState<ReadonlySet<string>>(EMPTY_FOLD_SET)
   const orderRef = useRef(order)
-  orderRef.current = order
   const fixedIdsRef = useRef(fixedIds)
-  fixedIdsRef.current = fixedIds
   useLayoutEffect(() => {
-    if (!active || order.length === 0) {
-      setFolded((current) => (current.size === 0 ? current : EMPTY_FOLD_SET))
-    }
-  }, [active, order.length])
+    orderRef.current = order
+    fixedIdsRef.current = fixedIds
+  })
+  if ((!active || order.length === 0) && folded.size > 0) setFolded(EMPTY_FOLD_SET)
 
   useMeasuredWidths({
     resolveRoot: () => wrapperRef.current,
@@ -1074,6 +1083,7 @@ function useColumnFold(input: {
         // reads as one more `--vx-hit` control rather than a narrower afterthought.
         toggleWidth: HIT_COARSE,
         overhead,
+        fixedCount: fixedIdsRef.current.length,
         order: orderRef.current,
         widths,
       })
@@ -1089,7 +1099,7 @@ function useColumnFold(input: {
 /** The label half of a folded column's disclosure row — its own header when it is a plain string
  * (the common case), else the column id, since a function/`ReactNode` header has no header
  * CONTEXT to render with here (this is a body row, not the `<thead>`). */
-function columnLabel<T>(column: Column<T, unknown>): string {
+function columnLabel<T extends RowData>(column: Column<BasaltTableFeatures, T, unknown>): string {
   const header = column.columnDef.header
   return typeof header === 'string' ? header : column.id
 }
@@ -1097,11 +1107,11 @@ function columnLabel<T>(column: Column<T, unknown>): string {
 /** One row's folded columns as label/value pairs, directly under it. `row.getAllCells()` returns
  * every leaf cell regardless of visibility (unlike `getVisibleCells()`), so a folded column's own
  * `cell` renderer still draws here exactly as it would in the `<td>` it no longer occupies. */
-function RowDisclosure<T>({
+function RowDisclosure<T extends RowData>({
   row,
   folded,
 }: {
-  row: Row<T>
+  row: Row<BasaltTableFeatures, T>
   folded: ReadonlySet<string>
 }): ReactNode {
   const cells = row.getAllCells().filter((cell) => folded.has(cell.column.id))
@@ -1111,7 +1121,7 @@ function RowDisclosure<T>({
         <div key={cell.id} className={classes.foldDisclosureRow}>
           <Text className={classes.foldDisclosureLabel}>{columnLabel(cell.column)}</Text>
           <div className={classes.foldDisclosureValue}>
-            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+            <FlexRender cell={cell} />
           </div>
         </div>
       ))}
@@ -1314,9 +1324,9 @@ function useMeasuredContainment(active: boolean): {
  *   emptyState={<Text c="dimmed">No users found.</Text>}
  * />
  */
-export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
-  // F-ERR-1: without this, a table missing `data`/`columns` fails deep inside `useReactTable` as a
-  // raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no message naming either
+export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T>) {
+  // F-ERR-1: without this, a table missing `data`/`columns` fails deep inside `useTable` as a
+  // raw `TypeError` caught by `RootBoundary` — a blank subtree with no message naming either
   // prop.
   assertRequiredProps('BasaltDataTable', props, ['data', 'columns'])
   const {
@@ -1364,6 +1374,15 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   } = props
   const tableState = useDataTableState(props, pageSizeOptions[0] ?? 10)
   const { globalFilter, columnPinning, onGlobalFilterChange: handleGlobalFilterChange } = tableState
+  // The input binds to a local draft so typing stays instant; the table (and `onGlobalFilterChange`)
+  // only see the value once typing pauses. Invariant: the debounced commit is the ONLY writer of
+  // `globalFilter`, so the draft never needs syncing back from it. `flushOnUnmount` delivers a
+  // pending keystroke to `onGlobalFilterChange` rather than dropping it with the table.
+  const [searchDraft, setSearchDraft] = useState(globalFilter)
+  const commitSearch = useDebouncedCallback(handleGlobalFilterChange, {
+    delay: SEARCH_DEBOUNCE_MS,
+    flushOnUnmount: true,
+  })
 
   // `stickyHeaderOffset` is DROPPED whenever the table owns a scroll container — see
   // `resolvedStickyHeaderOffset` below for why it is always wrong there. Dropping it silently is
@@ -1416,20 +1435,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       const id = columnDefId(column)
       const facet = id === undefined ? undefined : facetById.get(id)
       if (!facet) return column
-      const filterFn: FilterFn<T> = facet.multiple
-        ? (row, columnId, filterValue: string[]) =>
-            !Array.isArray(filterValue) || filterValue.length === 0
-              ? true
-              : filterValue.includes(String(row.getValue(columnId)))
-        : (row, columnId, filterValue: string) =>
-            filterValue === null || filterValue === undefined || filterValue === ''
-              ? true
-              : String(row.getValue(columnId)) === filterValue
-      filterFn.autoRemove = (value) =>
-        value === null ||
-        value === undefined ||
-        value === '' ||
-        (Array.isArray(value) && value.length === 0)
+      const filterFn: FilterFn<BasaltTableFeatures, T> = facet.multiple ? facetAnyOf : facetExact
       return { ...column, filterFn }
     })
   }, [columns, facets])
@@ -1483,7 +1489,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   // column are excluded outright, not merely de-prioritized — both are the caller stating this
   // column must stay visible, the same declaration a fold candidate has no way to override.
   const { columnFoldOrder, columnFoldFixedIds } = useMemo(() => {
-    const pinnedIds = new Set([...(columnPinning.left ?? []), ...(columnPinning.right ?? [])])
+    const pinnedIds = new Set([...columnPinning.start, ...columnPinning.end])
     const excluded = new Set(
       columns.flatMap((column) => {
         const id = columnDefId(column)
@@ -1498,20 +1504,23 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   }, [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 && !projection.cards,
+  const { cards: showCards, rootRef: projectionRootRef } = useCardProjection(
+    renderCard !== undefined,
+  )
+  const { folded: foldedColumns, wrapperRef: foldWrapperRef } = useColumnFold({
+    active: foldEligible && !showCards,
     order: columnFoldOrder,
     fixedIds: columnFoldFixedIds,
   })
-  const columnVisibility: VisibilityState = useMemo(
-    () => Object.fromEntries([...columnFold.folded].map((id) => [id, false])),
-    [columnFold.folded],
+  const columnVisibility: ColumnVisibilityState = useMemo(
+    () => Object.fromEntries([...foldedColumns].map((id) => [id, false])),
+    [foldedColumns],
   )
-  const hasFolded = columnFold.folded.size > 0
+  const hasFolded = foldedColumns.size > 0
   const foldRows = useRowDisclosure({ data, getRowId })
 
-  const table = useReactTable<T>({
+  const table = useTable({
+    features: basaltTableFeatures,
     data,
     columns: tableColumns,
     state: {
@@ -1533,19 +1542,16 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       onRowSelectionChange: tableState.onRowSelectionChange,
     }),
     ...(getRowId !== undefined && { getRowId }),
-    getCoreRowModel: getCoreRowModel(),
-    getSortedRowModel: getSortedRowModel(),
-    getFilteredRowModel: getFilteredRowModel(),
-    // Both row models stay installed and are BYPASSED by these flags, which is TanStack's own
-    // seam — so a degraded table renders `data` in the order and completeness the server sent it.
-    // Forced only by a BREACH, never by `enableSorting={false}` on its own: that pair still applies
-    // an `initialSorting` today (it disables the header control, not the row model) and a table
-    // that is not misreporting has no business losing it.
+    // Every row model is registered on the feature set (v9 has no per-render switch) and BYPASSED by
+    // these flags, which is TanStack's own seam — so a degraded table renders `data` in the order
+    // and completeness the server sent it. Sorting/filtering are forced only by a BREACH, never by
+    // `enableSorting={false}` on its own: that pair still applies an `initialSorting` today (it
+    // disables the header control, not the row model) and a table that is not misreporting has no
+    // business losing it. Pagination is bypassed whenever it is not enabled, or is server-driven.
     manualSorting: manualSorting || breaches.includes('sorting'),
     manualFiltering: manualFiltering || breaches.includes('filtering'),
+    manualPagination: !enablePagination || manualPagination,
     ...(enablePagination && {
-      getPaginationRowModel: getPaginationRowModel(),
-      manualPagination,
       ...(manualPagination && rowCount !== undefined && { rowCount }),
       ...(manualPagination && pageCount !== undefined && { pageCount }),
     }),
@@ -1569,7 +1575,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
   // the prepended checkbox column, one more again for the fold-disclosure toggle once anything has
   // folded — a stale count left the empty state and the error row short of the header.
   const columnCount =
-    columns.length + (enableRowSelection ? 1 : 0) + (hasFolded ? 1 : 0) - columnFold.folded.size
+    columns.length + (enableRowSelection ? 1 : 0) + (hasFolded ? 1 : 0) - foldedColumns.size
 
   // `getSelectedRowModel()` is TanStack's own memo, so its `rows` array keeps its identity until
   // the selection or the row model actually moves — which is what makes both memos below hold.
@@ -1611,7 +1617,9 @@ 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 && !projection.cards)
+  const { wrapperRef: containmentRef, contained } = useMeasuredContainment(
+    pageStickyHeader && !showCards,
+  )
   const resolvedStickyHeaderOffset = scrolls ? undefined : stickyHeaderOffset
 
   // The error branch the table did not have (components audit #3) carries the query's OWN `refetch`
@@ -1686,9 +1694,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                     ...pinnedStyle,
                   }}
                 >
-                  {header.isPlaceholder
-                    ? null
-                    : flexRender(header.column.columnDef.header, header.getContext())}
+                  {header.isPlaceholder ? null : <FlexRender header={header} />}
                   {canSort && <SortIndicator direction={sorted} />}
                 </Table.Th>
               )
@@ -1719,9 +1725,9 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
           rows.map((row) => {
             const cells = enablePinning
               ? [
-                  ...row.getLeftVisibleCells(),
+                  ...row.getStartVisibleCells(),
                   ...row.getCenterVisibleCells(),
-                  ...row.getRightVisibleCells(),
+                  ...row.getEndVisibleCells(),
                 ]
               : row.getVisibleCells()
             const rowExpanded = hasFolded && foldRows.expanded.has(row.id)
@@ -1765,7 +1771,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                           ...pinnedStyle,
                         }}
                       >
-                        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                        <FlexRender cell={cell} />
                       </Table.Td>
                     )
                   })}
@@ -1773,7 +1779,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                 {rowExpanded && (
                   <Table.Tr id={`${row.id}-fold`} className={classes.foldDisclosureRowTr}>
                     <Table.Td colSpan={columnCount} className={classes.foldDisclosureCell}>
-                      <RowDisclosure row={row} folded={columnFold.folded} />
+                      <RowDisclosure row={row} folded={foldedColumns} />
                     </Table.Td>
                   </Table.Tr>
                 )}
@@ -1804,7 +1810,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
     </Stack>
   )
 
-  const paginationState = table.getState().pagination
+  const paginationState = table.state.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
   // `initialPagination.pageSize: 5` against the default `[10, 25, 50, 100]` showed a blank
@@ -1818,7 +1824,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
 
   return (
     <div
-      ref={projection.rootRef}
+      ref={projectionRootRef}
       className={cx(classNames?.root, className)}
       {...(style !== undefined && { style })}
     >
@@ -1861,8 +1867,11 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
                     style={TABLE_SEARCH_STYLE}
                     placeholder={globalFilterPlaceholder}
                     leftSection={searchIcon}
-                    value={globalFilter}
-                    onChange={(event) => handleGlobalFilterChange(event.currentTarget.value)}
+                    value={searchDraft}
+                    onChange={(event) => {
+                      setSearchDraft(event.currentTarget.value)
+                      commitSearch(event.currentTarget.value)
+                    }}
                   />
                 )}
                 {showFacets && (
@@ -1895,7 +1904,7 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
       {bulkBarActions !== undefined && (
         <BulkActionBar count={selectedRows.length} actions={bulkBarActions} />
       )}
-      {projection.cards ? (
+      {showCards ? (
         maxHeight === undefined ? (
           renderCardList()
         ) : (
@@ -1915,16 +1924,16 @@ export function BasaltDataTable<T>(props: BasaltDataTableProps<T>) {
         // `maxHeight`-only included: a vertical cap is orthogonal to column width, so a
         // `stickyHeader` + `maxHeight` table (the pairing this package's own docs recommend) still
         // folds instead of silently regressing to horizontal scroll. A plain block box, so it
-        // constrains nothing on its own; `columnFold.wrapperRef` only reads it.
-        <div ref={columnFold.wrapperRef} className={classes.foldWrapper}>
+        // constrains nothing on its own; `foldWrapperRef` only reads it.
+        <div ref={foldWrapperRef} className={classes.foldWrapper}>
           {pageStickyHeader ? (
             // Pinning takes this wrapper too — a pinned column's offsets are `position: sticky` on
             // the cells and need no overflow box of their own, so the `overflow-x: auto` Box that
             // used to sit here was the exact inert-sticky defect this shape exists to avoid.
             <div
-              ref={containment.wrapperRef}
+              ref={containmentRef}
               className={classes.containment}
-              data-contained={containment.contained ? 'true' : 'false'}
+              data-contained={contained ? 'true' : 'false'}
             >
               {tableNode}
             </div>