basalt-ui 1.27.0 → 1.29.0

package/dist/controls-dates/date-range-picker.js

@@ -1,6 +1,11 @@
 import { jsx } from "react/jsx-runtime";
 import { DatePicker } from "@mantine/dates";
-function DateRangePicker({ value, onChange }) {
+import { assertRequiredProps } from "../common/validate.js";
+function DateRangePicker(props) {
+  assertRequiredProps("DateRangePicker", props, ["value"], {
+    value: "pass `{ from, to }` \u2014 usually injected by `RangeFilter`'s `customPicker`."
+  });
+  const { value, onChange } = props;
   return /* @__PURE__ */ jsx(
     DatePicker,
     {

package/dist/dashboard/delta-badge.d.ts

@@ -1,7 +1,19 @@
-/**
- * `DeltaBadge` moved to `src/widget-header/` (docs/CONTROLS-SPEC.md §2.2) so `WidgetHeader` can
- * compose it Mantine-free. Re-exported here unchanged so this deep import path — and `StatCard`'s
- * own `./delta-badge` import — keep working without a wave-3 edit.
- */
-export { DeltaBadge, type DeltaBadgeProps } from '../widget-header/delta-badge.js';
+export type DeltaPolarity = 'up-good' | 'up-bad' | 'neutral';
+export type DeltaBadgeProps = {
+    /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
+    value: number;
+    /** Which sign reads as the good verdict. `'up-good'` (default) is today's behaviour — positive
+     * success, negative danger. `'up-bad'` inverts it for a metric where a rise is the worse reading.
+     * `'neutral'` renders every sign in the faint tint — a change with no verdict attached. Zero is
+     * always faint regardless. */
+    polarity?: DeltaPolarity;
+    /** Formats the value into the label text. Defaults to `${Math.abs(value).toFixed(1)}%`. */
+    format?: (value: number) => string;
+    /** Render the ▲/▼ direction glyph. Defaults to `true`; a zero value never shows a glyph. */
+    withGlyph?: boolean;
+    /** Optional comparison timeframe rendered directly after the value in a dimmer shade of the same
+     * tone (e.g. `MoM`, `WoW`, `YTD`) — states what the delta is measured against without a hover. */
+    period?: string | undefined;
+};
+export declare function DeltaBadge({ value, polarity, format, withGlyph, period, }: DeltaBadgeProps): import("react").JSX.Element;
 //# sourceMappingURL=delta-badge.d.ts.map

package/dist/dashboard/delta-badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delta-badge.d.ts","sourceRoot":"","sources":["../../src/dashboard/delta-badge.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"delta-badge.d.ts","sourceRoot":"","sources":["../../src/dashboard/delta-badge.tsx"],"names":[],"mappings":"AA2BA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE5D,MAAM,MAAM,eAAe,GAAG;IAC5B,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb;;;kCAG8B;IAC9B,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,4FAA4F;IAC5F,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;sGACkG;IAClG,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAAA;AAWD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAoB,EACpB,MAAsB,EACtB,SAAgB,EAChB,MAAM,GACP,EAAE,eAAe,+BAejB"}

package/dist/dashboard/delta-badge.js

@@ -1,4 +1,36 @@
-import { DeltaBadge } from "../widget-header/delta-badge.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { alpha, VX } from "../tokens/index.js";
+import classes from "./widget-header.module.css";
+const defaultFormat = (value) => `${Math.abs(value).toFixed(1)}%`;
+function resolveTone(value, polarity) {
+  if (value === 0 || polarity === "neutral") return VX.faint;
+  const rose = value > 0;
+  const good = polarity === "up-good" ? rose : !rose;
+  return good ? VX.status.good : VX.status.bad;
+}
+function DeltaBadge({
+  value,
+  polarity = "up-good",
+  format = defaultFormat,
+  withGlyph = true,
+  period
+}) {
+  const tone = resolveTone(value, polarity);
+  const glyph = value > 0 ? "\u25B2" : value < 0 ? "\u25BC" : void 0;
+  const showGlyph = withGlyph && glyph !== void 0;
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      className: classes.deltaBadge,
+      style: { backgroundColor: alpha(tone, 0.13), color: tone },
+      children: [
+        showGlyph && /* @__PURE__ */ jsx("span", { className: classes.deltaGlyph, children: glyph }),
+        format(value),
+        period !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.deltaPeriod, children: period })
+      ]
+    }
+  );
+}
 export {
   DeltaBadge
 };

package/dist/dashboard/empty-state.d.ts

@@ -1,5 +1,8 @@
 import type { ReactNode } from 'react';
-export type EmptyStateProps = {
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+/** The five boxes `EmptyState` paints, and the whole styling seam it offers (`common/props.ts`). */
+export type EmptyStateSlot = 'root' | 'icon' | 'title' | 'description' | 'action';
+export type EmptyStateProps = BasaltProps & SlotStylesProps<EmptyStateSlot> & {
     /** Optional glyph slot, rendered faint at ~28-32px. No shipped illustration assets. */
     icon?: ReactNode;
     /** Head-font title (18px, weight 550, ink). */
@@ -12,8 +15,9 @@ export type EmptyStateProps = {
     description?: string;
     /** Optional call-to-action rendered below the description. */
     action?: ReactNode;
-    /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */
-    variant?: 'page' | 'section';
+    /** How loud this state is: `'page'` (default) = generous padding for a full-page state;
+     * `'section'` = compact. */
+    tier?: 'page' | 'section';
 };
-export declare function EmptyState({ icon, title, description, action, variant, }: EmptyStateProps): import("react").JSX.Element;
+export declare function EmptyState({ icon, title, description, action, tier, className, style, classNames, }: EmptyStateProps): import("react").JSX.Element;
 //# sourceMappingURL=empty-state.d.ts.map

package/dist/dashboard/empty-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAgB,GACjB,EAAE,eAAe,+BA4BjB"}
+{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEnE,oGAAoG;AACpG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAA;AAEjF,MAAM,MAAM,eAAe,GAAG,WAAW,GACvC,eAAe,CAAC,cAAc,CAAC,GAAG;IAChC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;gCAC4B;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B,CAAA;AAaH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,IAAI,EACJ,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,eAAe,+BAkDjB"}

package/dist/dashboard/empty-state.js

@@ -1,27 +1,49 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Center, Stack } from "@mantine/core";
 import { VX } from "../tokens/index.js";
+import { cx } from "../common/props.js";
+const STACK_XS = "var(--vx-space-stack-xs, 0.25rem)";
+const PAGE_PADDING_Y = `calc(${STACK_XS} * 16)`;
+const PAGE_PADDING_X = `calc(${STACK_XS} * 6)`;
+const SECTION_PADDING_Y = `calc(${STACK_XS} * 8)`;
+const SECTION_PADDING_X = `calc(${STACK_XS} * 5)`;
 function EmptyState({
   icon,
   title,
   description,
   action,
-  variant = "page"
+  tier,
+  className,
+  style,
+  classNames
 }) {
+  const resolved = tier ?? "page";
   return /* @__PURE__ */ jsxs(
     Stack,
     {
       align: "center",
       gap: "xs",
+      className: cx(classNames?.root, className),
       style: {
-        padding: variant === "page" ? "64px 24px" : "32px 20px",
-        textAlign: "center"
+        padding: resolved === "page" ? `${PAGE_PADDING_Y} ${PAGE_PADDING_X}` : `${SECTION_PADDING_Y} ${SECTION_PADDING_X}`,
+        textAlign: "center",
+        ...style
       },
       children: [
-        icon && /* @__PURE__ */ jsx(Center, { style: { width: 32, height: 32, color: VX.faint }, children: icon }),
+        icon && // 32px is a fixed glyph-box size, not a density-tracking inset — no `--vx-icon-*` token
+        // exists for a generic (non-`WidgetHeader`-tiered) icon slot, so it stays a structural rem.
+        /* @__PURE__ */ jsx(
+          Center,
+          {
+            ...classNames?.icon !== void 0 && { className: classNames.icon },
+            style: { width: "2rem", height: "2rem", color: VX.faint },
+            children: icon
+          }
+        ),
         /* @__PURE__ */ jsx(
           "span",
           {
+            className: classNames?.title,
             style: {
               fontFamily: "var(--basalt-font-head)",
               fontStretch: "88%",
@@ -32,8 +54,16 @@ function EmptyState({
             children: title
           }
         ),
-        description !== void 0 && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }, children: description }),
-        action
+        description !== void 0 && // 360px (22.5rem) is a reading-width cap, not a density inset — kept structural.
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: classNames?.description,
+            style: { fontSize: VX.text.md, color: VX.muted, maxWidth: "22.5rem" },
+            children: description
+          }
+        ),
+        action !== void 0 && /* @__PURE__ */ jsx("div", { className: classNames?.action, children: action })
       ]
     }
   );

package/dist/dashboard/index.d.ts

@@ -1,6 +1,10 @@
-export { DeltaBadge, type DeltaBadgeProps } from './delta-badge.js';
-export { StatCard, type StatCardBreakdownRow, type StatCardProps, type StatCardTone, } from './stat-card.js';
-export { EmptyState, type EmptyStateProps } from './empty-state.js';
-export { SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './settings-section.js';
-export { QueryState, type QueryStateProps, type QueryStateLike, type QueryStateVariant, type QueryEmptyCopy, LoadingState, type LoadingStateProps, ErrorState, type ErrorStateProps, } from './query-state.js';
+export { WidgetHeader, type WidgetHeaderDeltaProps, type WidgetHeaderMetricProps, type WidgetHeaderProps, type WidgetHeaderSlot, type WidgetHeaderTier, type WidgetHeaderTitleProps, } from './widget-header.js';
+export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from './delta-badge.js';
+export { Section, type SectionProps, type SectionSlot } from './section.js';
+export { StatCard, type StatCardBreakdownRow, type StatCardProps, type StatCardSlot, type StatCardTone, } from './stat-card.js';
+export { WidgetGrid, type WidgetGridCols, type WidgetGridItemProps, type WidgetGridProps, } from './widget-grid.js';
+export { StatGroup, type StatGroupCols, type StatGroupProps } from './stat-group.js';
+export { EmptyState, type EmptyStateProps, type EmptyStateSlot } from './empty-state.js';
+export { SettingsSection, type SettingsSectionProps, type SettingsSectionSlot, SettingsRow, type SettingsRowProps, type SettingsRowSlot, DangerZone, type DangerZoneProps, } from './settings-section.js';
+export { QueryState, type QueryStateProps, type QueryStateLike, type QueryStateSlot, type QueryStateTier, type QueryEmptyCopy, LoadingState, type LoadingStateProps, ErrorState, type ErrorStateProps, } from './query-state.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EACL,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AACjF,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA"}

package/dist/dashboard/index.js

@@ -1,7 +1,15 @@
+import {
+  WidgetHeader
+} from "./widget-header.js";
 import { DeltaBadge } from "./delta-badge.js";
+import { Section } from "./section.js";
 import {
   StatCard
 } from "./stat-card.js";
+import {
+  WidgetGrid
+} from "./widget-grid.js";
+import { StatGroup } from "./stat-group.js";
 import { EmptyState } from "./empty-state.js";
 import {
   SettingsSection,
@@ -20,7 +28,11 @@ export {
   ErrorState,
   LoadingState,
   QueryState,
+  Section,
   SettingsRow,
   SettingsSection,
-  StatCard
+  StatCard,
+  StatGroup,
+  WidgetGrid,
+  WidgetHeader
 };

package/dist/dashboard/query-state.d.ts

@@ -1,24 +1,22 @@
 import type { ReactNode } from 'react';
-/** `'page'` = a full route body (generous padding). `'section'` = a card/panel region (compact). */
-export type QueryStateVariant = 'page' | 'section';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { QueryStateLike } from '../common/query-state-like.js';
 /**
- * The structural subset of a TanStack `UseQueryResult` these components read.
+ * How loud this state is: `'page'` = a full route body (generous padding), `'section'` = a
+ * card/panel region (compact).
  *
- * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast, and
- * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
- * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
- * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is
- * that the compiler stops policing the shape — which is why {@link QueryState} asserts it at
- * runtime.
+ * Named `tier`, not `variant` (audit B #19): `tier` is already the package's word for "how loud is
+ * this" on `WidgetHeader` and `CtlSlot`, and `'section'` meant two different things across the two
+ * spellings.
  */
-export type QueryStateLike<TData> = {
-    data: TData | undefined;
-    isError: boolean;
-    error: unknown;
-    fetchStatus: 'fetching' | 'paused' | 'idle';
-    refetch: () => unknown;
-};
+export type QueryStateTier = 'page' | 'section';
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read — defined in
+ * `common/query-state-like.ts` and re-exported here, where consumers have always imported it from.
+ * The runtime assertion over it lives beside the type, because `./data`'s containers read the same
+ * envelope and a second copy of the check had already drifted to a weaker one.
+ */
+export type { QueryStateLike };
 /** Copy for the empty branch. Rendered through `EmptyState`, so it looks like every other one. */
 export type QueryEmptyCopy = {
     title: string;
@@ -29,14 +27,15 @@ export type QueryEmptyCopy = {
     /** Call-to-action below the copy (e.g. "Reset filters"). */
     action?: ReactNode;
 };
-export type LoadingStateProps = {
-    variant?: QueryStateVariant;
+export type LoadingStateProps = BasaltProps & {
+    /** How loud this state is. Default `'page'`. */
+    tier?: QueryStateTier;
     /** Accessible name for the spinner. Say what is loading. */
     label?: string;
 };
-/** A spinner on its own — `variant="page"` centres it in a generous block, `'section'` is bare. */
-export declare function LoadingState({ variant, label, }: LoadingStateProps): ReactNode;
-export type ErrorStateProps = {
+/** A spinner on its own — `tier="page"` centres it in a generous block, `'section'` is bare. */
+export declare function LoadingState({ tier, label, className, style, }: LoadingStateProps): ReactNode;
+export type ErrorStateProps = BasaltProps & {
     /** Whatever was thrown — the raw Eden/fetch envelope is fine, it gets decoded. */
     error: unknown;
     /** Alert heading. Say what failed, e.g. `Could not load images`. */
@@ -46,7 +45,8 @@ export type ErrorStateProps = {
     onRetry?: () => void;
     /** Disables/spins the retry button while a refetch is in flight. */
     retrying?: boolean;
-    variant?: QueryStateVariant;
+    /** How loud this state is. Default `'page'`. */
+    tier?: QueryStateTier;
     /** Extra controls beside Retry (e.g. a "Back to shares" link). */
     action?: ReactNode;
 };
@@ -54,8 +54,19 @@ export type ErrorStateProps = {
  * The error branch: the REAL server message (via `toErrorMessage`) plus a retry. Usable on its own,
  * outside a query — an auth gate or a boundary fallback renders it directly.
  */
-export declare function ErrorState({ error, title, fallback, onRetry, retrying, variant, action, }: ErrorStateProps): ReactNode;
-export type QueryStateProps<TData> = {
+export declare function ErrorState({ error, title, fallback, onRetry, retrying, tier, action, className, style, }: ErrorStateProps): ReactNode;
+/**
+ * ONE slot, and the single-member union is the statement (`common/props.ts` lists this among the
+ * composites): `root` is whichever branch is live — the error alert's stack, the spinner's centre,
+ * the empty state, or the cached-data wrapper. `QueryState` renders exactly one of them at a time
+ * and never two boxes at once, so there is no second slot to name; `className` and `classNames.root`
+ * both land on it, joined rather than one replacing the other.
+ *
+ * A branch a consumer wants styled DIFFERENTLY from its siblings is `LoadingState`/`ErrorState`/
+ * `EmptyState` placed by hand — that escape hatch is why they ship.
+ */
+export type QueryStateSlot = 'root';
+export type QueryStateProps<TData> = BasaltProps & SlotStylesProps<QueryStateSlot> & {
     query: QueryStateLike<TData>;
     /** A render function gets `data` narrowed to non-undefined; a plain node also works. */
     children: ReactNode | ((data: TData) => ReactNode);
@@ -69,7 +80,8 @@ export type QueryStateProps<TData> = {
     errorFallback?: string;
     /** Extra controls beside Retry on the error branch. */
     errorAction?: ReactNode;
-    variant?: QueryStateVariant;
+    /** How loud every branch is. Default `'page'`. */
+    tier?: QueryStateTier;
     /** Replace the default spinner (e.g. with a skeleton grid). */
     loading?: ReactNode;
 };
@@ -92,5 +104,5 @@ export type QueryStateProps<TData> = {
  *   {(data) => <ImageGrid images={data.rows} />}
  * </QueryState>
  */
-export declare function QueryState<TData>({ query, children, empty, isEmpty, errorTitle, errorFallback, errorAction, variant, loading, }: QueryStateProps<TData>): ReactNode;
+export declare function QueryState<TData>({ query, children, empty, isEmpty, errorTitle, errorFallback, errorAction, tier, loading, className, style, classNames, }: QueryStateProps<TData>): ReactNode;
 //# sourceMappingURL=query-state.d.ts.map

package/dist/dashboard/query-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/query-state.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,oGAAoG;AACpG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAA;AAElD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAID,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,EAC3B,OAAgB,EAChB,KAAiB,GAClB,EAAE,iBAAiB,GAAG,SAAS,CAI/B;AAID,MAAM,MAAM,eAAe,GAAG;IAC5B,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAA8B,EAC9B,QAAgC,EAChC,OAAO,EACP,QAAgB,EAChB,OAAgB,EAChB,MAAM,GACP,EAAE,eAAe,GAAG,SAAS,CAoB7B;AAyCD,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IACnC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IAClD,uDAAuD;IACvD,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,EAChC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,OAAO,EACP,UAA6B,EAC7B,aAAqC,EACrC,WAAW,EACX,OAAgB,EAChB,OAAO,GACR,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,SAAS,CAiDpC"}
+{"version":3,"file":"query-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/query-state.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,CAAA;AAE/C;;;;;GAKG;AACH,YAAY,EAAE,cAAc,EAAE,CAAA;AAE9B,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAID,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,gDAAgD;IAChD,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,gGAAgG;AAChG,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAiB,EACjB,SAAS,EACT,KAAK,GACN,EAAE,iBAAiB,GAAG,SAAS,CAuB/B;AAID,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gDAAgD;IAChD,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAA8B,EAC9B,QAAgC,EAChC,OAAO,EACP,QAAgB,EAChB,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,eAAe,GAAG,SAAS,CAmC7B;AAcD;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI,WAAW,GAC9C,eAAe,CAAC,cAAc,CAAC,GAAG;IAChC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IAClD,uDAAuD;IACvD,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,kDAAkD;IAClD,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,EAChC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,OAAO,EACP,UAA6B,EAC7B,aAAqC,EACrC,WAAW,EACX,IAAI,EACJ,OAAO,EACP,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,SAAS,CAqEpC"}

package/dist/dashboard/query-state.js

@@ -1,14 +1,35 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Alert, Button, Center, Group, Loader, Stack, Text } from "@mantine/core";
-import { toErrorMessage } from "../query/error-message.js";
+import { toErrorMessage } from "../common/errors.js";
+import { cx } from "../common/props.js";
 import { EmptyState } from "./empty-state.js";
+import { assertQueryStateLike } from "../common/query-state-like.js";
 function LoadingState({
-  variant = "page",
-  label = "Loading"
+  tier,
+  label = "Loading",
+  className,
+  style
 }) {
-  const loader = /* @__PURE__ */ jsx(Loader, { size: "sm", "aria-label": label });
-  if (variant === "section") return loader;
-  return /* @__PURE__ */ jsx(Center, { py: 64, children: loader });
+  const resolved = tier ?? "page";
+  if (resolved === "section") {
+    return /* @__PURE__ */ jsx(
+      Loader,
+      {
+        size: "sm",
+        "aria-label": label,
+        ...className !== void 0 && { className },
+        ...style !== void 0 && { style }
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    Center,
+    {
+      ...className !== void 0 && { className },
+      style: { paddingBlock: "calc(var(--vx-space-stack-xs, 0.25rem) * 16)", ...style },
+      children: /* @__PURE__ */ jsx(Loader, { size: "sm", "aria-label": label })
+    }
+  );
 }
 function ErrorState({
   error,
@@ -16,18 +37,39 @@ function ErrorState({
   fallback = "The request failed.",
   onRetry,
   retrying = false,
-  variant = "page",
-  action
+  tier,
+  action,
+  className,
+  style
 }) {
-  const alert = /* @__PURE__ */ jsx(Alert, { color: "red", variant: "light", title, children: /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
-    /* @__PURE__ */ jsx(Text, { size: "sm", children: toErrorMessage(error, fallback) }),
-    (onRetry ?? action) !== void 0 && /* @__PURE__ */ jsxs(Group, { gap: "xs", children: [
-      onRetry && /* @__PURE__ */ jsx(Button, { size: "xs", variant: "default", loading: retrying, onClick: onRetry, children: "Retry" }),
-      action
-    ] })
-  ] }) });
-  if (variant === "section") return alert;
-  return /* @__PURE__ */ jsx(Stack, { py: "md", children: alert });
+  const resolved = tier ?? "page";
+  const alert = /* @__PURE__ */ jsx(
+    Alert,
+    {
+      color: "red",
+      variant: "light",
+      title,
+      ...resolved === "section" && className !== void 0 && { className },
+      ...resolved === "section" && style !== void 0 && { style },
+      children: /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
+        /* @__PURE__ */ jsx(Text, { size: "sm", children: toErrorMessage(error, fallback) }),
+        (onRetry ?? action) !== void 0 && /* @__PURE__ */ jsxs(Group, { gap: "xs", children: [
+          onRetry && /* @__PURE__ */ jsx(Button, { size: "xs", variant: "default", loading: retrying, onClick: onRetry, children: "Retry" }),
+          action
+        ] })
+      ] })
+    }
+  );
+  if (resolved === "section") return alert;
+  return /* @__PURE__ */ jsx(
+    Stack,
+    {
+      py: "md",
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style },
+      children: alert
+    }
+  );
 }
 function defaultIsEmpty(data) {
   if (data === null || data === void 0) return true;
@@ -37,22 +79,6 @@ function defaultIsEmpty(data) {
   }
   return false;
 }
-const FETCH_STATUSES = /* @__PURE__ */ new Set(["fetching", "paused", "idle"]);
-function assertQueryStateLike(query) {
-  const bad = (detail) => {
-    throw new Error(
-      `QueryState: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } \u2014 a TanStack UseQueryResult does; a hand-composed one must spell every field, because a missing branch flag renders a false claim about the data instead of an error.`
-    );
-  };
-  if (query === null || typeof query !== "object")
-    bad(`is ${query === null ? "null" : typeof query}`);
-  const q = query;
-  if (!("data" in q)) bad("has no `data` key");
-  if (typeof q["isError"] !== "boolean") bad("has no boolean `isError`");
-  if (typeof q["fetchStatus"] !== "string" || !FETCH_STATUSES.has(q["fetchStatus"]))
-    bad(`has fetchStatus=${JSON.stringify(q["fetchStatus"])}, not 'fetching' | 'paused' | 'idle'`);
-  if (typeof q["refetch"] !== "function") bad("has no `refetch()`");
-}
 function QueryState({
   query,
   children,
@@ -61,10 +87,15 @@ function QueryState({
   errorTitle = "Could not load",
   errorFallback = "The request failed.",
   errorAction,
-  variant = "page",
-  loading
+  tier,
+  loading,
+  className,
+  style,
+  classNames
 }) {
-  assertQueryStateLike(query);
+  assertQueryStateLike("QueryState", query);
+  const resolvedTier = tier ?? "page";
+  const rootClassName = cx(classNames?.root, className) || void 0;
   const { data, isError, error, fetchStatus } = query;
   const retrying = fetchStatus === "fetching";
   const retry = () => void query.refetch();
@@ -77,42 +108,62 @@ function QueryState({
         fallback: errorFallback,
         onRetry: retry,
         retrying,
-        variant,
-        ...errorAction !== void 0 && { action: errorAction }
+        tier: resolvedTier,
+        ...errorAction !== void 0 && { action: errorAction },
+        ...rootClassName !== void 0 && { className: rootClassName },
+        ...style !== void 0 && { style }
       }
     );
   }
   if (data === void 0) {
-    if (fetchStatus === "idle" && !isError) return empty ? renderEmpty(empty, variant) : null;
-    return loading ?? /* @__PURE__ */ jsx(LoadingState, { variant });
+    if (fetchStatus === "idle" && !isError)
+      return empty ? renderEmpty(empty, resolvedTier, rootClassName, style) : null;
+    return loading ?? /* @__PURE__ */ jsx(
+      LoadingState,
+      {
+        tier: resolvedTier,
+        ...rootClassName !== void 0 && { className: rootClassName },
+        ...style !== void 0 && { style }
+      }
+    );
   }
   const emptyNow = isEmpty ? isEmpty(data) : defaultIsEmpty(data);
-  const body = emptyNow ? empty ? renderEmpty(empty, variant) : null : typeof children === "function" ? children(data) : children;
+  const body = emptyNow ? empty ? renderEmpty(empty, resolvedTier, rootClassName, style) : null : typeof children === "function" ? children(data) : children;
   if (!isError) return body;
-  return /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
-    /* @__PURE__ */ jsx(
-      ErrorState,
-      {
-        error,
-        title: "Showing cached data",
-        fallback: "The last refresh failed.",
-        onRetry: retry,
-        retrying,
-        variant: "section"
-      }
-    ),
-    body
-  ] });
+  return /* @__PURE__ */ jsxs(
+    Stack,
+    {
+      gap: "sm",
+      ...rootClassName !== void 0 && { className: rootClassName },
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsx(
+          ErrorState,
+          {
+            error,
+            title: "Showing cached data",
+            fallback: "The last refresh failed.",
+            onRetry: retry,
+            retrying,
+            tier: "section"
+          }
+        ),
+        body
+      ]
+    }
+  );
 }
-function renderEmpty(empty, variant) {
+function renderEmpty(empty, tier, className, style) {
   return /* @__PURE__ */ jsx(
     EmptyState,
     {
       title: empty.title,
-      variant,
+      tier,
       ...empty.description !== void 0 && { description: empty.description },
       ...empty.icon !== void 0 && { icon: empty.icon },
-      ...empty.action !== void 0 && { action: empty.action }
+      ...empty.action !== void 0 && { action: empty.action },
+      ...className !== void 0 && { className },
+      ...style !== void 0 && { style }
     }
   );
 }