basalt-ui 1.27.0 → 1.29.0

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
@@ -92,13 +95,33 @@
 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 { 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

package/src/dashboard/stat-group.tsx

@@ -0,0 +1,74 @@
+/**
+ * StatGroup — the KPI row, and the second half of the column law `WidgetGrid` owns for widgets
+ * (audit B #6/#7). Same argument, different numbers: a KPI is a short pre-formatted string, so it
+ * packs tighter than a chart card and the law starts at TWO on a phone.
+ *
+ * **`cols` is the DESKTOP count** and the only number a consumer states; the law is
+ * `base 2 → sm min(cols, 3) → lg cols`. Five is the ceiling — past that the cells are narrower than
+ * a formatted currency value and the row is a table.
+ *
+ * **`lg` enters the package here and in `WidgetGrid`, nowhere else.** `sm` stays the only
+ * breakpoint a consumer writes (`docs/CONTROLS-SPEC.md` §2).
+ *
+ * `divided` swaps the column gap for a hairline rail between cells — the bare-metric-row look, for
+ * KPIs that are one reading split several ways rather than several independent cards. It draws the
+ * rule on the GROUP, so the cells stay whatever they are; on `StatCard`s (which carry their own
+ * panel and shadow ring) the rail reads as a second frame, so pair it with unadorned children.
+ *
+ * @example
+ * import { StatCard, StatGroup } from 'basalt-ui'
+ *
+ * <StatGroup cols={4}>
+ *   {kpis.map((kpi) => (
+ *     <StatCard key={kpi.key} title={kpi.title} value={kpi.value} delta={kpi.delta} />
+ *   ))}
+ * </StatGroup>
+ */
+import type { CSSProperties, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import classes from './stat-group.module.css'
+
+/** The desktop KPI column count. */
+export type StatGroupCols = 2 | 3 | 4 | 5
+
+export type StatGroupProps = BasaltProps & {
+  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)`, a phone gets 2.
+   * Never a responsive object — the law is basalt's, see the module docblock. */
+  cols?: StatGroupCols
+  /** Swap the column gap for a hairline rail between cells. Default `false`. */
+  divided?: boolean
+  /** The KPI cells — normally `StatCard`s. */
+  children: ReactNode
+}
+
+export function StatGroup({
+  cols = 4,
+  divided = false,
+  children,
+  className,
+  style,
+}: StatGroupProps) {
+  const smCols = Math.min(cols, 3)
+
+  return (
+    <div
+      className={cx(classes.root, className)}
+      data-cols={cols}
+      data-sm-cols={smCols}
+      // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
+      // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
+      // same idiom `stat-card.module.css` uses for `[data-placement]`.
+      {...(divided && { 'data-divided': 'true' })}
+      style={
+        {
+          '--basalt-stat-group-cols-sm': smCols,
+          '--basalt-stat-group-cols-lg': cols,
+          ...style,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,53 @@
+/*
+ * WidgetGrid's column law, in CSS (law C9 — a responsive swap belongs to the control, never to a JS
+ * media query). The two literals below are Mantine's own `--mantine-breakpoint-sm` (48em) and
+ * `--mantine-breakpoint-lg` (75em); a `@media` condition is resolved before custom properties
+ * exist, so the number has to be written — same standing constraint `content/article-layout.
+ * module.css` documents.
+ *
+ * The COUNTS are custom properties instead, set once per instance by the component: three
+ * hand-written `repeat()` blocks would have to enumerate every `cols` value, and the whole point of
+ * this primitive is that a consumer states one desktop number and basalt owns the rest.
+ */
+
+.root {
+  display: grid;
+  /* Below `sm` a widget column is always 1 — a dashboard card holds a chart, and two of them on a
+     phone is two unreadable charts. */
+  grid-template-columns: repeat(1, minmax(0, 1fr));
+  gap: var(--vx-space-stack-md);
+}
+
+@media (min-width: 48em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 75em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+  }
+}
+
+/*
+ * `min-width: 0` on every cell: a grid track's default `min-width: auto` is its content's intrinsic
+ * width, so one wide `<table>` or one long unbroken value blows the whole row out instead of
+ * scrolling inside its own card.
+ */
+.item {
+  grid-column: span 1;
+  min-width: 0;
+}
+
+@media (min-width: 48em) {
+  .item {
+    grid-column: span var(--basalt-widget-grid-span-sm);
+  }
+}
+
+@media (min-width: 75em) {
+  .item {
+    grid-column: span var(--basalt-widget-grid-span-lg);
+  }
+}

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

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