basalt-ui 1.27.0 → 1.28.0

package/dist/dashboard/settings-section.js

@@ -3,6 +3,7 @@ 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 { 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/index.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,kBAAkB,CAAA;AAIzB,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"}

package/dist/dashboard/stat-card.js

@@ -4,6 +4,8 @@ import { useEffect, useRef, useState } from "react";
 import { WidgetHeader } from "../widget-header/index.js";
 import { CtlSlot } from "../theme/index.js";
 import { VX } from "../tokens/index.js";
+import { cx } from "../common/props.js";
+import { QueryState } from "./query-state.js";
 import classes from "./stat-card.module.css";
 const SPARKLINE_RIGHT_WIDTH = 72;
 const SPARKLINE_RIGHT_HEIGHT = 26;
@@ -45,22 +47,64 @@ function StatCard({
   value,
   unit,
   breakdown,
+  query,
   delta,
   deltaPeriod,
+  deltaPolarity,
   deltaFormat,
   deltaGlyph,
   sparkline,
   sparklinePlacement = "bleed",
   actions,
-  tone
+  tone,
+  className,
+  style,
+  classNames
 }) {
   const isRender = typeof sparkline === "function";
   const bleeds = sparklinePlacement === "bleed";
   const slot = useSlotWidth(isRender);
   const measured = { width: slot.width, height: SPARKLINE_RIGHT_HEIGHT };
+  const breakdownRows = breakdown === void 0 || breakdown.length === 0 ? null : /* @__PURE__ */ jsx("dl", { className: classes.breakdown, children: breakdown.map((row) => /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: classes.breakdownRow,
+      ...row.tone !== void 0 && { "data-tone": row.tone },
+      children: [
+        /* @__PURE__ */ jsx("dt", { className: classes.breakdownLabel, children: row.label }),
+        /* @__PURE__ */ jsx("dd", { className: classes.breakdownValue, children: row.value })
+      ]
+    },
+    row.label
+  )) });
+  const breakdownContent = query === void 0 ? breakdownRows : /* @__PURE__ */ jsx(QueryState, { query, tier: "section", children: breakdownRows });
+  const sparklineNode = sparkline === void 0 ? null : /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: slot.ref,
+      className: cx(
+        bleeds ? classes.sparklineBleed : classes.sparklineRight,
+        classNames?.sparkline
+      ),
+      ...!bleeds && {
+        // CUSTOM PROPERTIES, not `flexBasis`/`height` directly. A React inline style beats every
+        // stylesheet rule, so an inline `flexBasis: 72` also applied below `sm` — where `'right'`
+        // collapses `.metricsRow` to a COLUMN and flex-basis is therefore the main-axis HEIGHT.
+        // The mobile sparkline rendered in a 72px-tall box holding 26px of bars, which is the dead
+        // band under every KPI value on a phone. Handed to CSS as values instead, the media query
+        // can reset the box and the numbers still live in one place.
+        style: {
+          "--basalt-stat-sparkline-w": `${SPARKLINE_RIGHT_WIDTH}px`,
+          "--basalt-stat-sparkline-h": `${SPARKLINE_RIGHT_HEIGHT}px`
+        }
+      },
+      children: isRender ? measured.width > 0 && sparkline(measured) : sparkline
+    }
+  );
   return /* @__PURE__ */ jsxs(
     Card,
     {
+      className: cx(classNames?.root, className),
       style: {
         // Card inset = spacing xs / sm, matching every other basalt card. `overflow: hidden` clips
         // the full-bleed sparkline to the card's rounded corners; an element's own `box-shadow`
@@ -78,7 +122,8 @@ function StatCard({
         overflow: "hidden",
         // Anchors the tone rail. Set unconditionally so a card's stacking context does not change
         // depending on whether it happens to have crossed a threshold this render.
-        position: "relative"
+        position: "relative",
+        ...style
       },
       "data-tone": tone,
       children: [
@@ -102,8 +147,8 @@ function StatCard({
             }
           )
         ] }),
-        /* @__PURE__ */ jsxs("div", { className: classes.body, "data-placement": sparklinePlacement, children: [
-          /* @__PURE__ */ jsxs("div", { className: classes.header, children: [
+        /* @__PURE__ */ jsxs("div", { className: cx(classes.body, classNames?.body), "data-placement": sparklinePlacement, children: [
+          /* @__PURE__ */ jsxs("div", { className: cx(classes.header, classNames?.header), children: [
             /* @__PURE__ */ jsx(
               WidgetHeader,
               {
@@ -116,6 +161,7 @@ function StatCard({
                 ...unit !== void 0 && { unit },
                 ...delta !== void 0 && { delta },
                 ...deltaPeriod !== void 0 && { deltaPeriod },
+                ...deltaPolarity !== void 0 && { deltaPolarity },
                 ...deltaFormat !== void 0 && { deltaFormat },
                 ...deltaGlyph !== void 0 && { deltaGlyph },
                 ...actions !== void 0 && {
@@ -123,45 +169,12 @@ function StatCard({
                 }
               }
             ),
-            breakdown !== void 0 && breakdown.length > 0 && // A `<dl>`, not a table and not a stack of divs: each row IS a term and its value, which
-            // is the one semantic that survives a reader meeting the card out of context.
-            //
-            // INSIDE `.header`, not beside it: with `sparklinePlacement="right"` the body is a flex
-            // ROW, so a third child here would sit next to the trend rather than under the number
-            // it splits. The header block is the card's text column in both placements.
-            /* @__PURE__ */ jsx("dl", { className: classes.breakdown, children: breakdown.map((row) => /* @__PURE__ */ jsxs(
-              "div",
-              {
-                className: classes.breakdownRow,
-                ...row.tone !== void 0 && { "data-tone": row.tone },
-                children: [
-                  /* @__PURE__ */ jsx("dt", { className: classes.breakdownLabel, children: row.label }),
-                  /* @__PURE__ */ jsx("dd", { className: classes.breakdownValue, children: row.value })
-                ]
-              },
-              row.label
-            )) })
+            bleeds && breakdownContent
           ] }),
-          sparkline !== void 0 && /* @__PURE__ */ jsx(
-            "div",
-            {
-              ref: slot.ref,
-              className: bleeds ? classes.sparklineBleed : classes.sparklineRight,
-              ...!bleeds && {
-                // CUSTOM PROPERTIES, not `flexBasis`/`height` directly. A React inline style beats
-                // every stylesheet rule, so an inline `flexBasis: 72` also applied below `sm` — where
-                // `'right'` collapses to a COLUMN and flex-basis is therefore the main-axis HEIGHT.
-                // The mobile sparkline rendered in a 72px-tall box holding 26px of bars, which is the
-                // dead band under every KPI value on a phone. Handed to CSS as values instead, the
-                // media query can reset the box and the numbers still live in one place.
-                style: {
-                  "--basalt-stat-sparkline-w": `${SPARKLINE_RIGHT_WIDTH}px`,
-                  "--basalt-stat-sparkline-h": `${SPARKLINE_RIGHT_HEIGHT}px`
-                }
-              },
-              children: isRender ? measured.width > 0 && sparkline(measured) : sparkline
-            }
-          )
+          bleeds ? sparklineNode : (breakdownContent !== null || sparklineNode !== null) && /* @__PURE__ */ jsxs("div", { className: classes.metricsRow, children: [
+            breakdownContent,
+            sparklineNode
+          ] })
         ] })
       ]
     }

package/dist/dashboard/stat-card.module.css

@@ -2,9 +2,10 @@
  * StatCard's sparkline placement (docs/CONTROLS-SPEC.md §2.2). `bleed` (default) keeps the historic
  * full-width row beneath the hero value, bled past the card's own inset padding — same negative
  * margins the pre-WidgetHeader version drew inline. `right` sits the sparkline beside the
- * `WidgetHeader`'s hero-value row instead, the reference-design look, and collapses back to
- * `bleed`'s stacked layout below `sm` — CSS only, no JS branch (`47.99375em` is Mantine's own
- * complement of `min-width: 48em`, same value `content/prose.module.css` derives it from).
+ * BREAKDOWN row instead, the reference-design look, and collapses back to `bleed`'s stacked layout
+ * below `sm` — CSS only for the sparkline's own box, `.metricsRow` below for the row it sits in
+ * (`47.99375em` is Mantine's own complement of `min-width: 48em`, same value
+ * `content/prose.module.css` derives it from).
  */
 
 .body {
@@ -14,31 +15,30 @@
   height: 100%;
 }
 
-/*
- * `flex-end`, not `center`: the sparkline belongs to the HERO ROW, and the hero row is the header
- * block's last line. Centred against the whole body it floated between the title and the value,
- * which reads as a third, unrelated element; bottom-aligned to the header block it sits beside the
- * number it describes, the reference layout. `gap` is the card's own control gap so the trend never
- * touches a long value.
- */
-.body[data-placement='right'] {
-  flex-direction: row;
-  align-items: flex-end;
-  gap: var(--vx-space-control-gap);
-}
-
 .header {
   min-width: 0;
 }
 
 /*
- * `flex-shrink: 0` on the header, `1` on the sparkline slot below: the hero value and its delta keep
- * their width and the TREND gives ground. The other way round, a 4-up KPI grid on a 1440 viewport
- * ellipsized `$1,294,900` to `$1294.…` in order to keep 72px of bars intact, which is the wrong
- * thing to protect. The value still carries `overflow: hidden` as the last resort, and `Card` clips.
+ * `right` placement's second row (measured defect: the "···" actions trigger, and the "Data"
+ * select, sat ~74-88px in from the card's right edge — a phone-only 13px is correct). The cause was
+ * `.body[data-placement='right']` making the WHOLE header (title row, actions included) share a row
+ * with the sparkline, so the header's own right edge — where `.actions` lives — stopped wherever the
+ * sparkline began, not at the card. `.header` is no longer placement-scoped at all now: `.body` stays
+ * a COLUMN in both placements (its base rule above), so `.header` gets the FULL card width for free
+ * via the column's default `align-items: stretch` — the actions slot's own `margin-inline-start:
+ * auto` (`widget-header.module.css`) now resolves against the true card edge. Only the breakdown —
+ * the one text `StatCard` renders itself, outside `WidgetHeader`'s box, and the one piece the
+ * `docs/CONTROLS-SPEC.md` `breakdown` doc calls "the parts the hero number is made of" — shares this
+ * row with the sparkline; `justify-content: flex-end` is what still right-aligns the sparkline on a
+ * card with no breakdown, where this row's only child.
  */
-.body[data-placement='right'] .header {
-  flex: 1 0 auto;
+.metricsRow {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
   min-width: 0;
 }
 
@@ -59,6 +59,17 @@
   min-width: 0;
 }
 
+/* Inside `.metricsRow` (`right` placement) the breakdown is no longer stacked directly under
+ * `WidgetHeader`'s own metric row in the SAME box — `.body`'s own `gap` already separates `.header`
+ * from `.metricsRow`, so the `margin-top` above would double that spacing. It also takes the row's
+ * remaining width (`flex: 1 1 auto`) so the sparkline — fixed to its own slot width — gets pushed to
+ * the row's end instead of sitting immediately after a shrink-wrapped breakdown column. */
+.metricsRow .breakdown {
+  margin-top: 0;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
 /*
  * One row, one line, at the TAG tier (`controlHeightTag`, 20px at level 0) — the smallest control
  * step basalt declares, and a token rather than a literal so the rows track the density knob with
@@ -120,32 +131,36 @@
 }
 
 /* Asks for `StatCard`'s `SPARKLINE_RIGHT_WIDTH`/`_HEIGHT` (handed down as custom properties, so this
- * rule and the `< sm` reset below can both reach them) and shrinks below the width before the hero
- * row does — see the `.header` note above. `min-width: 0` is what lets it. */
+ * rule and the `< sm` reset below can both reach them). `align-self: flex-end` is the one alignment
+ * this restructure keeps at the SPARKLINE's own level rather than the row's: `.metricsRow` does not
+ * set `align-items: flex-end` itself, because a card with no breakdown would then need nothing to
+ * anchor against — only the sparkline opts into sitting at the row's bottom edge, which matters once
+ * a breakdown taller than the trend's own 26px is the row's other child. */
 .sparklineRight {
   display: flex;
   flex: 0 1 var(--basalt-stat-sparkline-w, 4.5rem);
   min-width: 0;
   height: var(--basalt-stat-sparkline-h, 1.625rem);
   align-items: flex-end;
+  align-self: flex-end;
   overflow: hidden;
 }
 
 @media (max-width: 47.99375em) {
-  .body[data-placement='right'] {
+  .metricsRow {
     flex-direction: column;
     align-items: stretch;
-  }
-
-  .body[data-placement='right'] .header {
-    flex: initial;
+    justify-content: flex-start;
   }
 
   /* The row became a COLUMN, so `flex-basis` is now the main-axis HEIGHT — the 72px width would
    * become a 72px-tall box around 26px of bars. `flex: none` + the height keeps the bled trend the
-   * same 26px it is beside a hero row. */
-  .body[data-placement='right'] .sparklineRight {
+   * same 26px it is beside a hero row. `align-self: stretch` resets the row-only `flex-end` above:
+   * the cross axis is horizontal now, and this slot must fill the card's width like `.sparklineBleed`
+   * does, not shrink to its content and sit flush right. */
+  .metricsRow .sparklineRight {
     flex: none;
+    align-self: stretch;
     margin-top: auto;
     margin-inline: calc(-1 * var(--mantine-spacing-sm));
     margin-bottom: calc(-1 * var(--mantine-spacing-xs));

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

@@ -5,6 +5,7 @@
 declare const classes: {
   readonly body: string
   readonly header: string
+  readonly metricsRow: string
   readonly breakdown: string
   readonly breakdownRow: string
   readonly breakdownLabel: string

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

@@ -0,0 +1,41 @@
+/**
+ * StatGroup — the KPI row, and the second half of the column law `WidgetGrid` owns for widgets
+ * (audit B #6/#7). Same argument, different numbers: a KPI is a short pre-formatted string, so it
+ * packs tighter than a chart card and the law starts at TWO on a phone.
+ *
+ * **`cols` is the DESKTOP count** and the only number a consumer states; the law is
+ * `base 2 → sm min(cols, 3) → lg cols`. Five is the ceiling — past that the cells are narrower than
+ * a formatted currency value and the row is a table.
+ *
+ * **`lg` enters the package here and in `WidgetGrid`, nowhere else.** `sm` stays the only
+ * breakpoint a consumer writes (`docs/CONTROLS-SPEC.md` §2).
+ *
+ * `divided` swaps the column gap for a hairline rail between cells — the bare-metric-row look, for
+ * KPIs that are one reading split several ways rather than several independent cards. It draws the
+ * rule on the GROUP, so the cells stay whatever they are; on `StatCard`s (which carry their own
+ * panel and shadow ring) the rail reads as a second frame, so pair it with unadorned children.
+ *
+ * @example
+ * import { StatCard, StatGroup } from 'basalt-ui'
+ *
+ * <StatGroup cols={4}>
+ *   {kpis.map((kpi) => (
+ *     <StatCard key={kpi.key} title={kpi.title} value={kpi.value} delta={kpi.delta} />
+ *   ))}
+ * </StatGroup>
+ */
+import type { ReactNode } from 'react';
+import type { BasaltProps } from '../common/props.js';
+/** The desktop KPI column count. */
+export type StatGroupCols = 2 | 3 | 4 | 5;
+export type StatGroupProps = BasaltProps & {
+    /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)`, a phone gets 2.
+     * Never a responsive object — the law is basalt's, see the module docblock. */
+    cols?: StatGroupCols;
+    /** Swap the column gap for a hairline rail between cells. Default `false`. */
+    divided?: boolean;
+    /** The KPI cells — normally `StatCard`s. */
+    children: ReactNode;
+};
+export declare function StatGroup({ cols, divided, children, className, style, }: StatGroupProps): import("react").JSX.Element;
+//# sourceMappingURL=stat-group.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stat-group.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-group.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAEzC,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC;mFAC+E;IAC/E,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAQ,EACR,OAAe,EACf,QAAQ,EACR,SAAS,EACT,KAAK,GACN,EAAE,cAAc,+BAuBhB"}

package/dist/dashboard/stat-group.js

@@ -0,0 +1,30 @@
+import { jsx } from "react/jsx-runtime";
+import { cx } from "../common/props.js";
+import classes from "./stat-group.module.css";
+function StatGroup({
+  cols = 4,
+  divided = false,
+  children,
+  className,
+  style
+}) {
+  const smCols = Math.min(cols, 3);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cx(classes.root, className),
+      "data-cols": cols,
+      "data-sm-cols": smCols,
+      ...divided && { "data-divided": "true" },
+      style: {
+        "--basalt-stat-group-cols-sm": smCols,
+        "--basalt-stat-group-cols-lg": cols,
+        ...style
+      },
+      children
+    }
+  );
+}
+export {
+  StatGroup
+};