basalt-ui 2.2.0 → 2.3.0

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

@@ -29,18 +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
+  state?: ChartState | undefined
 }
 
 type Point = { i: number; v: number | null }

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'
 
 /**
@@ -249,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
@@ -548,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,

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,44 +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. 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
+  empty?: boolean | string | undefined
 }
 
 /** A row of `plot.rows(key)`: one per datum, `y: null` kept as a gap. */
@@ -215,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