basalt-ui 1.24.0 → 1.26.0

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/query-state.d.ts

@@ -5,7 +5,7 @@ export type QueryStateVariant = 'page' | 'section';
  * The structural subset of a TanStack `UseQueryResult` these components read.
  *
  * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast (3 of image-share's 10 call sites are), and
+ * 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

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,60 @@
 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';
+/**
+ * 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;
     /** 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;
+    /**
+     * 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, delta, deltaPeriod, 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;AAclD;;;;;;;;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,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,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,KAAK,EACL,WAAW,EACX,SAAS,EACT,kBAA4B,EAC5B,OAAO,EACP,IAAI,GACL,EAAE,aAAa,+BAmGf"}

package/dist/dashboard/stat-card.js

@@ -1,7 +1,36 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Box, Card, Group, VisuallyHidden } from "@mantine/core";
-import { DeltaBadge } from "./delta-badge.js";
+import { Box, Card, VisuallyHidden } from "@mantine/core";
+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 classes from "./stat-card.module.css";
+const SPARKLINE_RIGHT_WIDTH = 72;
+const SPARKLINE_RIGHT_HEIGHT = 26;
+function useSlotWidth(active) {
+  const [width, setWidth] = useState(0);
+  const nodeRef = useRef(null);
+  useEffect(() => {
+    const node = nodeRef.current;
+    if (!active || node === null) return;
+    const measure = () => {
+      setWidth(node.getBoundingClientRect().width);
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => {
+      observer.disconnect();
+    };
+  }, [active]);
+  return {
+    ref: (node) => {
+      nodeRef.current = node;
+    },
+    width
+  };
+}
 const TONE_RAIL_WIDTH = 3;
 const TONE_LABEL = {
   good: "Within the good threshold",
@@ -9,14 +38,22 @@ const TONE_LABEL = {
   bad: "Past the severe threshold"
 };
 function StatCard({
-  label,
+  title,
+  icon,
+  subtitle,
+  info,
   value,
   delta,
   deltaPeriod,
   sparkline,
-  menu,
+  sparklinePlacement = "bleed",
+  actions,
   tone
 }) {
+  const isRender = typeof sparkline === "function";
+  const bleeds = sparklinePlacement === "bleed";
+  const slot = useSlotWidth(isRender);
+  const measured = { width: slot.width, height: SPARKLINE_RIGHT_HEIGHT };
   return /* @__PURE__ */ jsxs(
     Card,
     {
@@ -27,12 +64,13 @@ function StatCard({
         // shadow-card ring is unaffected (verified — only an ANCESTOR's overflow clips a
         // descendant's shadow). Mantine's Card root already sets `overflow: hidden`; this is
         // explicit for intent.
+        //
+        // NO `minHeight`. It was 118px, which is ~25px of dead space under a card holding a title
+        // row, a hero row and a 26px trend — and it was dead space the card could not use, since the
+        // body is `height: 100%` and the sparkline is `margin-top: auto`. The content is what states
+        // the height now (~88-96px), and four cards in a `SimpleGrid` still match because a grid row
+        // stretches its items.
         padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)",
-        minHeight: 118,
-        display: "flex",
-        // theme-allow inline-display — Card root as a flex column; Mantine Card takes no layout props
-        flexDirection: "column",
-        gap: "var(--vx-space-stat-card-gap)",
         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.
@@ -60,50 +98,44 @@ function StatCard({
             }
           )
         ] }),
-        /* @__PURE__ */ jsxs(Group, { justify: "space-between", align: "flex-start", wrap: "nowrap", gap: "xs", children: [
-          /* @__PURE__ */ jsx(
-            "span",
+        /* @__PURE__ */ jsxs("div", { className: classes.body, "data-placement": sparklinePlacement, children: [
+          /* @__PURE__ */ jsx("div", { className: classes.header, children: /* @__PURE__ */ jsx(
+            WidgetHeader,
             {
-              style: {
-                fontFamily: "var(--basalt-font-mono)",
-                fontSize: VX.text.xs,
-                fontWeight: 500,
-                letterSpacing: "0.06em",
-                textTransform: "uppercase",
-                color: VX.faint
-              },
-              children: label
+              tier: "widget",
+              title,
+              ...icon !== void 0 && { icon },
+              ...subtitle !== void 0 && { subtitle },
+              ...info !== void 0 && { info },
+              value,
+              ...delta !== void 0 && { delta },
+              ...deltaPeriod !== void 0 && { deltaPeriod },
+              ...actions !== void 0 && {
+                actions: /* @__PURE__ */ jsx(CtlSlot, { tier: "widget", children: actions })
+              }
             }
-          ),
-          menu
-        ] }),
-        /* @__PURE__ */ jsxs(Group, { align: "center", gap: 8, wrap: "nowrap", children: [
-          /* @__PURE__ */ jsx(
-            "span",
+          ) }),
+          sparkline !== void 0 && /* @__PURE__ */ jsx(
+            "div",
             {
-              style: {
-                fontFamily: "var(--basalt-font-mono)",
-                fontSize: VX.text.kpi,
-                fontWeight: 600,
-                letterSpacing: "-0.02em",
-                color: VX.ink
+              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: value
+              children: isRender ? measured.width > 0 && sparkline(measured) : sparkline
             }
-          ),
-          delta !== void 0 && /* @__PURE__ */ jsx(DeltaBadge, { value: delta, period: deltaPeriod })
-        ] }),
-        sparkline && /* @__PURE__ */ jsx(
-          "div",
-          {
-            style: {
-              marginTop: "auto",
-              marginInline: "calc(-1 * var(--mantine-spacing-sm))",
-              marginBottom: "calc(-1 * var(--mantine-spacing-xs))"
-            },
-            children: sparkline
-          }
-        )
+          )
+        ] })
       ]
     }
   );

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

@@ -0,0 +1,82 @@
+/*
+ * 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).
+ */
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stat-card-gap);
+  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.
+ */
+.body[data-placement='right'] .header {
+  flex: 1 0 auto;
+  min-width: 0;
+}
+
+.sparklineBleed {
+  margin-top: auto;
+  margin-inline: calc(-1 * var(--mantine-spacing-sm));
+  margin-bottom: calc(-1 * var(--mantine-spacing-xs));
+}
+
+/* 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. */
+.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;
+  overflow: hidden;
+}
+
+@media (max-width: 47.99375em) {
+  .body[data-placement='right'] {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .body[data-placement='right'] .header {
+    flex: initial;
+  }
+
+  /* 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 {
+    flex: none;
+    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

@@ -0,0 +1,11 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly body: string
+  readonly header: string
+  readonly sparklineBleed: string
+  readonly sparklineRight: string
+}
+export default classes