basalt-ui 1.26.0 → 1.28.0

package/dist/widget-header/index.js

@@ -1,4 +1,6 @@
-import { WidgetHeader } from "./widget-header.js";
+import {
+  WidgetHeader
+} from "./widget-header.js";
 import { DeltaBadge } from "./delta-badge.js";
 export {
   DeltaBadge,

package/dist/widget-header/widget-header.d.ts

@@ -1,8 +1,25 @@
 import type { ReactNode } from 'react';
-export type WidgetHeaderProps = {
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { DeltaPolarity } from './delta-badge.js';
+export type WidgetHeaderTier = 'section' | 'widget' | 'group';
+/**
+ * The four boxes a consumer can reach (`common/props.ts`): `root` is the header stack, `title` is
+ * the heading ELEMENT (`<h2>`/`<h3>`) rather than its row, `metric` is the hero `value`/`unit`/
+ * `delta` row, `icon` is the leading `IconSlot`.
+ *
+ * The other boxes this paints — the title row, the count tag, the actions span, the subtitle, the
+ * sparkline, the info bubble — are deliberately absent. Each is a one-shot readout basalt positions,
+ * not a layout box a consumer places, and `actions`/`sparkline` already take a `ReactNode` the
+ * caller can class itself.
+ */
+export type WidgetHeaderSlot = 'root' | 'title' | 'metric' | 'icon';
+export type WidgetHeaderProps = BasaltProps & SlotStylesProps<WidgetHeaderSlot> & {
     /** `section` renders an `<h2>` at the section-header height; `widget` renders an `<h3>` at the
-     * tighter icon-tier height, display-only. */
-    tier: 'section' | 'widget';
+     * tighter icon-tier height, display-only; `group` also renders an `<h3>` but as the quietest
+     * heading rank on the page — mono micro uppercase faint, one step below `widget` — for an
+     * inspector/aside group label. `Section` resolves `group` automatically from the enclosing filter
+     * surface; it is never a call-site prop. */
+    tier: WidgetHeaderTier;
     /** Head-font title (88% stretch, weight 550). */
     title: string;
     /** Optional leading icon, rendered before the title. Decorative — hidden from assistive tech. */
@@ -20,10 +37,43 @@ export type WidgetHeaderProps = {
     /** Pre-formatted metric value (mono, hero size). Renders on its own row with `delta`, directly
      * under the title row — never inline with the title. */
     value?: string;
+    /**
+     * The value's unit, rendered immediately after it on the hero row: muted, mono, `--vx-text-sm`.
+     *
+     * It exists because `value` is a pre-formatted `string` and a KPI's unit is not part of the
+     * number: `412` and `TSS` are two facts at two weights, and jamming them into one string paints
+     * the unit at the hero's 24px — which reads as a second numeral. `subtitle` was the only place a
+     * unit could go before this, and a unit on its own line under the value is a different claim (the
+     * BASIS: `7-day rolling`), so cards using both had to pick one.
+     *
+     * Never a substitute for the number's own formatting: a thousands separator, a currency symbol or
+     * a `%` belong in `value`, where they are part of how the numeral reads.
+     */
+    unit?: string;
     /** Signed delta rendered via `DeltaBadge`, on the same hero-metric row as `value`. */
     delta?: number;
     /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
     deltaPeriod?: string;
+    /** Which sign reads as the good verdict — forwarded to `DeltaBadge`'s `polarity`. Defaults to
+     * `'up-good'` (today's behaviour). See {@link DeltaPolarity}. */
+    deltaPolarity?: DeltaPolarity;
+    /**
+     * Formats `delta` into the chip's label — forwarded to `DeltaBadge`'s `format`. Defaults to
+     * `${Math.abs(delta).toFixed(1)}%`.
+     *
+     * It exists because not every delta is a percentage: a pace card's trend is `0:12 /km` and a
+     * throughput card's is `0.3 km/h`, and the default printed both as a percent — a wrong unit on a
+     * KPI, which is worse than no chip. A FUNCTION rather than a label string, so the number stays the
+     * number: `delta` still drives the tone and the glyph, and there is exactly one place the sign is
+     * decided.
+     *
+     * The value arrives SIGNED, so a formatter that wants to print the sign itself (`−0:12 /km`) can —
+     * pair it with `deltaGlyph={false}` so the ▼ does not say the same thing twice.
+     */
+    deltaFormat?: (delta: number) => string;
+    /** Render `DeltaBadge`'s ▲/▼ glyph. Defaults to `true`; a zero delta never shows one. Pass
+     * `false` when `deltaFormat` prints the sign itself. */
+    deltaGlyph?: boolean;
     /** Trend visual slot, rendered below the metric row. Carries `data-placement="right"` so a
      * wave-3 composer's `bleed` layout can select it. */
     sparkline?: ReactNode;
@@ -33,5 +83,50 @@ export type WidgetHeaderProps = {
     /** Right-aligned slot (`margin-inline-start: auto`) — the C1/C5 home for header actions. */
     actions?: ReactNode;
 };
-export declare function WidgetHeader({ tier, title, icon, subtitle, info, value, delta, deltaPeriod, sparkline, count, actions, }: WidgetHeaderProps): import("react").JSX.Element;
+/**
+ * The named slices of {@link WidgetHeaderProps} its composers share, and the answer to audit B #2:
+ * four composers exposed four DIFFERENT subsets of the same base through four ad-hoc `Omit`s, so a
+ * consumer moving a KPI from `StatCard` → `ChartCard` → `Section` lost `unit`, `count`,
+ * `deltaFormat` or `deltaGlyph` with no compiler word about it. A slice is a `Pick` with a NAME:
+ * a composer states which slices it re-publishes, and an omission becomes a deliberate, readable
+ * line rather than an accident of whichever props the author happened to remember.
+ *
+ * The three are cut along the three ROWS `WidgetHeader` actually paints — the title row, the hero
+ * metric, and the delta chip on it — so "which slice does this composer take" and "which boxes does
+ * it draw" are the same question.
+ *
+ * Adopted by `StatCard` and `SettingsSection`. `Section` and `ChartCard` still cut their own
+ * subsets; both should compose these instead — the composer table in `docs/CONTROLS-SPEC.md` §2.2
+ * is the ledger of which one takes which.
+ *
+ * The title row: what every composer without exception publishes.
+ */
+export type WidgetHeaderTitleProps = Pick<WidgetHeaderProps, 'title' | 'icon' | 'subtitle' | 'info'>;
+/**
+ * The hero metric row's value half. `value` is OPTIONAL here because it is on `WidgetHeader`; a
+ * composer whose whole reason to exist is the number (`StatCard`) redeclares it as required.
+ */
+export type WidgetHeaderMetricProps = Pick<WidgetHeaderProps, 'value' | 'unit'>;
+/**
+ * The delta chip that rides the hero metric row — all five props together, never a subset. Splitting
+ * them is how `deltaFormat` came to type-check on `Section` and render nothing: a composer that
+ * publishes `delta` and not its formatter prints a percent sign over a pace.
+ */
+export type WidgetHeaderDeltaProps = Pick<WidgetHeaderProps, 'delta' | 'deltaPeriod' | 'deltaPolarity' | 'deltaFormat' | 'deltaGlyph'>;
+/**
+ * The info affordance. A `title` attribute alone was never enough — it renders on hover only, so a
+ * keyboard user focusing the glyph saw nothing at all. This is the bubble `ChartCard` used to own
+ * before it composed `WidgetHeader`, moved down here so every tier gets the same behaviour:
+ * opens on hover/focus/click, closes on leave/blur/Escape/outside pointer-down, and is wired to the
+ * trigger with `aria-describedby` only while open.
+ *
+ * Exported from the MODULE but deliberately not from `src/widget-header/index.ts`: it is not a
+ * public primitive, it is the one info affordance basalt draws, and `controls/panel-row.tsx`
+ * composes it so an inspector row's `hint` is the same glyph, bubble and keyboard behaviour a
+ * `WidgetHeader`'s `info` is — not a second one that drifts.
+ */
+export declare function InfoGlyph({ text }: {
+    text: string;
+}): import("react").JSX.Element;
+export declare function WidgetHeader({ tier, title, icon, subtitle, info, value, unit, delta, deltaPeriod, deltaPolarity, deltaFormat, deltaGlyph, sparkline, count, actions, className, style, classNames, }: WidgetHeaderProps): import("react").JSX.Element;
 //# sourceMappingURL=widget-header.d.ts.map

package/dist/widget-header/widget-header.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget-header.d.ts","sourceRoot":"","sources":["../../src/widget-header/widget-header.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,MAAM,MAAM,iBAAiB,GAAG;IAC9B;iDAC6C;IAC7C,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC1B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,iGAAiG;IACjG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;4DACwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;yDACqD;IACrD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4FAA4F;IAC5F,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAyDD,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,KAAK,EACL,OAAO,GACR,EAAE,iBAAiB,+BAiCnB"}
+{"version":3,"file":"widget-header.d.ts","sourceRoot":"","sources":["../../src/widget-header/widget-header.tsx"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAGlD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEnE,MAAM,MAAM,iBAAiB,GAAG,WAAW,GACzC,eAAe,CAAC,gBAAgB,CAAC,GAAG;IAClC;;;;gDAI4C;IAC5C,IAAI,EAAE,gBAAgB,CAAA;IACtB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,iGAAiG;IACjG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;4DACwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;qEACiE;IACjE,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;4DACwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;yDACqD;IACrD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;2EACuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4FAA4F;IAC5F,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC,CAAA;AAEpG;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC,CAAA;AAE/E;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,iBAAiB,EACjB,OAAO,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,YAAY,CACzE,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,+BA8CnD;AAED,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,KAAK,EACL,OAAO,EACP,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,iBAAiB,+BAoDnB"}

package/dist/widget-header/widget-header.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../common/props.js";
 import { IconSlot } from "../theme/icon-slot.js";
 import { DeltaBadge } from "./delta-badge.js";
 import classes from "./widget-header.module.css";
@@ -47,31 +48,57 @@ function WidgetHeader({
   subtitle,
   info,
   value,
+  unit,
   delta,
   deltaPeriod,
+  deltaPolarity,
+  deltaFormat,
+  deltaGlyph,
   sparkline,
   count,
-  actions
+  actions,
+  className,
+  style,
+  classNames
 }) {
   const Heading = tier === "section" ? "h2" : "h3";
-  return /* @__PURE__ */ jsxs("div", { className: classes.root, "data-tier": tier, children: [
-    /* @__PURE__ */ jsxs("div", { className: classes.titleRow, children: [
-      /* @__PURE__ */ jsxs(Heading, { className: classes.heading, children: [
-        icon !== void 0 && /* @__PURE__ */ jsx(IconSlot, { className: classes.icon, children: icon }),
-        /* @__PURE__ */ jsx("span", { className: classes.titleText, children: title })
-      ] }),
-      info !== void 0 && /* @__PURE__ */ jsx(InfoGlyph, { text: info }),
-      count !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.count, children: count }),
-      actions !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.actions, children: actions })
-    ] }),
-    (value !== void 0 || delta !== void 0) && /* @__PURE__ */ jsxs("div", { className: classes.metrics, children: [
-      value !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.value, children: value }),
-      delta !== void 0 && /* @__PURE__ */ jsx(DeltaBadge, { value: delta, period: deltaPeriod })
-    ] }),
-    subtitle !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.subtitle, children: subtitle }),
-    sparkline !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.sparkline, "data-placement": "right", children: sparkline })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(classes.root, classNames?.root, className),
+      "data-tier": tier,
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: classes.titleRow, children: [
+          /* @__PURE__ */ jsxs(Heading, { className: cx(classes.heading, classNames?.title), children: [
+            icon !== void 0 && /* @__PURE__ */ jsx(IconSlot, { className: cx(classes.icon, classNames?.icon), children: icon }),
+            /* @__PURE__ */ jsx("span", { className: classes.titleText, children: title })
+          ] }),
+          info !== void 0 && /* @__PURE__ */ jsx(InfoGlyph, { text: info }),
+          count !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.count, children: count }),
+          actions !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.actions, children: actions })
+        ] }),
+        (value !== void 0 || delta !== void 0) && /* @__PURE__ */ jsxs("div", { className: cx(classes.metrics, classNames?.metric), children: [
+          value !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.value, children: value }),
+          value !== void 0 && unit !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.unit, children: unit }),
+          delta !== void 0 && /* @__PURE__ */ jsx(
+            DeltaBadge,
+            {
+              value: delta,
+              period: deltaPeriod,
+              ...deltaPolarity !== void 0 && { polarity: deltaPolarity },
+              ...deltaFormat !== void 0 && { format: deltaFormat },
+              ...deltaGlyph !== void 0 && { withGlyph: deltaGlyph }
+            }
+          )
+        ] }),
+        subtitle !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.subtitle, children: subtitle }),
+        sparkline !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.sparkline, "data-placement": "right", children: sparkline })
+      ]
+    }
+  );
 }
 export {
+  InfoGlyph,
   WidgetHeader
 };

package/dist/widget-header/widget-header.module.css

@@ -10,7 +10,7 @@
  * `--mantine-spacing-*` fallbacks.
  *
  * Layout: the title row holds title/icon/info/count/actions only. `value` + `delta` render on
- * their own hero-metric row directly beneath it — for BOTH tiers, never inline with the title.
+ * their own hero-metric row directly beneath it — for every tier, never inline with the title.
  */
 
 .root {
@@ -40,24 +40,75 @@
     flex-wrap: wrap;
     row-gap: var(--vx-space-stack-sm);
   }
+
+  /*
+   * WRAP ONLY WHEN IT DOES NOT FIT (M4 follow-up) — `flex: 1 1 100%` forced EVERY actions slot onto
+   * its own row, even a single 24px icon that fit beside the title fine (a KPI card's lone `···`
+   * menu dropped under the title and pushed the value down with it). `flex: 0 1 auto` restores
+   * ordinary flex sizing: no grow, so a short slot stays put beside the title on the shared row;
+   * `min-width: 0` plus `flex-shrink: 1` (part of the same shorthand, overriding the base rule's
+   * `flex-shrink: 0`) let it shrink and, once `.titleRow`'s own `flex-wrap: wrap` decides it truly
+   * does not fit, drop to its own line. `max-width: 100%` is the cap once it IS alone on that line —
+   * without it a `.actions` still carrying unshrinkable content (the `visibleFrom="sm"` control plus
+   * a nowrap switch `Group`, see below) can overflow the card rather than shrink into it. The base
+   * rule's `margin-inline-start: auto` still applies in both states — right-aligned beside the title
+   * when it fits, right-aligned as the lone item on its own wrapped line when it does not.
+   *
+   * `.actions` keeps its OWN `flex-wrap: wrap` from the prior fix: `Section` can hand it a `tabs`
+   * control (`CtlSlot`-wrapped) AND an `actions` control (another `CtlSlot`) in the same slot, and
+   * without this a nowrap `Group` of switches beside a view-switch control gets squeezed into one
+   * shared line and overflows below its own min-content width — the exact regression this rule
+   * once fixed. It is orthogonal to the row-level "wrap only when it does not fit" law above: with
+   * one child, wrapping has nothing to do, so a lone `···` menu still stays on the title line.
+   *
+   * The real flex items get `flex: 1 1 auto; min-width: 0` so they can shrink or (via the `> * > *`
+   * twin) stack within whatever width `.actions` itself resolves to — a full-width phone `Select`
+   * still reads as its own full-width line because the CONTROL sets that itself (`ViewTabs`'
+   * `fullWidth`/`.phoneSelect`), not because `.actions` forces it.
+   *
+   * The `> * > *` twin exists because `CtlSlot` (`theme/ctl-theme.tsx`) wraps a home's actions in a
+   * `display: contents` box — invisible to the flex box tree, so its OWN children (not it) are the
+   * real flex items. `display: contents` elements still match `.actions > *` by DOM structure but
+   * carry no box to apply `flex`/`min-width` to, hence styling one level deeper as well; a call site
+   * that skips `CtlSlot` and hands `actions` a real element directly gets the same rule from the
+   * first selector.
+   */
+  .actions {
+    flex: 0 1 auto;
+    flex-wrap: wrap;
+    min-width: 0;
+    max-width: 100%;
+  }
+
+  .actions > *,
+  .actions > * > * {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
 }
 
 .root[data-tier='section'] .titleRow {
   min-height: var(--vx-space-section-header-height, 2.25rem);
 }
 
-.root[data-tier='widget'] .titleRow {
+/* `group` shares the `widget` tier's row height — an inspector/aside group label carries no more
+ * vertical weight than a card's own title. */
+.root[data-tier='widget'] .titleRow,
+.root[data-tier='group'] .titleRow {
   min-height: var(--vx-space-widget-header-height, 1.75rem);
 }
 
 /*
- * Section → h2, widget → h3, and the two tiers now read DIFFERENTLY on purpose — they did not, and
- * that is what flattened the page.
+ * Section → h2, widget → h3, group → h3, and the three tiers now read DIFFERENTLY on purpose — they
+ * did not, and that is what flattened the page.
  *
  * A `section` heading names a region of the page: 15px, weight 600, INK. A `widget` heading labels a
  * number that is itself the thing being read (a KPI card's hero value, a chart card's total), so it
  * is the quieter of the pair — one step down and MUTED, which is what lets the 24px mono value under
- * it carry the card. Both keep the shared head-font 88% stretch.
+ * it carry the card. A `group` heading is quieter still: the sidebar's own micro-label recipe (mono,
+ * uppercase, faint), because an inspector/aside group ("Presets", "Composition") must never outrank
+ * a canvas card's title. All three keep the shared head-font 88% stretch as their base, though
+ * `group` overrides every visual property of it (see below).
  *
  * Rendered identically (15px ink both) the hero value competed with its own label, four cards in a
  * row read as four headings, and the section that grouped them read as one more of the same.
@@ -84,6 +135,18 @@
   color: var(--vx-muted);
 }
 
+/* The `group` tier's heading — the sidebar `.sectionLabel` recipe (`shell/app-sidebar.module.css`),
+ * the quietest heading rank on the page. An inspector/aside group label, not a title. */
+.root[data-tier='group'] .heading {
+  font-family: var(--basalt-font-mono);
+  font-stretch: normal;
+  font-size: var(--vx-text-micro);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--vx-faint);
+}
+
 .titleText {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -106,7 +169,8 @@
   color: var(--vx-faint);
 }
 
-.root[data-tier='widget'] .icon {
+.root[data-tier='widget'] .icon,
+.root[data-tier='group'] .icon {
   --vx-space-icon-size: 0.875rem;
 }
 
@@ -139,7 +203,7 @@
 }
 
 /*
- * The hero-metric row — value + delta, directly under the title row, for both tiers. The delta rides
+ * The hero-metric row — value + delta, directly under the title row, for every tier. The delta rides
  * 4px off the value, not 8: it is a suffix ON the number (`$168,920 +47%`), and at 8px it read as a
  * second, unrelated chip in the row. `baseline` alignment is what keeps the mono numeral and the
  * badge's own smaller mono text sitting on one line.
@@ -199,6 +263,21 @@
   color: var(--vx-ink);
 }
 
+/*
+ * The unit beside the hero value. Mono like the number it qualifies (so `412 TSS` sits on one
+ * baseline grid), `--vx-text-sm` and `--vx-muted` so it never competes with the numeral — the whole
+ * point is that a unit is the SMALL half of the pair. `flex-shrink: 0`: the value is the row's
+ * shrinkable half (see `.value`), and a unit that ellipsized to `TS…` would state nothing.
+ */
+.unit {
+  flex-shrink: 0;
+  align-self: baseline;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-muted);
+}
+
 /* The C1/C5 home for header actions — always pinned right, regardless of what else is present. */
 .actions {
   display: inline-flex;
@@ -206,6 +285,7 @@
   align-items: center;
   gap: var(--vx-space-control-gap, 0.375rem);
   margin-inline-start: auto;
+  min-width: 0;
 }
 
 /* Directly under the title row, 4px off it — 1px put it inside the title's own line box, so a

package/dist/widget-header/widget-header.module.css.d.ts

@@ -11,6 +11,7 @@ declare const classes: {
   readonly count: string
   readonly metrics: string
   readonly value: string
+  readonly unit: string
   readonly actions: string
   readonly subtitle: string
   readonly sparkline: string

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.26.0
+# basalt-ui v1.28.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.26.0
+Version: 1.28.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)
+Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)
 Layer: mantine-coupled
 Rule: basalt-mantine
 OptionalPeers: react-markdown@^10.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.3.0, shiki@^4.3.0, beautiful-mermaid@^1.1.0
@@ -48,7 +48,7 @@ Layer: mantine-coupled
 ## basalt-ui/vite
 Import: import { ... } from 'basalt-ui/vite'
 Description: basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette
-Layer: mantine-coupled
+Layer: build-tooling
 OptionalPeers: vite-plugin-pwa@^1.3.0
 
 ## basalt-ui/guard
@@ -72,7 +72,7 @@ OptionalPeers: @tanstack/react-router@^1.170.0
 
 ## basalt-ui/forms
 Import: import { ... } from 'basalt-ui/forms'
-Description: Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)
+Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema; deprecated `field` alias for `inputProps` until the surface next changes)
 Layer: mantine-coupled
 Rule: basalt-batteries
 OptionalPeers: @mantine/form@^9.3.0
@@ -135,7 +135,7 @@ OptionalPeers: shiki@^4.3.0, @shikijs/langs@^4.3.1, @shikijs/themes@^4.3.1, beau
 
 ## basalt-ui/controls
 Import: import { ... } from 'basalt-ui/controls'
-Description: The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
+Description: The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
 Layer: mantine-coupled
 Rule: basalt-controls
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -31,6 +31,8 @@
   "files": [
     "dist/",
     "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "configs/",
     "agent/",
     "bin/",
@@ -47,100 +49,122 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./charts": {
       "types": "./dist/charts/index.d.ts",
-      "import": "./dist/charts/index.js"
+      "import": "./dist/charts/index.js",
+      "default": "./dist/charts/index.js"
     },
     "./tokens": {
       "types": "./dist/tokens/index.d.ts",
-      "import": "./dist/tokens/index.js"
+      "import": "./dist/tokens/index.js",
+      "default": "./dist/tokens/index.js"
     },
     "./theme-lab": {
       "types": "./dist/theme-lab/index.d.ts",
-      "import": "./dist/theme-lab/index.js"
+      "import": "./dist/theme-lab/index.js",
+      "default": "./dist/theme-lab/index.js"
     },
     "./vite": {
       "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
+      "import": "./dist/vite.js",
+      "default": "./dist/vite.js"
     },
     "./guard": {
       "types": "./dist/guard/index.d.ts",
-      "import": "./dist/guard/index.js"
+      "import": "./dist/guard/index.js",
+      "default": "./dist/guard/index.js"
     },
     "./forms": {
       "types": "./dist/forms/index.d.ts",
-      "import": "./dist/forms/index.js"
+      "import": "./dist/forms/index.js",
+      "default": "./dist/forms/index.js"
     },
     "./commands": {
       "types": "./dist/commands/index.d.ts",
-      "import": "./dist/commands/index.js"
+      "import": "./dist/commands/index.js",
+      "default": "./dist/commands/index.js"
     },
     "./notifications": {
       "types": "./dist/notifications/index.d.ts",
-      "import": "./dist/notifications/index.js"
+      "import": "./dist/notifications/index.js",
+      "default": "./dist/notifications/index.js"
     },
     "./query": {
       "types": "./dist/query/index.d.ts",
-      "import": "./dist/query/index.js"
+      "import": "./dist/query/index.js",
+      "default": "./dist/query/index.js"
     },
     "./router-tanstack": {
       "types": "./dist/router-tanstack/index.d.ts",
-      "import": "./dist/router-tanstack/index.js"
+      "import": "./dist/router-tanstack/index.js",
+      "default": "./dist/router-tanstack/index.js"
     },
     "./data": {
       "types": "./dist/data/index.d.ts",
-      "import": "./dist/data/index.js"
+      "import": "./dist/data/index.js",
+      "default": "./dist/data/index.js"
     },
     "./data/table": {
       "types": "./dist/data/table.d.ts",
-      "import": "./dist/data/table.js"
+      "import": "./dist/data/table.js",
+      "default": "./dist/data/table.js"
     },
     "./data/virtual": {
       "types": "./dist/data/virtual.d.ts",
-      "import": "./dist/data/virtual.js"
+      "import": "./dist/data/virtual.js",
+      "default": "./dist/data/virtual.js"
     },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
-      "import": "./dist/agent/index.js"
+      "import": "./dist/agent/index.js",
+      "default": "./dist/agent/index.js"
     },
     "./agent-chat": {
       "types": "./dist/agent-chat/index.d.ts",
-      "import": "./dist/agent-chat/index.js"
+      "import": "./dist/agent-chat/index.js",
+      "default": "./dist/agent-chat/index.js"
     },
     "./content": {
       "types": "./dist/content/index.d.ts",
-      "import": "./dist/content/index.js"
+      "import": "./dist/content/index.js",
+      "default": "./dist/content/index.js"
     },
     "./controls": {
       "types": "./dist/controls/index.d.ts",
-      "import": "./dist/controls/index.js"
+      "import": "./dist/controls/index.js",
+      "default": "./dist/controls/index.js"
     },
     "./controls-dates": {
       "types": "./dist/controls-dates/index.d.ts",
-      "import": "./dist/controls-dates/index.js"
+      "import": "./dist/controls-dates/index.js",
+      "default": "./dist/controls-dates/index.js"
     },
     "./state": {
       "types": "./dist/state.d.ts",
-      "import": "./dist/state.js"
+      "import": "./dist/state.js",
+      "default": "./dist/state.js"
     },
     "./connectivity": {
       "types": "./dist/connectivity/index.d.ts",
-      "import": "./dist/connectivity/index.js"
+      "import": "./dist/connectivity/index.js",
+      "default": "./dist/connectivity/index.js"
     },
     "./styles.css": "./dist/styles.css",
     "./tokens.css": "./dist/tokens.css",
     "./configs/*": "./configs/*",
-    "./llms.txt": "./llms.txt"
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly --declarationMap && bun scripts/copy-assets.mjs && bun scripts/gen-tokens-css.mjs && bun scripts/fix-esm-extensions.mjs",
-    "typecheck": "tsc --noEmit && tsc -p tests/layout/tsconfig.json",
+    "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly --declarationMap && bun scripts/copy-assets.mjs && bun scripts/gen-tokens-css.mjs && bun scripts/fix-esm-extensions.mjs",
+    "typecheck": "tsc --noEmit",
     "test": "cd ../.. && bun test packages/basalt-ui",
     "pack-test": "bash scripts/pack-test.sh",
     "prepack": "bun run build",

package/src/agent/coalesce.ts

@@ -38,6 +38,7 @@
  * <PartList parts={coalesceParts(parts)} />
  */
 import type { AgentPart, ReasoningPart, TextPart, ToolCallPart } from './parts'
+import { isDev } from '../utils/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -169,7 +170,7 @@ function mergeToolPart(existing: ToolCallPart, next: ToolCallPart): ToolCallPart
       // and make every field read below a compile error, so the assertion is what makes the
       // runtime value usable. It asserts nothing tsc has not already proved on the line above.
       const fallback = unhandled as ToolCallPart
-      if (process.env['NODE_ENV'] !== 'production') {
+      if (isDev()) {
         console.warn(
           `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} — kept, merged best-effort`,
         )

package/src/agent/merge.ts

@@ -29,6 +29,7 @@
  * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
  */
 import type { ReasoningPart, TextPart } from './parts'
+import { isDev } from '../utils/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -78,7 +79,7 @@ function clampOffset(offset: number, length: number): number {
   // A non-finite offset would make every slice() return '' and blank the part outright — it is
   // out of range like any other, and appending is the safe reading of "position unknown".
   const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
-  if (clamped !== offset && process.env['NODE_ENV'] !== 'production') {
+  if (clamped !== offset && isDev()) {
     console.warn(
       `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
     )