basalt-ui 1.25.0 → 1.27.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,97 @@ 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
+    },
+    // A facet column has no lane to unset: clearing the column filter IS its fallback state.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
+    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
+    },
+    // Same as the single-select facet: an empty column filter is this handle's fallback.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
+    isDefault: (value) => value.length === 0,
+  }
+}
+
 // ── Props ─────────────────────────────────────────────────────────────────────
 
 /**
@@ -159,6 +243,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[]
   /**
@@ -262,9 +359,9 @@ 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 }]}
    */
@@ -283,9 +380,10 @@ export type BasaltDataTableProps<T> = {
   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 ────────────────────────────────────────────────────────────────
 
@@ -389,9 +487,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
 }
@@ -428,6 +537,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
@@ -597,6 +723,9 @@ function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): vo
  * />
  */
 export function BasaltDataTable<T>({
+  title,
+  icon,
+  subtitle,
   data,
   columns,
   enableSorting = true,
@@ -616,7 +745,7 @@ export function BasaltDataTable<T>({
   facets,
   onColumnFiltersChange,
   manualFiltering = false,
-  toolbarActions,
+  actions,
   enablePagination = false,
   pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
   initialPagination,
@@ -633,7 +762,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 ?? '')
@@ -773,7 +902,7 @@ export function BasaltDataTable<T>({
 
   const showSearch = enableGlobalFilter && filteringEnabled
   const showFacets = hasFacets && filteringEnabled
-  const showToolbar = showSearch || showFacets || Boolean(toolbarActions)
+  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.
@@ -906,63 +1035,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">
-            {showSearch && (
-              <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()}
               />
-            )}
-            {showFacets &&
-              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"
-                      radius="md"
-                      placeholder={facet.label}
-                      data={facet.options}
-                      value={value}
-                      onChange={(next) => column.setFilterValue(next.length > 0 ? next : undefined)}
-                      clearable
-                      w={200}
-                    />
-                  )
-                }
-                const value = (column.getFilterValue() as string | undefined) ?? null
-                return (
-                  <Select
-                    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 ?? undefined)}
-                    clearable
-                    w={180}
+                    w={SEARCH_WIDTH}
+                    placeholder={globalFilterPlaceholder}
+                    leftSection={searchIcon}
+                    value={globalFilter}
+                    onChange={(event) => handleGlobalFilterChange(event.currentTarget.value)}
                   />
-                )
-              })}
-          </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 ? (
@@ -986,16 +1133,13 @@ export function BasaltDataTable<T>({
           </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"