basalt-ui 1.27.0 → 1.28.0

package/dist/data/data-table.module.css

@@ -0,0 +1,64 @@
+/*
+ * BasaltDataTable — the two boxes the base Mantine `Table` cannot paint from a prop: an activatable
+ * row, and the bulk-action bar a selection raises.
+ */
+
+/*
+ * `onRowActivate` — the row → detail hook that pairs with `PageAside`. The row keeps its native
+ * `<tr>` semantics and takes `tabIndex=0` + `data-activatable` rather than `role="button"`: a role
+ * swap would take the row OUT of the table's own row/cell semantics, so a screen reader would stop
+ * announcing the column headers with each cell — which is the whole reason the data is in a table.
+ * The affordance is therefore the cursor and the focus ring, not a role.
+ */
+.activatable {
+  cursor: pointer;
+}
+
+.activatable:focus-visible {
+  outline: 2px solid var(--vx-accent);
+  outline-offset: -2px;
+}
+
+/*
+ * The bulk bar. It sits between the header row and the table, and it is a SURFACE rather than a
+ * bare row: it appears and disappears with the selection, so without a background it reads as the
+ * table jumping. `--vx-surface-subtle` is the same one-step-up fill the sheet rows and the sidebar
+ * use, so nothing new is introduced to the page's surface ladder.
+ */
+.bulkBar {
+  padding: var(--vx-space-row-inset-y, 0.375rem) var(--vx-space-row-inset-x, 0.5rem);
+  border: 1px solid var(--vx-surface-hairline);
+  border-radius: var(--vx-radius-ctrl);
+  background: var(--vx-surface-subtle);
+}
+
+/*
+ * The count. Mono/micro, the same numeric readout idiom the pagination bar's range label uses
+ * (`docs/DESIGN-SPEC.md` §3) — a selection count is a figure, and reading it in the proportional
+ * body font beside proportional button labels made the bar read as a sentence.
+ */
+.bulkCount {
+  font-family: var(--mantine-font-family-monospace);
+  font-size: var(--vx-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--vx-muted);
+}
+
+/*
+ * The measured containment wrapper — `stickyHeader` with neither `maxHeight` nor `minWidth`, the
+ * one shape whose overflow mode cannot be decided statically. `useMeasuredContainment`
+ * (`data-table.tsx`) writes `data-contained`; the two states are declared here rather than as an
+ * inline style so the flip is a single attribute write and a reader can see both at once.
+ *
+ * `[data-contained='false']` is deliberately NOT `overflow: visible` — it is the absence of any
+ * overflow declaration, because `overflow-x: visible` beside a computed `overflow-y` is exactly
+ * the pairing the browser rewrites to `auto`. `min-width: 0` is the flex/grid floor every
+ * containing chain in this library needs and none of them get by default.
+ */
+.containment {
+  min-width: 0;
+}
+
+.containment[data-contained='true'] {
+  overflow-x: auto;
+}

package/dist/data/data-table.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly activatable: string
+  readonly bulkBar: string
+  readonly bulkCount: string
+  readonly containment: string
+}
+export default classes

package/dist/data/index.d.ts

@@ -33,6 +33,6 @@
  * const items = Array.from({ length: 10_000 }, (_, i) => ({ id: i, label: `Row ${i}` }))
  * <BasaltVirtualList items={items} height={400} renderItem={(item) => <div>{item.label}</div>} />
  */
-export * from './table.js';
-export * from './virtual.js';
+export { BasaltDataTable, type BasaltDataTableProps, type BasaltDataTableSlot, type DataTableAlign, type DataTableColumnId, type DataTableColumnPinning, type DataTableFacet, type DataTableFacetOption, createColumnHelper, useReactTable, flexRender, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, type ColumnDef, type SortingState, type ColumnHelper, type PaginationState, type ColumnPinningState, type ColumnFiltersState, type RowSelectionState, } from './table.js';
+export { BasaltVirtualList, type BasaltVirtualListHandle, type BasaltVirtualListProps, type BasaltVirtualListSlot, } from './virtual.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,cAAc,SAAS,CAAA;AAGvB,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,iBAAiB,EACjB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAA"}

package/dist/data/index.js

@@ -1,2 +1,24 @@
-export * from "./table.js";
-export * from "./virtual.js";
+import {
+  BasaltDataTable,
+  createColumnHelper,
+  useReactTable,
+  flexRender,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel
+} from "./table.js";
+import {
+  BasaltVirtualList
+} from "./virtual.js";
+export {
+  BasaltDataTable,
+  BasaltVirtualList,
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable
+};

package/dist/data/query-branch.d.ts

@@ -0,0 +1,28 @@
+import type { QueryStateLike } from '../common/query-state-like.js';
+/**
+ * Which body a data container paints.
+ *
+ * `'ready'` covers three of `QueryState`'s four cases — data, an EMPTY resolved result, and an
+ * error that arrived over cached data. The container itself decides between rows and its own empty
+ * state, because it already knows whether it has any (`table.getRowCount()`, `items.length`) and a
+ * query envelope does not.
+ *
+ * A refetch that fails while rows are already on screen therefore keeps the rows, with no banner —
+ * that is `QueryState`'s "a background refetch failing must not blank a page that already works",
+ * minus the banner it draws. Compose `QueryState` AROUND the container when the banner is wanted.
+ */
+export type DataQueryBranch = 'pending' | 'error' | 'ready';
+/**
+ * Resolves a `QueryStateLike` to the branch its container should paint, asserting first — through
+ * the SAME `assertQueryStateLike` `QueryState` runs (`common/query-state-like.ts`), so the table and
+ * the wrapper cannot disagree about what a valid envelope is. This function once carried its own
+ * narrower copy that skipped the `data` key and the `refetch()` check, which let a result whose
+ * Retry button did nothing through the very branch that renders one.
+ *
+ * `isError` WITH data is `'ready'`, not `'error'`: the stale rows stay on screen. That is deliberate
+ * and it differs from `QueryState`, which paints the same case as children PLUS a "showing cached
+ * data" banner — a container swaps only its body, so it has nowhere to draw one. Compose
+ * `QueryState` AROUND the container when the banner is wanted. Pinned in `data-table.test.tsx`.
+ */
+export declare function dataQueryBranch(component: string, query: QueryStateLike<unknown>): DataQueryBranch;
+//# sourceMappingURL=query-branch.d.ts.map

package/dist/data/query-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-branch.d.ts","sourceRoot":"","sources":["../../src/data/query-branch.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAE3D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,GAC7B,eAAe,CAOjB"}

package/dist/data/query-branch.js

@@ -0,0 +1,10 @@
+import { assertQueryStateLike } from "../common/query-state-like.js";
+function dataQueryBranch(component, query) {
+  assertQueryStateLike(component, query);
+  if (query.isError && query.data === void 0) return "error";
+  if (query.data === void 0 && query.fetchStatus !== "idle") return "pending";
+  return "ready";
+}
+export {
+  dataQueryBranch
+};

package/dist/data/table.d.ts

@@ -19,6 +19,6 @@
  * <BasaltDataTable data={rows} columns={columns} enableGlobalFilter enablePagination />
  */
 export { BasaltDataTable } from './data-table.js';
-export type { BasaltDataTableProps, DataTableAlign, DataTableFacet, DataTableFacetOption, } from './data-table.js';
-export { createColumnHelper, useReactTable, flexRender, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, type ColumnDef, type SortingState, type ColumnHelper, type PaginationState, type ColumnPinningState, type ColumnFiltersState, } from '@tanstack/react-table';
+export type { BasaltDataTableProps, BasaltDataTableSlot, DataTableAlign, DataTableColumnId, DataTableColumnPinning, DataTableFacet, DataTableFacetOption, } from './data-table.js';
+export { createColumnHelper, useReactTable, flexRender, getCoreRowModel, getSortedRowModel, getFilteredRowModel, getPaginationRowModel, type ColumnDef, type SortingState, type ColumnHelper, type PaginationState, type ColumnPinningState, type RowSelectionState, type ColumnFiltersState, } from '@tanstack/react-table';
 //# sourceMappingURL=table.d.ts.map

package/dist/data/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/data/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAA;AASrB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/data/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAA;AASrB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAA"}

package/dist/data/virtual-list.d.ts

@@ -1,4 +1,10 @@
-import type { ReactNode } from 'react';
+import type { ScrollToOptions, Virtualizer } from '@tanstack/react-virtual';
+import type { ReactNode, Ref } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { QueryStateLike } from '../dashboard/query-state.js';
+/** 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}.
  *
@@ -12,7 +18,7 @@ import type { ReactNode } from 'react';
  *   getItemKey: (item) => item.id,
  * }
  */
-export type BasaltVirtualListProps<T> = {
+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. */
@@ -33,21 +39,74 @@ export type BasaltVirtualListProps<T> = {
      */
     renderItem: (item: T, index: number) => ReactNode;
     /**
-     * Stable key for each item. Falls back to the numeric list index when omitted.
-     * Providing a stable key prevents react reconciliation churn on scroll.
+     * 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;
+    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>;
+};
+/**
+ * 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>;
 };
 /**
  * A windowed virtual list backed by TanStack Virtual, rendered inside a Mantine `Box` scroll
@@ -70,5 +129,5 @@ export type BasaltVirtualListProps<T> = {
  *   getItemKey={(item) => item.id}
  * />
  */
-export declare function BasaltVirtualList<T>({ items, height, estimateSize, overscan, renderItem, getItemKey, isLoading, skeletonRows, }: BasaltVirtualListProps<T>): import("react").JSX.Element;
+export declare function BasaltVirtualList<T>(props: BasaltVirtualListProps<T>): import("react").JSX.Element;
 //# sourceMappingURL=virtual-list.d.ts.map

package/dist/data/virtual-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-list.d.ts","sourceRoot":"","sources":["../../src/data/virtual-list.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI;IACtC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,EAAE,CAAA;IACV,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IACjD;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAA;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,EACnC,KAAK,EACL,MAAM,EACN,YAAiB,EACjB,QAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAiB,EACjB,YAAgB,GACjB,EAAE,sBAAsB,CAAC,CAAC,CAAC,+BAmF3B"}
+{"version":3,"file":"virtual-list.d.ts","sourceRoot":"","sources":["../../src/data/virtual-list.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE3E,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAInE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAK9D;yCACyC;AACzC,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,KAAK,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,WAAW,GACjD,eAAe,CAAC,qBAAqB,CAAC,GAAG;IACvC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,EAAE,CAAA;IACV,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IACjD;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAA;IACvD;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,GAAG,CAAC,EAAE,GAAG,CAAC,uBAAuB,CAAC,CAAA;CACnC,CAAA;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,iDAAiD;IACjD,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAC9D,qDAAqD;IACrD,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,KAAK,IAAI,CAAA;IAChE,sCAAsC;IACtC,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,KAAK,IAAI,CAAA;IAC/D;;;;;OAKG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;CAC3D,CAAA;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,+BA+JpE"}

package/dist/data/virtual-list.js

@@ -1,17 +1,35 @@
 import { jsx } from "react/jsx-runtime";
 import { Box, Skeleton } from "@mantine/core";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { useRef } from "react";
-function BasaltVirtualList({
-  items,
-  height,
-  estimateSize = 40,
-  overscan = 5,
-  renderItem,
-  getItemKey,
-  isLoading = false,
-  skeletonRows = 5
-}) {
+import { useImperativeHandle, useRef } from "react";
+import { cx } from "../common/props.js";
+import { BASALT_PREFIX } from "../common/errors.js";
+import { assertRequiredProps, useValidateProps } from "../common/validate.js";
+import { ErrorState } from "../dashboard/query-state.js";
+import { dataQueryBranch } from "./query-branch.js";
+function BasaltVirtualList(props) {
+  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;
+  useValidateProps(
+    "BasaltVirtualList",
+    () => query === void 0 || props.isLoading === void 0 ? null : `${BASALT_PREFIX} BasaltVirtualList: props "query" and "isLoading" are both set \u2014 "query" wins and "isLoading" is ignored. Drop "isLoading".`,
+    [query === void 0, props.isLoading === void 0]
+  );
   const parentRef = useRef(null);
   const rowVirtualizer = useVirtualizer({
     count: items.length,
@@ -21,44 +39,76 @@ function BasaltVirtualList({
     // 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 !== void 0 && {
-      getItemKey: (index) => {
-        const item = items[index];
-        return item !== void 0 ? getItemKey(item, index) : index;
-      }
+    getItemKey: (index) => {
+      const item = items[index];
+      return item !== void 0 ? getItemKey(item, index) : index;
     }
   });
-  if (isLoading) {
-    return (
-      // theme-allow raw-scroll-container — matches the virtualizer's own scroll box below, so the skeleton doesn't reflow.
-      /* @__PURE__ */ jsx(Box, { style: { height, overflow: "auto" }, children: Array.from({ length: skeletonRows }, (_, i) => /* @__PURE__ */ jsx(
-        Box,
-        {
-          style: {
-            height: estimateSize,
-            padding: "var(--vx-space-virtual-row-inset-y) var(--vx-space-virtual-row-inset-x)",
-            boxSizing: "border-box"
-          },
-          children: /* @__PURE__ */ jsx(
-            Skeleton,
-            {
-              height: `calc(${estimateSize}px - 2 * var(--vx-space-virtual-row-inset-y))`,
-              radius: "sm"
-            }
-          )
+  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 === void 0 ? void 0 : dataQueryBranch("BasaltVirtualList", query);
+  const showSkeleton = branch === void 0 ? isLoading : branch === "pending";
+  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",
+      ...style
+    }
+  };
+  if (branch === "error" && query !== void 0) {
+    return /* @__PURE__ */ jsx(Box, { ...boxProps, children: /* @__PURE__ */ jsx(
+      ErrorState,
+      {
+        error: query.error,
+        title: "Could not load",
+        tier: "section",
+        retrying: query.fetchStatus === "fetching",
+        onRetry: () => void query.refetch()
+      }
+    ) });
+  }
+  if (showSkeleton) {
+    return /* @__PURE__ */ jsx(Box, { ...boxProps, children: Array.from({ length: skeletonRows }, (_, i) => /* @__PURE__ */ jsx(
+      Box,
+      {
+        style: {
+          height: estimateSize,
+          padding: "var(--vx-space-virtual-row-inset-y) var(--vx-space-virtual-row-inset-x)",
+          boxSizing: "border-box"
         },
-        `skeleton-${i}`
-      )) })
-    );
+        children: /* @__PURE__ */ jsx(
+          Skeleton,
+          {
+            height: `calc(${estimateSize}px - 2 * var(--vx-space-virtual-row-inset-y))`,
+            radius: "sm"
+          }
+        )
+      },
+      `skeleton-${i}`
+    )) });
   }
+  if (items.length === 0 && emptyState !== void 0) return /* @__PURE__ */ jsx(Box, { ...boxProps, children: emptyState });
   return /* @__PURE__ */ jsx(
     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"
+        overflow: "auto",
+        ...style
       },
       children: /* @__PURE__ */ jsx(
         Box,
@@ -73,6 +123,7 @@ function BasaltVirtualList({
             return /* @__PURE__ */ jsx(
               Box,
               {
+                className: cx(classNames?.row),
                 style: {
                   position: "absolute",
                   top: 0,

package/dist/data/virtual.d.ts

@@ -17,5 +17,5 @@
  * <BasaltVirtualList items={items} height={400} renderItem={(item) => <div>{item.label}</div>} />
  */
 export { BasaltVirtualList } from './virtual-list.js';
-export type { BasaltVirtualListProps } from './virtual-list.js';
+export type { BasaltVirtualListHandle, BasaltVirtualListProps, BasaltVirtualListSlot, } from './virtual-list.js';
 //# sourceMappingURL=virtual.d.ts.map

package/dist/data/virtual.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"virtual.d.ts","sourceRoot":"","sources":["../../src/data/virtual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"virtual.d.ts","sourceRoot":"","sources":["../../src/data/virtual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,gBAAgB,CAAA"}

package/dist/forms/FormErrorSummary.d.ts

@@ -1,6 +1,7 @@
 import type { UseFormReturnType } from '@mantine/form';
+import type { BasaltProps } from '../common/props.js';
 /** Props for FormErrorSummary. */
-export type FormErrorSummaryProps<Values extends Record<string, unknown>> = {
+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;
@@ -20,10 +21,10 @@ export type FormErrorSummaryProps<Values extends Record<string, unknown>> = {
  *   return (
  *     <form onSubmit={form.onSubmit(console.log)}>
  *       <FormErrorSummary form={form} title="Fix these before submitting" />
- *       <TextInput {...field(form, 'email')} label="Email" />
+ *       <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} label="Email" />
  *     </form>
  *   )
  * }
  */
-export declare function FormErrorSummary<Values extends Record<string, unknown>>({ form, title, }: FormErrorSummaryProps<Values>): import("react").JSX.Element | null;
+export declare function FormErrorSummary<Values extends Record<string, unknown>>(props: FormErrorSummaryProps<Values>): import("react").JSX.Element | null;
 //# sourceMappingURL=FormErrorSummary.d.ts.map

package/dist/forms/FormErrorSummary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormErrorSummary.d.ts","sourceRoot":"","sources":["../../src/forms/FormErrorSummary.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAKtD,kCAAkC;AAClC,MAAM,MAAM,qBAAqB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC1E,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAC/B,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACvE,IAAI,EACJ,KAAyC,GAC1C,EAAE,qBAAqB,CAAC,MAAM,CAAC,sCAuB/B"}
+{"version":3,"file":"FormErrorSummary.d.ts","sourceRoot":"","sources":["../../src/forms/FormErrorSummary.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAMlD,kCAAkC;AAClC,MAAM,MAAM,qBAAqB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,WAAW,GAAG;IACxF,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAA;IAC/B,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC,sCA8BrC"}

package/dist/forms/FormErrorSummary.js

@@ -1,10 +1,10 @@
 import { jsx } from "react/jsx-runtime";
 import { Alert, List, Text } from "@mantine/core";
+import { assertRequiredProps } from "../common/validate.js";
 import { alpha, VX } from "../tokens/index.js";
-function FormErrorSummary({
-  form,
-  title = "Please fix the following errors"
-}) {
+function FormErrorSummary(props) {
+  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 /* @__PURE__ */ jsx(
@@ -12,6 +12,8 @@ function FormErrorSummary({
     {
       role: "alert",
       title: /* @__PURE__ */ jsx(Text, { fw: 600, children: title }),
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style },
       styles: {
         root: {
           backgroundColor: alpha(VX.status.bad, 0.13),

package/dist/forms/create-form.d.ts

@@ -17,14 +17,14 @@ export type UseBasaltFormOptions<Values extends Record<string, unknown>> = Omit<
  *
  * @example
  * import * as v from 'valibot'
- * import { useBasaltForm, field } from 'basalt-ui/forms'
+ * import { useBasaltForm, inputProps, fieldKey } from 'basalt-ui/forms'
  *
  * const Schema = v.object({ name: v.pipe(v.string(), v.minLength(2)), email: v.string() })
  * type Values = v.InferOutput<typeof Schema>
  *
  * function MyForm() {
  *   const form = useBasaltForm({ initialValues: { name: '', email: '' }, schema: Schema })
- *   return <TextInput {...field(form, 'name')} label="Name" />
+ *   return <TextInput key={fieldKey(form, 'name')} {...inputProps(form, 'name')} label="Name" />
  * }
  */
 export declare function useBasaltForm<Values extends Record<string, unknown>>(opts: UseBasaltFormOptions<Values>): UseFormReturnType<Values>;

package/dist/forms/field.d.ts

@@ -1,21 +1,61 @@
 /**
- * ./forms — field: DX helper for Mantine v9 uncontrolled fields.
+ * ./forms — inputProps + fieldKey: the two-call idiom every Mantine v9 uncontrolled field needs.
  * Mantine-coupled. Optional peer: @mantine/form.
+ *
+ * **`key` is NOT in `inputProps`' return, and that is the whole point of this file's shape.**
+ * It used to be — one object holding `getInputProps(path)` and `form.key(path)` together, so a
+ * single spread covered both. React 19 logs
+ * `A props object containing a "key" prop is being spread into JSX` on every such render: a spread
+ * `key` is read as the element key but the warning says it is deprecated, and three fields meant
+ * three warnings per page. The bundle was basalt's own invention; Mantine's documented idiom is
+ * `key={form.key(path)} {...form.getInputProps(path)}`, and this is that idiom with basalt's names.
+ *
+ * The `@deprecated` `field` alias below did NOT follow it there — it still returns the 1.27 bundle,
+ * because a deprecated export is a schedule and not a silent behaviour change. See its own doc.
  */
 import type { LooseKeys, UseFormReturnType } from '@mantine/form';
 /**
- * Bundles the two props every Mantine v9 uncontrolled field needs — `getInputProps` spread
- * plus the reconciler `key` — into a single object. Eliminates the two-call boilerplate at
- * every field site.
+ * The spread half: `form.getInputProps(path)`, and nothing else.
+ *
+ * Pair it with {@link fieldKey} — an uncontrolled field renders from a `defaultValue`, so without
+ * the reconciler key React reuses the DOM node and `form.reset()` / `setValues()` / a removed list
+ * row leave the old text on screen.
  *
  * @example
- * import { useBasaltForm, field } from 'basalt-ui/forms'
+ * import { useBasaltForm, inputProps, fieldKey } from 'basalt-ui/forms'
  *
  * function MyForm() {
  *   const form = useBasaltForm({ initialValues: { email: '' } })
- *   return <TextInput {...field(form, 'email')} label="Email" />
+ *   return <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} label="Email" />
  * }
  */
+export declare function inputProps<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(form: UseFormReturnType<Values>, path: Path): ReturnType<UseFormReturnType<Values>['getInputProps']>;
+/**
+ * The key half: `form.key(path)`, as a JSX `key` attribute — never spread.
+ *
+ * A separate call rather than a second member of {@link inputProps}' object, because an object
+ * carrying `key` cannot be spread without React 19 warning about it. Two calls on one line is the
+ * cost; a clean console and a reconciler that actually resets its inputs is what it buys.
+ *
+ * @example
+ * <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} />
+ */
+export declare function fieldKey<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(form: UseFormReturnType<Values>, path: Path): string;
+/**
+ * @deprecated Renamed to `inputProps` in 1.x — collides with the `field` store builder in
+ * `basalt-ui/state`. Kept until the forms surface next changes; removal ships as a plain `feat:`,
+ * never a major. Write `key={fieldKey(form, path)} {...inputProps(form, path)}` instead.
+ *
+ * **It is NOT `export const field = inputProps` any more, and the difference is the whole point.**
+ * It returns the 1.27 shape — `getInputProps(path)` PLUS `key` — because an alias of the new
+ * `inputProps` would have changed what every existing `<TextInput {...field(form, 'x')} />` does
+ * without changing whether it compiles: the element loses its reconciler key, keeps its old text
+ * through `form.reset()`, and nothing anywhere says so. A deprecated export is a SCHEDULE, not a
+ * behaviour change (`../../CLAUDE.md`, "Deprecation lifecycle"), so this one keeps its behaviour
+ * byte for byte — including the React 19 `A props object containing a "key" prop is being spread
+ * into JSX` warning it has always produced. That warning is the migration signal; `1.29.0` removing
+ * the export is the deadline. `basalt/forms-field-key` reports every remaining call site.
+ */
 export declare function field<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(form: UseFormReturnType<Values>, path: Path): ReturnType<UseFormReturnType<Values>['getInputProps']> & {
     key: string;
 };

package/dist/forms/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/forms/field.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAIjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,EAC1F,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,IAAI,GACT,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAK1E"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/forms/field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAIjE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,EAC/F,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,IAAI,GACT,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,EAC7F,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,IAAI,GACT,MAAM,CAER;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,EAC1F,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,IAAI,GACT,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAE1E"}

package/dist/forms/field.js

@@ -1,9 +1,14 @@
+function inputProps(form, path) {
+  return form.getInputProps(path);
+}
+function fieldKey(form, path) {
+  return form.key(path);
+}
 function field(form, path) {
-  return {
-    ...form.getInputProps(path),
-    key: form.key(path)
-  };
+  return { ...form.getInputProps(path), key: form.key(path) };
 }
 export {
-  field
+  field,
+  fieldKey,
+  inputProps
 };