basalt-ui 1.24.0 → 1.26.0

package/src/data/data-table.tsx

@@ -21,27 +21,18 @@
  * <BasaltDataTable data={rows} columns={columns} />
  *
  * @example
- * // With the toolbar + pagination bar:
+ * // With the title, the toolbar + pagination bar:
  * <BasaltDataTable
+ *   title="Top pages"
  *   data={rows}
  *   columns={columns}
  *   enableGlobalFilter
  *   facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
- *   toolbarActions={<Button size="xs">Export</Button>}
+ *   actions={<Button>Export</Button>}
  *   enablePagination
  * />
  */
-import {
-  Box,
-  Group,
-  MultiSelect,
-  Pagination,
-  Select,
-  Skeleton,
-  Table,
-  Text,
-  TextInput,
-} from '@mantine/core'
+import { Box, Group, Pagination, Select, Skeleton, Table, Text, TextInput } from '@mantine/core'
 import type { MantineSpacing } from '@mantine/core'
 import type {
   Column,
@@ -65,7 +56,17 @@ import {
 } from '@tanstack/react-table'
 import type { CSSProperties, ReactNode } from 'react'
 import { useCallback, useMemo, useState } from 'react'
+import { FilterSet } from '../controls'
+// `EnumFilter` is deliberately NOT on the `./controls` barrel (`docs/CONTROLS-SPEC.md` §3 —
+// reaching for it directly is hand-rolling a filter, `basalt/hand-rolled-filter`); a facet column
+// is the one place inside the framework itself that legitimately builds a `FieldHandle` over
+// something that is not a store field, so it reaches past the barrel on purpose.
+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 { WidgetHeader } from '../widget-header'
 
 // ── Column alignment ──────────────────────────────────────────────────────────
 
@@ -113,17 +114,17 @@ function resolveAlign<T>(column: Column<T, unknown>): DataTableAlign | undefined
 
 // ── Facets ────────────────────────────────────────────────────────────────────
 
-/** A single selectable option inside a {@link DataTableFacet}'s Select/MultiSelect. */
+/** A single selectable option inside a {@link DataTableFacet}'s `EnumFilter`/`MultiSelectFilter` pill. */
 export type DataTableFacetOption = {
   /** The raw filter value, compared against the column's stringified cell value. */
   value: string
-  /** Label shown in the Select/MultiSelect dropdown. */
+  /** Label shown in the pill's popover. */
   label: string
 }
 
 /**
- * Declares one faceted column filter, rendered as a Mantine Select (or MultiSelect when
- * `multiple` is set) inside the toolbar.
+ * Declares one faceted column filter, rendered as an `EnumFilter` pill (or `MultiSelectFilter`
+ * when `multiple` is set) inside a `FilterSet` in the toolbar (`docs/CONTROLS-SPEC.md` §3).
  *
  * @example
  * const facets: DataTableFacet[] = [
@@ -135,14 +136,89 @@ export type DataTableFacetOption = {
 export type DataTableFacet = {
   /** The TanStack column id — the column's manual `id`, or its `accessorKey` string. */
   columnId: string
-  /** Label shown as the Select/MultiSelect placeholder. */
+  /** The pill's label — read at rest (single-select) and as the `Filters`/count fallback (multi). */
   label: string
   /** Selectable options for this facet. */
   options: DataTableFacetOption[]
-  /** Render a MultiSelect (any-of match) instead of a single Select (exact match). @default false */
+  /** Render a `MultiSelectFilter` (any-of match) instead of an `EnumFilter` (exact match). @default false */
   multiple?: boolean
 }
 
+/**
+ * The "no filter" member of a single-select facet's `FieldHandle`. A closed enum field always has
+ * a real member as its fallback (C4) — there is no "unset" — so a facet, whose underlying
+ * `column.getFilterValue()` genuinely can be `undefined`, needs one synthetic option to stand for
+ * that state. Rendered as the enum's first radio; picking it clears the column filter, same as every
+ * other value change.
+ *
+ * Its label is `Any <facet>`, and it used to be a bare `All`. The pill now reads the SELECTED
+ * option's label at every value including the fallback (`controls/enum-filter.tsx` — a bar reading
+ * `Compare` over a field holding `'previous'` is the bug that law fixes), and a toolbar with three
+ * facets would then have read `All` three times. `Any project` is the one label that works in both
+ * places at once: it is a legible popover row for "no constraint", and a legible pill readout of the
+ * state the filter is actually in. Derived from `facet.label`, so no facet has to declare it.
+ */
+const FACET_ALL_VALUE = '__basalt_facet_all__'
+
+/** The synthetic row's label — see {@link FACET_ALL_VALUE}. */
+function facetAllLabel(facet: DataTableFacet): string {
+  return `Any ${facet.label.toLowerCase()}`
+}
+
+/**
+ * Presents a single-select facet column as a `FieldHandle<EnumField<string>>` so it can render
+ * through the shared `EnumFilter` pill instead of a hand-rolled `Select` (`basalt/hand-rolled-filter`).
+ * `use()` reads/writes `column.getFilterValue()`/`setFilterValue()` directly — no internal
+ * 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>,
+  facet: DataTableFacet,
+): FieldHandle<EnumField<string>> {
+  return {
+    kind: 'enum',
+    fallback: FACET_ALL_VALUE,
+    options: [{ value: FACET_ALL_VALUE, label: facetAllLabel(facet) }, ...facet.options],
+    use: () => {
+      const current = (column.getFilterValue() as string | undefined) ?? FACET_ALL_VALUE
+      return [
+        current,
+        (next: string) => {
+          column.setFilterValue(next === FACET_ALL_VALUE ? undefined : next)
+        },
+      ] as const
+    },
+    isDefault: (value) => value === FACET_ALL_VALUE,
+  }
+}
+
+/**
+ * Presents a multi-select facet column as a `FieldHandle<MultiField<string>>`. Unlike the
+ * 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>,
+  facet: DataTableFacet,
+): FieldHandle<MultiField<string>> {
+  return {
+    kind: 'multi',
+    fallback: [],
+    options: facet.options,
+    use: () => {
+      const current = (column.getFilterValue() as readonly string[] | undefined) ?? []
+      return [
+        current,
+        (next: readonly string[]) => {
+          column.setFilterValue(next.length > 0 ? [...next] : undefined)
+        },
+      ] as const
+    },
+    isDefault: (value) => value.length === 0,
+  }
+}
+
 // ── Props ─────────────────────────────────────────────────────────────────────
 
 /**
@@ -159,6 +235,19 @@ export type DataTableFacet = {
  * }
  */
 export type BasaltDataTableProps<T> = {
+  // ── 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.
+   */
+  title?: string
+  /** Optional leading icon, forwarded to `WidgetHeader`. */
+  icon?: ReactNode
+  /** Optional muted line rendered below the title row. */
+  subtitle?: string
+
   /** Row data array. */
   data: T[]
   /**
@@ -171,15 +260,43 @@ export type BasaltDataTableProps<T> = {
   // oxlint-disable-next-line typescript/no-explicit-any -- TanStack-idiomatic heterogeneous column array
   columns: ColumnDef<T, any>[]
   /**
-   * Enable column sorting via clickable headers.
+   * Enable column sorting via clickable headers. Client-side — the rows in `data` are what get
+   * reordered.
+   *
+   * Under `manualPagination` that is one page, so leaving this on without also passing
+   * `manualSorting` is a contract violation and throws in dev — see `manualPagination`.
    * @default true
    */
   enableSorting?: boolean
+  /**
+   * Hand sorting to the server: the table stops reordering `data` locally and renders it in the
+   * order given, while the headers keep toggling `SortingState` and reporting it through
+   * `onSortingChange` — which is where you re-request the sorted page.
+   *
+   * This is the required companion to `manualPagination` whenever sort headers are live; without
+   * it a server-paginated table sorts one page and the "of N" bar presents that as a sort of all N.
+   * @default false
+   * @example
+   * <BasaltDataTable
+   *   data={page.rows}
+   *   columns={columns}
+   *   enablePagination
+   *   manualPagination
+   *   manualSorting
+   *   rowCount={page.total}
+   *   onSortingChange={(s) => refetch({ sort: s[0] })}
+   * />
+   */
+  manualSorting?: boolean
   /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
   striped?: boolean | 'odd' | 'even'
   /** Highlight hovered rows. Forwarded to Mantine `Table`. */
   highlightOnHover?: boolean
-  /** Rendered when `data` is empty. Falls back to a simple message when omitted. */
+  /**
+   * Rendered when no rows are VISIBLE — `data` is empty, or a filter/page matches none of it.
+   * Falls back to a simple message when omitted. (Before 1.25.0 this tracked `data.length` alone,
+   * so a search matching nothing rendered a blank `<tbody>` with no message at all.)
+   */
   emptyState?: ReactNode
   /**
    * When true, renders skeleton placeholder rows instead of the empty-state branch.
@@ -234,18 +351,31 @@ export type BasaltDataTableProps<T> = {
   /** Called whenever the internal global filter value changes. */
   onGlobalFilterChange?: (value: string) => void
   /**
-   * Faceted column filters, rendered in the toolbar as Mantine Select/MultiSelect controls wired
-   * to TanStack's per-column `columnFilters` state. The toolbar renders whenever this array is
-   * non-empty, `enableGlobalFilter` is set, or `toolbarActions` is passed.
+   * Faceted column filters, rendered in the toolbar as `EnumFilter`/`MultiSelectFilter` pills
+   * inside a `FilterSet`, wired to TanStack's per-column `columnFilters` state. The toolbar
+   * renders whenever this array is non-empty, `enableGlobalFilter` is set, or `actions` is passed.
    * @example
    * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
    */
   facets?: DataTableFacet[]
+  /** Called whenever the faceted column filters change — the seam for server-side faceting. */
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void
+  /**
+   * Hand filtering to the server: the table stops narrowing `data` locally and renders every row
+   * given, while the search input and facets keep reporting through `onGlobalFilterChange` /
+   * `onColumnFiltersChange` — which is where you re-request the filtered page.
+   *
+   * Required alongside `manualPagination` whenever `enableGlobalFilter` or `facets` is set;
+   * without it the controls narrow one page while "of N" keeps counting the whole set.
+   * @default false
+   */
+  manualFiltering?: boolean
   /**
    * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
-   * search input or facets are configured.
+   * search input or facets are configured. Renamed from `toolbarActions` — the toolbar (search +
+   * facets + this slot) is wrapped in `CtlSlot` (C1/C5), so its controls resolve to the `ctl` tier.
    */
-  toolbarActions?: ReactNode
+  actions?: ReactNode
 
   // ── Pagination ────────────────────────────────────────────────────────────────
 
@@ -272,6 +402,21 @@ export type BasaltDataTableProps<T> = {
    * Disables local pagination slicing — pass the already-paginated page of `data` plus `rowCount`
    * (and optionally `pageCount`) for server-driven pagination. `onPaginationChange` is where you
    * fetch the next page.
+   *
+   * **It imposes a contract, enforced at render.** `data` is now one page, but the pagination bar
+   * says "Showing 1–25 of 412" — so every OTHER client-side control becomes a claim about 412 rows
+   * that it can only make about 25. Each has to be resolved explicitly, because only the call site
+   * knows whether the server does the work:
+   *
+   * - `rowCount` (or `pageCount`) must be given, or "of N" counts the page and the pager collapses
+   *   to a single page nobody can leave;
+   * - sorting must be handed over with `manualSorting`, or switched off with `enableSorting={false}`;
+   * - `enableGlobalFilter` / `facets`, if used, must be handed over with `manualFiltering`;
+   * - `enablePagination` must be on, or `manualPagination` is inert and the page renders as if it
+   *   were the whole table.
+   *
+   * Unresolved, each throws in dev and degrades to the honest render in production (no sort
+   * headers, no filter controls, no "of N") — never to the plausible wrong answer.
    * @default false
    * @example
    * <BasaltDataTable
@@ -334,9 +479,20 @@ export type BasaltDataTableProps<T> = {
   /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
   withRowBorders?: boolean
   /**
-   * Outer table border. Turn it OFF for a table that already sits inside a `Card`/`ChartCard`,
-   * where the card owns the frame and a second one reads as a nested box.
-   * @default true
+   * Outer table border — a full box around the table.
+   *
+   * **`false` by default since this minor** (it was `true`). Three separate faults, all visible on
+   * the playground's `Controls (mobile)` page at 390px: its TOP edge sat directly under the table's
+   * own `WidgetHeader`, separating a header from its own content; its BOTTOM edge landed on the last
+   * row's own hairline, two rules at zero distance; and its left/right edges carried no information
+   * at all on a table that fills the page (`docs/DESIGN-SPEC.md` §8 — a border is a layout divider,
+   * and there is nothing here to divide). The head-row rule and the between-row rules stay, so the
+   * table still reads as a table.
+   *
+   * Pass `true` for a table that genuinely needs a frame — a small table floating in whitespace
+   * beside other content, where the box IS the grouping.
+   *
+   * @default false
    */
   withTableBorder?: boolean
 }
@@ -373,6 +529,23 @@ const RANGE_LABEL_STYLE: CSSProperties = {
 
 const DEFAULT_PAGE_SIZE_OPTIONS = [10, 25, 50, 100]
 
+/**
+ * The header row's two halves. The lead SHRINKS and the toolbar does not — a title can ellipsize, a
+ * 220px search field with a facet pill beside it cannot, and when both were shrinkable flex split
+ * the overflow between them and clipped the search's placeholder mid-word.
+ */
+const TABLE_HEADER_LEAD_STYLE: CSSProperties = { flex: '1 1 auto', minWidth: 0 }
+const TABLE_TOOLBAR_STYLE: CSSProperties = { flex: '0 0 auto' }
+/**
+ * The toolbar search's width. Mantine's Input grows to its container, which in a `justify:
+ * space-between` row means "whatever is left" — so the field was 600px on a wide table and 180px on a
+ * narrow one, for the same one-word query. A stated width also makes the toolbar's own minimum width
+ * knowable, which is what lets it wrap under the title below `sm` with no media query.
+ */
+const SEARCH_WIDTH = 220
+/** The rows-per-page Select's width — see `SEARCH_WIDTH` for why a toolbar field states one. */
+const PAGE_SIZE_WIDTH = 116
+
 // ── Column pinning helpers ────────────────────────────────────────────────────
 
 // Merges the left/center/right header-group triad TanStack exposes for pinning into the single
@@ -423,14 +596,110 @@ function getPinnedCellStyle<T>(
   }
 }
 
+// ── The manual-pagination contract ────────────────────────────────────────────
+
+/** The house dev gate (`src/provider`, `src/charts/kinds/BandStrip` use the same expression):
+ * `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle constant-folds this to
+ * `false` and drops the throw. Read per call, never hoisted, so a test can flip it. */
+function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}
+
+/** One client-side control that `manualPagination` turns into a claim the table cannot support. */
+type ManualPaginationBreach = 'inert' | 'total' | 'sorting' | 'filtering'
+
+const BREACH_REMEDY: Record<ManualPaginationBreach, string> = {
+  inert:
+    '`enablePagination` is not set, so `manualPagination` never reaches the table and the server ' +
+    'page renders as if it were the whole set, with no bar to say otherwise. Pass ' +
+    '`enablePagination`, or drop `manualPagination`.',
+  total:
+    'neither `rowCount` nor `pageCount` was given, so "of N" counts only the rows on this page and ' +
+    'the pager collapses to one page nobody can leave. Pass `rowCount={total}`.',
+  sorting:
+    'client-side sorting is still armed. It reorders only the rows in `data` — one page — while the ' +
+    'header chevron and "of N" together present it as a sort of all of them. Pass `manualSorting` ' +
+    'and sort in the request you make from `onSortingChange`, or `enableSorting={false}`.',
+  filtering:
+    'the search input / facets still filter client-side. They narrow only the rows in `data` — one ' +
+    'page — while "of N" keeps counting the whole set. Pass `manualFiltering` and filter in the ' +
+    'request you make from `onGlobalFilterChange` / `onColumnFiltersChange`, or drop ' +
+    '`enableGlobalFilter` / `facets`.',
+}
+
+/**
+ * Every way the props on hand contradict `manualPagination`. Computed from PROPS only — never from
+ * the table instance, whose `getCanSort()` would read back the very `enableSorting` this decides.
+ */
+function manualPaginationBreaches(config: {
+  columns: readonly { enableSorting?: boolean }[]
+  enablePagination: boolean
+  manualPagination: boolean
+  rowCount: number | undefined
+  pageCount: number | undefined
+  enableSorting: boolean
+  manualSorting: boolean
+  enableGlobalFilter: boolean
+  hasFacets: boolean
+  manualFiltering: boolean
+}): ManualPaginationBreach[] {
+  if (!config.manualPagination) return []
+  if (!config.enablePagination) return ['inert']
+  const breaches: ManualPaginationBreach[] = []
+  if (config.rowCount === undefined && config.pageCount === undefined) breaches.push('total')
+  const anyColumnMaySort = config.columns.some((column) => column.enableSorting !== false)
+  if (config.enableSorting && anyColumnMaySort && !config.manualSorting) breaches.push('sorting')
+  if ((config.enableGlobalFilter || config.hasFacets) && !config.manualFiltering)
+    breaches.push('filtering')
+  return breaches
+}
+
+function manualPaginationMessage(breaches: ManualPaginationBreach[]): string {
+  return (
+    'BasaltDataTable: `manualPagination` is set, so `data` is one server page — but:\n  · ' +
+    breaches.map((breach) => BREACH_REMEDY[breach]).join('\n  · ') +
+    '\nEach has to be resolved explicitly: only the call site knows whether the server does the ' +
+    'work, so there is no default that is not a guess about the data.'
+  )
+}
+
+/** Bounded by the sixteen possible breach sets, so it cannot grow with render count. */
+const reportedBreaches = new Set<string>()
+
+/**
+ * Dev throws; production reports once and lets the caller degrade.
+ *
+ * Split deliberately from BandStrip's datum/prop rule rather than copied. That rule throws on a bad
+ * PROP because a prop is authored, deterministic, and caught the first time the component renders —
+ * all true here. What differs is that a bad `meta.align` has no honest render (every alignment we
+ * could pick might be the wrong one, and would look right in review), whereas this one does: a
+ * table with no sort headers, no filter controls and no "of N" asserts nothing false. Throwing in
+ * production would add no correctness the degradation does not already give, and would convert a
+ * misreport on a rarely-visited page into a blank one. The report is what keeps the degradation
+ * from being its own silence.
+ */
+function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): void {
+  if (breaches.length === 0) return
+  const message = manualPaginationMessage(breaches)
+  if (isDev()) throw new Error(message)
+  if (reportedBreaches.has(message)) return
+  reportedBreaches.add(message)
+  console.error(message)
+}
+
 // ── Component ─────────────────────────────────────────────────────────────────
 
 /**
  * A sortable data table backed by TanStack Table and rendered with Mantine primitives.
  * Generic over `T` — column types are inferred from `ColumnDef<T>`.
  *
- * Sorting is local/client-side (no `any`). When `enableSorting` is `false` the table
- * is read-only. An `emptyState` node is rendered when `data` is empty.
+ * Sorting is local/client-side by default (no `any`); `manualSorting` hands it to the server.
+ * When `enableSorting` is `false` the table is read-only. An `emptyState` node is rendered
+ * whenever no rows are visible — empty `data`, or a filter that matches none of it.
+ *
+ * `manualPagination` imposes a contract on the rest of the props (see its docblock): every
+ * client-side control it would turn into a false claim about the unseen rows must be handed to the
+ * server or switched off, and an unresolved one throws in dev rather than misreporting.
  *
  * Toolbar (search + facets), pagination, and column pinning are opt-in chrome layered on top —
  * see the corresponding props below. None of them change rendering unless explicitly enabled.
@@ -446,9 +715,13 @@ function getPinnedCellStyle<T>(
  * />
  */
 export function BasaltDataTable<T>({
+  title,
+  icon,
+  subtitle,
   data,
   columns,
   enableSorting = true,
+  manualSorting = false,
   striped,
   highlightOnHover,
   emptyState,
@@ -462,7 +735,9 @@ export function BasaltDataTable<T>({
   initialGlobalFilter,
   onGlobalFilterChange,
   facets,
-  toolbarActions,
+  onColumnFiltersChange,
+  manualFiltering = false,
+  actions,
   enablePagination = false,
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
   initialPagination,
@@ -479,7 +754,7 @@ export function BasaltDataTable<T>({
   verticalSpacing,
   horizontalSpacing,
   withRowBorders,
-  withTableBorder = true,
+  withTableBorder = false,
 }: BasaltDataTableProps<T>) {
   const [sorting, setSorting] = useState<SortingState>(initialSorting ?? [])
   const [globalFilter, setGlobalFilter] = useState(initialGlobalFilter ?? '')
@@ -511,6 +786,17 @@ export function BasaltDataTable<T>({
     [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) => {
@@ -550,6 +836,27 @@ export function BasaltDataTable<T>({
     })
   }, [columns, facets])
 
+  // Enforced before the table is built, so the degraded options below are the ones TanStack gets —
+  // a degraded table must not merely hide a control, it must not compute the answer either.
+  const hasFacets = Boolean(facets && facets.length > 0)
+  const breaches = manualPaginationBreaches({
+    columns,
+    enablePagination,
+    manualPagination,
+    rowCount,
+    pageCount,
+    enableSorting,
+    manualSorting,
+    enableGlobalFilter,
+    hasFacets,
+    manualFiltering,
+  })
+  enforceManualPaginationContract(breaches)
+  // Unreachable in dev (the line above threw); in production these are the honest fallbacks.
+  const sortingEnabled = enableSorting && !breaches.includes('sorting')
+  const filteringEnabled = !breaches.includes('filtering')
+  const totalIsAuthoritative = !breaches.includes('total')
+
   const table = useReactTable<T>({
     data,
     columns: tableColumns,
@@ -562,25 +869,36 @@ export function BasaltDataTable<T>({
     },
     onSortingChange: handleSortingChange,
     onGlobalFilterChange: handleGlobalFilterChange,
-    onColumnFiltersChange: setColumnFilters,
+    onColumnFiltersChange: handleColumnFiltersChange,
     onColumnPinningChange: setColumnPinning,
     ...(enablePagination && { onPaginationChange: handlePaginationChange }),
     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.
+    manualSorting: manualSorting || breaches.includes('sorting'),
+    manualFiltering: manualFiltering || breaches.includes('filtering'),
     ...(enablePagination && {
       getPaginationRowModel: getPaginationRowModel(),
       manualPagination,
       ...(manualPagination && rowCount !== undefined && { rowCount }),
       ...(manualPagination && pageCount !== undefined && { pageCount }),
     }),
-    enableSorting,
+    enableSorting: sortingEnabled,
     enableColumnPinning: enablePinning,
   })
 
-  const showToolbar =
-    enableGlobalFilter || Boolean(facets && facets.length > 0) || Boolean(toolbarActions)
+  const showSearch = enableGlobalFilter && filteringEnabled
+  const showFacets = hasFacets && filteringEnabled
+  const showToolbar = showSearch || showFacets || Boolean(actions)
   const headerGroups = enablePinning ? getOrderedHeaderGroups(table) : table.getHeaderGroups()
+  // The rows actually rendered, not `data` — a filter or a page index that matches nothing leaves
+  // `data` non-empty while the body has nothing in it, and a blank body reads as a broken table.
+  const rows = table.getRowModel().rows
 
   const tableNode = (
     <Table
@@ -597,7 +915,7 @@ export function BasaltDataTable<T>({
         {headerGroups.map((headerGroup) => (
           <Table.Tr key={headerGroup.id}>
             {headerGroup.headers.map((header) => {
-              const canSort = enableSorting && header.column.getCanSort()
+              const canSort = sortingEnabled && header.column.getCanSort()
               const sorted = header.column.getIsSorted()
               const toggleSorting = header.column.getToggleSortingHandler()
               const pinnedStyle = enablePinning
@@ -654,7 +972,7 @@ export function BasaltDataTable<T>({
               ))}
             </Table.Tr>
           ))
-        ) : data.length === 0 ? (
+        ) : rows.length === 0 ? (
           <Table.Tr>
             <Table.Td colSpan={columns.length}>
               {emptyState ?? (
@@ -665,7 +983,7 @@ export function BasaltDataTable<T>({
             </Table.Td>
           </Table.Tr>
         ) : (
-          table.getRowModel().rows.map((row) => {
+          rows.map((row) => {
             const cells = enablePinning
               ? [
                   ...row.getLeftVisibleCells(),
@@ -709,62 +1027,81 @@ export function BasaltDataTable<T>({
   const scrolls = maxHeight !== undefined || minWidth !== undefined
 
   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
+  // `initialPagination.pageSize: 5` against the default `[10, 25, 50, 100]` showed a blank
+  // rows-per-page box — a control stating nothing, next to a range label stating `1–5`.
+  const pageSizeRows = [...new Set([...pageSizeOptions, paginationState.pageSize])]
+    .sort((a, b) => a - b)
+    .map((size) => ({ value: String(size), label: `${size} / page` }))
   const total = table.getRowCount()
   const rangeStart = total === 0 ? 0 : paginationState.pageIndex * paginationState.pageSize + 1
   const rangeEnd = Math.min((paginationState.pageIndex + 1) * paginationState.pageSize, total)
 
   return (
     <>
-      {showToolbar && (
-        <Group justify="space-between" align="flex-end" wrap="wrap" gap="xs" mb="xs">
-          <Group gap="xs" wrap="wrap" align="flex-end">
-            {enableGlobalFilter && (
-              <TextInput
-                size="xs"
-                radius="md"
-                placeholder={globalFilterPlaceholder}
-                leftSection={searchIcon}
-                value={globalFilter}
-                onChange={(event) => handleGlobalFilterChange(event.currentTarget.value)}
-                w={220}
+      {/*
+       * 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
+       * spent title → 11px → search → 11px → thead before a single datum appeared, and the toolbar
+       * read as page furniture rather than as this table's controls.
+       *
+       * `wrap="wrap"` is the below-`sm` behaviour and needs no media query: the toolbar's minimum
+       * width (a 220px search plus its pills) exceeds what is left beside a title on a phone, so flex
+       * wraps it under the title on its own. `align="center"` puts the 30px toolbar controls on the
+       * title's optical line rather than on its baseline.
+       */}
+      {(title !== undefined || showToolbar) && (
+        <Group justify="space-between" align="center" wrap="wrap" gap="xs" mb="xs">
+          {title !== undefined ? (
+            <Box style={TABLE_HEADER_LEAD_STYLE}>
+              <WidgetHeader
+                tier="widget"
+                title={title}
+                {...(icon !== undefined && { icon })}
+                {...(subtitle !== undefined && { subtitle })}
+                count={table.getRowCount()}
               />
-            )}
-            {facets?.map((facet) => {
-              const column = table.getColumn(facet.columnId)
-              if (!column) return null
-              if (facet.multiple) {
-                const value = (column.getFilterValue() as string[] | undefined) ?? []
-                return (
-                  <MultiSelect
-                    key={facet.columnId}
-                    size="xs"
+            </Box>
+          ) : null}
+          {showToolbar && (
+            <CtlSlot>
+              <Group gap="xs" wrap="wrap" align="center" style={TABLE_TOOLBAR_STYLE}>
+                {showSearch && (
+                  <TextInput
                     radius="md"
-                    placeholder={facet.label}
-                    data={facet.options}
-                    value={value}
-                    onChange={(next) => column.setFilterValue(next.length > 0 ? next : undefined)}
-                    clearable
-                    w={200}
+                    w={SEARCH_WIDTH}
+                    placeholder={globalFilterPlaceholder}
+                    leftSection={searchIcon}
+                    value={globalFilter}
+                    onChange={(event) => handleGlobalFilterChange(event.currentTarget.value)}
                   />
-                )
-              }
-              const value = (column.getFilterValue() as string | undefined) ?? null
-              return (
-                <Select
-                  key={facet.columnId}
-                  size="xs"
-                  radius="md"
-                  placeholder={facet.label}
-                  data={facet.options}
-                  value={value}
-                  onChange={(next) => column.setFilterValue(next ?? undefined)}
-                  clearable
-                  w={180}
-                />
-              )
-            })}
-          </Group>
-          {toolbarActions}
+                )}
+                {showFacets && (
+                  <FilterSet>
+                    {facets?.map((facet) => {
+                      const column = table.getColumn(facet.columnId)
+                      if (!column) return null
+                      return facet.multiple ? (
+                        <MultiSelectFilter
+                          key={facet.columnId}
+                          field={facetMultiHandle(column, facet)}
+                          label={facet.label}
+                        />
+                      ) : (
+                        <EnumFilter
+                          key={facet.columnId}
+                          field={facetEnumHandle(column, facet)}
+                          label={facet.label}
+                        />
+                      )
+                    })}
+                  </FilterSet>
+                )}
+                {actions}
+              </Group>
+            </CtlSlot>
+          )}
         </Group>
       )}
       {scrolls ? (
@@ -783,20 +1120,18 @@ export function BasaltDataTable<T>({
       {enablePagination && (
         <Group justify="space-between" mt="xs" wrap="wrap" gap="xs" align="center">
           <Text style={RANGE_LABEL_STYLE}>
-            Showing {rangeStart}–{rangeEnd} of {total}
+            Showing {rangeStart}–{rangeEnd}
+            {totalIsAuthoritative ? ` of ${total}` : ''}
           </Text>
           <Group gap="xs" align="center">
             <Select
-              size="xs"
+              size="ctl"
               radius="md"
-              data={pageSizeOptions.map((size) => ({
-                value: String(size),
-                label: `${size} / page`,
-              }))}
+              w={PAGE_SIZE_WIDTH}
+              data={pageSizeRows}
               value={String(paginationState.pageSize)}
               onChange={(value) => value && table.setPageSize(Number(value))}
               allowDeselect={false}
-              w={110}
             />
             <Pagination
               size="sm"