basalt-ui 1.40.3 → 2.0.0

package/src/data/virtual-list.tsx

@@ -1,356 +0,0 @@
-/**
- * ./data — BasaltVirtualList: a windowed virtual list over @tanstack/react-virtual,
- * rendered with a Mantine Box scroll container.
- * Optional peer: @tanstack/react-virtual >=3.13.26 <4. This list works on any 3.x — the floor is
- * set by ./agent-chat's virtualize mode (see ./data/index.ts), so do not lower it.
- *
- * @example
- * import { BasaltVirtualList } from 'basalt-ui/data/virtual'
- *
- * const items = Array.from({ length: 10_000 }, (_, i) => ({ id: i, label: `Row ${i}` }))
- * <BasaltVirtualList
- *   items={items}
- *   height={400}
- *   renderItem={(item) => <div>{item.label}</div>}
- *   getItemKey={(item) => item.id}
- * />
- */
-import { Box, Skeleton } from '@mantine/core'
-import { useVirtualizer } from '@tanstack/react-virtual'
-import type { ScrollToOptions, Virtualizer } from '@tanstack/react-virtual'
-import { useImperativeHandle, useRef } from 'react'
-import type { ReactNode, Ref } from 'react'
-import { cx } from '../common/props'
-import type { BasaltProps, SlotStylesProps } from '../common/props'
-import { BASALT_PREFIX } from '../common/errors'
-import { HIT_COARSE } from '../common/hit-floor'
-import { assertRequiredProps, useValidateProps } from '../common/validate'
-import { readMediaQuery } from '../common/use-media-query'
-import { ErrorState } from '../dashboard/query-state'
-import type { QueryStateLike } from '../dashboard/query-state'
-import { dataQueryBranch } from './query-branch'
-
-// ── Props ─────────────────────────────────────────────────────────────────────
-
-/** The two boxes `BasaltVirtualList` paints: `root` is the scroll container, `row` is each
- * absolutely-positioned virtual item. */
-export type BasaltVirtualListSlot = 'root' | 'row'
-
-/**
- * Props for {@link BasaltVirtualList}.
- *
- * @example
- * const props: BasaltVirtualListProps<{ id: number; label: string }> = {
- *   items: rows,
- *   height: 400,
- *   estimateSize: 48,
- *   overscan: 5,
- *   renderItem: (item, index) => <div key={item.id}>{index}: {item.label}</div>,
- *   getItemKey: (item) => item.id,
- * }
- */
-export type BasaltVirtualListProps<T> = BasaltProps &
-  SlotStylesProps<BasaltVirtualListSlot> & {
-    /** All items in the list (unsliced — virtualization is handled internally). */
-    items: T[]
-    /** Height of the scroll container. Accepts a CSS value ('400px', '60vh') or a number in px. */
-    height: number | string
-    /**
-     * Estimated row height in px (used for virtual layout before measure).
-     * @default 40
-     */
-    estimateSize?: number
-    /**
-     * Number of items rendered beyond the visible viewport (above + below) to reduce flicker.
-     * @default 5
-     */
-    overscan?: number
-    /**
-     * Render function for a single item. Receives the item and its list index.
-     * The returned node is placed inside an absolutely-positioned row container.
-     */
-    renderItem: (item: T, index: number) => ReactNode
-    /**
-     * Stable key for each item, handed straight to the virtualizer's own `getItemKey` — required,
-     * not merely recommended: the previous index fallback hid stale rows across a mutation (an
-     * insert/delete shifting every index below it keeps rendering the OLD item at each shifted
-     * index until React's own reconciliation happens to catch up), silently, in the one component
-     * whose job is a long mutable list.
-     */
-    getItemKey: (item: T, index: number) => string | number
-    /**
-     * When true, renders skeleton placeholder rows at the given height instead of the virtual item
-     * list. The scroll container is still rendered at the specified `height`. Use while async data
-     * is loading.
-     *
-     * Superseded by `query`, which resolves this branch AND the two this prop cannot express — pass
-     * both and `query` wins, with a dev warning.
-     */
-    isLoading?: boolean
-    /**
-     * The result behind `items`, resolved into a body: pending → the skeleton rows, error with no
-     * data → an `ErrorState` inside the scroll box (the query's own `refetch` behind Retry),
-     * anything else → the rows, or `emptyState` when `items` is empty.
-     *
-     * Law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1). The list took `isLoading`
-     * and nothing else (components audit #3), so a failed fetch and a genuinely empty list rendered
-     * the same blank box — the exact false claim `QueryState` exists to delete.
-     *
-     * The container keeps its declared `height` through every branch, so the page does not jump as
-     * the state resolves.
-     */
-    query?: QueryStateLike<unknown>
-    /**
-     * Rendered inside the scroll container when `items` is empty and nothing is pending. Omit to
-     * keep today's rendering — an empty box. Works with or without `query`.
-     */
-    emptyState?: ReactNode
-    /**
-     * Number of skeleton rows to render when `isLoading` is true.
-     * @default 5
-     */
-    skeletonRows?: number
-    /** Imperative scroll handle — see {@link BasaltVirtualListHandle}. */
-    ref?: Ref<BasaltVirtualListHandle>
-  }
-
-/** `estimateSize` sets every row's rendered height — there is no per-row measurement in this
- * component — so a value under the coarse floor understates the touch target for every row. */
-function shortRowHeightMessage(estimateSize: number): string {
-  return (
-    `${BASALT_PREFIX} BasaltVirtualList: "estimateSize" is ${estimateSize}px under a coarse ` +
-    '(touch) pointer — every row renders at this height, below the `--vx-hit` floor (44px, WCAG ' +
-    '2.5.5). Raise "estimateSize" to at least 44, or pad the row content so it clears the floor.'
-  )
-}
-
-/**
- * Imperative escape hatch for {@link BasaltVirtualList} — the virtualizer's own `scrollToIndex` /
- * `scrollToOffset` / `scrollToEnd` were otherwise unreachable, since the component owns the
- * `useVirtualizer()` instance internally. `getVirtualizer()` is the full escape hatch for anything
- * not covered by the three convenience methods (mirrors `./data/table`'s `useReactTable` export as
- * the table's own escape hatch).
- *
- * @example
- * const listRef = useRef<BasaltVirtualListHandle>(null)
- * <BasaltVirtualList ref={listRef} items={items} height={400} renderItem={renderRow} getItemKey={(i) => i.id} />
- * listRef.current?.scrollToIndex(42, { align: 'center' })
- */
-export type BasaltVirtualListHandle = {
-  /** Scrolls so the item at `index` is in view. */
-  scrollToIndex: (index: number, opts?: ScrollToOptions) => void
-  /** Scrolls the container to a raw pixel `offset`. */
-  scrollToOffset: (offset: number, opts?: ScrollToOptions) => void
-  /** Scrolls to the end of the list. */
-  scrollToEnd: (opts?: Pick<ScrollToOptions, 'behavior'>) => void
-  /**
-   * The underlying `@tanstack/react-virtual` instance — the full escape hatch. Returns the RAW
-   * `@tanstack/react-virtual` `Virtualizer`, so a future major of that library reaching this shape
-   * ships here as a plain `feat:` under the no-majors doctrine (`../../CLAUDE.md` "Commit type
-   * discipline"), not a silent break.
-   */
-  getVirtualizer: () => Virtualizer<HTMLDivElement, Element>
-}
-
-// ── Component ─────────────────────────────────────────────────────────────────
-
-/**
- * A windowed virtual list backed by TanStack Virtual, rendered inside a Mantine `Box` scroll
- * container. Only the visible rows (+`overscan`) are in the DOM at any time.
- *
- * Important: `useFlushSync: false` is set explicitly to silence a React 19 scroll warning
- * (TanStack Virtual internally calls the deprecated `flushSync` on scroll events; this opt-out
- * disables that path and is the correct setting for React 19+ apps).
- *
- * Render pattern: scroll container (fixed height, overflow auto) → inner sizer div (total height,
- * position relative) → absolutely-positioned virtual rows via `transform: translateY(vi.start)`.
- *
- * @example
- * const items = Array.from({ length: 5_000 }, (_, i) => ({ id: i, name: `User ${i}` }))
- * <BasaltVirtualList
- *   items={items}
- *   height={300}
- *   estimateSize={40}
- *   renderItem={(item) => <div style={{ padding: '8px 12px' }}>{item.name}</div>}
- *   getItemKey={(item) => item.id}
- * />
- */
-export function BasaltVirtualList<T>(props: BasaltVirtualListProps<T>) {
-  // F-ERR-1: without this, a list missing `items`/`renderItem`/`getItemKey` fails deep inside
-  // `useVirtualizer` as a raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no
-  // message naming any of the three.
-  assertRequiredProps('BasaltVirtualList', props, ['items', 'renderItem', 'getItemKey'])
-  const {
-    items,
-    height,
-    estimateSize = 40,
-    overscan = 5,
-    renderItem,
-    getItemKey,
-    isLoading = false,
-    query,
-    emptyState,
-    skeletonRows = 5,
-    ref,
-    className,
-    style,
-    classNames,
-  } = props
-
-  // `query` resolves the pending branch `isLoading` used to own, plus the error and empty ones the
-  // boolean cannot express — so it wins outright, and says so rather than letting the flag look
-  // broken.
-  useValidateProps(
-    'BasaltVirtualList',
-    () =>
-      query === undefined || props.isLoading === undefined
-        ? null
-        : `${BASALT_PREFIX} BasaltVirtualList: props "query" and "isLoading" are both set — ` +
-          '"query" wins and "isLoading" is ignored. Drop "isLoading".',
-    [query === undefined, props.isLoading === undefined],
-  )
-
-  // A coarse pointer only — a mouse user's row height is a layout choice, not an accessibility
-  // floor. `estimateSize` sets every row's actual rendered height (this component never measures
-  // one), so a value under the floor is not a false positive to catch later.
-  //
-  // Reads `props.estimateSize`, not the destructured `estimateSize` above: the shipped DEFAULT
-  // (40) is itself under `HIT_COARSE` (44), so warning off the destructured value fired on every
-  // coarse-pointer mount that never named `estimateSize` at all. Only a caller's OWN too-short
-  // value is a defect to report.
-  useValidateProps(
-    'BasaltVirtualList',
-    () =>
-      props.estimateSize !== undefined &&
-      props.estimateSize < HIT_COARSE &&
-      readMediaQuery('(pointer: coarse)', false)
-        ? shortRowHeightMessage(props.estimateSize)
-        : null,
-    [props.estimateSize],
-  )
-
-  const parentRef = useRef<HTMLDivElement>(null)
-
-  const rowVirtualizer = useVirtualizer({
-    count: items.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize: () => estimateSize,
-    overscan,
-    // Silences a React 19 deprecation warning: TanStack Virtual calls flushSync on scroll;
-    // setting this to false opts out of that path entirely.
-    useFlushSync: false,
-    getItemKey: (index: number) => {
-      const item = items[index]
-      return item !== undefined ? getItemKey(item, index) : index
-    },
-  })
-
-  useImperativeHandle(
-    ref,
-    () => ({
-      scrollToIndex: (index, opts) => rowVirtualizer.scrollToIndex(index, opts),
-      scrollToOffset: (offset, opts) => rowVirtualizer.scrollToOffset(offset, opts),
-      scrollToEnd: (opts) => rowVirtualizer.scrollToEnd(opts),
-      getVirtualizer: () => rowVirtualizer,
-    }),
-    [rowVirtualizer],
-  )
-
-  const branch = query === undefined ? undefined : dataQueryBranch('BasaltVirtualList', query)
-  const showSkeleton = branch === undefined ? isLoading : branch === 'pending'
-  // Every non-virtual branch paints into the SAME box at the SAME declared height, so the page does
-  // not reflow as one state resolves into the next.
-  const boxProps = {
-    className: cx(classNames?.root, className),
-    style: {
-      height,
-      // theme-allow raw-scroll-container — matches the virtualizer's own scroll box below, so a
-      // placeholder branch doesn't reflow.
-      overflow: 'auto' as const,
-      ...style,
-    },
-  }
-
-  if (branch === 'error' && query !== undefined) {
-    return (
-      <Box {...boxProps}>
-        <ErrorState
-          error={query.error}
-          title="Could not load"
-          tier="section"
-          retrying={query.fetchStatus === 'fetching'}
-          onRetry={() => void query.refetch()}
-        />
-      </Box>
-    )
-  }
-
-  if (showSkeleton) {
-    return (
-      <Box {...boxProps}>
-        {Array.from({ length: skeletonRows }, (_, i) => (
-          <Box
-            key={`skeleton-${i}`}
-            style={{
-              height: estimateSize,
-              padding: 'var(--vx-space-virtual-row-inset-y) var(--vx-space-virtual-row-inset-x)',
-              boxSizing: 'border-box',
-            }}
-          >
-            {/* Inner height = row height minus the row's own vertical inset (top + bottom), read
-                from the same density-tracking var the padding above uses — a hardcoded subtrahend
-                would only be correct at density level 0. */}
-            <Skeleton
-              height={`calc(${estimateSize}px - 2 * var(--vx-space-virtual-row-inset-y))`}
-              radius="sm"
-            />
-          </Box>
-        ))}
-      </Box>
-    )
-  }
-
-  if (items.length === 0 && emptyState !== undefined) return <Box {...boxProps}>{emptyState}</Box>
-
-  return (
-    <Box
-      ref={parentRef}
-      className={cx(classNames?.root, className)}
-      style={{
-        height,
-        // theme-allow raw-scroll-container — TanStack Virtual measures this element as the scroll container.
-        overflow: 'auto',
-        ...style,
-      }}
-    >
-      {/* Inner sizer — defines total scroll height for the virtualizer */}
-      <Box
-        style={{
-          height: rowVirtualizer.getTotalSize(),
-          position: 'relative',
-        }}
-      >
-        {rowVirtualizer.getVirtualItems().map((virtualItem) => {
-          const item = items[virtualItem.index]
-          if (item === undefined) return null
-          return (
-            <Box
-              key={virtualItem.key}
-              className={cx(classNames?.row)}
-              style={{
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                width: '100%',
-                height: virtualItem.size,
-                transform: `translateY(${virtualItem.start}px)`,
-              }}
-            >
-              {renderItem(item, virtualItem.index)}
-            </Box>
-          )
-        })}
-      </Box>
-    </Box>
-  )
-}

package/src/data/virtual.ts

@@ -1,26 +0,0 @@
-/**
- * ./data/virtual — BasaltVirtualList: a windowed virtual list over @tanstack/react-virtual,
- * rendered with a Mantine Box scroll container.
- *
- * Optional peer: @tanstack/react-virtual >=3.13.26 <4. This list works on any 3.x — the floor is
- * set by ./agent-chat's virtualize mode, so do not lower it.
- *
- * This subpath does NOT value-import @tanstack/react-table, so the data-table peer is never
- * required — use `./data/table` when your app only needs the table.
- *
- * Install with:
- *   bun add @tanstack/react-virtual
- *
- * @example
- * import { BasaltVirtualList } from 'basalt-ui/data/virtual'
- * const items = Array.from({ length: 10_000 }, (_, i) => ({ id: i, label: `Row ${i}` }))
- * <BasaltVirtualList items={items} height={400} renderItem={(item) => <div>{item.label}</div>} />
- */
-
-// ── BasaltVirtualList ─────────────────────────────────────────────────────────
-export { BasaltVirtualList } from './virtual-list'
-export type {
-  BasaltVirtualListHandle,
-  BasaltVirtualListProps,
-  BasaltVirtualListSlot,
-} from './virtual-list'

package/src/forms/FormErrorSummary.tsx

@@ -1,71 +0,0 @@
-/**
- * ./forms — FormErrorSummary: accessible error-summary component for long forms.
- * Mantine-coupled. Optional peer: @mantine/form.
- */
-import { Alert, List, Text } from '@mantine/core'
-import type { UseFormReturnType } from '@mantine/form'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import { alpha, VX } from '../tokens'
-
-// ── FormErrorSummary ──────────────────────────────────────────────────────────
-
-/** Props for FormErrorSummary. */
-export type FormErrorSummaryProps<Values extends Record<string, unknown>> = BasaltProps & {
-  form: UseFormReturnType<Values>
-  /** Accessible heading shown above the error list. Defaults to "Please fix the following errors". */
-  title?: string
-}
-
-/**
- * Renders an accessible error summary list for long forms and screen readers.
- * Follows the WCAG error-summary pattern — a single `role="alert"` container that
- * lists all field errors, placed at the top of the form so AT announces it on submit.
- *
- * Returns `null` when the form has no errors (renders nothing when the form is clean).
- *
- * @example
- * import { FormErrorSummary, useBasaltForm } from 'basalt-ui/forms'
- *
- * function MyForm() {
- *   const form = useBasaltForm({ initialValues: { email: '' } })
- *   return (
- *     <form onSubmit={form.onSubmit(console.log)}>
- *       <FormErrorSummary form={form} title="Fix these before submitting" />
- *       <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} label="Email" />
- *     </form>
- *   )
- * }
- */
-export function FormErrorSummary<Values extends Record<string, unknown>>(
-  props: FormErrorSummaryProps<Values>,
-) {
-  // F-ERR-1: without this, a missing `form` fails deep inside `Object.entries(form.errors)` as a
-  // raw `TypeError` caught by `BasaltErrorBoundary` — a blank subtree with no message naming it.
-  assertRequiredProps('FormErrorSummary', props, ['form'])
-  const { form, title = 'Please fix the following errors', className, style } = props
-  const errorEntries = Object.entries(form.errors)
-  if (errorEntries.length === 0) return null
-
-  return (
-    <Alert
-      role="alert"
-      title={<Text fw={600}>{title}</Text>}
-      {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
-      styles={{
-        root: {
-          backgroundColor: alpha(VX.status.bad, 0.13),
-          color: VX.status.bad,
-          borderRadius: 'var(--vx-radius-ctrl)',
-        },
-      }}
-    >
-      <List size="sm" mt={4}>
-        {errorEntries.map(([path, message]) => (
-          <List.Item key={path}>{String(message)}</List.Item>
-        ))}
-      </List>
-    </Alert>
-  )
-}

package/src/forms/use-field-array.ts

@@ -1,94 +0,0 @@
-/**
- * ./forms — useFieldArray: the list-field surface over Mantine's four list actions.
- * Mantine-coupled. Optional peer: @mantine/form.
- *
- * The gap (audit B §4): `insertListItem` / `removeListItem` / `reorderListItem` are all reachable
- * off the raw form object, but they are unexported by name, undocumented in the forms doctrine, and
- * each takes a different argument shape (`(path, item, index?)`, `(path, index)`,
- * `(path, { from, to })`). The list ALSO has to be read back out of the values by dotted path, and
- * every row needs `form.key(\`${path}.${i}\`)` or the uncontrolled reconciler reuses the wrong DOM
- * node when a row is removed from the middle — which is the defect this hook exists to make
- * unwritable.
- */
-import type { FormArrayElement, LooseKeys, UseFormReturnType } from '@mantine/form'
-
-export type UseFieldArrayReturn<Item> = {
-  /** The live list. `[]` when the path holds nothing, so a call site never guards before mapping. */
-  items: Item[]
-  /** Push one item onto the end. */
-  append: (value: Item) => void
-  /** Drop the item at `index`. Mantine re-indexes the field errors with it. */
-  remove: (index: number) => void
-  /** Move one item, e.g. from a drag handle or a pair of arrow buttons. */
-  move: (from: number, to: number) => void
-  /**
-   * Mantine's reconciler key for row `index` (`form.key('<path>.<index>')`) — pass it as the row's
-   * JSX `key`, never spread it.
-   *
-   * **Positional, and that is a real limit worth stating**: it identifies the SLOT, not the item.
-   * Mantine's list actions write values through `$values` directly and never bump the form-level
-   * key generation (verified in 9.3.2's use-form-list), so removing row 0 does not change row 0's
-   * key — it changes which item sits there. That is correct for an append/remove list, where the
-   * uncontrolled inputs below re-read their `defaultValue` from the new values anyway. A list the
-   * USER reorders wants an identity key instead: put a `randomId()` on the item and key the row on
-   * that.
-   */
-  key: (index: number) => string
-}
-
-/**
- * Reads and edits a list field as one object.
- *
- * **`items` is read from `form.getValues()`, not from `form.values`**, so it is correct under the
- * `mode: 'uncontrolled'` default `useBasaltForm` sets: the list actions all re-render the form
- * (they call `setValues` with `updateState: true`), so the snapshot this returns is the one the
- * caller just produced.
- *
- * @example
- * const items = useFieldArray(form, 'contacts')
- *
- * {items.items.map((_, index) => (
- *   <FormRow key={items.key(index)} label={`Contact ${index + 1}`}>
- *     <TextInput
- *       key={fieldKey(form, `contacts.${index}.email`)}
- *       {...inputProps(form, `contacts.${index}.email`)}
- *     />
- *     <Button onClick={() => items.remove(index)}>Remove</Button>
- *   </FormRow>
- * ))}
- * <Button onClick={() => items.append({ email: '' })}>Add contact</Button>
- */
-export function useFieldArray<
-  Values extends Record<string, unknown>,
-  Path extends LooseKeys<Values>,
->(
-  form: UseFormReturnType<Values>,
-  path: Path,
-): UseFieldArrayReturn<FormArrayElement<Values, Path & string>> {
-  type Item = FormArrayElement<Values, Path & string>
-
-  return {
-    items: readList<Item>(form.getValues(), String(path)),
-    append: (value) => form.insertListItem(path, value),
-    remove: (index) => form.removeListItem(path, index),
-    move: (from, to) => form.reorderListItem(path, { from, to }),
-    key: (index) => form.key(`${String(path)}.${index}`),
-  }
-}
-
-/**
- * The dotted-path read. Mantine's own `getPath` is internal to `@mantine/form/paths` and is not on
- * the package's public entry, so this walks the path itself rather than reaching past the export
- * map for six lines.
- *
- * Returns `[]` for a missing path or a non-array value: the alternative is a `.map` on `undefined`
- * at the call site, and "the field is not a list" is a typing error the compiler already reports.
- */
-function readList<Item>(values: Record<string, unknown>, path: string): Item[] {
-  let current: unknown = values
-  for (const segment of path.split('.')) {
-    if (current === null || typeof current !== 'object') return []
-    current = (current as Record<string, unknown>)[segment]
-  }
-  return Array.isArray(current) ? (current as Item[]) : []
-}