basalt-ui 1.25.0 → 1.27.0

package/dist/controls/view-tabs.js

@@ -0,0 +1,59 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { SegmentedControl, Select } from "@mantine/core";
+import classes from "./controls.module.css";
+const PHONE_TRACK_MAX = 3;
+function ViewTabs({
+  field,
+  options,
+  label = "View"
+}) {
+  const [value, setValue] = field.use();
+  const all = options ?? field.options.map((option) => ({ value: option.value, label: option.label }));
+  const desktop = all.filter((option) => option.only !== "sm-down");
+  const phone = all.filter((option) => option.only !== "sm-up");
+  const commit = (next) => {
+    setValue(next);
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      SegmentedControl,
+      {
+        "aria-label": label,
+        visibleFrom: "sm",
+        size: "ctl",
+        value,
+        data: desktop.map((option) => ({ value: option.value, label: option.label })),
+        onChange: commit
+      }
+    ),
+    phone.length <= PHONE_TRACK_MAX ? /* @__PURE__ */ jsx(
+      SegmentedControl,
+      {
+        "aria-label": label,
+        hiddenFrom: "sm",
+        size: "ctl",
+        fullWidth: true,
+        value,
+        data: phone.map((option) => ({ value: option.value, label: option.label })),
+        onChange: commit
+      }
+    ) : /* @__PURE__ */ jsx(
+      Select,
+      {
+        "aria-label": label,
+        hiddenFrom: "sm",
+        size: "ctl",
+        className: classes.phoneSelect,
+        value,
+        allowDeselect: false,
+        data: phone.map((option) => ({ value: option.value, label: option.label })),
+        onChange: (next) => {
+          if (next !== null) commit(next);
+        }
+      }
+    )
+  ] });
+}
+export {
+  ViewTabs
+};

package/dist/controls-dates/date-range-picker.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+import type { RangeCustomPickerProps } from '../controls/range-filter.js';
+export declare function DateRangePicker({ value, onChange }: RangeCustomPickerProps): ReactNode;
+//# sourceMappingURL=date-range-picker.d.ts.map

package/dist/controls-dates/date-range-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-range-picker.d.ts","sourceRoot":"","sources":["../../src/controls-dates/date-range-picker.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAEtE,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAAG,SAAS,CAatF"}

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

@@ -0,0 +1,18 @@
+import { jsx } from "react/jsx-runtime";
+import { DatePicker } from "@mantine/dates";
+function DateRangePicker({ value, onChange }) {
+  return /* @__PURE__ */ jsx(
+    DatePicker,
+    {
+      type: "range",
+      allowSingleDateInRange: true,
+      value: [value.from ?? null, value.to ?? null],
+      onChange: ([from, to]) => {
+        if (from !== null && to !== null) onChange({ from, to });
+      }
+    }
+  );
+}
+export {
+  DateRangePicker
+};

package/dist/controls-dates/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `basalt-ui/controls-dates` — the one export that needs `@mantine/dates`
+ * (`docs/CONTROLS-SPEC.md` §3). Split off `./controls` on purpose: `./controls` resolves and renders
+ * with no `@mantine/dates` installed, and this subpath is the only place that stops being true.
+ * Proven from outside the package by `scripts/pack-test.sh`.
+ */
+export { DateRangePicker } from './date-range-picker.js';
+export type { RangeCustomPickerProps } from '../controls/range-filter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/controls-dates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/controls-dates/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/controls-dates/index.js

@@ -0,0 +1,4 @@
+import { DateRangePicker } from "./date-range-picker.js";
+export {
+  DateRangePicker
+};

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

@@ -1,13 +1,7 @@
-export type DeltaBadgeProps = {
-    /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
-    value: number;
-    /** 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, format, withGlyph, period, }: DeltaBadgeProps): import("react").JSX.Element;
+/**
+ * `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';
 //# 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":"AAkBA,MAAM,MAAM,eAAe,GAAG;IAC5B,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb,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;AAID,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,MAAsB,EACtB,SAAgB,EAChB,MAAM,GACP,EAAE,eAAe,+BAsCjB"}
+{"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"}

package/dist/dashboard/delta-badge.js

@@ -1,53 +1,4 @@
-import { jsx, jsxs } from "react/jsx-runtime";
-import { Badge } from "@mantine/core";
-import { alpha, VX } from "../tokens/index.js";
-const defaultFormat = (value) => `${Math.abs(value).toFixed(1)}%`;
-function DeltaBadge({
-  value,
-  format = defaultFormat,
-  withGlyph = true,
-  period
-}) {
-  const tone = value > 0 ? VX.status.good : value < 0 ? VX.status.bad : VX.faint;
-  const glyph = value > 0 ? "\u25B2" : value < 0 ? "\u25BC" : void 0;
-  const showGlyph = withGlyph && glyph !== void 0;
-  return /* @__PURE__ */ jsxs(
-    Badge,
-    {
-      styles: {
-        root: {
-          backgroundColor: alpha(tone, 0.13),
-          padding: "var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x)",
-          height: "auto"
-        },
-        label: {
-          display: "inline-flex",
-          // theme-allow inline-display — a Badge `styles.label` part, not a layout node Flex could replace
-          alignItems: "center",
-          gap: 3,
-          // theme-allow inline-spacing — sub-scale glyph-to-label gap, below the smallest scale stop
-          fontFamily: "var(--basalt-font-mono)",
-          fontSize: VX.text.xs,
-          fontWeight: 600,
-          textTransform: "none",
-          letterSpacing: "normal",
-          color: tone
-        }
-      },
-      children: [
-        showGlyph && /* @__PURE__ */ jsx("span", { style: { fontSize: "0.8em" }, children: glyph }),
-        format(value),
-        period && /* @__PURE__ */ jsx(
-          "span",
-          {
-            style: { marginLeft: 4, fontWeight: 500, opacity: 0.6 },
-            children: period
-          }
-        )
-      ]
-    }
-  );
-}
+import { DeltaBadge } from "../widget-header/delta-badge.js";
 export {
   DeltaBadge
 };

package/dist/dashboard/index.d.ts

@@ -1,5 +1,5 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge.js';
-export { StatCard, type StatCardProps, type StatCardTone } from './stat-card.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';

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,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,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,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"}

package/dist/dashboard/index.js

@@ -1,5 +1,7 @@
 import { DeltaBadge } from "./delta-badge.js";
-import { StatCard } from "./stat-card.js";
+import {
+  StatCard
+} from "./stat-card.js";
 import { EmptyState } from "./empty-state.js";
 import {
   SettingsSection,

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

@@ -1,13 +1,15 @@
 import type { ReactNode } from 'react';
 export type SettingsSectionProps = {
-    /** Head-font section title (15px, weight 550, ink). */
+    /** Head-font section title, rendered via `WidgetHeader tier="section"`. */
     title: string;
     /** Optional 13px muted description below the title. */
-    description?: string;
+    subtitle?: string;
+    /** 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, description, children }: SettingsSectionProps): import("react").JSX.Element;
+export declare function SettingsSection({ title, subtitle, actions, children }: SettingsSectionProps): import("react").JSX.Element;
 export type SettingsRowProps = {
     /** 13px ink label on the left. */
     label: string;
@@ -20,5 +22,5 @@ export type SettingsRowProps = {
 };
 export declare function SettingsRow({ label, description, control, children }: SettingsRowProps): import("react").JSX.Element;
 export type DangerZoneProps = SettingsSectionProps;
-export declare function DangerZone({ title, description, children }: DangerZoneProps): import("react").JSX.Element;
+export declare function DangerZone({ title, subtitle, actions, children }: 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":"AA4BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAqBtC,MAAM,MAAM,oBAAoB,GAAG;IACjC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BAYrF;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,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,+BAkB3E"}
+{"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"}

package/dist/dashboard/settings-section.js

@@ -1,14 +1,9 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Card, Stack } from "@mantine/core";
+import { WidgetHeader } from "../widget-header/index.js";
+import { CtlSlot } from "../theme/index.js";
 import { alpha, VX } from "../tokens/index.js";
 import classes from "./settings-section.module.css";
-const titleStyle = {
-  fontFamily: "var(--basalt-font-head)",
-  fontStretch: "88%",
-  fontSize: VX.text.md,
-  fontWeight: 550,
-  color: VX.ink
-};
 const eyebrowStyle = {
   fontFamily: "var(--basalt-font-mono)",
   fontSize: VX.text.micro,
@@ -17,12 +12,17 @@ const eyebrowStyle = {
   textTransform: "uppercase",
   color: VX.status.bad
 };
-function SettingsSection({ title, description, children }) {
+function SettingsSection({ title, subtitle, actions, children }) {
   return /* @__PURE__ */ jsxs(Card, { style: { padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)" }, children: [
-    /* @__PURE__ */ jsxs(Stack, { gap: 2, mb: "sm", children: [
-      /* @__PURE__ */ jsx("span", { style: titleStyle, children: title }),
-      description && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.sm, color: VX.muted }, children: description })
-    ] }),
+    /* @__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 })
   ] });
 }
@@ -35,7 +35,7 @@ function SettingsRow({ label, description, control, children }) {
     /* @__PURE__ */ jsx("div", { className: classes.control, children: control ?? children })
   ] });
 }
-function DangerZone({ title, description, children }) {
+function DangerZone({ title, subtitle, actions, children }) {
   return /* @__PURE__ */ jsxs(
     Card,
     {
@@ -44,10 +44,17 @@ function DangerZone({ title, description, children }) {
         boxShadow: `${VX.shadowCard}, 0 0 0 1px ${alpha(VX.status.bad, 0.25)}`
       },
       children: [
-        /* @__PURE__ */ jsxs(Stack, { gap: 2, mb: "sm", children: [
+        /* @__PURE__ */ jsxs("div", { className: classes.header, children: [
           /* @__PURE__ */ jsx("span", { style: eyebrowStyle, children: "Danger Zone" }),
-          /* @__PURE__ */ jsx("span", { style: titleStyle, children: title }),
-          description && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.sm, color: VX.muted }, children: description })
+          /* @__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 })
       ]

package/dist/dashboard/settings-section.module.css

@@ -3,6 +3,16 @@
  * vertical padding and a 1px `--vx-divider` rule below it, EXCEPT the last row in the section —
  * `:not(:last-child)` strips the divider there so the section doesn't end on a trailing line.
  */
+
+/* The WidgetHeader block (plus DangerZone's eyebrow, when present) sits above `.rows` with the
+ * same gap the old inline `Stack gap={2} mb="sm"` produced. */
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-bottom: var(--mantine-spacing-sm);
+}
+
 .rows > * {
   padding: var(--vx-space-settings-row-inset-y) 0;
 }

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

@@ -3,6 +3,7 @@
  * signature — so dot access stays verbatim under the package's strict flags.
  */
 declare const classes: {
+  readonly header: string
   readonly rows: string
   readonly row: string
   readonly control: string

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=settings-section.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settings-section.test.d.ts","sourceRoot":"","sources":["../../src/dashboard/settings-section.test.tsx"],"names":[],"mappings":""}

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

@@ -1,25 +1,111 @@
 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';
+/**
+ * One row of a {@link StatCardProps.breakdown} — the two or three parts a hero number is made of.
+ *
+ * `value` is a pre-formatted `string` for the same reason the hero's is: the card cannot know the
+ * locale, the currency or the precision the number was measured at. `tone` marks ONE row as past a
+ * threshold and is the same vocabulary as the card's own `tone`, so a row saying `bad` and a rail
+ * saying `bad` are the same claim at two scales; omitting it is untinted, never `'good'`.
+ */
+export type StatCardBreakdownRow = {
+    readonly label: string;
+    readonly value: string;
+    readonly tone?: StatCardTone;
+};
+/**
+ * The measured box a `sparkline` render prop receives.
+ *
+ * A `LineSparkline`/`BarSparkline` takes `width`/`height` as NUMBERS (they are SVG attributes — an
+ * svg cannot size itself from CSS and then scale its scales), so "full bleed" was never expressible
+ * as a `ReactNode`: the caller had to guess a pixel width, or write its own `useChartSize` wrapper
+ * component. Four consumers wrote that wrapper; two of them hardcoded a width and drew a sparkline
+ * that stopped short of the card edge on every viewport but the one they built on.
+ */
+export type StatCardSparklineSize = {
+    width: number;
+    height: number;
+};
 export type StatCardProps = {
-    /** Mono uppercase micro-label (docs/DESIGN-SPEC.md §3: 12.5px, tracking 0.06em, faint). */
-    label: string;
-    /** Pre-formatted KPI value string (mono ~24px, weight 600, ink). */
+    /** 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. */
     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.
+     *
+     * It exists because three consumers wanted a KPI card that also SPLITS its number (revenue by
+     * channel, uptime by probe) and the only shapes basalt offered were a `subtitle` (one muted line,
+     * no second column) and a table. Both hand-rolled a card instead — which is the fork
+     * `shadow-basalt-export` reports as a `HeroCard`.
+     *
+     * Deliberately not a table and deliberately unruled: the divider law puts a hairline between
+     * OPTION rows and nowhere else (`docs/CONTROLS-SPEC.md` §2.1), and a KPI card that draws three
+     * of them stops reading as one card. Keep it to two or three rows — past that the card is a
+     * 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;
-    /** Optional trend visual — a slot; pass a `LineSparkline`/`BarSparkline` from `basalt-ui/charts`.
-     * Rendered full-bleed to the card's left/right/bottom edges, clipped to the corner radius. */
-    sparkline?: ReactNode;
-    /** Optional header-right slot (e.g. a ghost "..." menu trigger) — consumer-owned. */
-    menu?: ReactNode;
+    /**
+     * Formats `delta` into the chip's label — forwarded to `WidgetHeader` and on to `DeltaBadge`.
+     * Defaults to `${Math.abs(delta).toFixed(1)}%`.
+     *
+     * 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).
+     *
+     * @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} />
+     */
+    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;
+    /**
+     * Optional trend visual. Either a node, or a RENDER PROP receiving the slot's measured box.
+     *
+     * Prefer the render prop for anything from `basalt-ui/charts`: those take numeric `width`/`height`
+     * (SVG attributes), so a plain node has to hardcode a width, and a hardcoded width is not
+     * full-bleed on any viewport but the one it was typed on. With `sparklinePlacement="bleed"` the
+     * measured width is the card's own inner width including the bled inset; with `'right'` it is the
+     * fixed 72×26 slot (see {@link SPARKLINE_RIGHT_WIDTH} for why that one is not measured).
+     *
+     * @example
+     * sparkline={({ width, height }) => <BarSparkline data={history} width={width} height={height} />}
+     */
+    sparkline?: ReactNode | ((size: StatCardSparklineSize) => ReactNode);
+    /** Where `sparkline` sits. `'bleed'` (default) is today's full-width row bled to the card edges;
+     * `'right'` sits it beside the hero value row. Collapses to `'bleed'` below `sm`. */
+    sparklinePlacement?: 'bleed' | 'right';
+    /** Header-right slot (e.g. a ghost "..." menu trigger) — wrapped in `CtlSlot tier="widget"`, so a
+     * raw `ActionIcon` with no `size` lands on the 24px step the 28px header row holds (C1/C5). */
+    actions?: ReactNode;
     /** Threshold verdict — draws an accent rail down the card's leading edge and announces itself to
      * assistive tech. Omitting it is NOT `'good'`: omitted covers a reading that is fine AND one that
      * is absent, and stays untinted so a card with nothing measured can never render green. Pass
      * `'good'` only to assert a measured value that has earned the verdict. */
     tone?: StatCardTone;
 };
-export declare function StatCard({ label, value, delta, deltaPeriod, sparkline, menu, tone, }: StatCardProps): import("react").JSX.Element;
+export declare function StatCard({ title, icon, subtitle, info, value, unit, breakdown, delta, deltaPeriod, deltaFormat, deltaGlyph, sparkline, sparklinePlacement, actions, tone, }: 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":"AAsDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAYlD,MAAM,MAAM,aAAa,GAAG;IAC1B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;kGAC8F;IAC9F,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,IAAI,EACJ,IAAI,GACL,EAAE,aAAa,+BAyFf"}
+{"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"}