basalt-ui 2.1.0 → 2.3.0

package/src/charts/state.tsx

@@ -45,6 +45,9 @@ export function ChartPlaceholder(props: {
   state: ChartState | undefined
   height?: ChartBoxHeight
   action?: ReactNode
+  /** For a box too small to hold a sentence (a sparkline): error and empty show a `—` and carry the
+   * label as the accessible name and the hover title. */
+  compact?: boolean
 }): ReactElement | null {
   const kind = resolveChartState(props.state)
   if (kind === null) return null
@@ -60,20 +63,29 @@ export function ChartPlaceholder(props: {
     kind === 'error'
       ? toErrorMessage(props.state?.error, 'The chart failed to load.')
       : emptyLabel(props.state)
-  const body = (
+  const body = props.compact ? (
+    <span aria-hidden="true">—</span>
+  ) : (
     <>
       <span>{label}</span>
       {props.action}
     </>
   )
+  const name = props.compact ? { 'aria-label': label, title: label } : {}
   if (kind === 'error')
     return fit(
-      <div role="alert" data-basalt-chart-state={kind} className={stateClass} style={style}>
+      <div
+        role="alert"
+        data-basalt-chart-state={kind}
+        className={stateClass}
+        style={style}
+        {...name}
+      >
         {body}
       </div>,
     )
   return fit(
-    <output data-basalt-chart-state={kind} className={stateClass} style={style}>
+    <output data-basalt-chart-state={kind} className={stateClass} style={style} {...name}>
       {body}
     </output>,
   )

package/src/charts/types.ts

@@ -24,35 +24,44 @@ export type ChartSeries<T> = {
    * series whose `getValue` is always `null` is a legend-only entry (a zone or reference key). */
   getValue: (d: T) => number | null
   /** The legend swatch shape. Default: the kind's own mark (`line` in `Lines`, `bar` in `Bars`). */
-  mark?: 'line' | 'bar' | 'area'
+  mark?: 'line' | 'bar' | 'area' | undefined
   /** Default `'solid'`; `'dashed'` is `VX.dashArray` on the line, the legend and the tooltip. */
-  dash?: 'solid' | 'dashed'
+  dash?: 'solid' | 'dashed' | undefined
   /** Interpolation between points. Default `'monotone'`. A piecewise-constant quantity (a price
    * tier, a config value) is a step: a smoothed curve draws values that never existed. */
-  curve?: CurveName
-  strokeWidth?: number
+  curve?: CurveName | undefined
+  strokeWidth?: number | undefined
   /** Dims the plotted stroke (a faint companion line). Strokes only. */
-  strokeOpacity?: number
+  strokeOpacity?: number | undefined
   /** Bars and areas. */
-  fillOpacity?: number
-  /** `Lines`: a soft gradient fill under the line — `true` in the series color, or a color ref. */
-  area?: boolean | string
+  fillOpacity?: number | undefined
+  /** `Lines`: a soft gradient fill under the line — `true` in the series color, a color ref, or
+   * `'zones'`: a vertical gradient coloured by the chart's `zones` on this series' axis, hard stops
+   * at the zone boundaries (no zone in reach: the series color). Linear axes only. */
+  area?: boolean | 'zones' | (string & {}) | undefined
   /** Which y axis the series is measured against. `'right'` needs the chart's `y2`. */
-  axis?: 'left' | 'right'
+  axis?: 'left' | 'right' | undefined
   /** Legend grouping: series → overlay → reference. Default `'series'`. */
-  role?: 'series' | 'overlay' | 'reference'
+  role?: 'series' | 'overlay' | 'reference' | undefined
   /** `false` keeps it out of the legend (a companion line folded under `parent`). Default `true`. */
-  legend?: boolean
+  legend?: boolean | undefined
   /** `false` draws and legends it but never lists it as a tooltip row. Default `true`. */
-  tooltip?: boolean
+  tooltip?: boolean | undefined
   /** A companion (an MA line) names its parent, so a legend toggle and hover keep the pair. */
-  parent?: string
+  parent?: string | undefined
   /** A short qualifier after the label in the legend and the tooltip row, in muted text. */
-  note?: string
+  note?: string | undefined
   /** Per-series tooltip value format; receives the datum so a row can read more than the value. */
-  formatValue?: (v: number, d: T) => string
+  formatValue?: ((v: number, d: T) => string) | undefined
   /** A marker at a point (a PR star, a status dot); `null` for none. */
-  getMarker?: (d: T) => { color?: string; r?: number; fillOpacity?: number; ring?: boolean } | null
+  getMarker?:
+    | ((d: T) => {
+        color?: string | undefined
+        r?: number | undefined
+        fillOpacity?: number | undefined
+        ring?: boolean | undefined
+      } | null)
+    | undefined
 }
 
 /** One y axis. */
@@ -66,23 +75,24 @@ export type AxisConfig<T> = {
     | readonly [number, number]
     | 'auto'
     | ((data: readonly T[], visible: readonly ChartSeries<T>[]) => readonly [number, number])
+    | undefined
   /** When `'auto'`: the raw upper bound is at least this; padding applies after. */
-  autoMaxFloor?: number
+  autoMaxFloor?: number | undefined
   /** When `'auto'`: the lower bound is at most this. Default `0` (a zero baseline); `Infinity` pads
    * down from the data minimum instead. Ignored on a log axis. */
-  autoMinCeil?: number
+  autoMinCeil?: number | undefined
   /** When `'auto'`: padding multiplier away from the data. Default `1.1`. */
-  autoPad?: number
+  autoPad?: number | undefined
   /** A tick count, or the exact tick values. Default: one per ~48px of plot height, ≤ 5. */
-  ticks?: number | readonly number[]
+  ticks?: number | readonly number[] | undefined
   /** Tick and tooltip formatter. Default: compact numbers (`12.5k`). */
-  format?: (v: number) => string
+  format?: ((v: number) => string) | undefined
   /** Horizontal grid rules. Default: on for `y`, off for `y2`. */
-  grid?: boolean
+  grid?: boolean | undefined
   /** Round the domain outward to nice ticks. Default `false` (a fixed domain stays fixed). */
-  nice?: boolean
+  nice?: boolean | undefined
   /** Default `'linear'`. A log axis floors at the smallest positive visible value. */
-  scale?: 'linear' | 'log'
+  scale?: 'linear' | 'log' | undefined
 }
 
 /** A horizontal band on one y axis. `±Infinity` reaches the plot edge. */
@@ -90,7 +100,7 @@ export type ZoneSpec = {
   from: number
   to: number
   fill: string
-  axisSide?: 'left' | 'right'
+  axisSide?: 'left' | 'right' | undefined
 }
 
 /**
@@ -99,18 +109,18 @@ export type ZoneSpec = {
  * from one hour to another, both hours included).
  */
 export type XZoneSpec<X extends ChartX = ChartX> = {
-  from?: X
-  to?: X
+  from?: X | undefined
+  to?: X | undefined
   fill: string
-  align?: 'center' | 'edge'
+  align?: 'center' | 'edge' | undefined
 }
 
 /** A horizontal reference line — annotation only, no domain role beyond staying inside the plot. */
 export type RefLine = {
   value: number
   color: string
-  dashed?: boolean
-  axis?: 'left' | 'right'
+  dashed?: boolean | undefined
+  axis?: 'left' | 'right' | undefined
 }
 
 /** A fill between the line and a value, on one side of it, tracking the line. */
@@ -134,43 +144,46 @@ export type ChartTooltipRow = {
 export type ChartTooltipConfig<T, X extends ChartX = ChartX> = {
   /** The tooltip title. Default: the x value through `formatX`'s long form (a date reads
    * `Mon Sep 1 2026`). */
-  formatHeader?: (x: X, d: T) => string
+  formatHeader?: ((x: X, d: T) => string) | undefined
   /** Rows after the per-series rows (a total, a zone badge, a context line). `visible`/`hidden` are
    * the legend's split, so a row never names a series the plot no longer draws. */
-  rows?: (
-    d: T,
-    ctx: { visible: readonly ChartSeries<T>[]; hidden: readonly ChartSeries<T>[] },
-  ) => readonly ChartTooltipRow[]
+  rows?:
+    | ((
+        d: T,
+        ctx: { visible: readonly ChartSeries<T>[]; hidden: readonly ChartSeries<T>[] },
+      ) => readonly ChartTooltipRow[])
+    | undefined
   /** Show this chart's tooltip while it FOLLOWS a sibling's cursor. Default `false`: only the chart
    * under the pointer or keyboard focus shows a tooltip and a live region. */
-  onFollow?: boolean
+  onFollow?: boolean | undefined
 }
 
 export type ChartLegendConfig = {
   /** Default `'bottom'`. `'header'` draws the legend at the top of the chart body, spaced as the
    * enclosing `ChartCard`'s header legend row (in the chart's own markup, so it is in the server
    * HTML and the header never grows); outside a card it is `'top'`. */
-  placement?: 'top' | 'bottom' | 'header'
+  placement?: 'top' | 'bottom' | 'header' | undefined
   /** Visually separate roles: series | overlay | reference. */
-  groups?: boolean
+  groups?: boolean | undefined
   /** Clicking an entry hides that series. Default: on whenever there are two or more entries. */
-  toggle?: boolean
+  toggle?: boolean | undefined
 }
 
 /** A height per container class, `base` below `regular`. A plain number is fixed. */
 export type ResponsiveChartHeight = {
   base: number
-  regular?: number
-  wide?: number
+  regular?: number | undefined
+  wide?: number | undefined
 }
 
 /** The three "nothing to draw" states, pending → error → empty. */
 export type ChartState = {
-  pending?: boolean
+  pending?: boolean | undefined
   /** Truthy = the query failed; an `Error`'s message is the label. */
   error?: unknown
-  /** `true`, or the empty label itself. */
-  empty?: boolean | string
+  /** `true`, or the empty label itself. The label is the one way to say WHY (`'No runs match the
+   * filter'` vs `'No runs yet'`): § 9 fixes the state shape, so there is no reason field. */
+  empty?: boolean | string | undefined
 }
 
 /** A row of `plot.rows(key)`: one per datum, `y: null` kept as a gap. */
@@ -214,27 +227,27 @@ export type CartesianChartProps<T, X extends ChartX = ChartX> = BasaltProps & {
   series: readonly ChartSeries<T>[]
   /** The plot's marks. Draw `plot.rows(key)` / `plot.visible`, never `series` directly. */
   marks: (plot: PlotContext<T, X>) => ChartMarks
-  y?: AxisConfig<T>
+  y?: AxisConfig<T> | undefined
   /** A right axis; series with `axis: 'right'` and marks bound to `plot.y2` read it. */
-  y2?: AxisConfig<T>
+  y2?: AxisConfig<T> | undefined
   /** A tick count, or the exact x tick values. Default: by container class. */
-  xTicks?: number | readonly X[]
+  xTicks?: number | readonly X[] | undefined
   /** Tick label for an x value. Default: `DD.MM` for dates, compact numbers, strings verbatim. */
-  formatX?: (x: X) => string
-  zones?: readonly ZoneSpec[]
-  xZones?: readonly XZoneSpec<X>[]
-  refLines?: readonly RefLine[]
+  formatX?: ((x: X) => string) | undefined
+  zones?: readonly ZoneSpec[] | undefined
+  xZones?: readonly XZoneSpec<X>[] | undefined
+  refLines?: readonly RefLine[] | undefined
   /** `false` hides the legend. */
-  legend?: ChartLegendConfig | false
+  legend?: ChartLegendConfig | false | undefined
   /** Default: the height law (measured width × class ratio, 160–420px, ≤ 45vh on touch). */
-  height?: number | ResponsiveChartHeight
-  state?: ChartState
+  height?: number | ResponsiveChartHeight | undefined
+  state?: ChartState | undefined
   /** Joins a named cursor group instead of the page-shared default. */
-  cursorGroup?: string
+  cursorGroup?: string | undefined
   /** Default `'nearest'`. `'leading'` for a series keyed by a bucket's leading edge (a weekly
    * value keyed by its Monday). */
-  cursorResolution?: CursorResolution
-  tooltip?: ChartTooltipConfig<T, X> | false
+  cursorResolution?: CursorResolution | undefined
+  tooltip?: ChartTooltipConfig<T, X> | false | undefined
 }
 
 /** The x channel of a `plot.rows()` row, as an accessor (a field name does not type-check against a

package/src/cli/doctor.ts

@@ -395,7 +395,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
       ],
       [
         'dropped-subpaths: no import of a basalt-ui subpath the install lacks',
-        droppedSubpathsCheck(cwd, cfg, install),
+        droppedSubpathsCheck(appDir, cfg, install),
       ],
       [
         'app-wiring: the entry mounts BasaltProvider and the router tree is generated',
@@ -404,7 +404,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
       ['exact-peers: installed exact-pinned peers match basalt-ui', exactPeersCheck(cwd, install)],
       [
         'subpath-peers: every imported basalt-ui subpath has its required peers installed',
-        subpathPeersCheck(cwd, cfg, install),
+        subpathPeersCheck(appDir, cfg, install),
       ],
       [
         'config-keys: the basalt config block sets only keys basalt-ui reads',

package/src/dashboard/index.ts

@@ -1,7 +1,12 @@
 export { WidgetHeader } from './widget-header'
 export { DeltaBadge } from './delta-badge'
 export { Section } from './section'
-export { StatCard, type StatCardBreakdownRow, type StatCardTone } from './stat-card'
+export {
+  StatCard,
+  type StatCardBreakdownRow,
+  type StatCardSparklineSize,
+  type StatCardTone,
+} from './stat-card'
 export { StatGroup } from './stat-group'
 export { EmptyState } from './empty-state'
 export { SettingsSection, SettingsRow, DangerZone } from './settings-section'

package/src/dashboard/stat-card.tsx

@@ -23,7 +23,9 @@
  * here. Pass your own sparkline at the call site (basalt ships no `Sparkline` kind in 2.0.0).
  *
  * `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.
+ * rendered under the header rather than over it — the title row is chrome and must not flicker. The
+ * same query also reaches a render-prop `sparkline` as `size.state`, so `<Sparkline {...size} />`
+ * shows its sized pending / error placeholder with no hand-rolled `'—'`.
  *
  * `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
@@ -106,6 +108,7 @@ 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 { assertQueryStateLike } from '../common/query-state-like'
 import classes from './stat-card.module.css'
 
 /**
@@ -160,6 +163,13 @@ const SPARKLINE_RIGHT_HEIGHT = 26
 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 }
 }
 
 /**
@@ -199,6 +209,18 @@ function useSlotWidth(active: boolean): {
   }
 }
 
+/** The `query` as a sparkline state, by the same precedence as {@link QueryState}: an error with no
+ * data is an error, no data and not idle is pending, anything else draws. */
+function sparklineState(
+  query: QueryStateLike<unknown> | undefined,
+): StatCardSparklineSize['state'] {
+  if (query === undefined) return undefined
+  assertQueryStateLike('StatCard', query)
+  if (query.data !== undefined) return undefined
+  if (query.isError) return { error: query.error ?? true }
+  return query.fetchStatus === 'idle' ? undefined : { pending: true }
+}
+
 /** The rail's width, in px. Wide enough to read as a deliberate mark at a glance, narrow enough
  * that it cannot be mistaken for the card's own edge. */
 const TONE_RAIL_WIDTH = 3
@@ -270,8 +292,12 @@ export type StatCardProps = BasaltProps &
      * 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;
@@ -313,7 +339,12 @@ export function StatCard({
   const bleeds = sparklinePlacement === 'bleed'
   // Only a render prop needs a measurement; a plain node sizes itself.
   const { ref: slotRef, width: slotWidth } = useSlotWidth(isRender)
-  const measured: StatCardSparklineSize = { width: slotWidth, height: SPARKLINE_RIGHT_HEIGHT }
+  const state = sparklineState(query)
+  const measured: StatCardSparklineSize = {
+    width: slotWidth,
+    height: SPARKLINE_RIGHT_HEIGHT,
+    ...(state !== undefined && { state }),
+  }
 
   // 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.

package/src/index.ts

@@ -40,6 +40,7 @@ export {
   Section,
   StatCard,
   type StatCardBreakdownRow,
+  type StatCardSparklineSize,
   type StatCardTone,
   StatGroup,
   EmptyState,