basalt-ui 1.27.0 → 1.29.0

package/src/charts/primitives/CartesianChart.tsx

@@ -1,20 +1,24 @@
 import { GridRows } from '@visx/grid'
 import { Group } from '@visx/group'
-import { scaleLinear, scalePoint } from '@visx/scale'
+import { scaleLinear, scaleLog, scalePoint } from '@visx/scale'
 import { useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../../common/props'
 import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
 import { useChartCursor } from '../hooks/useChartCursor'
 import { autoMargin, probeAxisLabels } from '../layout/auto-margin'
-import { deriveTooltipRows } from '../series'
+import { logTickValues, niceLogDomain } from '../layout/log-ticks'
+import { deriveLegend, deriveTooltipRows } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { padAutoLower, padAutoUpper } from '../utils/domain'
 import { fmtAxisDate } from '../utils/format'
-import { smartTicks, smartTicksEvery } from '../utils/ticks'
+import { autoXLabelRotate, smartTicks, smartTicksEvery, xLabelPxFor } from '../utils/ticks'
 import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './Axes'
 import { ChartFrame, resolveLegend } from './ChartFrame'
+import { useChartTierMetrics } from './chart-tier'
+import type { ChartState } from './ChartPending'
 import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from './ChartTooltip'
 import { Crosshair, SeriesDot } from './Crosshair'
 import { HoverOverlay } from './HoverOverlay'
@@ -23,7 +27,11 @@ import type { XZoneSpec } from './XZoneRects'
 import { ZoneRects } from './ZoneRects'
 import type { ZoneSpec } from './ZoneRects'
 
-type LinearScale = ReturnType<typeof scaleLinear<number>>
+/** Either axis kind a `y`/`y2` can resolve to. Widened from a bare `scaleLinear` return type so a
+ * log axis's `scaleLog` scale keeps assigning into `PlotContext.yScale`/`y2Scale` and into every
+ * mark renderer (`ZoneRects`, `refLines`, `Crosshair`/`SeriesDot`) that only ever calls `scale(v)`
+ * or reads `scale.domain()` — both interfaces share that shape via d3's `ScaleContinuousNumeric`. */
+type ContinuousScale = ReturnType<typeof scaleLinear<number>> | ReturnType<typeof scaleLog<number>>
 type PointScale = ReturnType<typeof scalePoint<string>>
 
 const DEFAULT_TICKS = 5
@@ -49,7 +57,8 @@ export type AxisConfig<T> = {
    */
   autoMaxFloor?: number
   /** When 'auto': the lower bound is at most this. Default 0 (forced zero baseline). `Infinity`
-   * pads down from the raw data minimum instead. */
+   * pads down from the raw data minimum instead. Ignored when `scale: 'log'` — a log axis has no
+   * zero baseline, so its floor is always the smallest positive visible value. */
   autoMinCeil?: number
   /** When 'auto': padding multiplier applied away from the data. Default 1.1. */
   autoPad?: number
@@ -67,6 +76,15 @@ export type AxisConfig<T> = {
    * already-migrated chart. Opt in per axis.
    */
   nice?: boolean
+  /**
+   * `'linear'` (default) or `'log'`. On `'log'` the domain floor is the smallest positive VISIBLE
+   * value — `autoMinCeil` is ignored (documented there, not thrown on): a log axis has no zero
+   * baseline. `autoPad` still pads multiplicatively and `nice` still snaps to round bounds (decade
+   * powers instead of d3's linear-nice steps). Ticks are the 1-2-5 set from `logTickValues`
+   * (`$10,000 · $20,000 · $50,000 · $100,000`, never d3's own log ticks), and `format` is applied
+   * to those values — d3's `scale.tickFormat` is never used on a log axis.
+   */
+  scale?: 'linear' | 'log'
 }
 
 /** Handed to `prependRows`/`extraRows` alongside the hovered datum — the same `visible`/`hidden`
@@ -127,9 +145,9 @@ export type PlotContext<T> = {
   visible: ChartSeries<T>[]
   hidden: ReadonlySet<string>
   xScale: PointScale
-  yScale: LinearScale
+  yScale: ContinuousScale
   /** Present only when a `y2` axis is configured. */
-  y2Scale: LinearScale | null
+  y2Scale: ContinuousScale | null
   xMax: number
   yMax: number
   margin: ChartMargin
@@ -139,7 +157,7 @@ export type PlotContext<T> = {
   highlighted: string | null
 }
 
-export type CartesianChartProps<T> = {
+export type CartesianChartProps<T> = BasaltProps & {
   data: T[]
   /** Stable id — identifies this chart as the cursor's source. */
   chartId: string
@@ -171,6 +189,21 @@ export type CartesianChartProps<T> = {
   xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
+  /**
+   * Tilt the x tick labels by 45° or 90° (counter-clockwise, anchored at their right edge). The
+   * bottom gutter deepens by the rotated label's projected height, measured like every other side
+   * (`docs/CHARTS-SPEC.md` §1), so nothing clips.
+   *
+   * This is the phone answer to a label too wide to repeat horizontally: rotating keeps every tick
+   * the axis would otherwise have to thin away — which is why, LEFT UNSET, it is now the phone
+   * tier's DEFAULT: below `VX.phoneChartWidth`, labels too wide to fit three ticks side by side
+   * auto-rotate to 45 (`autoXLabelRotate`). Nothing changes at desktop width, and nothing changes
+   * for a chart that already passes a value.
+   *
+   * **`0` is the opt-out** — "never rotate, thin the axis instead" — and is the only way to get
+   * the pre-tier behaviour back on a phone-width chart with very wide labels.
+   */
+  xLabelRotate?: 0 | 45 | 90
   /** Value-range bands on the left scale, drawn behind the marks. */
   zones?: ZoneSpec[]
   /** X-range bands (time windows), drawn behind the marks. */
@@ -205,6 +238,13 @@ export type CartesianChartProps<T> = {
   cursorResolution?: CursorResolution
   ariaLabel?: string
   isPending?: boolean
+  /**
+   * The three "nothing to draw" states in one prop, forwarded to `ChartFrame` — pending → error →
+   * empty, resolved by `resolveChartState`. The Mantine-free answer to `dashboard/QueryState`,
+   * which `./charts` cannot import; `isPending` remains a supported alias for
+   * `state={{ pending: true }}`.
+   */
+  state?: ChartState
   /** Draw ONLY the marks. Everything around them is the primitive's job. */
   children: (ctx: PlotContext<T>) => ReactNode
 }
@@ -231,24 +271,40 @@ export function resolveAxisDomain<T>(
   if (Array.isArray(domain)) return domain
   if (typeof domain === 'function') return domain(data, series)
 
+  const isLog = cfg?.scale === 'log'
   let min = Infinity
   let max = -Infinity
   for (const d of data) {
     for (const s of series) {
       const v = s.getValue(d)
       if (v === null) continue
+      // A log axis has no zero and no negative half — a non-positive value can't sit on it, so it
+      // drops out of the domain instead of pulling the floor to (or past) zero.
+      if (isLog && v <= 0) continue
       if (v < min) min = v
       if (v > max) max = v
     }
   }
   for (const v of extraBounds) {
     if (!Number.isFinite(v)) continue
+    if (isLog && v <= 0) continue
     if (v < min) min = v
     if (v > max) max = v
   }
-  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1]
 
   const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD
+
+  if (isLog) {
+    // No zero baseline on a log axis: the floor is the smallest positive visible value, padded
+    // down with no `autoMinCeil` clamp (documented as ignored on `AxisConfig.autoMinCeil`).
+    if (min === Infinity) return [1, 10]
+    if (min === max) return [min / pad, max * pad]
+    const upper = padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)
+    return [min / pad, upper]
+  }
+
+  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1]
+
   const ceil = cfg?.autoMinCeil ?? 0
   // Symmetric with the lower bound: clamp the RAW value against the floor/ceiling first, then pad
   // once, away from zero. Padding before the clamp (the old law) lands a floored axis top exactly
@@ -262,6 +318,39 @@ export function resolveAxisDomain<T>(
   return [lower, upper]
 }
 
+/**
+ * One y-axis' real scale, built from its resolved domain — shared by the left and right axis so
+ * the log branch (`scaleLog` + `nice` + the 1-2-5 tick override) is written and commented exactly
+ * once instead of as two independently-maintained twins.
+ */
+function buildYScale<T>(
+  cfg: AxisConfig<T> | undefined,
+  domain: [number, number],
+  yMax: number,
+  ticks: number,
+): ContinuousScale {
+  if (cfg?.scale === 'log') {
+    const scale = scaleLog<number>({
+      domain,
+      range: [yMax, 0],
+      ...(cfg.nice === true && { nice: true }),
+    })
+    // Paint the 1-2-5 tick law instead of d3's own log ticks: `AxisLeftNumeric`/`GridRows` resolve
+    // ticks through visx's `getTicks(scale, numTicks)` -> `scale.ticks(numTicks)`, so overriding
+    // the method on this instance is the one seam that reaches both without a raw `<AxisLeft>`
+    // escape hatch. Nothing else calls `.ticks()` on the real scale (only `probeAxisLabels`' own
+    // throwaway probe does, and that stays untouched).
+    const tickDomain = cfg.nice === true ? niceLogDomain(domain) : domain
+    scale.ticks = () => logTickValues(tickDomain, ticks)
+    return scale
+  }
+  return scaleLinear<number>({
+    domain,
+    range: [yMax, 0],
+    ...(cfg?.nice === true && { nice: true }),
+  })
+}
+
 /**
  * The cartesian chart primitive — the rung that was missing between `ChartFrame` and raw visx
  * (`docs/CHARTS-SPEC.md` §2).
@@ -285,6 +374,7 @@ export function CartesianChart<T>({
   xTicks,
   xTickValues,
   formatX = fmtAxisDate,
+  xLabelRotate,
   zones,
   xZones,
   refLines,
@@ -298,6 +388,9 @@ export function CartesianChart<T>({
   cursorResolution,
   ariaLabel,
   isPending,
+  state,
+  className,
+  style,
   children,
 }: CartesianChartProps<T>): ReactNode {
   const [highlighted, setHighlighted] = useState<string | null>(null)
@@ -311,7 +404,14 @@ export function CartesianChart<T>({
       {...(fill !== undefined && { fill })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
-      legend={resolveLegend(legend, { highlighted, onHighlight: setHighlighted })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+      legend={resolveLegend(
+        legend,
+        { highlighted, onHighlight: setHighlighted },
+        deriveLegend(series).length,
+      )}
     >
       {(plot) => (
         <CartesianPlot
@@ -324,6 +424,7 @@ export function CartesianChart<T>({
           {...(xTicks !== undefined && { xTicks })}
           {...(xTickValues !== undefined && { xTickValues })}
           formatX={formatX}
+          {...(xLabelRotate !== undefined && { xLabelRotate })}
           {...(zones !== undefined && { zones })}
           {...(xZones !== undefined && { xZones })}
           {...(refLines !== undefined && { refLines })}
@@ -344,7 +445,15 @@ export function CartesianChart<T>({
 
 type CartesianPlotProps<T> = Omit<
   CartesianChartProps<T>,
-  'height' | 'aspectRatio' | 'fill' | 'legend' | 'isPending' | 'margin'
+  | 'height'
+  | 'aspectRatio'
+  | 'fill'
+  | 'legend'
+  | 'isPending'
+  | 'state'
+  | 'margin'
+  | 'className'
+  | 'style'
 > & {
   plot: { width: number; height: number; hidden: ReadonlySet<string> }
   highlighted: string | null
@@ -363,6 +472,7 @@ function CartesianPlot<T>({
   xTicks,
   xTickValues,
   formatX = fmtAxisDate,
+  xLabelRotate,
   zones,
   xZones,
   refLines,
@@ -376,6 +486,10 @@ function CartesianPlot<T>({
   children,
 }: CartesianPlotProps<T>): ReactNode {
   const { hidden } = plot
+  // The tier `ChartFrame` resolved from its own MEASURED width. Everything sized by it here is
+  // the half a hook cannot reach: the tick font the margins are MEASURED at, and the margin
+  // floors themselves (`docs/CHARTS-SPEC.md` §8).
+  const tier = useChartTierMetrics()
 
   const visible = useMemo(() => series.filter((s) => !hidden.has(s.key)), [series, hidden])
   const leftSeries = useMemo(() => visible.filter((s) => s.axis !== 'right'), [visible])
@@ -418,9 +532,10 @@ function CartesianPlot<T>({
         domain: leftDomain,
         ticks: leftTicks,
         nice: y?.nice ?? false,
+        ...(y?.scale !== undefined && { scale: y.scale }),
         ...(y?.format !== undefined && { format: y.format }),
       }),
-    [leftDomain, leftTicks, y?.format, y?.nice],
+    [leftDomain, leftTicks, y?.format, y?.nice, y?.scale],
   )
 
   const { labels: rightLabels, format: rightFormat } = useMemo(
@@ -431,22 +546,64 @@ function CartesianPlot<T>({
             domain: rightDomain,
             ticks: rightTicks,
             nice: y2?.nice ?? false,
+            ...(y2?.scale !== undefined && { scale: y2.scale }),
             ...(y2?.format !== undefined && { format: y2.format }),
           }),
-    [rightDomain, rightTicks, y2?.format, y2?.nice],
+    [rightDomain, rightTicks, y2?.format, y2?.nice, y2?.scale],
   )
 
   const xLabels = useMemo(() => keys.map(formatX), [keys, formatX])
 
+  /** The horizontal room one x tick label needs: the widest string that could be painted, plus
+   * breathing space to its neighbour. Feeds `smartTicks`, which otherwise thinned the axis by a
+   * constant that knew nothing about the label. Measured at the tick font the axis will actually
+   * paint, which the tier moves (`docs/CHARTS-SPEC.md` §8). */
+  const xLabelPx = useMemo(() => xLabelPxFor(xLabels, tier.axisFont), [xLabels, tier.axisFont])
+
+  /** Everything `autoMargin` measures except the rotation — shared by all three passes below so a
+   * measured label can never differ between the one that DECIDES and the one that PAINTS. */
+  const marginInput = useMemo(
+    () => ({
+      left: leftLabels,
+      right: rightLabels,
+      bottom: xLabels,
+      fontPx: tier.axisFont,
+      floor: tier.margin,
+      ...(marginOverride !== undefined && { override: marginOverride }),
+    }),
+    [leftLabels, rightLabels, xLabels, tier.axisFont, tier.margin, marginOverride],
+  )
+
+  /** The margin an UNROTATED axis resolves to. It is the final margin in every case except an
+   * auto-rotated phone axis, and it is what the rotation decision itself is measured against —
+   * deciding needs an `xMax`, and `xMax` needs a margin, so the unrotated pass breaks the loop. */
+  const flatMargin = useMemo(() => autoMargin(marginInput), [marginInput])
+
+  /** And the margin a 45° axis would resolve to — the OTHER half of the decision. A rotated label
+   * reaches into the left gutter, so rotating spends plot width; `autoXLabelRotate` refuses the
+   * trade when what is left cannot hold three labels at their projected pitch, which is how block
+   * (f1) at 320 used to rotate itself into a clipped axis (§8). */
+  const rotated45Margin = useMemo(() => autoMargin({ ...marginInput, rotate: 45 }), [marginInput])
+
+  // An explicit `xLabelRotate` always wins — including `0`, which is the documented "never rotate"
+  // opt-out. Only an unset one falls through to the phone tier's own default.
+  const rotate =
+    xLabelRotate ??
+    autoXLabelRotate({
+      tier: tier.tier,
+      xMax: Math.max(plot.width - flatMargin.left - flatMargin.right, 0),
+      labelPx: xLabelPx,
+      rotatedXMax: Math.max(plot.width - rotated45Margin.left - rotated45Margin.right, 0),
+    })
+
   const margin = useMemo(
     () =>
-      autoMargin({
-        left: leftLabels,
-        right: rightLabels,
-        bottom: xLabels,
-        ...(marginOverride !== undefined && { override: marginOverride }),
-      }),
-    [leftLabels, rightLabels, xLabels, marginOverride],
+      rotate === 0
+        ? flatMargin
+        : rotate === 45
+          ? rotated45Margin
+          : autoMargin({ ...marginInput, rotate }),
+    [flatMargin, rotated45Margin, marginInput, rotate],
   )
 
   // ── Pass 2: the real scales, now that the plot rect is known ────────────────────────────────
@@ -458,24 +615,12 @@ function CartesianPlot<T>({
     [keys, xMax],
   )
   const yScale = useMemo(
-    () =>
-      scaleLinear<number>({
-        domain: leftDomain,
-        range: [yMax, 0],
-        ...(y?.nice === true && { nice: true }),
-      }),
-    [leftDomain, yMax, y?.nice],
+    () => buildYScale(y, leftDomain, yMax, leftTicks),
+    [y, leftDomain, yMax, leftTicks],
   )
   const y2Scale = useMemo(
-    () =>
-      rightDomain === null
-        ? null
-        : scaleLinear<number>({
-            domain: rightDomain,
-            range: [yMax, 0],
-            ...(y2?.nice === true && { nice: true }),
-          }),
-    [rightDomain, yMax, y2?.nice],
+    () => (rightDomain === null ? null : buildYScale(y2, rightDomain, yMax, rightTicks)),
+    [y2, rightDomain, yMax, rightTicks],
   )
 
   // Resolution order: explicit VALUES win, then an explicit COUNT, then as many as fit.
@@ -484,9 +629,11 @@ function CartesianPlot<T>({
       xTickValues !== undefined
         ? [...xTickValues(keys, xMax)]
         : xTicks === undefined
-          ? smartTicks(keys, xMax)
+          ? // A rotated label stacks diagonally instead of beside its neighbour, so its WIDTH no
+            // longer governs tick spacing — the constant floor takes over, exactly as before.
+            smartTicks(keys, xMax, rotate === 0 ? xLabelPx : undefined)
           : smartTicksEvery(keys, xTicks),
-    [keys, xMax, xTicks, xTickValues],
+    [keys, xMax, xTicks, xTickValues, xLabelPx, rotate],
   )
 
   const cursor = useChartCursor<T>({
@@ -566,11 +713,11 @@ function CartesianPlot<T>({
 
           {children(ctx)}
 
-          {refLines?.map((line) => {
+          {refLines?.map((line, i) => {
             const scale = line.axis === 'right' && y2Scale !== null ? y2Scale : yScale
             return (
               <line
-                key={`${line.axis ?? 'left'}-${line.value}`}
+                key={`${line.axis ?? 'left'}-${line.value}-${i}`}
                 x1={0}
                 x2={xMax}
                 y1={scale(line.value)}
@@ -593,12 +740,17 @@ function CartesianPlot<T>({
                   cursorValue === undefined ? s.getValue(point) : cursorValue(point, s, visible)
                 if (value === null) return null
                 const scale = s.axis === 'right' && y2Scale !== null ? y2Scale : yScale
+                const cy = scale(value)
+                // A non-positive value on a log axis (or any other input a scale can't place)
+                // maps to NaN — the same guard the mark layer applies (`MultiLine`'s `LinePath
+                // defined`), so a stray crosshair dot never paints at `cy="NaN"`.
+                if (!Number.isFinite(cy)) return null
                 const marker = s.getMarker?.(point)
                 return (
                   <SeriesDot
                     key={s.key}
                     cx={cursorX}
-                    cy={scale(value)}
+                    cy={cy}
                     color={marker?.color ?? s.color}
                     {...(marker?.r !== undefined && { r: marker.r })}
                   />
@@ -625,6 +777,7 @@ function CartesianPlot<T>({
             scale={xScale}
             tickValues={tickValues}
             tickFormat={(v) => formatX(String(v))}
+            {...(rotate !== 0 && { rotate })}
           />
 
           <HoverOverlay

package/src/charts/primitives/ChartCard.tsx

@@ -3,7 +3,7 @@
  * tier="widget"` title row (icon/info/value/delta/count/actions) plus an optional subtitle, over a
  * clipped chart body. Do not wrap visx charts in bare divs.
  *
- * `WidgetHeader` lives in `src/widget-header/` and is itself Mantine-free, so composing it here
+ * `WidgetHeader` lives in `src/dashboard/` and is itself Mantine-free, so composing it here
  * keeps `./charts` resolving with no `@mantine/*` installed (`check-dist-layering.mjs`,
  * `basalt/token-layer-boundary`). The `actions` slot cannot mount `CtlSlot` (Mantine-coupled) for
  * the same reason — it carries only `data-basalt-tier="widget"`; a basalt control placed there
@@ -13,8 +13,13 @@
  * the `''`-as-hidden-header sentinel a consumer used to reach for otherwise.
  */
 import type { CSSProperties, ReactNode } from 'react'
+import { cx } from '../../common/props'
+import type { BasaltProps, SlotStylesProps } from '../../common/props'
 import { VX } from '../../tokens'
-import { WidgetHeader } from '../../widget-header'
+import { WidgetHeader } from '../../dashboard/widget-header'
+import type { DeltaPolarity } from '../../dashboard/delta-badge'
+import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
+import type { ChartState } from './ChartPending'
 
 // Surfaces resolve per theme via CSS vars, so the styles are static (no useMemo/isDark).
 // Depth = `shadow-card` (a whisper shadow + a 1px ring baked into the same value), never a
@@ -51,28 +56,68 @@ const headerWrapStyle: CSSProperties = {
   padding: 'var(--mantine-spacing-xs, 0.6875rem) var(--mantine-spacing-sm, 0.8125rem) 4px',
 }
 
-export type ChartCardProps = {
-  /** Optional — the header renders only when this or one of info/value/actions/icon/count is set. */
-  title?: string
-  /** Optional leading icon, forwarded to `WidgetHeader`. */
-  icon?: ReactNode
-  /** Optional muted line rendered below the title row — does NOT by itself trigger the header. */
-  subtitle?: string
-  /** Renders `WidgetHeader`'s info glyph beside the title — a `More information` button whose
-   * bubble opens on hover, focus and click. Never part of the heading's accessible name. */
-  info?: string
-  /** Pre-formatted metric value, on the hero-metric row with `delta`. */
-  value?: string
-  /** Signed delta rendered via `DeltaBadge`, alongside `value`. */
-  delta?: number
-  /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
-  deltaPeriod?: string
-  /** Mono count tag after the title. */
-  count?: number
-  /** Right-aligned slot — carries `data-basalt-tier="widget"` (no `CtlSlot`; see module doc). */
-  actions?: ReactNode
-  children: ReactNode
-}
+/**
+ * The three boxes a `ChartCard` paints, and therefore the slot set a consumer may class
+ * (`SlotStylesProps`). `root` is the card itself (shadow, radius, panel background), `header` the
+ * unclipped title band, `body` the clipped chart well. There is deliberately no slot for
+ * `WidgetHeader`'s own internals — that component owns its own contract.
+ */
+export type ChartCardSlot = 'root' | 'header' | 'body'
+
+/**
+ * The props below are a HAND-CUT subset of `WidgetHeaderProps`, and that is the open half of audit
+ * B #2: `widget-header` now publishes named slices (`WidgetHeaderTitleProps`,
+ * `WidgetHeaderMetricProps`, `WidgetHeaderDeltaProps`) precisely so a composer's omissions are
+ * declared rather than accidental, and `StatCard`/`SettingsSection` already compose them.
+ *
+ * `ChartCard` cannot yet: it lives inside the Mantine-free `charts/` boundary, and every prop here
+ * is spelled out so a `./charts`-only consumer reads the whole contract without following a type
+ * into another module. What that costs is visible in the omissions — no `unit`, no `deltaFormat`,
+ * no `deltaGlyph`, no `sparkline` — so a KPI moved from a `StatCard` into a `ChartCard` loses them
+ * silently. Compose the slices here next time this file is open; the ledger of which composer takes
+ * which is `docs/CONTROLS-SPEC.md` §2.2.
+ */
+export type ChartCardProps = BasaltProps &
+  SlotStylesProps<ChartCardSlot> & {
+    /** Optional — the header renders only when this or one of info/value/actions/icon/count is set. */
+    title?: string
+    /** Optional leading icon, forwarded to `WidgetHeader`. */
+    icon?: ReactNode
+    /** Optional muted line rendered below the title row — does NOT by itself trigger the header. */
+    subtitle?: string
+    /** Renders `WidgetHeader`'s info glyph beside the title — a `More information` button whose
+     * bubble opens on hover, focus and click. Never part of the heading's accessible name. */
+    info?: string
+    /** Pre-formatted metric value, on the hero-metric row with `delta`. */
+    value?: string
+    /** Signed delta rendered via `DeltaBadge`, alongside `value`. */
+    delta?: number
+    /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
+    deltaPeriod?: string
+    /** Which sign reads as the good verdict on the delta chip — forwarded to `DeltaBadge`'s
+     * `polarity`. Defaults to `'up-good'` (today's behaviour). */
+    deltaPolarity?: DeltaPolarity
+    /** Mono count tag after the title. */
+    count?: number
+    /** Right-aligned slot — carries `data-basalt-tier="widget"` (no `CtlSlot`; see module doc). */
+    actions?: ReactNode
+    /**
+     * Any resolved state (pending → error → empty, same precedence `resolveChartState` gives
+     * every chart kind) REPLACES `children` with its placeholder at `placeholderHeight` — the
+     * header still renders unchanged, so a card's title never reflows through the pending → drawn
+     * transition. `state={{}}` (or an all-falsy state) renders `children`, same as omitting the
+     * prop.
+     */
+    state?: ChartState
+    /** Body height while a placeholder shows. Default 240 (`ChartFrame`'s own default height). */
+    placeholderHeight?: number
+    /** Affordance under a pending/empty/error label — a retry button, a "clear filters" link.
+     * Forwarded to whichever placeholder resolves. */
+    stateAction?: ReactNode
+    /** Optional so a title-less pending card can BE a route's `<Suspense>` fallback
+     * (`<ChartCard state={{ pending: true }} placeholderHeight={320} />`, no `children` at all). */
+    children?: ReactNode
+  }
 
 export function ChartCard({
   title,
@@ -82,10 +127,18 @@ export function ChartCard({
   value,
   delta,
   deltaPeriod,
+  deltaPolarity,
   count,
   actions,
+  state,
+  placeholderHeight = 240,
+  stateAction,
+  className,
+  classNames,
+  style,
   children,
 }: ChartCardProps) {
+  const resolvedState = resolveChartState({ ...(state !== undefined && { state }) })
   const hasHeader =
     title !== undefined ||
     info !== undefined ||
@@ -95,9 +148,16 @@ export function ChartCard({
     count !== undefined
 
   return (
-    <div style={cardStyle}>
+    <div
+      className={cx(classNames?.root, className)}
+      style={{ ...cardStyle, ...style }}
+      {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
+    >
       {hasHeader && (
-        <div style={headerWrapStyle}>
+        <div
+          {...(classNames?.header !== undefined && { className: classNames.header })}
+          style={headerWrapStyle}
+        >
           <WidgetHeader
             tier="widget"
             title={title ?? ''}
@@ -107,6 +167,7 @@ export function ChartCard({
             {...(value !== undefined && { value })}
             {...(delta !== undefined && { delta })}
             {...(deltaPeriod !== undefined && { deltaPeriod })}
+            {...(deltaPolarity !== undefined && { deltaPolarity })}
             {...(count !== undefined && { count })}
             {...(actions !== undefined && {
               actions: <span data-basalt-tier="widget">{actions}</span>,
@@ -114,7 +175,30 @@ export function ChartCard({
           />
         </div>
       )}
-      <div style={bodyClipStyle}>{children}</div>
+      <div
+        {...(classNames?.body !== undefined && { className: classNames.body })}
+        style={bodyClipStyle}
+      >
+        {resolvedState === 'pending' ? (
+          <ChartPending width="100%" height={placeholderHeight} />
+        ) : resolvedState === 'error' ? (
+          <ChartError
+            width="100%"
+            height={placeholderHeight}
+            error={state?.error}
+            action={stateAction}
+          />
+        ) : resolvedState === 'empty' ? (
+          <ChartEmpty
+            width="100%"
+            height={placeholderHeight}
+            {...(typeof state?.empty === 'string' && { label: state.empty })}
+            action={stateAction}
+          />
+        ) : (
+          children
+        )}
+      </div>
     </div>
   )
 }