basalt-ui 2.6.1 → 2.7.0

package/src/forms/field.ts

@@ -15,7 +15,56 @@
  * which was the whole reason for the rename in the first place. Write
  * `key={fieldKey(form, path)} {...inputProps(form, path)}`.
  */
-import type { LooseKeys, UseFormReturnType } from '@mantine/form'
+import type { GetInputPropsReturnType, LooseKeys, UseFormReturnType } from '@mantine/form'
+import type { ReactNode } from 'react'
+
+/**
+ * What `inputProps` returns: Mantine's shape with `error` typed (`any` upstream). `error` is always
+ * present — Mantine sets the key on every call, `undefined` on a clean field — so it is `ReactNode`,
+ * not optional. It is the one typed way to read a field error: `form.errors` is an index signature
+ * (dot access is TS4111), and a raw control inside `FormRow` takes
+ * `<FormRow error={inputProps(form, path).error}>`. A Mantine input spread with `inputProps` already
+ * renders it; passing it to `FormRow` as well renders it twice.
+ */
+export type InputProps = Omit<GetInputPropsReturnType, 'error'> & { error: ReactNode }
+
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+
+type AllDigits<S extends string> = S extends `${Digit}${infer Rest}`
+  ? Rest extends ''
+    ? true
+    : AllDigits<Rest>
+  : false
+
+/** A canonical array index: digits only, no sign, no decimal point, no exponent, no leading zero. */
+type IsIndex<S extends string> = S extends '0'
+  ? true
+  : S extends `0${string}`
+    ? false
+    : AllDigits<S>
+
+/** One path segment applied to a value; `never` when the segment does not exist there. */
+type Child<T, K extends string> =
+  NonNullable<T> extends infer N
+    ? N extends readonly (infer V)[]
+      ? IsIndex<K> extends true
+        ? V
+        : never
+      : K extends keyof N
+        ? N[K]
+        : never
+    : never
+
+type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}`
+  ? ValueAt<Child<T, Head>, Rest>
+  : Child<T, P>
+
+/** `Path` if the value at that dot path is a (possibly optional/nullable) boolean, else `never`. */
+type BooleanAt<Values, Path extends string> = [ValueAt<Values, Path>] extends [never]
+  ? never
+  : [NonNullable<ValueAt<Values, Path>>] extends [boolean]
+    ? Path
+    : never
 
 // ── inputProps ────────────────────────────────────────────────────────────────
 
@@ -37,8 +86,34 @@ import type { LooseKeys, UseFormReturnType } from '@mantine/form'
 export function inputProps<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(
   form: UseFormReturnType<Values>,
   path: Path,
-): ReturnType<UseFormReturnType<Values>['getInputProps']> {
-  return form.getInputProps(path)
+): InputProps
+/**
+ * The boolean overload: `{ type: 'checkbox' }` binds a boolean field to Mantine `Checkbox` and
+ * `Switch`. It returns `onChange` plus `defaultChecked` in `useBasaltForm`'s default `uncontrolled`
+ * mode, or `checked` under `mode: 'controlled'` (Mantine decides; there is no `value`).
+ *
+ * Only a path whose value is a boolean (optional/nullable included) type-checks; a string path is a
+ * type error, not a silently wrong binding. Two limits of that check:
+ * - The path must be a literal. A `string`-typed path is rejected here (use a literal, or the
+ *   one-argument form), so the path argument does not autocomplete.
+ * - On a union parent, a key present on several members is accepted only when every member types it
+ *   as boolean; array segments must be canonical indices (`flags.0`, never `flags.1.5` or `flags.01`).
+ *
+ * @example
+ * <Switch key={fieldKey(form, 'active')} {...inputProps(form, 'active', { type: 'checkbox' })} />
+ */
+export function inputProps<Values extends Record<string, unknown>, Path extends string>(
+  form: UseFormReturnType<Values>,
+  path: BooleanAt<Values, Path>,
+  options: { type: 'checkbox' },
+): InputProps
+export function inputProps<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  path: string,
+  options?: { type: 'checkbox' },
+): InputProps {
+  // Mantine types `error` optional but sets the key on every call (`withError` defaults to true).
+  return form.getInputProps(path, options) as InputProps
 }
 
 /**

package/src/forms/index.ts

@@ -6,14 +6,13 @@
  * `basalt-ui`. Same reason `./charts` and `./tokens` stay off the root barrel, one optional peer
  * over. Import everything below from `basalt-ui/forms`.
  *
- * Four pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the submit lifecycle
- * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
- * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) lives in
- * `basalt-ui/controls` (it needs no `@mantine/form`); `useForm`/`schemaResolver` come from
- * `@mantine/form` directly. Both stopped being re-exported here in 1.39.0.
+ * One piece: the form (`useBasaltForm` + `inputProps`/`fieldKey`). The layout (FormRow /
+ * FormGroup) lives in `basalt-ui/controls` (it needs no `@mantine/form`); the form hook and
+ * schema resolvers come from `@mantine/form` directly.
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
  */
 
 export { useBasaltForm } from './create-form'
 export { inputProps, fieldKey } from './field'
+export type { InputProps } from './field'

package/src/surfaces.ts

@@ -502,7 +502,7 @@ export const SURFACES = {
       'C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy',
     ],
     description:
-      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction), and the form layout FormSection/FormRow/FormGroup/FormActions (moved here from ./forms in 1.36.0 — FormRow is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+      'The control tier (docs/CONTROLS-SPEC.md §3). Exports: `FilterSet` (nowrap row + measured +N fold + the mobile Filters (n) sheet), `RangeFilter`/`SelectFilter`/`MultiSelectFilter`/`NumberFilter`/`SearchFilter`/`ToggleFilter` (each bound to a FieldHandle — no value/onChange/size, law C2/C5; `NumberFilter` is the field.number lane, a radio list over `options` or a stepper without), `ViewTabs`, `SyncButton` with the `BarAction`/`GlobalAction` types, and the form layout `FormRow`/`FormGroup` (moved here from ./forms in 1.36.0 — `FormRow` is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop: pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3); the counts/max props on `MultiSelectFilter` render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
     optionalPeers: [],
     // `@mantine/dates` is an optional peer basaltViteConfig pre-bundles the whole @mantine scope
     // for — a consumer without the peer (linewatch) must never resolve it through this surface.

package/src/table/data-table.tsx

@@ -32,6 +32,7 @@
  * />
  */
 import {
+  ActionIcon,
   Box,
   Checkbox,
   Group,
@@ -46,6 +47,7 @@ import {
 } from '@mantine/core'
 import type { MantineSpacing } from '@mantine/core'
 import type {
+  Cell,
   Column,
   ColumnDef,
   ColumnFiltersState,
@@ -69,8 +71,8 @@ import { HIT_COARSE } from '../common/hit-floor'
 import { useMeasuredWidths } from '../common/use-measured-widths'
 import { assertRequiredProps, useValidateProps } from '../common/validate'
 import { FilterSet } from '../controls'
-import { ActionGroup, BarActionSlot } from '../controls/actions'
-import type { BarAction, SlotActions } from '../controls/actions'
+import { ActionGroup, BarActionSlot, OverflowMenu } from '../controls/actions'
+import type { BarAction, BarActionItem, SlotActions } from '../controls/actions'
 // `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
@@ -78,6 +80,7 @@ import type { BarAction, SlotActions } from '../controls/actions'
 import { EnumFilter } from '../controls/enum-filter'
 import { MultiSelectFilter } from '../controls/multi-select-filter'
 import { CtlSlot } from '../theme'
+import { IconSlot } from '../theme/icon-slot'
 import { alpha, VX } from '../tokens'
 import type { EnumField, FieldHandle, MultiField } from '../state/fields'
 import { WidgetHeader } from '../dashboard'
@@ -358,6 +361,113 @@ function selectionColumn<T extends RowData>(): ColumnDef<BasaltTableFeatures, T,
   }
 }
 
+// ── Row actions ───────────────────────────────────────────────────────────────
+
+/** One per-row action: `BarActionItem`'s vocabulary with the row handed to the handler. */
+export type DataTableRowAction<T = unknown> = {
+  key: string
+  label: string
+  /** A lone action with an icon renders as that icon button; anything else folds into the menu. */
+  icon?: ReactNode
+  onClick: (row: T) => void
+  danger?: boolean
+  /** A disabled action renders inert and never fires. */
+  disabled?: (row: T) => boolean
+  /** A loading action shows the busy state (icon button) or sits inert (menu) and never fires. */
+  loading?: (row: T) => boolean
+}
+
+/** The synthetic trailing column `rowActions` appends — namespaced like {@link SELECT_COLUMN_ID}. */
+const ACTIONS_COLUMN_ID = '__basalt_actions__'
+
+/** Wide enough for one 30px control plus the cell's horizontal padding. */
+const ACTIONS_COLUMN_SIZE = 56
+
+/**
+ * The cells whose own controls must not read as "activate the row": a tickable selection cell (a
+ * disabled row's tap IS a row tap) and every actions cell.
+ */
+function stopsRowActivation<T extends RowData>(
+  cell: Cell<BasaltTableFeatures, T, unknown>,
+): boolean {
+  if (cell.column.id === ACTIONS_COLUMN_ID) return true
+  return cell.column.id === SELECT_COLUMN_ID && cell.row.getCanSelect()
+}
+
+function RowActionCell<T>({
+  actions,
+  row,
+  rowIndex,
+  rowLabel,
+}: {
+  actions: readonly DataTableRowAction<T>[]
+  row: T
+  rowIndex: number
+  rowLabel: ((row: T) => string) | undefined
+}): ReactNode {
+  const named = rowLabel?.(row)
+  const [only] = actions
+  if (actions.length === 1 && only?.icon !== undefined) {
+    const inert = only.disabled?.(row) === true || only.loading?.(row) === true
+    return (
+      <ActionIcon
+        variant="subtle"
+        size="ctl"
+        aria-label={named === undefined ? only.label : `${only.label}: ${named}`}
+        disabled={only.disabled?.(row) === true}
+        loading={only.loading?.(row) === true}
+        {...(only.danger === true && { color: 'red' })}
+        onClick={() => {
+          if (!inert) only.onClick(row)
+        }}
+      >
+        <IconSlot>{only.icon}</IconSlot>
+      </ActionIcon>
+    )
+  }
+  const items: BarActionItem[] = actions.map((action) => ({
+    key: action.key,
+    label: action.label,
+    ...(action.icon !== undefined && { icon: action.icon }),
+    ...(action.danger === true && { danger: true }),
+    // The menu has no busy state of its own, so loading reads as inert there.
+    disabled: action.disabled?.(row) === true || action.loading?.(row) === true,
+    onClick: () => action.onClick(row),
+  }))
+  return (
+    <OverflowMenu
+      actions={items}
+      trigger="kebab"
+      label={named === undefined ? `Row ${rowIndex + 1} actions` : `Actions for ${named}`}
+    />
+  )
+}
+
+/**
+ * Header-less: the `<th>` carries a screen-reader-only name and nothing sorts across it. Built per
+ * render for the same reason as {@link selectionColumn} (`ColumnDef` is generic in `T`).
+ */
+function rowActionsColumn<T extends RowData>(
+  actions: readonly DataTableRowAction<T>[],
+  rowLabel: ((row: T) => string) | undefined,
+): ColumnDef<BasaltTableFeatures, T, unknown> {
+  return {
+    id: ACTIONS_COLUMN_ID,
+    size: ACTIONS_COLUMN_SIZE,
+    enableSorting: false,
+    enableHiding: false,
+    header: () => <span className={classes.srOnly}>Actions</span>,
+    cell: ({ row }) => (
+      <RowActionCell
+        actions={actions}
+        row={row.original}
+        rowIndex={row.index}
+        rowLabel={rowLabel}
+      />
+    ),
+  }
+}
+
 /**
  * The bar a selection raises, above the table and below its header — the count, then the actions,
  * through the SAME `BarAction[]` vocabulary `PageBar` uses, so the ≤3-inline fold and the mobile
@@ -661,6 +771,27 @@ export type BasaltDataTableProps<T extends RowData> = BasaltProps &
      */
     bulkActions?: (rows: T[]) => BarAction[]
 
+    /**
+     * Per-row actions as typed data. The table renders them itself in a trailing, pinned,
+     * header-less column: an icon button for one action that carries an `icon`, an overflow menu
+     * for anything else. Clicking either never fires `onRowActivate`. Never put a `Menu` or
+     * `ActionIcon` in a `display` / `cell` renderer (`basalt/control-outside-home`).
+     *
+     * Pass a STABLE reference — a module constant or a `useMemo` — because the column is rebuilt
+     * whenever the array identity changes. A `renderCard` projection owns its own card, so the
+     * column renders in the table body only.
+     *
+     * @example
+     * const ROW_ACTIONS: DataTableRowAction<Row>[] = [
+     *   { key: 'edit', label: 'Edit', icon: <IconEdit />, onClick: (row) => edit(row) },
+     *   { key: 'delete', label: 'Delete', danger: true, onClick: (row) => remove(row) },
+     * ]
+     * <BasaltDataTable rowActions={ROW_ACTIONS} rowLabel={(row) => row.name} … />
+     */
+    rowActions?: DataTableRowAction<T>[]
+    /** Names a row for assistive tech in its action controls; default `Row N actions`. */
+    rowLabel?: (row: T) => string
+
     // ── Pagination ────────────────────────────────────────────────────────────────
 
     /**
@@ -1354,6 +1485,8 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
     enableRowSelection = false,
     getRowId,
     bulkActions,
+    rowActions,
+    rowLabel,
     enablePagination = false,
     pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
     manualPagination = false,
@@ -1443,9 +1576,14 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
   // The checkbox column is PREPENDED here rather than asked of the caller, so `columns` stays the
   // caller's own data columns and `meta.align` / `numeral` never have to reason about a synthetic
   // one. Everything counting columns downstream reads `columnCount`, below.
+  const hasRowActions = rowActions !== undefined && rowActions.length > 0
   const tableColumns = useMemo(
-    () => (enableRowSelection ? [selectionColumn<T>(), ...facetColumns] : facetColumns),
-    [facetColumns, enableRowSelection],
+    () => [
+      ...(enableRowSelection ? [selectionColumn<T>()] : []),
+      ...facetColumns,
+      ...(hasRowActions ? [rowActionsColumn<T>(rowActions, rowLabel)] : []),
+    ],
+    [facetColumns, enableRowSelection, hasRowActions, rowActions, rowLabel],
   )
 
   // Enforced before the table is built, so the degraded options below are the ones TanStack gets —
@@ -1519,6 +1657,17 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
   const hasFolded = foldedColumns.size > 0
   const foldRows = useRowDisclosure({ data, getRowId })
 
+  // The actions column always sticks to the end edge, behind any end-pinned columns the caller
+  // asked for — so it is pinned through TanStack's own state, which also keeps their offsets right.
+  const pinningActive = enablePinning || hasRowActions
+  const tablePinning = useMemo(
+    () =>
+      hasRowActions
+        ? { ...columnPinning, end: [...columnPinning.end, ACTIONS_COLUMN_ID] }
+        : columnPinning,
+    [columnPinning, hasRowActions],
+  )
+
   const table = useTable({
     features: basaltTableFeatures,
     data,
@@ -1527,7 +1676,7 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
       sorting: tableState.sorting,
       globalFilter,
       columnFilters: tableState.columnFilters,
-      columnPinning,
+      columnPinning: tablePinning,
       columnVisibility,
       ...(enablePagination && { pagination: tableState.pagination }),
       ...(enableRowSelection && { rowSelection: tableState.rowSelection }),
@@ -1556,7 +1705,7 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
       ...(manualPagination && pageCount !== undefined && { pageCount }),
     }),
     enableSorting: sortingEnabled,
-    enableColumnPinning: enablePinning,
+    enableColumnPinning: pinningActive,
   })
 
   const showSearch = enableGlobalFilter && filteringEnabled
@@ -1575,7 +1724,11 @@ export function BasaltDataTable<T extends RowData>(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) - foldedColumns.size
+    columns.length +
+    (enableRowSelection ? 1 : 0) +
+    (hasRowActions ? 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.
@@ -1594,7 +1747,7 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
         : bulkActions(selectedRows),
     [bulkActions, selectedRows],
   )
-  const headerGroups = enablePinning ? getOrderedHeaderGroups(table) : table.getHeaderGroups()
+  const headerGroups = pinningActive ? 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
@@ -1672,18 +1825,19 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
               const canSort = sortingEnabled && header.column.getCanSort()
               const sorted = header.column.getIsSorted()
               const toggleSorting = header.column.getToggleSortingHandler()
-              const pinnedStyle = enablePinning
+              const pinnedStyle = pinningActive
                 ? getPinnedCellStyle(table, header.column)
                 : undefined
               const align = resolveAlign(header.column)
               const isSelectColumn = header.column.id === SELECT_COLUMN_ID
+              const isFoldCandidate = !isSelectColumn && header.column.id !== ACTIONS_COLUMN_ID
               return (
                 <Table.Th
                   key={header.id}
                   {...(isSelectColumn && { className: classes.selectCell })}
                   // The measured fold's own read (`useColumnFold`) — never present on the
                   // selection column, which is never a fold candidate.
-                  {...(!isSelectColumn && { [FOLD_ID_ATTR]: header.column.id })}
+                  {...(isFoldCandidate && { [FOLD_ID_ATTR]: header.column.id })}
                   onClick={canSort ? toggleSorting : undefined}
                   onKeyDown={
                     canSort
@@ -1731,7 +1885,7 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
           </Table.Tr>
         ) : (
           rows.map((row) => {
-            const cells = enablePinning
+            const cells = pinningActive
               ? [
                   ...row.getStartVisibleCells(),
                   ...row.getCenterVisibleCells(),
@@ -1755,7 +1909,7 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
                     </Table.Td>
                   )}
                   {cells.map((cell) => {
-                    const pinnedStyle = enablePinning
+                    const pinnedStyle = pinningActive
                       ? getPinnedCellStyle(table, cell.column)
                       : undefined
                     const align = resolveAlign(cell.column)
@@ -1764,11 +1918,11 @@ export function BasaltDataTable<T extends RowData>(props: BasaltDataTableProps<T
                         key={cell.id}
                         {...(cell.column.id === SELECT_COLUMN_ID && {
                           className: classes.selectCell,
-                          // The label's ::after fills the cell, so a tap on it bubbles to the row —
-                          // stop it only where a tick is possible; a disabled row's tap is a row tap.
-                          ...(cell.row.getCanSelect() && {
-                            onClick: (event: ReactMouseEvent) => event.stopPropagation(),
-                          }),
+                        })}
+                        {...(stopsRowActivation(cell) && {
+                          // The label's ::after fills the select cell, so a tap on it bubbles to the
+                          // row; the actions menu portals out but React bubbles through the portal.
+                          onClick: (event: ReactMouseEvent) => event.stopPropagation(),
                         })}
                         style={{
                           ...(typeof cell.getValue() === 'number' &&