basalt-ui 1.30.2 → 1.31.0

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

@@ -1,11 +1,8 @@
 /*
- * 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
- * BREAKDOWN row instead, the reference-design look, and collapses back to `bleed`'s stacked layout
- * below `sm` — CSS only for the sparkline's own box, `.metricsRow` below for the row it sits in
- * (`47.99375em` is Mantine's own complement of `min-width: 48em`, same value
- * `content/prose.module.css` derives it from).
+ * StatCard's sparkline placement (docs/CONTROLS-SPEC.md §2.2). `bleed` (default) keeps the full-width
+ * row beneath the hero value, bled past the card's inset padding. `right` sits the sparkline beside
+ * the BREAKDOWN row and collapses back to `bleed`'s stacked layout when the card itself is narrower
+ * than 480px (`container: basalt-card`, set on the Card root in `stat-card.tsx`).
  */
 
 .body {
@@ -131,7 +128,7 @@
 }
 
 /* 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). `align-self: flex-end` is the one alignment
+ * rule and the narrow-card reset below can both reach them). `align-self: flex-end` is the one alignment
  * this restructure keeps at the SPARKLINE's own level rather than the row's: `.metricsRow` does not
  * set `align-items: flex-end` itself, because a card with no breakdown would then need nothing to
  * anchor against — only the sparkline opts into sitting at the row's bottom edge, which matters once
@@ -146,7 +143,7 @@
   overflow: hidden;
 }
 
-@media (max-width: 47.99375em) {
+@container basalt-card (max-width: 479.9px) {
   .metricsRow {
     flex-direction: column;
     align-items: stretch;

package/src/dashboard/stat-card.tsx

@@ -11,7 +11,7 @@
  *
  * `sparklinePlacement` decides where the trend visual sits: `'bleed'` (default) keeps the historic
  * full-width row beneath the hero value, bled past the card's own inset padding; `'right'` sits it
- * beside the hero row, the reference-design look. Below `sm`, `'right'` collapses back to the
+ * beside the hero row, the reference-design look. In a card narrower than 480px, `'right'` collapses back to the
  * `'bleed'` layout — CSS only, no JS branch (`stat-card.module.css`).
  *
  * `info` and `subtitle` are forwarded to that same `WidgetHeader`, and a hero KPI usually wants
@@ -277,7 +277,7 @@ export type StatCardProps = BasaltProps &
      */
     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`. */
+     * `'right'` sits it beside the hero value row. Collapses to `'bleed'` in a card narrower than 480px. */
     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). */
@@ -357,7 +357,7 @@ export function StatCard({
         )}
         {...(!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'`
+          // stylesheet rule, so an inline `flexBasis: 72` also applied in a narrow card — where `'right'`
           // collapses `.metricsRow` to a COLUMN and flex-basis is therefore the main-axis HEIGHT.
           // The mobile sparkline rendered in a 72px-tall box holding 26px of bars, which is the dead
           // band under every KPI value on a phone. Handed to CSS as values instead, the media query
@@ -400,6 +400,9 @@ export function StatCard({
         // Anchors the tone rail. Set unconditionally so a card's stacking context does not change
         // depending on whether it happens to have crossed a threshold this render.
         position: 'relative',
+        // The card's own width drives its chrome (`widget-header.module.css`, `.metricsRow`).
+        containerType: 'inline-size',
+        containerName: 'basalt-card',
         ...style,
       }}
       data-tone={tone}

package/src/dashboard/stat-group.module.css

@@ -2,8 +2,8 @@
  * StatGroup's column law and its optional rail, in CSS (law C9).
  *
  * **The law keys on the CONTAINER, not the viewport.** A viewport breakpoint answers the wrong
- * question — the same one `resolveChartTier` refuses to ask (`charts/primitives/chart-frame-layout.
- * ts`): the shell has regions that change the AVAILABLE width with the viewport held still (a
+ * question — the same one `resolveContainerClass` refuses to ask (`tokens/size-classes.ts`): the
+ * shell has regions that change the AVAILABLE width with the viewport held still (a
  * `PageAside` claiming its 300px, the sidebar collapsing 256px → its 48px rail, a consumer's own
  * split layout), and `@media` cannot see any of them. Measured defect: a `PageAside` mounted on a
  * 1512px desktop left the KPI row ~956px wide, `@media` still resolved `lg`, and four cells of
@@ -26,8 +26,7 @@
  * boundary at the 16px initial font size — 768px and 1200px — but `em` inside a `@container`
  * condition resolves against the CONTAINER's font-size rather than the root's, so a consumer panel
  * with smaller text would silently move the breakpoint. px is the only spelling that cannot drift.
- * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`; the same complements `stat-card.module.css`
- * uses.) A condition still cannot read a custom property either way, so the numbers are written;
+ * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`.) A condition still cannot read a custom property either way, so the numbers are written;
  * the COUNTS are custom properties the component sets per instance.
  */
 
@@ -44,6 +43,19 @@
   gap: var(--vx-space-stack-md);
 }
 
+/* 260px is StatGroup's own literal (docs/DESIGN-CORE.md § Layout, elevation, shapes), not a container class: one column below it,
+ * so every cell leads a row and the rail draws no leading hairline at all. */
+@container basalt-stat-group (max-width: 259.9px) {
+  .root {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .root[data-divided] > *:nth-child(n) {
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+}
+
 @container basalt-stat-group (min-width: 768px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));

package/src/dashboard/widget-grid.tsx

@@ -10,7 +10,7 @@
  * **`cols` is the DESKTOP count, and it is the only number a consumer states.** The law is
  * `base 1 → sm min(cols, 2) → lg cols`: a phone gets one column because a dashboard card holds a
  * chart; a tablet gets at most two because a third makes every chart narrower than
- * `VX.phoneChartWidth`; the full count lands at `lg`. Mantine's `cols={{ … }}` object is
+ * `CONTAINER_CLASSES.regular`; the full count lands at `lg`. Mantine's `cols={{ … }}` object is
  * deliberately NOT forwarded — a responsive object on the public prop is exactly the seam that let
  * five call sites disagree.
  *
@@ -19,12 +19,13 @@
  * ACTUALLY has. The shell moves that width without moving the viewport — a `PageAside` claiming its
  * 300px, the sidebar collapsing 256px → its 48px rail, a consumer's split pane — and a `@media`
  * query sees none of it: it kept three chart columns in a 956px content box and every chart in the
- * row went narrower than `VX.phoneChartWidth`, which is the exact condition the `lg` rung exists to
- * avoid. See `widget-grid.module.css`'s header for the fallback.
+ * row went narrower than `CONTAINER_CLASSES.regular`, which is the exact condition the `lg` rung
+ * exists to avoid. See `widget-grid.module.css`'s header for the fallback.
  *
- * **This is the sanctioned place `lg` enters the package.** `sm` is still the only breakpoint a
- * consumer writes (`docs/CONTROLS-SPEC.md` §2); `WidgetGrid` and `StatGroup` own `lg` internally so
- * nobody else has to.
+ * **This is the sanctioned place `lg` enters the package.** A consumer never writes a
+ * breakpoint — component layout keys on the container's own width
+ * (`docs/DESIGN-CORE.md` § Layout, elevation, shapes); `WidgetGrid` and `StatGroup` own their `lg`
+ * container rung internally so nobody else has to.
  *
  * `WidgetGrid.Item` is for the one card that is wider than the rest — a hero chart beside two
  * stacked panels. `span` is likewise the DESKTOP span and is CLAMPED to the live column count at

package/src/dashboard/widget-header.module.css

@@ -9,8 +9,13 @@
  * by name with rem fallbacks at their level-0 px value (36/28/6), same idiom as ChartCard's
  * `--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 every tier, never inline with the title.
+ * Layout keys on the enclosing card's OWN width (`container: basalt-card`, declared by ChartCard /
+ * StatCard / Section — docs/DESIGN-CORE.md § Layout, elevation, shapes), never the viewport: below 480px the subtitle folds
+ * into the info glyph; from 480px (wave 8) `value` + `delta` move onto the title row. Wrapping and
+ * shrinking are unconditional. The subtitle ALSO folds (regardless of width) whenever the card's own
+ * height is under 280px — see the `[data-basalt-card-short]` block below (wave 8's header-economy
+ * law). No enclosing card, no container: the standard layout. Container conditions are px literals
+ * of CONTAINER_CLASSES.
  */
 
 .root {
@@ -18,73 +23,15 @@
   flex-direction: column;
 }
 
+/* The row WRAPS only when it does not fit (a lone kebab stays beside the title; a wide `actions` slot
+ * takes its own right-aligned line instead of squeezing the heading) — unconditional, so composers
+ * with no `basalt-card` container (`SettingsSection`, `BasaltDataTable`) keep the safety net. */
 .titleRow {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: var(--vx-space-control-gap, 0.375rem);
-}
-
-/*
- * Below `sm` the title row WRAPS, which is the safety net for an `actions` slot too wide to sit
- * beside the title. `flex-wrap` is the right tool precisely because it is conditional: a 30px kebab
- * fits and stays on the row, while a control whose hypothetical size does not fit takes its own line
- * instead of squeezing the heading to an ellipsis. No breakpoint arithmetic, no max-width fraction,
- * and no prop — the row measures the actual content.
- *
- * `row-gap` is the 8px rhythm step, so a wrapped slot reads as the line under the title rather than
- * as a second header. `.actions` keeps its `margin-inline-start: auto`, which on a wrapped line makes
- * it right-aligned — the same edge it holds when it is on the row.
- */
-@media (max-width: 47.99375em) {
-  .titleRow {
-    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;
-  }
+  row-gap: var(--vx-space-stack-sm);
 }
 
 .root[data-tier='section'] .titleRow {
@@ -203,59 +150,28 @@
 }
 
 /*
- * 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.
- */
-/*
- * The hero-metric row: the value, then its `DeltaBadge`.
- *
- * The gap is the 8px vertical-rhythm step (`--vx-space-stack-sm`), not the 4px it shipped as. 4px is
- * the rhythm's SMALLEST step — the distance between a label and the thing it labels — and at that
- * distance the badge read as a superscript hanging off the numeral rather than as a second fact
- * beside it. It is a token and not a literal so it tracks the density knob with every other spacing
- * in the header (`deriveSpacing`, `tokens/palette.ts`); `theme/layout-rhythm-css.test.ts`'s sibling
- * assertion in `widget-header.test.tsx` pins it against exactly the literal it used to be.
- *
- * `align-items: center`, not `baseline`. The badge is a BOX with its own padding and a mono 11.5px
- * label, so aligning its text baseline to a 24px KPI numeral's baseline put the box itself low —
- * its top edge sat below the numeral's x-height and its bottom edge hung under the numeral's
- * baseline. A chip beside a numeral is centred on the numeral, the same law the `count` tag in the
- * title row above already follows.
+ * The hero-metric row: the value, then its `DeltaBadge`, 8px apart (`--vx-space-stack-sm`, tracks
+ * density). It always WRAPS — the badge drops under the value when they do not fit, the value never
+ * ellipsizes. `center`, not `baseline`: the badge is a padded box, so a chip beside a numeral is
+ * centred on it (same law as the `count` tag above).
  */
 .metrics {
   display: flex;
-  flex-wrap: nowrap;
+  flex-wrap: wrap;
   align-items: center;
   gap: var(--vx-space-stack-sm);
+  /* Tight when the badge wraps under the value. */
+  row-gap: 2px;
   margin-top: 2px;
   min-width: 0;
 }
 
-/*
- * Below `sm` the metric row WRAPS, so the badge drops under the value instead of ellipsizing it.
- * `nowrap` plus the `.value` clamp below is right on desktop — a `+18.9%` cannot ellipsize and read,
- * a numeral can — but a KPI's numeral IS the content, and in a 2-up card grid at 390px
- * `$1294.9k ▲18.9%` rendered as `$129… ▲18.9%`. Truncating the number to protect the delta about the
- * number is the wrong way round. Conditional like the title row above it: a short value keeps the
- * badge beside it, and only a value that would otherwise clip gives up the line.
- */
-@media (max-width: 47.99375em) {
-  .metrics {
-    flex-wrap: wrap;
-    row-gap: 2px;
-  }
-}
-
-/* The value is the row's shrinkable half and the delta badge is not: a pre-formatted numeral can
- * ellipsize and still read, a `+18.9%` cannot. Without the clamp the badge grew past the header box
- * and painted over `StatCard`'s 72px sparkline slot beside it. */
+/* NEVER truncated: the numeral IS the content. It shrinks with the card's own width instead —
+ * `cqi` against `basalt-card` (the clamp, at the end of this file), from the `kpi` step down to the
+ * `lg` step (16px), and `overflow-wrap` breaks a pathological string rather than clipping it. */
 .value {
   min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
+  overflow-wrap: anywhere;
   font-family: var(--basalt-font-mono);
   font-size: var(--vx-text-kpi);
   font-weight: 600;
@@ -266,8 +182,8 @@
 /*
  * 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.
+ * point is that a unit is the SMALL half of the pair. `flex-shrink: 0`: a unit clipped to `TS…`
+ * would state nothing.
  */
 .unit {
   flex-shrink: 0;
@@ -278,14 +194,28 @@
   color: var(--vx-muted);
 }
 
-/* The C1/C5 home for header actions — always pinned right, regardless of what else is present. */
+/* The C1/C5 home for header actions — always pinned right, regardless of what else is present.
+ * Law C15: adopts the shared hit overlay (`data-basalt-hit-scope`, `styles.css`); `--vx-hit-gap`
+ * caps the expansion at the control gap so neighbouring 24px icons never overlap. */
 .actions {
+  --vx-hit-gap: var(--vx-space-control-gap);
   display: inline-flex;
-  flex-shrink: 0;
+  /* No grow, but it may shrink and wrap once `.titleRow` decides it does not fit, capped at 100% once
+   * alone on its line. Its flex items shrink too; the `> * > *` twin reaches through `CtlSlot`'s
+   * `display: contents` wrapper, whose own children are the real items. */
+  flex: 0 1 auto;
+  flex-wrap: wrap;
   align-items: center;
   gap: var(--vx-space-control-gap, 0.375rem);
   margin-inline-start: auto;
   min-width: 0;
+  max-width: 100%;
+}
+
+.actions > *,
+.actions > * > * {
+  flex: 1 1 auto;
+  min-width: 0;
 }
 
 /* Directly under the title row, 4px off it — 1px put it inside the title's own line box, so a
@@ -306,6 +236,7 @@
 /* ── info glyph ─────────────────────────────────────────────────────────────────────────────── */
 
 .info {
+  --vx-hit-gap: var(--vx-space-control-gap);
   position: relative;
   display: inline-flex;
   flex-shrink: 0;
@@ -330,6 +261,12 @@
   color: var(--vx-muted);
 }
 
+/* Folded-subtitle pieces: hidden until a `basalt-card` narrower than 480px shows them (below). */
+.foldGlyph,
+.foldNote {
+  display: none;
+}
+
 /*
  * The tooltip bubble reads like every other floating surface — panel bg + `shadow-card` + card
  * radius (docs/DESIGN-SPEC.md §5). It opens DOWNWARD by convention, into whatever sits below the
@@ -383,33 +320,108 @@
   opacity: 0.6;
 }
 
+/* Card narrower than 480px: the subtitle folds into the info glyph (`InfoGlyph`'s `note`, or
+ * `.foldGlyph` when there is no `info`) — exactly one of the two shows. */
+@container basalt-card (max-width: 479.9px) {
+  .subtitle {
+    display: none;
+  }
+
+  .foldGlyph {
+    display: inline-flex;
+  }
+
+  .foldNote {
+    display: block;
+  }
+}
+
 /*
- * Law C15 — the `actions` slot is the tier-2/tier-3 home, and its controls are 30px (`ctl`) or 24px
- * (`icon`). Below `sm` an `::after` overlay lifts the HIT area to
- * `--vx-space-touch-control-height` (36px at level 0) without moving the visible box, the same
- * overlay `shell/page-bar.module.css` draws for the bar. `overflow: visible` is load-bearing:
- * Mantine's Button/ActionIcon roots are `overflow: hidden`, which clips an overlay that by
- * definition extends past the box — the clipping only exists for their loading overlay, painted
- * under `[data-loading]`, which is excluded here.
+ * The same fold, triggered by the CARD'S OWN HEIGHT instead of its width (wave 8's header-economy
+ * law) — a short-but-wide chart card (a KPI-style plot with little vertical room) still needs the
+ * subtitle line back. Not a `@container basalt-card` SIZE query: `container-type: size` on an
+ * auto-height card collapses it to 0 (see `ChartCard`'s `CARD_SHORT_HEIGHT` doc), so `ChartCard`
+ * measures itself with a ResizeObserver instead and sets `data-basalt-card-short` under 280px.
  */
-@media (max-width: 47.99375em) {
-  .actions :is(button, a) {
-    position: relative;
+[data-basalt-card-short] .subtitle {
+  display: none;
+}
+
+[data-basalt-card-short] .foldGlyph {
+  display: inline-flex;
+}
+
+[data-basalt-card-short] .foldNote {
+  display: block;
+}
+
+/* A short card's KPI numeral is the header's own tallest line (the merged title row has no other
+ * source of height once the subtitle folds) — the same floor the width `cqi` clamp already uses,
+ * so a short card never introduces a THIRD value size. */
+[data-basalt-card-short] .value {
+  font-size: var(--vx-text-lg);
+}
+
+/* The KPI numeral shrinks with its card. `(width >= 0px)` is always true but only inside a
+ * `basalt-card` container, so `cqi` never resolves against an unrelated one (or the viewport) —
+ * with no card the numeral stays at the plain `kpi` step above. 8cqi reaches the 24px `kpi` step at
+ * a 300px card. */
+@container basalt-card (width >= 0px) {
+  .value {
+    font-size: clamp(var(--vx-text-lg), 8cqi, var(--vx-text-kpi));
+  }
+}
+
+/*
+ * From 480px (`CONTAINER_CLASSES.regular`, wave 8's header-economy law) `value` + `delta` ride the
+ * title row: the title row dissolves (`display: contents`) so heading, info, count, metrics and
+ * actions share the root's one flex line, and `order` puts the metrics before the actions. The
+ * metrics take the free space (`margin-inline-start: auto`), which pushes metrics AND actions
+ * right; with no metrics, `.actions` keeps its own auto margin. The heading keeps the tier's row
+ * height (`min-height` was on `.titleRow`), so a title-less header does not collapse.
+ *
+ * This threshold moved from `wide` (800px) in wave 5/7 — most cards sit in the 480-799px `regular`
+ * band, which never reached the merged row before, keeping the taller stacked layout on the
+ * majority of dashboard cards (wave 8, `docs/waves/PLAN.md`).
+ */
+@container basalt-card (min-width: 480px) {
+  .root {
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: var(--vx-space-control-gap, 0.375rem);
+  }
+
+  .titleRow {
+    display: contents;
+  }
+
+  .root[data-tier='section'] .heading {
+    min-height: var(--vx-space-section-header-height, 2.25rem);
+  }
+
+  .root[data-tier='widget'] .heading,
+  .root[data-tier='group'] .heading {
+    min-height: var(--vx-space-widget-header-height, 1.75rem);
+  }
+
+  .metrics {
+    order: 1;
+    margin-block: 0;
+    margin-inline-start: auto;
+  }
+
+  .actions {
+    order: 2;
   }
 
-  .actions :is(button, a):not([data-loading]) {
-    overflow: visible;
+  .root:has(.metrics) .actions {
+    margin-inline-start: 0;
   }
 
-  .actions :is(button, a)::after {
-    content: '';
-    position: absolute;
-    top: 50%;
-    left: 50%;
-    translate: -50% -50%;
-    width: 100%;
-    height: 100%;
-    min-width: var(--vx-space-touch-control-height, 2.25rem);
-    min-height: var(--vx-space-touch-control-height, 2.25rem);
+  .subtitle,
+  .sparkline {
+    order: 3;
+    flex: 0 0 100%;
   }
 }

package/src/dashboard/widget-header.module.css.d.ts

@@ -17,6 +17,8 @@ declare const classes: {
   readonly sparkline: string
   readonly info: string
   readonly infoTrigger: string
+  readonly foldGlyph: string
+  readonly foldNote: string
   readonly infoBubble: string
   readonly deltaBadge: string
   readonly deltaGlyph: string

package/src/dashboard/widget-header.tsx

@@ -9,9 +9,11 @@
  * 88%/550 title treatment. `tier: 'group'` also renders an `<h3>`, but at the quietest rank on the
  * page: a mono, uppercase, faint micro-label — an inspector/aside group heading, one step below a
  * `widget` tier and resolved automatically by `Section` when it renders on the `PageAside` panel
- * surface (never a call-site prop). The title row holds title/icon/info/count/actions only; `value`
- * + `delta` render on their own hero-metric row directly beneath it, for every tier — never inline
- * with the title. `StatCard`, `ChartCard`, `Section`, `SettingsSection`/`DangerZone` and
+ * surface (never a call-site prop). The title row holds title/icon/info/count/actions; `value` +
+ * `delta` render on their own hero-metric row beneath it, and move onto the title row when the
+ * enclosing card (`container: basalt-card`) is 480px or wider — CSS only (wave 8: was 800px). The
+ * subtitle also folds into the info glyph whenever the card's own height is under 280px, regardless
+ * of width. `StatCard`, `ChartCard`, `Section`, `SettingsSection`/`DangerZone` and
  * `BasaltDataTable` each compose this and render nothing else above their body (wave 3,
  * docs/CONTROLS-SPEC.md §2.2's composer table).
  *
@@ -62,7 +64,9 @@ export type WidgetHeaderProps = BasaltProps &
     title: string
     /** Optional leading icon, rendered before the title. Decorative — hidden from assistive tech. */
     icon?: ReactNode
-    /** Optional muted line rendered below the title row. */
+    /** Optional muted line rendered below the title row. In a card narrower than 480px, or shorter
+     * than 280px regardless of width, it folds into the info glyph's bubble instead (CSS only —
+     * exactly one of the two shows). */
     subtitle?: string
     /**
      * Renders an info glyph BESIDE the heading (never inside it — this text would otherwise become
@@ -72,8 +76,8 @@ export type WidgetHeaderProps = BasaltProps &
      * click — so a keyboard user gets it too. Mantine-free: a plain state bubble, not a Tooltip.
      */
     info?: string
-    /** Pre-formatted metric value (mono, hero size). Renders on its own row with `delta`, directly
-     * under the title row — never inline with the title. */
+    /** Pre-formatted metric value (mono, hero size, never truncated). Renders on its own row with
+     * `delta` under the title row, or on the title row in a card 480px or wider. */
     value?: string
     /**
      * The value's unit, rendered immediately after it on the hero row: muted, mono, `--vx-text-sm`.
@@ -170,7 +174,22 @@ export type WidgetHeaderDeltaProps = Pick<
  * 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 function InfoGlyph({ text }: { text: string }) {
+export function InfoGlyph({
+  text,
+  note,
+  ariaLabel = 'More information',
+  className,
+}: {
+  text: string
+  /** A second paragraph in the bubble, shown only where `.foldNote` is (the folded subtitle). */
+  note?: string
+  /** The GLYPH's own accessible name. Default `'More information'`; `WidgetHeader` overrides it to
+   * include the subtitle text for its fold-glyph mount (`info === undefined`), where this trigger
+   * IS the subtitle's only accessible surface — the bubble it opens is otherwise unreachable
+   * without first knowing there is something to open. */
+  ariaLabel?: string
+  className?: string
+}) {
   const [open, setOpen] = useState(false)
   const tipId = useId()
   const triggerRef = useRef<HTMLButtonElement>(null)
@@ -186,14 +205,15 @@ export function InfoGlyph({ text }: { text: string }) {
   }, [open])
 
   return (
-    <span className={classes.info}>
+    <span className={cx(classes.info, className)}>
       <button
         ref={triggerRef}
         type="button"
+        data-basalt-hit
         className={classes.infoTrigger}
         // The GLYPH is named, not the text — `text` reaches AT through `aria-describedby` below, so
         // it never lands in the heading's or the button's accessible name.
-        aria-label="More information"
+        aria-label={ariaLabel}
         aria-describedby={open ? tipId : undefined}
         data-open={open}
         onMouseEnter={() => setOpen(true)}
@@ -212,6 +232,7 @@ export function InfoGlyph({ text }: { text: string }) {
       {open && (
         <span id={tipId} role="tooltip" className={classes.infoBubble}>
           {text}
+          {note !== undefined && <span className={classes.foldNote}>{note}</span>}
         </span>
       )}
     </span>
@@ -258,9 +279,22 @@ export function WidgetHeader({
           <span className={classes.titleText}>{title}</span>
         </Heading>
         {/* OUTSIDE the heading on purpose — see `info`'s own doc. */}
-        {info !== undefined && <InfoGlyph text={info} />}
+        {info !== undefined && (
+          <InfoGlyph text={info} {...(subtitle !== undefined && { note: subtitle })} />
+        )}
+        {info === undefined && subtitle !== undefined && (
+          <InfoGlyph
+            text={subtitle}
+            className={classes.foldGlyph}
+            ariaLabel={`More information: ${subtitle}`}
+          />
+        )}
         {count !== undefined && <span className={classes.count}>{count}</span>}
-        {actions !== undefined && <span className={classes.actions}>{actions}</span>}
+        {actions !== undefined && (
+          <span className={classes.actions} data-basalt-hit-scope>
+            {actions}
+          </span>
+        )}
       </div>
       {(value !== undefined || delta !== undefined) && (
         <div className={cx(classes.metrics, classNames?.metric)}>