basalt-ui 1.27.0 → 1.29.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/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 } 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;AAOrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/data/table.js

@@ -1,20 +1,6 @@
 import { BasaltDataTable } from "./data-table.js";
-import {
-  createColumnHelper,
-  useReactTable,
-  flexRender,
-  getCoreRowModel,
-  getSortedRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel
-} from "@tanstack/react-table";
+import { createColumnHelper } from "@tanstack/react-table";
 export {
   BasaltDataTable,
-  createColumnHelper,
-  flexRender,
-  getCoreRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
-  useReactTable
+  createColumnHelper
 };

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

@@ -3,10 +3,10 @@
  * 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.
+ * set by ./agent-chat's virtualize mode, so do not lower it.
  *
- * Use this fine subpath instead of the `./data` barrel when your app only needs the virtual list
- * — it does NOT value-import @tanstack/react-table, so the data-table peer is never required.
+ * 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
@@ -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/dev-dock.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import type { BasaltProps } from './common/props.js';
+import type { ThemeLabControlsProps } from './theme-lab/index.js';
+/** Which panel is open. `null` renders nothing (the dock is unmounted, not hidden). */
+export type BasaltDevDockTool = 'router' | 'query' | 'theme';
+type DevDockRouter = {
+    __routerHasBeenSetup?: unknown;
+} | Record<string, unknown>;
+export type BasaltDevDockProps = BasaltProps & {
+    /** Which panel to show. `null` renders nothing. */
+    tool: BasaltDevDockTool | null;
+    /** Called when the dock's own close button fires, or a hosted panel asks to close itself
+     * (the router devtools' own `setIsOpen`, the query devtools' own `onClose`). */
+    onClose: () => void;
+    /** The active TanStack `Router` instance — required only to render the `'router'` tool; a
+     * consumer that never opens it may omit this entirely. */
+    router?: DevDockRouter;
+    /** Forwarded to the hosted `ThemeLabControls` (icons, the copy callback — see its own props). */
+    themeLab?: ThemeLabControlsProps;
+};
+/**
+ * Lazy, production-excluded dock. Safe to mount unconditionally with `tool={null}` — the dynamic
+ * imports for whichever peer a tool needs only fire once that tool is actually selected, and
+ * never at all in production.
+ */
+export declare function BasaltDevDock({ tool, onClose, router, themeLab, className, style, }: BasaltDevDockProps): ReactNode;
+export {};
+//# sourceMappingURL=dev-dock.d.ts.map

package/dist/dev-dock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-dock.d.ts","sourceRoot":"","sources":["../src/dev-dock.tsx"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,uFAAuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAY5D,KAAK,aAAa,GAAG;IAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAuBjF,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAC7C,mDAAmD;IACnD,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B;oFACgF;IAChF,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;8DAC0D;IAC1D,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,qBAAqB,CAAA;CACjC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,OAAO,EACP,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,GACN,EAAE,kBAAkB,GAAG,SAAS,CA8DhC"}

package/dist/dev-dock.js

@@ -0,0 +1,85 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { lazy, Suspense } from "react";
+import { Box, CloseButton, Flex, Group, Text } from "@mantine/core";
+const TOOL_TITLE = {
+  router: "Router Devtools",
+  query: "Query Devtools",
+  theme: "Theme Lab"
+};
+const LazyRouterDevtoolsPanel = lazy(
+  () => import("@tanstack/react-router-devtools").then((m) => ({
+    default: m.TanStackRouterDevtoolsPanel
+  }))
+);
+Object.assign(LazyRouterDevtoolsPanel, { displayName: "LazyRouterDevtoolsPanel" });
+const LazyQueryDevtoolsPanel = lazy(
+  () => import("@tanstack/react-query-devtools").then((m) => ({ default: m.ReactQueryDevtoolsPanel }))
+);
+Object.assign(LazyQueryDevtoolsPanel, { displayName: "LazyQueryDevtoolsPanel" });
+const LazyThemeLabControls = lazy(
+  () => import("./theme-lab/index.js").then((m) => ({ default: m.ThemeLabControls }))
+);
+Object.assign(LazyThemeLabControls, { displayName: "LazyThemeLabControls" });
+function BasaltDevDock({
+  tool,
+  onClose,
+  router,
+  themeLab,
+  className,
+  style
+}) {
+  if (process.env["NODE_ENV"] === "production") return null;
+  if (tool === null) return null;
+  return /* @__PURE__ */ jsxs(
+    Flex,
+    {
+      direction: "column",
+      ...className !== void 0 && { className },
+      style: {
+        position: "fixed",
+        left: 0,
+        right: 0,
+        bottom: 0,
+        height: "42vh",
+        zIndex: 400,
+        background: "var(--mantine-color-body)",
+        borderTop: "1px solid var(--mantine-color-default-border)",
+        // Floating tier: a fixed dock sits above the page like a menu/drawer, so it takes
+        // basalt's overlay depth token rather than Mantine's raw shadow ramp.
+        boxShadow: "var(--vx-shadow-overlay)",
+        ...style
+      },
+      children: [
+        /* @__PURE__ */ jsxs(
+          Group,
+          {
+            justify: "space-between",
+            px: "sm",
+            py: 6,
+            style: { borderBottom: "1px solid var(--mantine-color-default-border)" },
+            children: [
+              /* @__PURE__ */ jsx(Text, { size: "xs", fw: 600, tt: "uppercase", c: "dimmed", children: TOOL_TITLE[tool] }),
+              /* @__PURE__ */ jsx(CloseButton, { size: "sm", onClick: onClose, "aria-label": "Close devtools" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx(Box, { style: { flex: 1, minHeight: 0, overflow: "auto" }, children: /* @__PURE__ */ jsxs(Suspense, { fallback: null, children: [
+          tool === "router" && router !== void 0 && /* @__PURE__ */ jsx(
+            LazyRouterDevtoolsPanel,
+            {
+              router,
+              isOpen: true,
+              setIsOpen: onClose,
+              style: { height: "100%" }
+            }
+          ),
+          tool === "query" && /* @__PURE__ */ jsx(LazyQueryDevtoolsPanel, { onClose, style: { height: "100%" } }),
+          tool === "theme" && /* @__PURE__ */ jsx(Box, { p: "md", children: /* @__PURE__ */ jsx(LazyThemeLabControls, { ...themeLab }) })
+        ] }) })
+      ]
+    }
+  );
+}
+export {
+  BasaltDevDock
+};

package/dist/format/date.d.ts

@@ -0,0 +1,62 @@
+import type { LocaleOption } from './shared.js';
+/** Axis-friendly short date: DD.MM. A non-finite or invalid date prints {@link NON_FINITE}. */
+export declare function fmtAxisDate(value: unknown): string;
+/** Tooltip-friendly long date: "Mon Apr 21 2026". A non-finite or invalid date prints
+ * {@link NON_FINITE}. */
+export declare function fmtTooltipDate(date: unknown): string;
+export type ClockOptions = LocaleOption & {
+    /** IANA zone (`'Europe/Vienna'`). Default the runtime's own zone — the same "local" argo's
+     * `d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })` call sites meant. */
+    timeZone?: string;
+    /** Render `:ss` too. Default false. */
+    seconds?: boolean;
+};
+/** A local clock reading — `"09:41"`. Seeds: `m365-explorer/explorer-page.tsx`,
+ * `walking-pad/session-history.tsx` (both `toLocaleTimeString([...], { hour: '2-digit', minute:
+ * '2-digit' })`). A non-finite/unparseable input prints {@link NON_FINITE}. */
+export declare function clock(value: Date | number | string, options?: ClockOptions): string;
+export type WeekdayOptions = LocaleOption & {
+    /** `Intl.DateTimeFormat`'s own weekday widths. Default `'short'` (`"Mon"`). */
+    format?: 'short' | 'long' | 'narrow';
+};
+/** Weekday name — seeded from `astro-window/formulas.ts#fmtWeekday`. A plain `YYYY-MM-DD` string
+ * is parsed as a LOCAL calendar date (never UTC), matching that seed's own rationale: the weekday
+ * must not shift a day depending on the reader's timezone. A non-finite/unparseable input prints
+ * {@link NON_FINITE}. */
+export declare function weekday(value: Date | number | string, options?: WeekdayOptions): string;
+export type RelativeTimeOptions = LocaleOption & {
+    /** The reference "now" instant, epoch ms. Default `Date.now()` — mainly for tests. */
+    now?: number;
+};
+/**
+ * Short relative phrase — `"3 hours ago"`, `"in 2 days"`, `"just now"`. Seeded from
+ * `agent-chat/relative-time.ts#formatRelativeTime` (epoch-ms, 'en'-hardcoded), generalized with a
+ * `locale` option and accepting `Date`/ISO-string inputs too (argo's
+ * `reading/format.ts#relativeTime` and `garmin-health/formulas.ts#formatRelativeTime` both take an
+ * ISO string). A non-finite/unparseable input prints {@link NON_FINITE} rather than throwing —
+ * `Intl.RelativeTimeFormat.format` throws a `RangeError` on non-finite input, and this is
+ * render-path code where one bad timestamp must not blank a whole list.
+ */
+export declare function relativeTime(value: number | Date | string, options?: RelativeTimeOptions): string;
+export type DurationUnit = 'seconds' | 'minutes';
+export type DurationOptions = {
+    /** Unit of the input value. Default `'seconds'`. */
+    unit?: DurationUnit;
+};
+/**
+ * Human duration — `"1h 02m"`, `"5m"`, `"42s"`. Minutes zero-pad once an hour is present (`"1h
+ * 02m"`, a clock-reading convention); alone they don't (`"5m"`). Seconds show only under a minute
+ * (`"42s"`). A non-finite value prints {@link NON_FINITE}.
+ *
+ * The one signature standing in for argo's four duration spellings: `walking-pad/
+ * formatters.ts#formatDuration` (seconds, `<60s` → `"Ns"` — this IS that shape),
+ * `reading/format.ts#formatReadTime` (seconds, no `<60s` branch, floors at `"0m"` — pass a value
+ * `>= 60` and the shapes match), `astro-window/formulas.ts#fmtMinutes` (minutes as input — pass
+ * `{ unit: 'minutes' }`). The fourth, `walking-pad/formatters.ts#formatDurationClock` (`h:mm:ss`),
+ * is {@link durationClock} below, not this.
+ */
+export declare function duration(value: number, options?: DurationOptions): string;
+/** Clock-style duration — `"1:02:03"`, `"04:12"`. Seeded from `walking-pad/
+ * formatters.ts#formatDurationClock`. A non-finite value prints {@link NON_FINITE}. */
+export declare function durationClock(seconds: number): string;
+//# sourceMappingURL=date.d.ts.map