basalt-ui 1.27.0 → 1.29.0

package/dist/dashboard/section.d.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { SlotActions } from '../controls/actions.js';
+import type { QueryEmptyCopy, QueryStateLike } from './query-state.js';
+import type { WidgetHeaderProps } from './widget-header.js';
+/**
+ * The three boxes `Section` paints, and the whole styling seam it offers (`common/props.ts`):
+ * `root` is the outer stack, `header` is the `WidgetHeader` row, `body` is the collapsible content
+ * box. `summary` is deliberately absent — it is a one-row readout under the header, not a layout
+ * box a consumer positions.
+ */
+export type SectionSlot = 'root' | 'header' | 'body';
+export type SectionProps = Omit<WidgetHeaderProps, 'tier' | 'classNames' | 'actions'> & BasaltProps & SlotStylesProps<SectionSlot> & {
+    /**
+     * Header actions, in either form (law C15): a typed `BarAction[]`, which basalt projects through
+     * the SAME row `PageBar` and `ActionGroup` use — ≤3 inline, the rest folded into `More`, one
+     * kebab below `sm` — or an opaque `ReactNode` a caller drew itself, rendered verbatim. The ≤3
+     * budget (C6) is checked against whichever form is given.
+     */
+    actions?: SlotActions;
+    /**
+     * The section's async result. Given one, the BODY renders through `QueryState` at the section
+     * tier — pending / error-with-retry / empty each REPLACE `children`, data renders them — while
+     * the header, the fold chevron and `summary` stay drawn throughout, so a section never blinks out
+     * of the page while it refetches.
+     *
+     * This is law C3's uniform container contract (`docs/CONTROLS-SPEC.md` §1): without it every
+     * caller re-derives the four-way switch `QueryState` exists to delete, and gets it wrong in the
+     * one direction that matters — "nothing here" printed over a 500.
+     */
+    query?: QueryStateLike<unknown>;
+    /**
+     * Copy for `query`'s EMPTY branch, rendered through `EmptyState` like every other one. Omit to
+     * render nothing when the result is empty — `QueryState`'s own contract, unchanged. Ignored
+     * without `query`.
+     */
+    empty?: QueryEmptyCopy;
+    /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
+    tabs?: ReactNode;
+    /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
+     * (and `tabs`) unmount. @default false */
+    collapsible?: boolean;
+    /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
+     * (`useState`). */
+    persistKey?: string;
+    /** The fold state a section opens on, respected only while no persisted value exists — a section
+     * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
+    defaultOpen?: boolean;
+    /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
+     * still states its headline figures, which is what makes collapsing it a real option. Keep it to
+     * one row — the body is what `children` is for. */
+    summary?: ReactNode;
+    /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
+    id?: string;
+    children: ReactNode;
+};
+export declare function Section({ actions, query, empty, tabs, collapsible, persistKey, defaultOpen, summary, id, children, className, style, classNames, ...headerProps }: SectionProps): import("react").JSX.Element;
+//# sourceMappingURL=section.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../src/dashboard/section.tsx"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAGtD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAGxD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAMpD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC,GACnF,WAAW,GACX,eAAe,CAAC,WAAW,CAAC,GAAG;IAC7B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;uGACmG;IACnG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;uDAEmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAyDH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,KAAK,EACL,IAAI,EACJ,WAAmB,EACnB,UAAU,EACV,WAAkB,EAClB,OAAO,EACP,EAAE,EACF,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,EACV,GAAG,WAAW,EACf,EAAE,YAAY,+BA4Fd"}

package/dist/dashboard/section.js

@@ -0,0 +1,118 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Children, useId } from "react";
+import { cx } from "../common/props.js";
+import { BASALT_PREFIX } from "../common/errors.js";
+import { useValidateProps } from "../common/validate.js";
+import { CtlSlot } from "../theme/index.js";
+import { BarActionSlot, isBarActionList } from "../controls/actions.js";
+import { useFilterSurface } from "../controls/filter-context.js";
+import { QueryState } from "./query-state.js";
+import { usePersistedOrLocal } from "../state/persisted-or-local.js";
+import { WidgetHeader } from "./widget-header.js";
+import classes from "./section.module.css";
+function actionBudgetMessage(title, actions) {
+  const count = isBarActionList(actions) ? actions.length : Children.count(actions);
+  if (count <= 3) return null;
+  return `${BASALT_PREFIX} Section "${title}": ${count} actions exceeds the \u22643 budget (docs/CONTROLS-SPEC.md C6) \u2014 move the rest behind a menu.`;
+}
+function ChevronToggle({
+  open,
+  onToggle,
+  controls
+}) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: classes.chevron,
+      "data-open": open,
+      "aria-expanded": open,
+      "aria-controls": controls,
+      "aria-label": open ? "Collapse section" : "Expand section",
+      onClick: onToggle,
+      children: /* @__PURE__ */ jsx(
+        "svg",
+        {
+          width: 12,
+          height: 12,
+          viewBox: "0 0 24 24",
+          fill: "none",
+          stroke: "currentColor",
+          strokeWidth: 2.5,
+          "aria-hidden": "true",
+          children: /* @__PURE__ */ jsx("path", { d: "M6 9l6 6 6-6", strokeLinecap: "round", strokeLinejoin: "round" })
+        }
+      )
+    }
+  );
+}
+function Section({
+  actions,
+  query,
+  empty,
+  tabs,
+  collapsible = false,
+  persistKey,
+  defaultOpen = true,
+  summary,
+  id,
+  children,
+  className,
+  style,
+  classNames,
+  ...headerProps
+}) {
+  const { title } = headerProps;
+  useValidateProps(
+    "Section",
+    () => [
+      persistKey !== void 0 && !collapsible ? `${BASALT_PREFIX} Section "${title}": \`persistKey\` is set but \`collapsible\` is false \u2014 there is no fold to persist. Add \`collapsible\`, or drop \`persistKey\`.` : null,
+      actions === void 0 ? null : actionBudgetMessage(title, actions)
+    ],
+    [persistKey, collapsible, title, actions]
+  );
+  const [open, setOpen] = usePersistedOrLocal({
+    scope: "section",
+    persistKey,
+    initial: defaultOpen
+  });
+  const bodyId = useId();
+  const tier = useFilterSurface() === "pill" ? "section" : "group";
+  const anchorStyle = id === void 0 ? void 0 : { scrollMarginTop: "var(--vx-space-sticky-header-clearance)" };
+  const rootStyle = anchorStyle === void 0 && style === void 0 ? void 0 : { ...anchorStyle, ...style };
+  const headerActions = tabs !== void 0 || actions !== void 0 || collapsible ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    tabs !== void 0 && open && /* @__PURE__ */ jsx(CtlSlot, { children: tabs }),
+    actions !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: /* @__PURE__ */ jsx(BarActionSlot, { actions }) }),
+    collapsible && /* @__PURE__ */ jsx(ChevronToggle, { open, onToggle: () => setOpen(!open), controls: bodyId })
+  ] }) : void 0;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(classes.root, classNames?.root, className),
+      "data-tier": tier,
+      ...id !== void 0 && { id },
+      ...rootStyle !== void 0 && { style: rootStyle },
+      children: [
+        /* @__PURE__ */ jsx(
+          WidgetHeader,
+          {
+            tier,
+            ...headerProps,
+            ...classNames?.header !== void 0 && { className: classNames.header },
+            ...headerActions !== void 0 && { actions: headerActions }
+          }
+        ),
+        summary !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.summary, children: summary }),
+        open && /* @__PURE__ */ jsx("div", { id: bodyId, className: cx(classes.body, classNames?.body), children: query === void 0 ? children : (
+          // `tier="section"` is the compact one: a bare spinner rather than a 64px centred
+          // block, and the error alert without the page-level stack around it. A Section IS the
+          // region, so the state belongs inside its body, never around its header.
+          /* @__PURE__ */ jsx(QueryState, { query, tier: "section", ...empty !== void 0 && { empty }, children })
+        ) })
+      ]
+    }
+  );
+}
+export {
+  Section
+};

package/dist/{section → dashboard}/section.module.css

@@ -22,6 +22,17 @@
   gap: var(--vx-space-stack-md, 0.75rem);
 }
 
+/*
+ * `group` tier (an aside/inspector Section): zero gap between children. `PanelRow`s already own
+ * their own vertical rhythm — `--vx-space-row-inset-y` (6px) plus the `.row + .row` hairline — so
+ * stacking the 12px `stack-md` gap ON TOP made a one-line row's pitch 55px with the hairline sitting
+ * 33/22 off-centre in it. At gap 0 the pitch is 43px and the rule is centred (Trellis ≈29, Quiver
+ * ≈33, the sidebar's own rows 33) — no negative margins, the gap simply isn't there to fight.
+ */
+.root[data-tier='group'] .body {
+  gap: 0;
+}
+
 /*
  * `summary` — the always-visible row under the header. No border, no background (the Section owns
  * neither); it is a plain flow row, so a consumer's `Group` of stats or one line of `Text` lands

package/dist/dashboard/settings-section.d.ts

@@ -1,16 +1,26 @@
 import type { ReactNode } from 'react';
-export type SettingsSectionProps = {
-    /** Head-font section title, rendered via `WidgetHeader tier="section"`. */
-    title: string;
-    /** Optional 13px muted description below the title. */
-    subtitle?: string;
+import type { WidgetHeaderTitleProps } from './widget-header.js';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+/** The three boxes `SettingsSection`/`DangerZone` paint (`common/props.ts`). */
+export type SettingsSectionSlot = 'root' | 'header' | 'body';
+/**
+ * Composed from the named `WidgetHeaderTitleProps` slice (audit B #2) rather than a hand-picked
+ * `title`/`subtitle` pair — which is why `icon` and `info` now reach the header too. `value`/`delta`
+ * are deliberately NOT taken: a settings section groups controls, it states no metric.
+ *
+ * `Section` and `ChartCard` still cut their own ad-hoc subsets; both should move onto the same
+ * slices.
+ */
+export type SettingsSectionProps = BasaltProps & SlotStylesProps<SettingsSectionSlot> & WidgetHeaderTitleProps & {
     /** Header-right slot — wrapped in `CtlSlot` (C1/C5). */
     actions?: ReactNode;
     /** Section body — typically a stack of `SettingsRow`s. */
     children: ReactNode;
 };
-export declare function SettingsSection({ title, subtitle, actions, children }: SettingsSectionProps): import("react").JSX.Element;
-export type SettingsRowProps = {
+export declare function SettingsSection({ title, icon, subtitle, info, actions, children, className, style, classNames, }: SettingsSectionProps): import("react").JSX.Element;
+/** The three boxes `SettingsRow` paints (`common/props.ts`). */
+export type SettingsRowSlot = 'root' | 'label' | 'control';
+export type SettingsRowProps = BasaltProps & SlotStylesProps<SettingsRowSlot> & {
     /** 13px ink label on the left. */
     label: string;
     /** Optional 12.5px muted description under the label. */
@@ -20,7 +30,7 @@ export type SettingsRowProps = {
     /** Alternative to `control` for a fully custom right-hand region. */
     children?: ReactNode;
 };
-export declare function SettingsRow({ label, description, control, children }: SettingsRowProps): import("react").JSX.Element;
+export declare function SettingsRow({ label, description, control, children, className, style, classNames, }: SettingsRowProps): import("react").JSX.Element;
 export type DangerZoneProps = SettingsSectionProps;
-export declare function DangerZone({ title, subtitle, actions, children }: DangerZoneProps): import("react").JSX.Element;
+export declare function DangerZone({ title, icon, subtitle, info, actions, children, className, style, classNames, }: DangerZoneProps): import("react").JSX.Element;
 //# sourceMappingURL=settings-section.d.ts.map

package/dist/dashboard/settings-section.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/dashboard/settings-section.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAetC,MAAM,MAAM,oBAAoB,GAAG;IACjC,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BAc3F;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAED,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,gBAAgB,+BAYtF;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAA;AAElD,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,eAAe,+BAoBjF"}
+{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/dashboard/settings-section.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAI7D,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAYnE,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAC5C,eAAe,CAAC,mBAAmB,CAAC,GACpC,sBAAsB,GAAG;IACvB,wDAAwD;IACxD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,oBAAoB,+BAmBtB;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAE1D,MAAM,MAAM,gBAAgB,GAAG,WAAW,GACxC,eAAe,CAAC,eAAe,CAAC,GAAG;IACjC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAEH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,OAAO,EACP,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,gBAAgB,+BAelB;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAA;AAElD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,eAAe,+BAwBjB"}

package/dist/dashboard/settings-section.js

@@ -1,8 +1,9 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Card, Stack } from "@mantine/core";
-import { WidgetHeader } from "../widget-header/index.js";
+import { WidgetHeader } from "./widget-header.js";
 import { CtlSlot } from "../theme/index.js";
 import { alpha, VX } from "../tokens/index.js";
+import { cx } from "../common/props.js";
 import classes from "./settings-section.module.css";
 const eyebrowStyle = {
   fontFamily: "var(--basalt-font-mono)",
@@ -12,51 +13,99 @@ const eyebrowStyle = {
   textTransform: "uppercase",
   color: VX.status.bad
 };
-function SettingsSection({ title, subtitle, actions, children }) {
-  return /* @__PURE__ */ jsxs(Card, { style: { padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)" }, children: [
-    /* @__PURE__ */ jsx("div", { className: classes.header, children: /* @__PURE__ */ jsx(
-      WidgetHeader,
-      {
-        tier: "section",
-        title,
-        ...subtitle !== void 0 && { subtitle },
-        ...actions !== void 0 && { actions: /* @__PURE__ */ jsx(CtlSlot, { children: actions }) }
-      }
-    ) }),
-    /* @__PURE__ */ jsx("div", { className: classes.rows, children })
-  ] });
+function SettingsSection({
+  title,
+  icon,
+  subtitle,
+  info,
+  actions,
+  children,
+  className,
+  style,
+  classNames
+}) {
+  return /* @__PURE__ */ jsxs(
+    Card,
+    {
+      className: cx(classNames?.root, className),
+      style: { padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)", ...style },
+      children: [
+        /* @__PURE__ */ jsx("div", { className: cx(classes.header, classNames?.header), children: /* @__PURE__ */ jsx(
+          WidgetHeader,
+          {
+            tier: "section",
+            title,
+            ...icon !== void 0 && { icon },
+            ...subtitle !== void 0 && { subtitle },
+            ...info !== void 0 && { info },
+            ...actions !== void 0 && { actions: /* @__PURE__ */ jsx(CtlSlot, { children: actions }) }
+          }
+        ) }),
+        /* @__PURE__ */ jsx("div", { className: cx(classes.rows, classNames?.body), children })
+      ]
+    }
+  );
 }
-function SettingsRow({ label, description, control, children }) {
-  return /* @__PURE__ */ jsxs("div", { className: classes.row, children: [
-    /* @__PURE__ */ jsxs(Stack, { gap: 2, children: [
-      /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.ink }, children: label }),
-      description && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.sm, color: VX.muted }, children: description })
-    ] }),
-    /* @__PURE__ */ jsx("div", { className: classes.control, children: control ?? children })
-  ] });
+function SettingsRow({
+  label,
+  description,
+  control,
+  children,
+  className,
+  style,
+  classNames
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(classes.row, classNames?.root, className),
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsxs(Stack, { gap: 2, ...classNames?.label !== void 0 && { className: classNames.label }, children: [
+          /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.ink }, children: label }),
+          description && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.sm, color: VX.muted }, children: description })
+        ] }),
+        /* @__PURE__ */ jsx("div", { className: cx(classes.control, classNames?.control), children: control ?? children })
+      ]
+    }
+  );
 }
-function DangerZone({ title, subtitle, actions, children }) {
+function DangerZone({
+  title,
+  icon,
+  subtitle,
+  info,
+  actions,
+  children,
+  className,
+  style,
+  classNames
+}) {
   return /* @__PURE__ */ jsxs(
     Card,
     {
+      className: cx(classNames?.root, className),
       style: {
         padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)",
-        boxShadow: `${VX.shadowCard}, 0 0 0 1px ${alpha(VX.status.bad, 0.25)}`
+        boxShadow: `${VX.shadowCard}, 0 0 0 1px ${alpha(VX.status.bad, 0.25)}`,
+        ...style
       },
       children: [
-        /* @__PURE__ */ jsxs("div", { className: classes.header, children: [
+        /* @__PURE__ */ jsxs("div", { className: cx(classes.header, classNames?.header), children: [
           /* @__PURE__ */ jsx("span", { style: eyebrowStyle, children: "Danger Zone" }),
           /* @__PURE__ */ jsx(
             WidgetHeader,
             {
               tier: "section",
               title,
+              ...icon !== void 0 && { icon },
               ...subtitle !== void 0 && { subtitle },
+              ...info !== void 0 && { info },
               ...actions !== void 0 && { actions: /* @__PURE__ */ jsx(CtlSlot, { children: actions }) }
             }
           )
         ] }),
-        /* @__PURE__ */ jsx("div", { className: classes.rows, children })
+        /* @__PURE__ */ jsx("div", { className: cx(classes.rows, classNames?.body), children })
       ]
     }
   );

package/dist/dashboard/stat-card.d.ts

@@ -1,6 +1,19 @@
 import type { ReactNode } from 'react';
-/** A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock. */
-export type StatCardTone = 'good' | 'warn' | 'bad';
+import type { WidgetHeaderDeltaProps, WidgetHeaderMetricProps, WidgetHeaderTitleProps } from './widget-header.js';
+import type { BasaltProps, SlotStylesProps, Tone } from '../common/props.js';
+import type { QueryStateLike } from './query-state.js';
+/**
+ * A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock.
+ * Alias of the common `Tone` vocabulary (audit A13) — byte-identical, kept as its own name so a
+ * consumer's existing `StatCardTone` reference never breaks.
+ */
+export type StatCardTone = Tone;
+/**
+ * The four boxes `StatCard` paints, and the whole styling seam it offers (`common/props.ts`).
+ * `value` is not its own slot: the hero number is painted by `WidgetHeader`'s internal metrics row,
+ * which does not yet accept a slot class of its own.
+ */
+export type StatCardSlot = 'root' | 'header' | 'body' | 'sparkline';
 /**
  * One row of a {@link StatCardProps.breakdown} — the two or three parts a hero number is made of.
  *
@@ -27,24 +40,25 @@ export type StatCardSparklineSize = {
     width: number;
     height: number;
 };
-export type StatCardProps = {
-    /** Head-font title, rendered via `WidgetHeader tier="widget"`. */
-    title: string;
-    /** Optional leading icon, forwarded to `WidgetHeader`. */
-    icon?: ReactNode;
-    /** Muted line under the hero row, forwarded to `WidgetHeader` — the unit or basis a
-     * pre-formatted `value` cannot carry (`per day`, `of 40 planned`). Not a second metric. */
-    subtitle?: string;
-    /** Info tooltip beside the title, forwarded to `WidgetHeader` — how the number is computed. Never
-     * part of the heading's accessible name; see `WidgetHeaderProps.info`. */
-    info?: string;
-    /** Pre-formatted KPI value string (mono ~24px, weight 600, ink) — the hero-row value. */
+/**
+ * `StatCard` re-publishes three NAMED `WidgetHeader` slices (`WidgetHeaderTitleProps` /
+ * `WidgetHeaderMetricProps` / `WidgetHeaderDeltaProps`, audit B #2) rather than re-declaring the
+ * props one by one — which is how `count` came to be missing here and `unit` missing on `Section`,
+ * with nothing in either type saying whether that was a decision.
+ *
+ * Two deliberate departures from the slices, and they are the whole omission list:
+ *
+ *  - **`value` is REQUIRED.** A KPI card with no number is an empty box; on `WidgetHeader` the same
+ *    prop is optional because a section heading legitimately has none.
+ *  - **`count` is not taken.** It is the table/list count (law C11) and a KPI card is neither.
+ *
+ * `Section` and `ChartCard` still cut their own ad-hoc subsets; both should move onto these same
+ * three slices.
+ */
+export type StatCardProps = BasaltProps & SlotStylesProps<StatCardSlot> & WidgetHeaderTitleProps & Omit<WidgetHeaderMetricProps, 'value'> & WidgetHeaderDeltaProps & {
+    /** Pre-formatted KPI value string (mono ~24px, weight 600, ink) — the hero-row value. Required
+     * here, unlike on `WidgetHeader`: see the type's own doc. */
     value: string;
-    /** The value's unit, muted and mono at `--vx-text-sm`, immediately after it on the hero row —
-     * forwarded to `WidgetHeader`. `412` + `TSS`, not `"412 TSS"`: a unit painted at the hero's 24px
-     * reads as a second numeral. The BASIS (`7-day rolling`) is still `subtitle`; see
-     * `WidgetHeaderProps.unit`. */
-    unit?: string;
     /**
      * The parts the hero number is made of — compact rows under it, one line each, no hairlines.
      *
@@ -59,29 +73,21 @@ export type StatCardProps = {
      * table, and a table is `BasaltDataTable` in a `Section`.
      */
     breakdown?: readonly StatCardBreakdownRow[];
-    /** Signed delta rendered via `DeltaBadge`; omit to hide the trend chip entirely. */
-    delta?: number;
-    /** Optional comparison timeframe shown after the delta (e.g. `MoM`) — forwarded to `DeltaBadge`. */
-    deltaPeriod?: string;
     /**
-     * Formats `delta` into the chip's label — forwarded to `WidgetHeader` and on to `DeltaBadge`.
-     * Defaults to `${Math.abs(delta).toFixed(1)}%`.
+     * The async result behind the number. Supplied, the card renders its pending / error / empty
+     * branch through {@link QueryState} at the `'section'` tier, INSIDE the card body and directly
+     * under the header — so the title, the icon and the info glyph stay put while the reading below
+     * them resolves. Omitted, the card renders exactly as it always has (audit B #3).
      *
-     * A delta is not always a percentage, and the default silently claimed it was: a pace card's trend
-     * (`0:12 /km`) and a speed card's (`0.3 km/h`) both rendered as `0.3%` — a wrong unit on a KPI is
-     * the one failure worse than no chip, and it is why the consumer that needed it kept the card
-     * hand-rolled instead (the `HeroCard` fork `shadow-basalt-export` reports).
+     * It exists because the alternative every consumer wrote is the four-way switch `QueryState`
+     * exists to delete, and got it wrong in the direction that renders "no data" over a 500. The
+     * BRANCH is basalt's; the number is not — `value` is still whatever you formatted, so pass a
+     * placeholder (`'—'`) while the query is pending rather than a stale one.
      *
      * @example
-     * // An absolute delta that prints its own sign — no percent, no glyph saying it twice.
-     * <StatCard title="Pace" value="5:31" unit="/km" delta={-12}
-     *   deltaFormat={(s) => `${s < 0 ? '−' : '+'}0:${String(Math.abs(s)).padStart(2, '0')} /km`}
-     *   deltaGlyph={false} />
+     * <StatCard title="Active users" value={q.data ? fmt(q.data.count) : '—'} query={q} />
      */
-    deltaFormat?: (delta: number) => string;
-    /** Render the ▲/▼ glyph on the delta chip. Defaults to `true`; a zero delta never shows one. Pass
-     * `false` when `deltaFormat` prints the sign itself. */
-    deltaGlyph?: boolean;
+    query?: QueryStateLike<unknown>;
     /**
      * Optional trend visual. Either a node, or a RENDER PROP receiving the slot's measured box.
      *
@@ -107,5 +113,5 @@ export type StatCardProps = {
      * `'good'` only to assert a measured value that has earned the verdict. */
     tone?: StatCardTone;
 };
-export declare function StatCard({ title, icon, subtitle, info, value, unit, breakdown, delta, deltaPeriod, deltaFormat, deltaGlyph, sparkline, sparklinePlacement, actions, tone, }: StatCardProps): import("react").JSX.Element;
+export declare function StatCard({ title, icon, subtitle, info, value, unit, breakdown, query, delta, deltaPeriod, deltaPolarity, deltaFormat, deltaGlyph, sparkline, sparklinePlacement, actions, tone, className, style, classNames, }: StatCardProps): import("react").JSX.Element;
 //# sourceMappingURL=stat-card.d.ts.map

package/dist/dashboard/stat-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AA6FA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAMrD,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAcD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAkDD,MAAM,MAAM,aAAa,GAAG;IAC1B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;+FAC2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;8EAC0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;IACb;;;mCAG+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC3C,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;4DACwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,qBAAqB,KAAK,SAAS,CAAC,CAAA;IACpE;yFACqF;IACrF,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACtC;mGAC+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,SAAS,EACT,KAAK,EACL,WAAW,EACX,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAA4B,EAC5B,OAAO,EACP,IAAI,GACL,EAAE,aAAa,+BA4Hf"}
+{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AAgGA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAA;AAE/B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAcD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAkDD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GACrC,eAAe,CAAC,YAAY,CAAC,GAC7B,sBAAsB,GACtB,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,GACtC,sBAAsB,GAAG;IACvB;iEAC6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,qBAAqB,KAAK,SAAS,CAAC,CAAA;IACpE;yFACqF;IACrF,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACtC;mGAC+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAEH,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,SAAS,EACT,KAAK,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAA4B,EAC5B,OAAO,EACP,IAAI,EACJ,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,aAAa,+BA6Jf"}