basalt-ui 1.27.0 → 1.28.0

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

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

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

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

package/src/dashboard/stat-card.tsx

@@ -22,6 +22,9 @@
  * `src/dashboard` stays @visx-free — `sparkline` is a plain `ReactNode` slot, never a chart import
  * here. Pass a `LineSparkline`/`BarSparkline` from `basalt-ui/charts` at the call site.
  *
+ * `query` hands the card's pending/error/empty branch to `QueryState` at the `'section'` tier,
+ * rendered under the header rather than over it — the title row is chrome and must not flicker.
+ *
  * `tone` marks the card as past a threshold with an accent rail down its leading edge. It exists
  * because `value` is typed `string`: without it, a card whose number has crossed a threshold reads
  * exactly as calm as one that hasn't, and the only way out from the consumer side is to wrap the
@@ -93,12 +96,32 @@ import { Box, Card, VisuallyHidden } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import { WidgetHeader } from '../widget-header'
+import type {
+  WidgetHeaderDeltaProps,
+  WidgetHeaderMetricProps,
+  WidgetHeaderTitleProps,
+} from '../widget-header'
 import { CtlSlot } from '../theme'
 import { VX } from '../tokens'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps, Tone } from '../common/props'
+import { QueryState } from './query-state'
+import type { QueryStateLike } from './query-state'
 import classes from './stat-card.module.css'
 
-/** A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock. */
-export type StatCardTone = 'good' | 'warn' | 'bad'
+/**
+ * A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock.
+ * Alias of the common `Tone` vocabulary (audit A13) — byte-identical, kept as its own name so a
+ * consumer's existing `StatCardTone` reference never breaks.
+ */
+export type StatCardTone = Tone
+
+/**
+ * The four boxes `StatCard` paints, and the whole styling seam it offers (`common/props.ts`).
+ * `value` is not its own slot: the hero number is painted by `WidgetHeader`'s internal metrics row,
+ * which does not yet accept a slot class of its own.
+ */
+export type StatCardSlot = 'root' | 'header' | 'body' | 'sparkline'
 
 /**
  * One row of a {@link StatCardProps.breakdown} — the two or three parts a hero number is made of.
@@ -188,86 +211,83 @@ const TONE_LABEL: Record<StatCardTone, string> = {
   bad: 'Past the severe threshold',
 }
 
-export type StatCardProps = {
-  /** Head-font title, rendered via `WidgetHeader tier="widget"`. */
-  title: string
-  /** Optional leading icon, forwarded to `WidgetHeader`. */
-  icon?: ReactNode
-  /** Muted line under the hero row, forwarded to `WidgetHeader` — the unit or basis a
-   * pre-formatted `value` cannot carry (`per day`, `of 40 planned`). Not a second metric. */
-  subtitle?: string
-  /** Info tooltip beside the title, forwarded to `WidgetHeader` — how the number is computed. Never
-   * part of the heading's accessible name; see `WidgetHeaderProps.info`. */
-  info?: string
-  /** Pre-formatted KPI value string (mono ~24px, weight 600, ink) — the hero-row value. */
-  value: string
-  /** The value's unit, muted and mono at `--vx-text-sm`, immediately after it on the hero row —
-   * forwarded to `WidgetHeader`. `412` + `TSS`, not `"412 TSS"`: a unit painted at the hero's 24px
-   * reads as a second numeral. The BASIS (`7-day rolling`) is still `subtitle`; see
-   * `WidgetHeaderProps.unit`. */
-  unit?: string
-  /**
-   * The parts the hero number is made of — compact rows under it, one line each, no hairlines.
-   *
-   * It exists because three consumers wanted a KPI card that also SPLITS its number (revenue by
-   * channel, uptime by probe) and the only shapes basalt offered were a `subtitle` (one muted line,
-   * no second column) and a table. Both hand-rolled a card instead — which is the fork
-   * `shadow-basalt-export` reports as a `HeroCard`.
-   *
-   * Deliberately not a table and deliberately unruled: the divider law puts a hairline between
-   * OPTION rows and nowhere else (`docs/CONTROLS-SPEC.md` §2.1), and a KPI card that draws three
-   * of them stops reading as one card. Keep it to two or three rows — past that the card is a
-   * table, and a table is `BasaltDataTable` in a `Section`.
-   */
-  breakdown?: readonly StatCardBreakdownRow[]
-  /** Signed delta rendered via `DeltaBadge`; omit to hide the trend chip entirely. */
-  delta?: number
-  /** Optional comparison timeframe shown after the delta (e.g. `MoM`) — forwarded to `DeltaBadge`. */
-  deltaPeriod?: string
-  /**
-   * Formats `delta` into the chip's label — forwarded to `WidgetHeader` and on to `DeltaBadge`.
-   * Defaults to `${Math.abs(delta).toFixed(1)}%`.
-   *
-   * A delta is not always a percentage, and the default silently claimed it was: a pace card's trend
-   * (`0:12 /km`) and a speed card's (`0.3 km/h`) both rendered as `0.3%` — a wrong unit on a KPI is
-   * the one failure worse than no chip, and it is why the consumer that needed it kept the card
-   * hand-rolled instead (the `HeroCard` fork `shadow-basalt-export` reports).
-   *
-   * @example
-   * // An absolute delta that prints its own sign — no percent, no glyph saying it twice.
-   * <StatCard title="Pace" value="5:31" unit="/km" delta={-12}
-   *   deltaFormat={(s) => `${s < 0 ? '−' : '+'}0:${String(Math.abs(s)).padStart(2, '0')} /km`}
-   *   deltaGlyph={false} />
-   */
-  deltaFormat?: (delta: number) => string
-  /** Render the ▲/▼ glyph on the delta chip. Defaults to `true`; a zero delta never shows one. Pass
-   * `false` when `deltaFormat` prints the sign itself. */
-  deltaGlyph?: boolean
-  /**
-   * 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
-}
+/**
+ * `StatCard` re-publishes three NAMED `WidgetHeader` slices (`WidgetHeaderTitleProps` /
+ * `WidgetHeaderMetricProps` / `WidgetHeaderDeltaProps`, audit B #2) rather than re-declaring the
+ * props one by one — which is how `count` came to be missing here and `unit` missing on `Section`,
+ * with nothing in either type saying whether that was a decision.
+ *
+ * Two deliberate departures from the slices, and they are the whole omission list:
+ *
+ *  - **`value` is REQUIRED.** A KPI card with no number is an empty box; on `WidgetHeader` the same
+ *    prop is optional because a section heading legitimately has none.
+ *  - **`count` is not taken.** It is the table/list count (law C11) and a KPI card is neither.
+ *
+ * `Section` and `ChartCard` still cut their own ad-hoc subsets; both should move onto these same
+ * three slices.
+ */
+export type StatCardProps = BasaltProps &
+  SlotStylesProps<StatCardSlot> &
+  WidgetHeaderTitleProps &
+  Omit<WidgetHeaderMetricProps, 'value'> &
+  WidgetHeaderDeltaProps & {
+    /** Pre-formatted KPI value string (mono ~24px, weight 600, ink) — the hero-row value. Required
+     * here, unlike on `WidgetHeader`: see the type's own doc. */
+    value: string
+    /**
+     * The parts the hero number is made of — compact rows under it, one line each, no hairlines.
+     *
+     * It exists because three consumers wanted a KPI card that also SPLITS its number (revenue by
+     * channel, uptime by probe) and the only shapes basalt offered were a `subtitle` (one muted line,
+     * no second column) and a table. Both hand-rolled a card instead — which is the fork
+     * `shadow-basalt-export` reports as a `HeroCard`.
+     *
+     * Deliberately not a table and deliberately unruled: the divider law puts a hairline between
+     * OPTION rows and nowhere else (`docs/CONTROLS-SPEC.md` §2.1), and a KPI card that draws three
+     * of them stops reading as one card. Keep it to two or three rows — past that the card is a
+     * table, and a table is `BasaltDataTable` in a `Section`.
+     */
+    breakdown?: readonly StatCardBreakdownRow[]
+    /**
+     * The async result behind the number. Supplied, the card renders its pending / error / empty
+     * branch through {@link QueryState} at the `'section'` tier, INSIDE the card body and directly
+     * under the header — so the title, the icon and the info glyph stay put while the reading below
+     * them resolves. Omitted, the card renders exactly as it always has (audit B #3).
+     *
+     * It exists because the alternative every consumer wrote is the four-way switch `QueryState`
+     * exists to delete, and got it wrong in the direction that renders "no data" over a 500. The
+     * BRANCH is basalt's; the number is not — `value` is still whatever you formatted, so pass a
+     * placeholder (`'—'`) while the query is pending rather than a stale one.
+     *
+     * @example
+     * <StatCard title="Active users" value={q.data ? fmt(q.data.count) : '—'} query={q} />
+     */
+    query?: QueryStateLike<unknown>
+    /**
+     * 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 function StatCard({
   title,
@@ -277,14 +297,19 @@ export function StatCard({
   value,
   unit,
   breakdown,
+  query,
   delta,
   deltaPeriod,
+  deltaPolarity,
   deltaFormat,
   deltaGlyph,
   sparkline,
   sparklinePlacement = 'bleed',
   actions,
   tone,
+  className,
+  style,
+  classNames,
 }: StatCardProps) {
   const isRender = typeof sparkline === 'function'
   const bleeds = sparklinePlacement === 'bleed'
@@ -292,8 +317,66 @@ export function StatCard({
   const slot = useSlotWidth(isRender)
   const measured: StatCardSparklineSize = { width: slot.width, height: SPARKLINE_RIGHT_HEIGHT }
 
+  // A `<dl>`, not a table and not a stack of divs: each row IS a term and its value, which is the
+  // one semantic that survives a reader meeting the card out of context.
+  const breakdownRows =
+    breakdown === undefined || breakdown.length === 0 ? null : (
+      <dl className={classes.breakdown}>
+        {breakdown.map((row) => (
+          <div
+            key={row.label}
+            className={classes.breakdownRow}
+            {...(row.tone !== undefined && { 'data-tone': row.tone })}
+          >
+            <dt className={classes.breakdownLabel}>{row.label}</dt>
+            <dd className={classes.breakdownValue}>{row.value}</dd>
+          </div>
+        ))}
+      </dl>
+    )
+
+  // Wraps `breakdownRows` in `QueryState` when a query is supplied — computed once, consumed by
+  // whichever placement branch below actually renders it (`bleed` inside `.header`, `right` inside
+  // `.metricsRow`), never both.
+  const breakdownContent: ReactNode =
+    query === undefined ? (
+      breakdownRows
+    ) : (
+      <QueryState query={query} tier="section">
+        {breakdownRows}
+      </QueryState>
+    )
+
+  const sparklineNode: ReactNode =
+    sparkline === undefined ? null : (
+      <div
+        ref={slot.ref}
+        className={cx(
+          bleeds ? classes.sparklineBleed : classes.sparklineRight,
+          classNames?.sparkline,
+        )}
+        {...(!bleeds && {
+          // CUSTOM PROPERTIES, not `flexBasis`/`height` directly. A React inline style beats every
+          // stylesheet rule, so an inline `flexBasis: 72` also applied below `sm` — where `'right'`
+          // collapses `.metricsRow` to a COLUMN and flex-basis is therefore the main-axis HEIGHT.
+          // The mobile sparkline rendered in a 72px-tall box holding 26px of bars, which is the dead
+          // band under every KPI value on a phone. Handed to CSS as values instead, the media query
+          // can reset the box and the numbers still live in one place.
+          style: {
+            '--basalt-stat-sparkline-w': `${SPARKLINE_RIGHT_WIDTH}px`,
+            '--basalt-stat-sparkline-h': `${SPARKLINE_RIGHT_HEIGHT}px`,
+          } as CSSProperties,
+        })}
+      >
+        {/* A measured slot renders nothing on the first commit (width 0) — an SVG at width 0 is a
+            visible 0-width box that then jumps, which is worse than one frame of nothing. */}
+        {isRender ? measured.width > 0 && sparkline(measured) : sparkline}
+      </div>
+    )
+
   return (
     <Card
+      className={cx(classNames?.root, className)}
       style={{
         // Card inset = spacing xs / sm, matching every other basalt card. `overflow: hidden` clips
         // the full-bleed sparkline to the card's rounded corners; an element's own `box-shadow`
@@ -312,6 +395,7 @@ 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',
+        ...style,
       }}
       data-tone={tone}
     >
@@ -338,8 +422,8 @@ export function StatCard({
         </>
       )}
 
-      <div className={classes.body} data-placement={sparklinePlacement}>
-        <div className={classes.header}>
+      <div className={cx(classes.body, classNames?.body)} data-placement={sparklinePlacement}>
+        <div className={cx(classes.header, classNames?.header)}>
           <WidgetHeader
             tier="widget"
             title={title}
@@ -350,6 +434,7 @@ export function StatCard({
             {...(unit !== undefined && { unit })}
             {...(delta !== undefined && { delta })}
             {...(deltaPeriod !== undefined && { deltaPeriod })}
+            {...(deltaPolarity !== undefined && { deltaPolarity })}
             {...(deltaFormat !== undefined && { deltaFormat })}
             {...(deltaGlyph !== undefined && { deltaGlyph })}
             // `tier="widget"`, not the default `ctl`: the header row this slot sits in is 28px
@@ -361,51 +446,24 @@ export function StatCard({
             })}
           />
 
-          {breakdown !== undefined &&
-            breakdown.length > 0 && (
-              // A `<dl>`, not a table and not a stack of divs: each row IS a term and its value, which
-              // is the one semantic that survives a reader meeting the card out of context.
-              //
-              // INSIDE `.header`, not beside it: with `sparklinePlacement="right"` the body is a flex
-              // ROW, so a third child here would sit next to the trend rather than under the number
-              // it splits. The header block is the card's text column in both placements.
-              <dl className={classes.breakdown}>
-                {breakdown.map((row) => (
-                  <div
-                    key={row.label}
-                    className={classes.breakdownRow}
-                    {...(row.tone !== undefined && { 'data-tone': row.tone })}
-                  >
-                    <dt className={classes.breakdownLabel}>{row.label}</dt>
-                    <dd className={classes.breakdownValue}>{row.value}</dd>
-                  </div>
-                ))}
-              </dl>
-            )}
+          {/* INSIDE `.header` for `bleed` ONLY (measured defect: `right` used to put the WHOLE
+              header — actions included — beside the sparkline, so `.actions`' own
+              `margin-inline-start: auto` resolved against wherever the sparkline began instead of
+              the card's true right edge). For `right`, breakdown moves to `.metricsRow` below,
+              beside the sparkline instead — `.header` now stays the FULL card width in both
+              placements, so the actions slot always reaches the same edge the phone form already
+              got right. */}
+          {bleeds && breakdownContent}
         </div>
 
-        {sparkline !== undefined && (
-          <div
-            ref={slot.ref}
-            className={bleeds ? classes.sparklineBleed : classes.sparklineRight}
-            {...(!bleeds && {
-              // CUSTOM PROPERTIES, not `flexBasis`/`height` directly. A React inline style beats
-              // every stylesheet rule, so an inline `flexBasis: 72` also applied below `sm` — where
-              // `'right'` collapses to a COLUMN and flex-basis is therefore the main-axis HEIGHT.
-              // The mobile sparkline rendered in a 72px-tall box holding 26px of bars, which is the
-              // dead band under every KPI value on a phone. Handed to CSS as values instead, the
-              // media query can reset the box and the numbers still live in one place.
-              style: {
-                '--basalt-stat-sparkline-w': `${SPARKLINE_RIGHT_WIDTH}px`,
-                '--basalt-stat-sparkline-h': `${SPARKLINE_RIGHT_HEIGHT}px`,
-              } as CSSProperties,
-            })}
-          >
-            {/* A measured slot renders nothing on the first commit (width 0) — an SVG at width 0 is
-                a visible 0-width box that then jumps, which is worse than one frame of nothing. */}
-            {isRender ? measured.width > 0 && sparkline(measured) : sparkline}
-          </div>
-        )}
+        {bleeds
+          ? sparklineNode
+          : (breakdownContent !== null || sparklineNode !== null) && (
+              <div className={classes.metricsRow}>
+                {breakdownContent}
+                {sparklineNode}
+              </div>
+            )}
       </div>
     </Card>
   )

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

@@ -0,0 +1,66 @@
+/*
+ * StatGroup's column law and its optional rail, in CSS (law C9). The literals are Mantine's
+ * `--mantine-breakpoint-sm` (48em) and `--mantine-breakpoint-lg` (75em) — a `@media` condition
+ * cannot read a custom property, so the number has to be written; the COUNTS are custom properties
+ * the component sets per instance.
+ */
+
+.root {
+  display: grid;
+  /* Two KPIs abreast on a phone, never one: a KPI is a short pre-formatted number, and a single
+     column turns a four-metric row into four screens of scrolling. */
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--vx-space-stack-md);
+}
+
+@media (min-width: 48em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 75em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
+  }
+}
+
+/*
+ * The rail. `column-gap: 0` and one hairline per cell, suppressed on whichever cell LEADS a row —
+ * which is why the three blocks below are bounded to mutually EXCLUSIVE ranges rather than stacked
+ * `min-width` ones. `:nth-child(3n + 1)` is more specific than the `[data-divided] > *` that draws the
+ * border, so an open-ended `sm` block would keep suppressing the wrong cells once `lg` took over.
+ */
+.root[data-divided] {
+  column-gap: 0;
+}
+
+.root[data-divided] > * {
+  border-inline-start: 1px solid var(--vx-divider);
+  padding-inline-start: var(--vx-space-stack-md);
+}
+
+@media (max-width: 47.99375em) {
+  .root[data-divided] > *:nth-child(2n + 1) {
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+}
+
+@media (min-width: 48em) and (max-width: 74.99375em) {
+  .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
+  .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+}
+
+@media (min-width: 75em) {
+  .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
+  .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
+  .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
+  .root[data-divided][data-cols='5'] > *:nth-child(5n + 1) {
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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 root: string
+}
+export default classes