basalt-ui 2.1.0 → 2.3.0

package/dist/dashboard/stat-card.d.ts

@@ -39,6 +39,17 @@ export type StatCardBreakdownRow = {
 export type StatCardSparklineSize = {
     width: number;
     height: number;
+    /**
+     * The card's `query` as a chart state — present only while the sparkline has nothing to draw
+     * (pending, or failed with no data), so `<Sparkline {...size} />` forwards it and the tile shows a
+     * sized placeholder instead of a hand-rolled `'—'`. Structurally a `ChartState`: this module
+     * stays chart-free. Absent without a `query`, and once data has arrived.
+     */
+    state?: {
+        pending?: boolean;
+        error?: unknown;
+        empty?: boolean;
+    };
 };
 /**
  * `StatCard` re-publishes three NAMED `WidgetHeader` slices (`WidgetHeaderTitleProps` /
@@ -97,8 +108,12 @@ export type StatCardProps = BasaltProps & SlotStylesProps<StatCardSlot> & Widget
      * 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).
      *
+     * A render prop is a sanctioned pattern here, so `react/no-unstable-nested-components` is
+     * configured with `allowAsProps` in the shipped preset. Spread the size (`{...size}`) to forward
+     * `state` along with the box.
+     *
      * @example
-     * sparkline={({ width, height }) => <MySparkline data={history} width={width} height={height} />}
+     * sparkline={(size) => <Sparkline ariaLabel="Active users" data={history} {...size} />}
      */
     sparkline?: ReactNode | ((size: StatCardSparklineSize) => ReactNode);
     /** Where `sparkline` sits. `'bleed'` (default) is today's full-width row bled to the card edges;

package/dist/dashboard/stat-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AA+FA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAA;AAE/B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAcD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAiDD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GACrC,eAAe,CAAC,YAAY,CAAC,GAC7B,sBAAsB,GACtB,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,GACtC,sBAAsB,GAAG;IACvB;iEAC6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,qBAAqB,KAAK,SAAS,CAAC,CAAA;IACpE;4GACwG;IACxG,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACtC;mGAC+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAEH,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,SAAS,EACT,KAAK,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAA4B,EAC5B,OAAO,EACP,IAAI,EACJ,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,aAAa,+BAqKf"}
+{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AAiGA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAInD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAA;AAE/B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAcD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAChE,CAAA;AA6DD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GACrC,eAAe,CAAC,YAAY,CAAC,GAC7B,sBAAsB,GACtB,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,GACtC,sBAAsB,GAAG;IACvB;iEAC6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,qBAAqB,KAAK,SAAS,CAAC,CAAA;IACpE;4GACwG;IACxG,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACtC;mGAC+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAEH,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,SAAS,EACT,KAAK,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAA4B,EAC5B,OAAO,EACP,IAAI,EACJ,SAAS,EACT,KAAK,EACL,UAAU,GACX,EAAE,aAAa,+BA0Kf"}

package/dist/dashboard/stat-card.js

@@ -6,6 +6,7 @@ import { CtlSlot } from "../theme/index.js";
 import { VX } from "../tokens/index.js";
 import { cx } from "../common/props.js";
 import { QueryState } from "./query-state.js";
+import { assertQueryStateLike } from "../common/query-state-like.js";
 import classes from "./stat-card.module.css";
 const SPARKLINE_RIGHT_WIDTH = 72;
 const SPARKLINE_RIGHT_HEIGHT = 26;
@@ -33,6 +34,13 @@ function useSlotWidth(active) {
     width
   };
 }
+function sparklineState(query) {
+  if (query === void 0) return void 0;
+  assertQueryStateLike("StatCard", query);
+  if (query.data !== void 0) return void 0;
+  if (query.isError) return { error: query.error ?? true };
+  return query.fetchStatus === "idle" ? void 0 : { pending: true };
+}
 const TONE_RAIL_WIDTH = 3;
 const TONE_LABEL = {
   good: "Within the good threshold",
@@ -64,7 +72,12 @@ function StatCard({
   const isRender = typeof sparkline === "function";
   const bleeds = sparklinePlacement === "bleed";
   const { ref: slotRef, width: slotWidth } = useSlotWidth(isRender);
-  const measured = { width: slotWidth, height: SPARKLINE_RIGHT_HEIGHT };
+  const state = sparklineState(query);
+  const measured = {
+    width: slotWidth,
+    height: SPARKLINE_RIGHT_HEIGHT,
+    ...state !== void 0 && { state }
+  };
   const breakdownRows = breakdown === void 0 || breakdown.length === 0 ? null : /* @__PURE__ */ jsx("dl", { className: classes.breakdown, children: breakdown.map((row) => /* @__PURE__ */ jsxs(
     "div",
     {

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { scrollParentOf, useCoarsePointer } from './common/index.js';
 export { createBasaltTheme } from './theme/index.js';
 export { ThemeToggle } from './theme/theme-toggle.js';
 export { BasaltShell, PageBar, PageAside, useSizeClass, PageTitle, type ShellBaseProps, type SidebarBlock, type SettingsMenuItem, } from './shell/index.js';
-export { WidgetHeader, DeltaBadge, Section, StatCard, type StatCardBreakdownRow, type StatCardTone, StatGroup, EmptyState, SettingsSection, SettingsRow, DangerZone, } from './dashboard/index.js';
+export { WidgetHeader, DeltaBadge, Section, StatCard, type StatCardBreakdownRow, type StatCardSparklineSize, type StatCardTone, StatGroup, EmptyState, SettingsSection, SettingsRow, DangerZone, } from './dashboard/index.js';
 export { unwrap } from './query-client.js';
 export type { BasaltRegister, SeriesKey } from './register.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EACL,WAAW,EACX,OAAO,EACP,SAAS,EACT,YAAY,EACZ,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,OAAO,EACP,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,SAAS,EACT,UAAU,EACV,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAMvC,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EACL,WAAW,EACX,OAAO,EACP,SAAS,EACT,YAAY,EACZ,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,OAAO,EACP,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,SAAS,EACT,UAAU,EACV,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAMvC,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA"}

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.1.0
+# basalt-ui v2.3.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,7 +13,7 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.1.0
+Version: 2.3.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/BandStrip.tsx

@@ -39,7 +39,7 @@ export type BandStripSeries<T> = Pick<
    * The tooltip row's value for a band in this state. `null` is an ABSENT reading and renders an
    * em dash; omit the function when the state's name is the whole reading ("Not measured").
    */
-  formatValue?: (d: T) => string | null
+  formatValue?: ((d: T) => string | null) | undefined
 }
 
 /** One band: its state, and the two ways to qualify it. */
@@ -47,23 +47,25 @@ export type BandSpan = {
   /** A `states` key: the band's legend entry, fill and tooltip row. */
   state: string
   /** Overrides the state's fill — an intensity ramp WITHIN a state. `alpha(VX.*, …)`, never a hex. */
-  fill?: string
+  fill?: string | undefined
   /**
    * A shorter, inset bar over the band, for a fact that must not be read off the fill ramp (a
    * renegotiation, a restart). Its color is a `states` entry, so the legend names it.
    */
-  marker?: {
-    /** Defaults to the band's own `state`. */
-    state?: string
-    /** Vertical inset from the band's top and bottom, in px. Default 6. */
-    inset?: number
-  }
+  marker?:
+    | {
+        /** Defaults to the band's own `state`. */
+        state?: string | undefined
+        /** Vertical inset from the band's top and bottom, in px. Default 6. */
+        inset?: number | undefined
+      }
+    | undefined
 }
 
 /** Collapse adjacent data where one band per datum would be thinner than `minBandPx`. */
 export type BandFold<T> = {
   /** Floor on a drawn band's px width. Default 3. */
-  minBandPx?: number
+  minBandPx?: number | undefined
   /**
    * The consumer's merge of a group of adjacent data into the datum drawn in its place — whether
    * that is a max, a sum or a recomputed rate is a question about the measurement. Keep the first
@@ -79,7 +81,7 @@ export type BandStripProps<T, X extends ChartX = ChartX> = Omit<
   states: readonly BandStripSeries<T>[]
   /** Which state, fill and marker each datum has. Memoize it: a new function recompiles the chart. */
   getBand: (d: T) => BandSpan
-  fold?: BandFold<T>
+  fold?: BandFold<T> | undefined
 }
 
 const DEFAULT_MIN_BAND_PX = 3

package/src/charts/Bars.tsx

@@ -27,7 +27,7 @@ export type BarsBar<T> = Pick<
   'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'
 > & {
   /** Default 0.85. */
-  fillOpacity?: number
+  fillOpacity?: number | undefined
 }
 
 /** A line overlay; `axis: 'right'` reads the chart's `y2`. */
@@ -54,11 +54,11 @@ export type BarsProps<T, X extends ChartX = ChartX> = Omit<
   'marks' | 'series'
 > & {
   bars: readonly BarsBar<T>[]
-  lines?: readonly BarsLine<T>[]
+  lines?: readonly BarsLine<T>[] | undefined
   /** Default `'stacked'`. `'normalized'` stacks each x to its share of the total. */
-  layout?: 'stacked' | 'grouped' | 'normalized'
+  layout?: 'stacked' | 'grouped' | 'normalized' | undefined
   /** Per-bar opacity (a partial week, an estimate). Overrides the series' `fillOpacity`. */
-  barOpacity?: (d: T, key: string) => number
+  barOpacity?: ((d: T, key: string) => number) | undefined
 }
 
 const DEFAULT_BAR_OPACITY = 0.85

package/src/charts/ChartCard.tsx

@@ -92,32 +92,38 @@ export type ChartCardSlot = 'root' | 'header' | 'body'
 
 export type ChartCardProps = BasaltProps &
   SlotStylesProps<ChartCardSlot> & {
-    title?: string
+    title?: string | undefined
     icon?: ReactNode
     /** A muted line below the title row; does not by itself render the header. */
-    subtitle?: string
+    subtitle?: string | undefined
     /** `WidgetHeader`'s info glyph beside the title. */
-    info?: string
+    info?: string | undefined
     /** A pre-formatted metric value, with `delta` on the hero row. */
-    value?: string
-    delta?: number
-    deltaPeriod?: string
-    deltaPolarity?: DeltaPolarity
+    value?: string | undefined
+    delta?: number | undefined
+    deltaPeriod?: string | undefined
+    deltaPolarity?: DeltaPolarity | undefined
     /** A mono count tag after the title. */
-    count?: number
+    count?: number | undefined
     /** Right-aligned controls. */
     actions?: ReactNode
     /** A resolved state replaces `children` with its placeholder; the header stays. */
-    state?: ChartState
+    state?: ChartState | undefined
     /** Body height while a placeholder shows. Default: the chart height law, i.e. exactly the box an
      * unsized chart takes — pass the chart's own `height` when it states one, so a `<Suspense
      * fallback={<ChartCard state={{ pending: true }} …/>}>` reserves the final size. */
-    placeholderHeight?: number | ResponsiveChartHeight
+    placeholderHeight?: number | ResponsiveChartHeight | undefined
     /** A retry button or a "clear filters" link under the placeholder. */
     stateAction?: ReactNode
     children?: ReactNode
   }
 
+/** Drops explicit `undefined`s: `WidgetHeader` is exact-optional, this props type is not. */
+const definedOnly = <T extends object>(o: T): { [K in keyof T]?: Exclude<T[K], undefined> } =>
+  Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as {
+    [K in keyof T]?: Exclude<T[K], undefined>
+  }
+
 /** A header renders when one of these is set (a subtitle or delta alone does not). */
 const HEADER_TRIGGERS = ['title', 'info', 'value', 'icon', 'count'] as const
 
@@ -150,7 +156,7 @@ export function ChartCard({
           <div className={cx(classes.header, classNames?.header)}>
             <WidgetHeader
               tier="widget"
-              {...header}
+              {...definedOnly(header)}
               title={header.title ?? ''}
               {...(actions !== undefined && {
                 actions: <span data-basalt-tier="widget">{actions}</span>,

package/src/charts/Donut.tsx

@@ -34,13 +34,13 @@ export type DonutProps<K extends string = string> = BasaltProps & {
   colorForKey: (key: K) => string
   formatValue: (v: number) => string
   /** Legend and tooltip label for a key. Default: the key. */
-  seriesLabel?: (key: K) => string
+  seriesLabel?: ((key: K) => string) | undefined
   /** The ring's centre text, and the smaller line under it. */
-  centerLabel?: string
-  centerSubLabel?: string
+  centerLabel?: string | undefined
+  centerSubLabel?: string | undefined
   /** Default 240. */
-  height?: number | ResponsiveChartHeight
-  state?: ChartState
+  height?: number | ResponsiveChartHeight | undefined
+  state?: ChartState | undefined
 }
 
 /** Slices kept before the rest fold into "Other". */

package/src/charts/DualPanel.tsx

@@ -64,12 +64,12 @@ export type DualPanelBar<T> = {
   /** Tick and tooltip formatter. */
   format: (v: number) => string
   /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
-  formatValue?: (v: number, d: T) => string
+  formatValue?: ((v: number, d: T) => string) | undefined
   /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
    * is used verbatim. */
-  domain?: readonly [number, number] | 'auto'
+  domain?: readonly [number, number] | 'auto' | undefined
   /** When `'auto'`: floors `maxAbs`, so a plateau does not amplify to fill the pane. */
-  maxAbsFloor?: number
+  maxAbsFloor?: number | undefined
 }
 
 export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
@@ -91,15 +91,22 @@ export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
   series: readonly DualPanelLine<T>[]
   /** Top pane y axis. Default domain `'auto'`: the visible lines' span plus 8%, rounded to nice
    * ticks (not zero-based: the interesting range is often a narrow band far from zero). */
-  top?: { domain?: readonly [number, number] | 'auto'; format?: (v: number) => string }
+  top?:
+    | {
+        domain?: readonly [number, number] | 'auto' | undefined
+        format?: ((v: number) => string) | undefined
+      }
+    | undefined
   /**
    * Shades the band between two top lines (by key), where both are visible. `aboveFill` colours the
    * side where `to` runs above `from`; omitted, both sides take `fill`.
    */
-  fillBetween?: { from: string; to: string; fill: string; aboveFill?: string }
+  fillBetween?:
+    | { from: string; to: string; fill: string; aboveFill?: string | undefined }
+    | undefined
   bar: DualPanelBar<T>
   /** The top pane's share of the chart height. Default 0.62. */
-  topFraction?: number
+  topFraction?: number | undefined
 }
 
 type FillRow<T, X> = { x: X; from: number; to: number; series: string; datum: T }

package/src/charts/Heatmap.tsx

@@ -18,6 +18,7 @@ import type { CSSProperties, ReactElement } from 'react'
 import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
+import { strideTicks } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { useCoarsePointer } from '../common/use-media-query'
@@ -37,26 +38,28 @@ export type HeatmapProps<T> = BasaltProps & {
   /** The intensity; `null` is an absent cell (flat neutral), never a zero. */
   getValue: (d: T) => number | null
   /** Explicit band order. Default: first seen in `data`. */
-  rows?: readonly string[]
-  cols?: readonly string[]
+  rows?: readonly string[] | undefined
+  cols?: readonly string[] | undefined
   /** The ink at full intensity, a `VX.*` ref or a series token. Default `VX.line`. */
-  color?: string
+  color?: string | undefined
   /** The value range the color scale spans. Default `[0, max]` of the data. */
-  domain?: readonly [number, number]
+  domain?: readonly [number, number] | undefined
   /** Tooltip, legend-end and `aria` value format. Default: the number as-is. */
-  formatValue?: (v: number) => string
+  formatValue?: ((v: number) => string) | undefined
   /** Band tick and tooltip header labels. Default: the band key. */
-  formatRow?: (row: string) => string
-  formatCol?: (col: string) => string
+  formatRow?: ((row: string) => string) | undefined
+  formatCol?: ((col: string) => string) | undefined
   /** `false` hides the gradient legend; `label` titles it. */
-  legend?: false | { label?: string }
+  legend?: false | { label?: string | undefined } | undefined
   /** Rows after the value row, per cell (a sample count, a failure reason). Called with the datum. */
-  tooltip?: false | { rows?: (d: T) => readonly ChartTooltipRow[] }
+  tooltip?: (false | { rows?: ((d: T) => readonly ChartTooltipRow[]) | undefined }) | undefined
   /** A fixed height, or one per container class. Default: by row count (160–420px). */
-  height?: number | ResponsiveChartHeight
-  /** Fill the parent's height instead (the parent needs a definite height). Overrides `height`. */
-  matchHeight?: boolean
-  state?: ChartState
+  height?: number | ResponsiveChartHeight | undefined
+  /** Fill the parent's height instead. Overrides `height`. CSS-owned like every other kind's box
+   * (`ChartBox`, no measuring, SSR-stable), so the parent needs a definite CSS height — a grid or
+   * flex stretch, `h-full`, an explicit height — which no kind can read off an auto-height parent. */
+  matchHeight?: boolean | undefined
+  state?: ChartState | undefined
 }
 
 /** Intensity steps: quantized, so the gradient legend and the cells are the same ramp. */
@@ -149,8 +152,9 @@ export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
     return {
       chart: ({ width }: ChartBuildContext): StoredChartSpec => {
         const ticks = { line: false as const, size: 0 }
+        const cls = resolveContainerClass(width)
         const tickLabels = {
-          fontSize: resolveContainerClass(width) === 'wide' ? VX.text.micro : VX.text.nano,
+          fontSize: cls === 'wide' ? VX.text.micro : VX.text.nano,
           opacity: 1,
           thin: true,
         }
@@ -190,7 +194,11 @@ export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
               scale: scaleBand<string>().domain(cols).paddingInner(0).paddingOuter(0),
               axis: {
                 line: AXIS_LINE,
-                ticks: { values: cols, format: (v) => formatCol(String(v)), ...ticks },
+                ticks: {
+                  values: strideTicks(cols, cls),
+                  format: (v) => formatCol(String(v)),
+                  ...ticks,
+                },
                 tickLabels,
               },
             },

package/src/charts/MirroredBars.tsx

@@ -35,11 +35,11 @@ export type MirroredBarPane = {
    * entry throws: the pane would vanish, which reads as a measured zero. */
   key: string
   /** The pane's upper bound. `'auto'` (default) is its own visible maximum; a number pins it. */
-  max?: number | 'auto'
+  max?: number | 'auto' | undefined
   /** When `'auto'`: floors the upper bound, so a quiet window does not amplify noise to full height. */
-  autoMaxFloor?: number
+  autoMaxFloor?: number | undefined
   /** Tick count for this pane's own axis. Default 3. */
-  ticks?: number
+  ticks?: number | undefined
   /** Tick and tooltip formatter, in the pane's OWN units. */
   format: (v: number) => string
 }
@@ -71,18 +71,18 @@ export type MirroredBarsProps<T, X extends ChartX = ChartX> = Pick<
   /** Drawn below the baseline. */
   down: MirroredBarPane
   /** The up pane's share of the height. Default 0.35: the pair is usually asymmetric. */
-  upFraction?: number
+  upFraction?: number | undefined
   /** 0..1 of a bar's width that no source sample covers, drawn neutral across both panes. */
-  getAbsentFraction?: (d: T) => number
+  getAbsentFraction?: ((d: T) => number) | undefined
   /** Per-datum bar opacity: a real but qualified measurement (a short bucket) drawn dimmer. */
-  getBarOpacity?: (d: T) => number
+  getBarOpacity?: ((d: T) => number) | undefined
   /**
    * Collapse adjacent data where one band per datum would be sub-pixel. `merge` is the consumer's
    * (max, sum, or a rate from summed parts) and must keep `group[0]`'s x, the slot start.
    */
-  fold?: { minBandPx?: number; merge: (group: T[]) => T }
+  fold?: { minBandPx?: number | undefined; merge: (group: T[]) => T } | undefined
   /** Default `'leading'`: x is a slot's start. */
-  cursorResolution?: CartesianChartProps<T, X>['cursorResolution']
+  cursorResolution?: CartesianChartProps<T, X>['cursorResolution'] | undefined
 }
 
 const DEFAULT_UP_FRACTION = 0.35

package/src/charts/Sparkline.tsx

@@ -18,7 +18,9 @@ import type { CartesianDefinition } from './compile'
 import { chartCurve } from './curves'
 import { barMark } from './marks'
 import { ChartEngine, idPrefixOf } from './host'
+import { ChartPlaceholder, resolveChartState } from './state'
 import { CHART_THEME } from './theme'
+import type { ChartState } from './types'
 
 export type SparklineProps = BasaltProps & {
   /** The accessible name. Required: a chart without one is an unlabeled image. */
@@ -27,15 +29,18 @@ export type SparklineProps = BasaltProps & {
   /** Height in px. */
   height: number
   /** Width in px. Default: the container's, measured by the host. */
-  width?: number
+  width?: number | undefined
   /** Default `'line'`. */
-  mark?: 'line' | 'bar'
+  mark?: 'line' | 'bar' | undefined
   /** A `VX.*` ref or a series token. Default `VX.faint`. */
-  color?: string
+  color?: string | undefined
   /** Paints the last point in `emphasisColor` — the one reading a trend beside a KPI is for. */
-  emphasizeLast?: boolean
+  emphasizeLast?: boolean | undefined
   /** Default `VX.accent`. */
-  emphasisColor?: string
+  emphasisColor?: string | undefined
+  /** Pending / error / empty, the same contract as every other kind. The placeholder fills the
+   * sparkline's own `width` × `height`, so a loading tile does not shift when the trend lands. */
+  state?: ChartState | undefined
 }
 
 type Point = { i: number; v: number | null }
@@ -145,6 +150,7 @@ export function Sparkline(props: SparklineProps): ReactElement {
     color = VX.faint,
     emphasizeLast = false,
     emphasisColor = VX.accent,
+    state,
     className,
     style,
   } = props
@@ -156,13 +162,15 @@ export function Sparkline(props: SparklineProps): ReactElement {
     if (range === null) return null
     return compileSparkline(rows, range, mark, color, emphasizeLast ? emphasisColor : null)
   }, [data, mark, color, emphasizeLast, emphasisColor])
+  const resolved = resolveChartState(state)
   return (
     <div
       data-basalt-sparkline=""
       {...(className !== undefined && { className })}
       style={{ width: width ?? '100%', height, minWidth: 0, ...style }}
     >
-      {definition !== null && (
+      {resolved !== null && <ChartPlaceholder state={state} height={height} compact />}
+      {resolved === null && definition !== null && (
         <ChartEngine
           definition={definition}
           ariaLabel={ariaLabel}

package/src/charts/StackedArea.tsx

@@ -25,7 +25,7 @@ export type StackedAreaBand<T> = Pick<
   'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'
 > & {
   /** Default 0.85. */
-  fillOpacity?: number
+  fillOpacity?: number | undefined
 }
 
 export type StackedAreaProps<T, X extends ChartX = ChartX> = Omit<
@@ -35,7 +35,7 @@ export type StackedAreaProps<T, X extends ChartX = ChartX> = Omit<
   /** The bands, bottom to top. */
   series: readonly StackedAreaBand<T>[]
   /** No `scale`: a log axis has no additive zero to stack from. */
-  y?: Omit<NonNullable<CartesianChartProps<T, X>['y']>, 'scale'>
+  y?: Omit<NonNullable<CartesianChartProps<T, X>['y']>, 'scale'> | undefined
 }
 
 export function StackedArea<T, X extends ChartX = ChartX>(

package/src/charts/compile.ts

@@ -39,6 +39,7 @@ import type {
   ChartTooltipRow,
   ChartX,
   PlotRow,
+  ZoneSpec,
 } from './types'
 
 /**
@@ -196,6 +197,16 @@ function xTickPolicy<X extends ChartX>(
   return { count: xTicks }
 }
 
+/**
+ * Every n-th value, n the smallest stride that leaves at most the class's x tick count (the same
+ * ladder a continuous x axis counts to). A band axis labels every value it is given and only drops
+ * the ones that collide, so a short-label grid (18 hour columns) would otherwise draw all of them.
+ */
+export function strideTicks<V>(values: readonly V[], cls: ContainerClass): V[] {
+  const stride = Math.max(1, Math.ceil(values.length / LADDER[cls].xTicks))
+  return values.filter((_, i) => i % stride === 0)
+}
+
 export function xGuide<X extends ChartX>(opts: {
   model: XScaleModel<X>
   xTicks: number | readonly X[] | undefined
@@ -239,6 +250,86 @@ export function areaGradient(index: number, color: string): ChartGradient {
   }
 }
 
+const areaTint = (color: string): string =>
+  `color-mix(in srgb, ${color} var(--vx-area-top), transparent)`
+
+/**
+ * A series area filled by value zone: a vertical gradient whose stops sit at the zone boundaries.
+ * The engine writes `<linearGradient>` in the default `objectBoundingBox` units, so offsets are
+ * fractions of the AREA's own box, not of the plot: from the larger of the series' maximum and 0 down
+ * to the smaller of its minimum and 0, the baseline the area closes to even when the y domain
+ * excludes 0. A boundary at value `v` sits at `(ceiling - v) / (ceiling - floor)`. Hard edges:
+ * neighbouring zones meet at one offset; overlapping zones never run backwards. `null` when no zone
+ * reaches the area (the caller keeps the plain series-colour fade). Linear axes only.
+ */
+export function zoneAreaGradient(
+  index: number,
+  zones: readonly ZoneSpec[],
+  values: readonly (number | null)[],
+): ChartGradient | null {
+  let floor = 0
+  let ceiling = 0
+  for (const v of values) {
+    if (v === null || !Number.isFinite(v)) continue
+    if (v < floor) floor = v
+    if (v > ceiling) ceiling = v
+  }
+  const span = ceiling - floor
+  if (span <= 0) return null
+  const offsetOf = (v: number): number => (ceiling - Math.min(ceiling, Math.max(floor, v))) / span
+  const reaching = zones
+    .filter((z) => !Number.isNaN(z.from) && !Number.isNaN(z.to) && z.to > floor && z.from < ceiling)
+    .toSorted((p, q) => q.to - p.to)
+  let previous = 0
+  const stops = reaching.flatMap((z) =>
+    [offsetOf(z.to), offsetOf(z.from)].map((raw) => {
+      previous = Math.max(previous, raw)
+      return { offset: previous, color: areaTint(z.fill) }
+    }),
+  )
+  if (stops.length === 0) return null
+  return { id: areaGradientId(index), x1: 0, y1: 0, x2: 0, y2: 1, stops }
+}
+
+let warnedLogZones = false
+
+/** Zone stops are placed linearly in value; a log axis would put them in the wrong place (V2-SPEC
+ * § 9.9 precedent): dev throws, production logs once and keeps the series-colour fade. */
+function guardLogZones(onLog: boolean): boolean {
+  if (!onLog) return false
+  const message = "area: 'zones' cannot use a log axis; use area: true"
+  if (process.env.NODE_ENV !== 'production') throw new Error(message)
+  // oxlint-disable-next-line no-console -- the production leg of a dev-only throw
+  if (!warnedLogZones) console.error(message)
+  warnedLogZones = true
+  return true
+}
+
+/** The gradient resource for a series' `area` fill: zones, a colour ref, or the series colour. */
+function seriesAreaGradient<T, X extends ChartX>(
+  s: ChartSeries<T>,
+  index: number,
+  input: CartesianInput<T, X>,
+  axes: Axes<T>,
+): ChartGradient {
+  const plain = areaGradient(
+    index,
+    typeof s.area === 'string' && s.area !== 'zones' ? s.area : s.color,
+  )
+  if (s.area !== 'zones') return plain
+  const side = axes.onRight(s) ? 'right' : 'left'
+  const axisConfig = side === 'right' ? input.y2 : input.y
+  if (guardLogZones(axisConfig?.scale === 'log')) return plain
+  const zones = (input.zones ?? []).filter((z) => axes.scaleId(z.axisSide) === axes.scaleId(side))
+  return (
+    zoneAreaGradient(
+      index,
+      zones,
+      input.data.map((d) => s.getValue(d)),
+    ) ?? plain
+  )
+}
+
 const isBar = <T>(s: ChartSeries<T>): boolean => s.mark === 'bar'
 
 /** The two synthetic totals standing in for a stack's bars in its AUTO domain only: the positive
@@ -538,7 +629,7 @@ export function compileCartesian<T, X extends ChartX>(
   const formatX = (v: ChartValue): string =>
     input.formatX ? input.formatX(v as X) : defaultFormatX(v)
   const gradients = input.series.flatMap((s, i) =>
-    s.area ? [areaGradient(i, typeof s.area === 'string' ? s.area : s.color)] : [],
+    s.area ? [seriesAreaGradient(s, i, input, axes)] : [],
   )
 
   return {

package/src/charts/index.ts

@@ -28,6 +28,7 @@ export {
 } from './MirroredBars'
 export { ChartCard, type ChartCardProps, type ChartCardSlot } from './ChartCard'
 export { chartCursor } from './cursor'
+export { chartCurve, type CurveName } from './curves'
 export type {
   AxisConfig,
   CartesianChartProps,