basalt-ui 1.25.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/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

package/dist/data/data-table.d.ts

@@ -24,16 +24,16 @@ declare module '@tanstack/react-table' {
         numeral?: boolean;
     }
 }
-/** A single selectable option inside a {@link DataTableFacet}'s Select/MultiSelect. */
+/** A single selectable option inside a {@link DataTableFacet}'s `EnumFilter`/`MultiSelectFilter` pill. */
 export type DataTableFacetOption = {
     /** The raw filter value, compared against the column's stringified cell value. */
     value: string;
-    /** Label shown in the Select/MultiSelect dropdown. */
+    /** Label shown in the pill's popover. */
     label: string;
 };
 /**
- * Declares one faceted column filter, rendered as a Mantine Select (or MultiSelect when
- * `multiple` is set) inside the toolbar.
+ * Declares one faceted column filter, rendered as an `EnumFilter` pill (or `MultiSelectFilter`
+ * when `multiple` is set) inside a `FilterSet` in the toolbar (`docs/CONTROLS-SPEC.md` §3).
  *
  * @example
  * const facets: DataTableFacet[] = [
@@ -45,11 +45,11 @@ export type DataTableFacetOption = {
 export type DataTableFacet = {
     /** The TanStack column id — the column's manual `id`, or its `accessorKey` string. */
     columnId: string;
-    /** Label shown as the Select/MultiSelect placeholder. */
+    /** The pill's label — read at rest (single-select) and as the `Filters`/count fallback (multi). */
     label: string;
     /** Selectable options for this facet. */
     options: DataTableFacetOption[];
-    /** Render a MultiSelect (any-of match) instead of a single Select (exact match). @default false */
+    /** Render a `MultiSelectFilter` (any-of match) instead of an `EnumFilter` (exact match). @default false */
     multiple?: boolean;
 };
 /**
@@ -66,6 +66,16 @@ export type DataTableFacet = {
  * }
  */
 export type BasaltDataTableProps<T> = {
+    /**
+     * Optional heading rendered above the toolbar via `WidgetHeader tier="widget"`. `count` always
+     * reads `table.getRowCount()` (C11) — never a raw `data.length` — so it tracks the row model
+     * (post-filter/-pagination) rather than the unfiltered input.
+     */
+    title?: string;
+    /** Optional leading icon, forwarded to `WidgetHeader`. */
+    icon?: ReactNode;
+    /** Optional muted line rendered below the title row. */
+    subtitle?: string;
     /** Row data array. */
     data: T[];
     /**
@@ -162,9 +172,9 @@ export type BasaltDataTableProps<T> = {
     /** Called whenever the internal global filter value changes. */
     onGlobalFilterChange?: (value: string) => void;
     /**
-     * Faceted column filters, rendered in the toolbar as Mantine Select/MultiSelect controls wired
-     * to TanStack's per-column `columnFilters` state. The toolbar renders whenever this array is
-     * non-empty, `enableGlobalFilter` is set, or `toolbarActions` is passed.
+     * Faceted column filters, rendered in the toolbar as `EnumFilter`/`MultiSelectFilter` pills
+     * inside a `FilterSet`, wired to TanStack's per-column `columnFilters` state. The toolbar
+     * renders whenever this array is non-empty, `enableGlobalFilter` is set, or `actions` is passed.
      * @example
      * facets={[{ columnId: 'department', label: 'Department', options: departmentOptions }]}
      */
@@ -183,9 +193,10 @@ export type BasaltDataTableProps<T> = {
     manualFiltering?: boolean;
     /**
      * Right-aligned toolbar slot (e.g. an "Export" button). Renders the toolbar row even when no
-     * search input or facets are configured.
+     * search input or facets are configured. Renamed from `toolbarActions` — the toolbar (search +
+     * facets + this slot) is wrapped in `CtlSlot` (C1/C5), so its controls resolve to the `ctl` tier.
      */
-    toolbarActions?: ReactNode;
+    actions?: ReactNode;
     /**
      * Enables the bottom pagination bar ("Showing X–Y of N", rows-per-page `Select`, Mantine
      * `Pagination`) wired to TanStack's `pagination` state. Client-side by default — see
@@ -280,9 +291,20 @@ export type BasaltDataTableProps<T> = {
     /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
     withRowBorders?: boolean;
     /**
-     * Outer table border. Turn it OFF for a table that already sits inside a `Card`/`ChartCard`,
-     * where the card owns the frame and a second one reads as a nested box.
-     * @default true
+     * Outer table border — a full box around the table.
+     *
+     * **`false` by default since this minor** (it was `true`). Three separate faults, all visible on
+     * the playground's `Controls (mobile)` page at 390px: its TOP edge sat directly under the table's
+     * own `WidgetHeader`, separating a header from its own content; its BOTTOM edge landed on the last
+     * row's own hairline, two rules at zero distance; and its left/right edges carried no information
+     * at all on a table that fills the page (`docs/DESIGN-SPEC.md` §8 — a border is a layout divider,
+     * and there is nothing here to divide). The head-row rule and the between-row rules stay, so the
+     * table still reads as a table.
+     *
+     * Pass `true` for a table that genuinely needs a frame — a small table floating in whitespace
+     * beside other content, where the box IS the grouping.
+     *
+     * @default false
      */
     withTableBorder?: boolean;
 };
@@ -311,5 +333,5 @@ export type BasaltDataTableProps<T> = {
  *   emptyState={<Text c="dimmed">No users found.</Text>}
  * />
  */
-export declare function BasaltDataTable<T>({ data, columns, enableSorting, manualSorting, striped, highlightOnHover, emptyState, isLoading, skeletonRows, initialSorting, onSortingChange, enableGlobalFilter, globalFilterPlaceholder, searchIcon, initialGlobalFilter, onGlobalFilterChange, facets, onColumnFiltersChange, manualFiltering, toolbarActions, enablePagination, pageSizeOptions, initialPagination, onPaginationChange, manualPagination, rowCount, pageCount, enablePinning, initialColumnPinning, maxHeight, minWidth, stickyHeader, stickyHeaderOffset, verticalSpacing, horizontalSpacing, withRowBorders, withTableBorder, }: BasaltDataTableProps<T>): import("react").JSX.Element;
+export declare function BasaltDataTable<T>({ title, icon, subtitle, data, columns, enableSorting, manualSorting, striped, highlightOnHover, emptyState, isLoading, skeletonRows, initialSorting, onSortingChange, enableGlobalFilter, globalFilterPlaceholder, searchIcon, initialGlobalFilter, onGlobalFilterChange, facets, onColumnFiltersChange, manualFiltering, actions, enablePagination, pageSizeOptions, initialPagination, onPaginationChange, manualPagination, rowCount, pageCount, enablePinning, initialColumnPinning, maxHeight, minWidth, stickyHeader, stickyHeaderOffset, verticalSpacing, horizontalSpacing, withRowBorders, withTableBorder, }: BasaltDataTableProps<T>): import("react").JSX.Element;
 //# sourceMappingURL=data-table.d.ts.map