basalt-ui 1.27.0 → 1.29.0

package/src/charts/kinds/MirroredBars.tsx

@@ -2,6 +2,8 @@ import { Group } from '@visx/group'
 import { scaleLinear } from '@visx/scale'
 import { memo, useMemo } from 'react'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import { VX, alpha } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import type { CursorResolution } from '../cursor/resolve'
@@ -19,6 +21,7 @@ import {
 import { Crosshair } from '../primitives/Crosshair'
 import { HatchPattern, hatchFill, hatchSizeFor } from '../primitives/HatchPattern'
 import { HoverOverlay } from '../primitives/HoverOverlay'
+import type { ChartState } from '../primitives/ChartPending'
 import { deriveTooltipRows } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { fmtAxisDate } from '../utils/format'
@@ -47,7 +50,7 @@ export type MirroredBarPane = {
   format: (v: number) => string
 }
 
-export type MirroredBarsProps<T> = {
+export type MirroredBarsProps<T> = BasaltProps & {
   data: readonly T[]
   chartId: string
   /** Extracts the x-domain key — a slot start, hence the `'leading'` cursor default. */
@@ -92,6 +95,9 @@ export type MirroredBarsProps<T> = {
   margin?: Partial<ChartMargin>
   ariaLabel?: string
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 const DEFAULT_UP_FRACTION = 0.35
@@ -137,7 +143,12 @@ function assertPaneKey<T>(
  * `useBandPlot` choreography instead, which is where the sharing actually belongs.
  */
 function MirroredBarsInner<T>(props: MirroredBarsProps<T>) {
-  const { series, chartId, height, fill, legend, ariaLabel, isPending } = props
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('MirroredBars', props, ['data', 'getX', 'series', 'up', 'down'])
+  const { series, chartId, height, fill, legend, ariaLabel, isPending, state, className, style } =
+    props
 
   return (
     <ChartFrame
@@ -147,6 +158,9 @@ function MirroredBarsInner<T>(props: MirroredBarsProps<T>) {
       {...(fill !== undefined && { fill })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <MirroredBarsPlot {...props} plot={plot} />}
@@ -488,4 +502,8 @@ function usePaneMax<T>(
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot kind is wrapped in
  * `React.memo` to retain the auto-memoization it had as source (parity with `DualPanel`).
  */
-export const MirroredBars = memo(MirroredBarsInner) as typeof MirroredBarsInner
+const MirroredBarsMemo = memo(MirroredBarsInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+MirroredBarsMemo.displayName = 'MirroredBars'
+export const MirroredBars = MirroredBarsMemo as typeof MirroredBarsInner

package/src/charts/kinds/MultiLine.tsx

@@ -1,17 +1,19 @@
-import { curveMonotoneX } from '@visx/curve'
 import { LinePath } from '@visx/shape'
 import { memo, useCallback, useMemo } from 'react'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
-import { LINE_OVERLAY_STROKE_WIDTH } from '../series'
+import type { ChartState } from '../primitives/ChartPending'
+import { curveFor, definedOn, LINE_OVERLAY_STROKE_WIDTH, toPlotPoint } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { VX } from '../../tokens'
 
-export type MultiLineProps<T> = {
+export type MultiLineProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
   height?: number
@@ -42,6 +44,9 @@ export type MultiLineProps<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 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
+   * see `CartesianChartProps.xLabelRotate`. */
+  xLabelRotate?: 0 | 45 | 90
   /**
    * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
    * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
@@ -60,6 +65,9 @@ export type MultiLineProps<T> = {
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 const STAR_R = 6
@@ -76,16 +84,17 @@ function starPath(cx: number, cy: number, r: number): string {
   return `M${pts.join('L')}Z`
 }
 
-type LinePt<T> = { __d: T; __y: number }
+type LinePt<T> = { __d: T; __y: number | null }
 
-/** Per-series valid points (null-value gaps dropped). Reused by the lines and the markers. */
+/**
+ * Every row, in x order, with `__y: null` where the series reports no value. The null row STAYS in
+ * the array: `ChartSeries.getValue` documents null as a line GAP, and dropping the row instead
+ * makes `LinePath` join straight across a coverage hole — drawing a measurement that was never
+ * taken. `defined` on the consuming shape is what turns it back into a gap. Reused by the lines
+ * and the markers.
+ */
 function seriesPoints<T>(series: ChartSeries<T>, data: readonly T[]): LinePt<T>[] {
-  const pts: LinePt<T>[] = []
-  for (const d of data) {
-    const v = series.getValue(d)
-    if (v !== null && v !== undefined && !Number.isNaN(v)) pts.push({ __d: d, __y: v })
-  }
-  return pts
+  return data.map((d) => ({ __d: d, __y: toPlotPoint(series.getValue(d)) }))
 }
 
 /**
@@ -99,9 +108,14 @@ function seriesPoints<T>(series: ChartSeries<T>, data: readonly T[]): LinePt<T>[
  * plotted lines, the legend, and the tooltip rows.
  *
  * X-axis is built from the full `data` array so the calendar is preserved even when a series
- * has nulls; each series line skips null points (creating visual gaps).
+ * has nulls; each series line BREAKS at a null point, leaving a real gap rather than interpolating
+ * across it.
  */
 function MultiLineInner<T>(props: MultiLineProps<T>) {
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('MultiLine', props, ['data', 'getX', 'series'])
   const {
     data,
     chartId,
@@ -115,6 +129,7 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
     xTicks,
     xTickValues,
     formatX,
+    xLabelRotate,
     cursorResolution,
     tooltip,
     markerShape = 'circle',
@@ -122,6 +137,9 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
     legend,
     ariaLabel,
     isPending,
+    state,
+    className,
+    style,
   } = props
 
   // Default line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied once
@@ -145,12 +163,16 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
       {...(xTicks !== undefined && { xTicks })}
       {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
+      {...(xLabelRotate !== undefined && { xLabelRotate })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(tooltip !== undefined && { tooltip })}
       {...(height !== undefined && { height })}
       {...(legend !== undefined && { legend })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(ctx: PlotContext<T>) => <MultiLineMarks getX={getX} markerShape={markerShape} ctx={ctx} />}
     </CartesianChart>
@@ -209,10 +231,16 @@ function MultiLineMarks<T>({
         const op = dimOpacity(s)
         const markers: ReactNode[] = []
         for (const p of pointsBySeries.get(s.key) ?? []) {
+          // A null point is an absence: no dot, no marker — the same claim the line's `defined`
+          // makes by breaking there.
+          if (p.__y === null) continue
           const m = getMarker(p.__d)
           if (m === null) continue
           const cx = xScale(getX(p.__d)) ?? 0
           const cy = scale(p.__y)
+          // A non-positive value on a log axis (or any input a scale can't place) maps to NaN —
+          // skip the marker rather than paint one at `cy="NaN"`.
+          if (!Number.isFinite(cy)) continue
           const color = m.color ?? s.color
           const r = m.r ?? (markerShape === 'star' ? STAR_R : VX.dotR)
           const ring = m.ring ?? true
@@ -247,20 +275,31 @@ function MultiLineMarks<T>({
   return (
     <>
       {visible.map((s) => {
-        const valid = pointsBySeries.get(s.key) ?? []
-        if (valid.length === 0) return null
+        const pts = pointsBySeries.get(s.key) ?? []
+        // A series that measured nothing (the legend-only `getValue: () => null` idiom) draws no
+        // path at all, rather than an empty one.
+        if (!pts.some((p) => p.__y !== null)) return null
         const scale = scaleFor(s)
         return (
           <LinePath<LinePt<T>>
             key={`line-${s.key}`}
-            data={valid}
+            data={pts}
             x={(p) => xScale(getX(p.__d)) ?? 0}
-            y={(p) => scale(p.__y)}
+            // Never reached with a null `__y`: d3's line generator calls the position accessors
+            // only for points `defined` accepted. The `NaN` floor is a type-level one, and it can
+            // never paint at zero the way a `?? 0` would.
+            y={(p) => scale(p.__y ?? NaN)}
+            // Two absences, one guard. A null value is a documented GAP (`ChartSeries.getValue`),
+            // and a non-positive value on a log axis maps to NaN via `scale(p.__y)` — `defined`
+            // breaks the line at both instead of interpolating across the hole (a coverage hole
+            // reading as a measured straight line) or emitting a NaN path command, which per SVG
+            // error handling blanks the ENTIRE polyline from that point on.
+            defined={definedOn(scale)}
             stroke={s.color}
             strokeWidth={s.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
             strokeDasharray={s.dash === 'dashed' ? VX.dashArray : undefined}
             strokeOpacity={dimOpacity(s) * (s.strokeOpacity ?? 1)}
-            curve={curveMonotoneX}
+            curve={curveFor(s.curve)}
           />
         )
       })}
@@ -274,4 +313,8 @@ function MultiLineMarks<T>({
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot MultiLine kind is
  * wrapped in `React.memo` to retain the auto-memoization it had as source (parity with ZonedLine).
  */
-export const MultiLine = memo(MultiLineInner) as typeof MultiLineInner
+const MultiLineMemo = memo(MultiLineInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+MultiLineMemo.displayName = 'MultiLine'
+export const MultiLine = MultiLineMemo as typeof MultiLineInner

package/src/charts/kinds/StackedArea.tsx

@@ -1,12 +1,16 @@
-import { curveMonotoneX } from '@visx/curve'
 import { AreaStack } from '@visx/shape'
 import { memo, useCallback, useMemo } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, PlotContext } from '../primitives/CartesianChart'
+import type { ChartState } from '../primitives/ChartPending'
+import { curveFor } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
+import { isDev } from '../../common/is-dev'
 
-export type StackedAreaProps<T> = {
+export type StackedAreaProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
   height?: number
@@ -18,8 +22,9 @@ export type StackedAreaProps<T> = {
   /** Axis config for ticks/format/grid. `domain` defaults to the summed per-point stack total
    * (padded ×1.1, or `autoMaxFloor` if higher) rather than a per-series max — the seam a stacked
    * chart needs, since the plotted quantity is the cumulative band top, not any one series' own
-   * value. Pass a fixed tuple or your own function to override. */
-  y?: AxisConfig<T>
+   * value. Pass a fixed tuple or your own function to override. No `scale` — stacking sums bar
+   * heights directly and a log axis has no additive zero to sum from. */
+  y?: Omit<AxisConfig<T>, 'scale'>
   /** Exact number of x ticks. Default: as many as fit. Ignored when `xTickValues` is set. */
   xTicks?: number
   /** Which domain keys get a tick, from the full key list and the resolved plot width. Takes
@@ -28,6 +33,9 @@ export type StackedAreaProps<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 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
+   * see `CartesianChartProps.xLabelRotate`. */
+  xLabelRotate?: 0 | 45 | 90
   /**
    * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
    * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
@@ -41,12 +49,32 @@ export type StackedAreaProps<T> = {
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
+}
+
+/**
+ * A stack is only as dense as its sparsest band. A band's value is only meaningful as part of a
+ * cumulative total, so a row where ANY visible band reports `null` has no total — every band gaps
+ * across it. Reading the missing band as `0` instead would be a positive claim the quantity was
+ * measured at zero, which is exactly the absence-as-data lie `ChartSeries.getValue`'s null
+ * contract exists to prevent.
+ */
+function rowIsDense<T>(d: T, bands: readonly ChartSeries<T>[]): boolean {
+  return bands.every((s) => s.getValue(d) !== null)
 }
 
 /**
  * Multi-series stacked-area chart with an optional derived legend (default on) and legend-hover
  * dimming. Each band's fillOpacity is dimmed when a different key is highlighted via the legend.
  *
+ * **A stack is only as dense as its sparsest series.** A row where any VISIBLE band is null is
+ * dropped from the stack entirely — the bands break across that x, the crosshair reports no
+ * cumulative value there, and the axis domain ignores it. Toggling the sparse band off in the
+ * legend closes the gap, because density is measured against the visible set. A chart that needs
+ * a null band to read as zero must say so in its own `getValue`.
+ *
  * Composes `CartesianChart` (`docs/CHARTS-SPEC.md` §2) — margin, scale, grid, axes, cursor, and
  * tooltip are the primitive's job. This file draws only the `AreaStack` bands.
  *
@@ -57,6 +85,10 @@ export type StackedAreaProps<T> = {
  * to restore the original bottom-to-top stacking order for `AreaStack`'s `keys`.
  */
 function StackedAreaInner<T>(props: StackedAreaProps<T>) {
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('StackedArea', props, ['data', 'getX', 'series'])
   const {
     data,
     chartId,
@@ -66,13 +98,26 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
     xTicks,
     xTickValues,
     formatX,
+    xLabelRotate,
     cursorResolution,
     height,
     legend,
     ariaLabel,
     isPending,
+    state,
+    className,
+    style,
   } = props
 
+  // The stack sums band heights via `getValue` totals directly — a log axis has no additive zero
+  // to sum from (`docs/CHARTS-SPEC.md`'s null-gap + log contract, mirrored from `Bars`' own guard).
+  if (isDev() && (y as { scale?: string } | undefined)?.scale === 'log') {
+    throw new Error(
+      'StackedArea: cannot use a log axis (y.scale: "log") — the stack sums band heights, ' +
+        'and a log axis has no additive zero to sum from.',
+    )
+  }
+
   // The plotted quantity is the CUMULATIVE stack top, not any one series' value — the built-in
   // 'auto' domain (per-series max) would clip a multi-band stack. Skipped when the caller already
   // supplies a fixed tuple or their own domain function.
@@ -87,6 +132,8 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
       domain: (rows: readonly T[], visible: readonly ChartSeries<T>[]) => {
         let maxTotal = 0
         for (const d of rows) {
+          // A sparse row is not drawn, so it cannot set the axis top either.
+          if (!rowIsDense(d, visible)) continue
           let total = 0
           for (const s of visible) total += s.getValue(d) ?? 0
           if (total > maxTotal) maxTotal = total
@@ -100,6 +147,10 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
   // tracking — not at the band's own raw value, which sits somewhere inside the fill.
   const stackedCursorValue = useCallback(
     (d: T, s: ChartSeries<T>, visible: readonly ChartSeries<T>[]): number | null => {
+      // No total on a sparse row — the bands gap there, so a dot would sit on nothing. The
+      // per-band tooltip rows keep skipping their own nulls (`deriveTooltipRows`), so a row the
+      // stack cannot draw never contributes a value anywhere.
+      if (!rowIsDense(d, visible)) return null
       let total = 0
       // `visible` arrives top-to-bottom (the `series.toReversed()` handed to the primitive);
       // stacking accumulates bottom-up.
@@ -128,11 +179,15 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
       {...(xTicks !== undefined && { xTicks })}
       {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
+      {...(xLabelRotate !== undefined && { xLabelRotate })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(height !== undefined && { height })}
       {...(legend !== undefined && { legend })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(ctx) => <StackedAreaMarks getX={getX} ctx={ctx} />}
     </CartesianChart>
@@ -159,6 +214,14 @@ function StackedAreaMarks<T>({ getX, ctx }: { getX: (d: T) => string; ctx: PlotC
   // `AreaStack` wants a mutable array; `ctx.data` is readonly. Copy once per data change.
   const rows = useMemo(() => [...ctx.data], [ctx.data])
 
+  // `AreaStack` draws every band from ONE curve — the bands share their boundaries, so two curves
+  // would leave gaps and overlaps between them. `visible` is in `reversedSeries` order (top band
+  // first), so this resolves to the TOPMOST VISIBLE band that declares a `curve` — the last such
+  // entry in the caller's own `series` array. A band declaring none is skipped rather than read as
+  // the monotone default, and a HIDDEN one is never consulted, so a legend toggle can hand the
+  // stack to the next declarer down. `series.curve.test.tsx` pins all four halves of that.
+  const curve = curveFor(visible.find((s) => s.curve !== undefined)?.curve)
+
   return (
     <AreaStack<T, string>
       data={rows}
@@ -166,8 +229,12 @@ function StackedAreaMarks<T>({ getX, ctx }: { getX: (d: T) => string; ctx: PlotC
       x={(d) => xScale(getX(d.data)) ?? 0}
       y0={(d) => yScale(d[0]) ?? 0}
       y1={(d) => yScale(d[1]) ?? 0}
+      // d3's stack layout needs a number per cell, so a null still enters the layout as 0 — but
+      // `defined` keeps that cell out of every band's PATH, so the zero is never drawn. Without it
+      // a missing band reads as a measured zero and the bands above it slide down onto it.
       value={(d, key) => seriesByKey.get(key)?.getValue(d) ?? 0}
-      curve={curveMonotoneX}
+      defined={(d) => rowIsDense(d.data, visible)}
+      curve={curve}
     >
       {({ stacks, path }) =>
         stacks.map((stack) => (
@@ -189,4 +256,8 @@ function StackedAreaMarks<T>({ getX, ctx }: { getX: (d: T) => string; ctx: PlotC
  * hot stacked-area kind in `React.memo` to retain the auto-memoization it had as source
  * (parity with ZonedLine / Bars / MultiLine).
  */
-export const StackedArea = memo(StackedAreaInner) as typeof StackedAreaInner
+const StackedAreaMemo = memo(StackedAreaInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+StackedAreaMemo.displayName = 'StackedArea'
+export const StackedArea = StackedAreaMemo as typeof StackedAreaInner

package/src/charts/kinds/ZonedLine.tsx

@@ -1,20 +1,19 @@
-import { curveMonotoneX } from '@visx/curve'
 import { AreaClosed, LinePath } from '@visx/shape'
 import { Threshold } from '@visx/threshold'
 import { memo, useMemo } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { AreaGradient, areaFillUrl } from '../primitives/AreaGradient'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
-import { LINE_OVERLAY_STROKE_WIDTH } from '../series'
+import type { ChartState } from '../primitives/ChartPending'
+import { curveFor, definedOn, LINE_OVERLAY_STROKE_WIDTH, toPlotPoint } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { VX } from '../../tokens'
 
-/** @deprecated Use ZoneSpec from primitives/ZoneRects. Kept as an alias for back-compat. */
-export type ZonedLineZone = ZoneSpec
-
 /** Semi-transparent fill above (or below) a threshold value, tracking the line. */
 export type ZonedLineThreshold = {
   value: number
@@ -30,7 +29,7 @@ export type ZonedLineRefLine = {
   dashed?: boolean
 }
 
-export type ZonedLineProps<T> = {
+export type ZonedLineProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
   height?: number
@@ -44,7 +43,7 @@ export type ZonedLineProps<T> = {
   /** Y-axis. Collapses the old `yDomain` / `yAutoMaxFloor` / `yAutoMinCeil` / `yAutoPad` /
    * `numTicksY` / `formatYTick` prop soup into one object. */
   y?: AxisConfig<T>
-  zones?: ZonedLineZone[]
+  zones?: ZoneSpec[]
   /** Vertical x-range overlays (time windows), rendered behind the line. Bounds are `getX`
    * domain keys. */
   xZones?: XZoneSpec[]
@@ -58,6 +57,9 @@ export type ZonedLineProps<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 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
+   * see `CartesianChartProps.xLabelRotate`. */
+  xLabelRotate?: 0 | 45 | 90
   /**
    * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
    * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
@@ -81,21 +83,22 @@ export type ZonedLineProps<T> = {
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
-type Valid<T> = T & { __y: number }
+type Pt<T> = T & { __y: number | null }
 
-/** The primary (and only) series' valid points — null values are dropped, creating line gaps. */
-function validPoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]): Valid<T>[] {
+/**
+ * Every row, in x order, with `__y: null` where the series reports no value. The null row STAYS in
+ * the array — see `MultiLine`'s `seriesPoints`: dropping it makes `LinePath`/`AreaClosed`/
+ * `Threshold` join straight across a coverage hole, drawing a measurement that was never taken.
+ * The shared `defined` guard below is what turns it back into a gap.
+ */
+function linePoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]): Pt<T>[] {
   if (!series) return []
-  const out: Valid<T>[] = []
-  for (const d of data) {
-    const y = series.getValue(d)
-    if (y !== null && y !== undefined && !Number.isNaN(y)) {
-      out.push(Object.assign({}, d, { __y: y }) as Valid<T>)
-    }
-  }
-  return out
+  return data.map((d) => Object.assign({}, d, { __y: toPlotPoint(series.getValue(d)) }) as Pt<T>)
 }
 
 /**
@@ -107,11 +110,15 @@ function validPoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]):
  * and the derived tooltip — this kind draws ONLY the marks (thresholds, area fill, and the line).
  * Single-series, so the legend is optional in practice but present by default.
  *
- * X-axis is built from the full `data` array so the calendar is preserved even
- * when the series has nulls; the line itself skips null points (creating
- * visual gaps).
+ * X-axis is built from the full `data` array so the calendar is preserved even when the series has
+ * nulls; the line, the area fill and the threshold fills all BREAK at a null point, leaving a real
+ * gap rather than interpolating across it.
  */
 function ZonedLineInner<T>(props: ZonedLineProps<T>) {
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('ZonedLine', props, ['data', 'getX', 'series'])
   const {
     data,
     chartId,
@@ -125,6 +132,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
     xTicks,
     xTickValues,
     formatX,
+    xLabelRotate,
     cursorResolution,
     tooltip,
     areaFill,
@@ -132,6 +140,9 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
     legend,
     ariaLabel,
     isPending,
+    state,
+    className,
+    style,
   } = props
 
   // Default the line overlay to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied
@@ -158,12 +169,16 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
       {...(xTicks !== undefined && { xTicks })}
       {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
+      {...(xLabelRotate !== undefined && { xLabelRotate })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(tooltip !== undefined && { tooltip })}
       {...(height !== undefined && { height })}
       {...(legend !== undefined && { legend })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(ctx: PlotContext<T>) => (
         <ZonedLineMarks
@@ -197,7 +212,22 @@ function ZonedLineMarks<T>({
   const primary = visible[0]
   // Memoized: the shared cursor re-renders every chart on every pointer frame, and this both
   // walks the full series and clones an object per point.
-  const valid = useMemo(() => validPoints(primary, data), [primary, data])
+  const pts = useMemo(() => linePoints(primary, data), [primary, data])
+
+  // ONE guard for all three shapes below, covering two absences. A null value is a documented GAP
+  // (`ChartSeries.getValue`), and a non-positive value on a log axis maps to NaN via `yScale` —
+  // without `defined` the first is drawn as an interpolated straight line across a coverage hole
+  // and the second emits a NaN path command, which per SVG error handling blanks the ENTIRE path
+  // from that point on.
+  const defined = definedOn(yScale)
+  // ONE curve for all three shapes: the threshold band, the area fill and the line are the SAME
+  // series drawn three ways, so a step line over a monotone fill would be two different readings
+  // of one measurement.
+  const curve = curveFor(primary?.curve)
+  // Never reached with a null `__y`: d3's line/area generators call the position accessors only
+  // for points `defined` accepted. The `NaN` floor is a type-level one, and it can never paint at
+  // zero the way a `?? 0` would.
+  const yOf = (d: Pt<T>) => yScale(d.__y ?? NaN)
 
   // Area is opt-in: pass a color token to get a cohesive single-hue fill under the line.
   // (A neutral fill under the neutral line just reads as grey haze, so there is no default-on.)
@@ -208,16 +238,17 @@ function ZonedLineMarks<T>({
   return (
     <>
       {thresholds.map((t, i) => (
-        <Threshold<Valid<T>>
+        <Threshold<Pt<T>>
           key={`thr-${i}`}
           id={`${chartId}-thr-${i}`}
-          data={valid}
+          data={pts}
+          defined={defined}
           x={(d) => xScale(getX(d)) ?? 0}
           y0={() => yScale(t.value)}
-          y1={(d) => yScale(d.__y)}
+          y1={yOf}
           clipAboveTo={0}
           clipBelowTo={yMax}
-          curve={curveMonotoneX}
+          curve={curve}
           belowAreaProps={{ fill: t.side === 'above' ? t.fill : 'transparent' }}
           aboveAreaProps={{ fill: t.side === 'below' ? t.fill : 'transparent' }}
         />
@@ -228,27 +259,29 @@ function ZonedLineMarks<T>({
           <defs>
             <AreaGradient id={areaId} color={areaColor} />
           </defs>
-          <AreaClosed<Valid<T>>
-            data={valid}
+          <AreaClosed<Pt<T>>
+            data={pts}
+            defined={defined}
             x={(d) => xScale(getX(d)) ?? 0}
-            y={(d) => yScale(d.__y)}
+            y={yOf}
             yScale={yScale}
-            curve={curveMonotoneX}
+            curve={curve}
             fill={areaFillUrl(areaId)}
           />
         </>
       )}
 
       {primary && (
-        <LinePath<Valid<T>>
-          data={valid}
+        <LinePath<Pt<T>>
+          data={pts}
+          defined={defined}
           x={(d) => xScale(getX(d)) ?? 0}
-          y={(d) => yScale(d.__y)}
+          y={yOf}
           stroke={primary.color}
           strokeWidth={primary.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
           strokeDasharray={primary.dash === 'dashed' ? VX.dashArray : undefined}
           strokeOpacity={primary.strokeOpacity ?? 1}
-          curve={curveMonotoneX}
+          curve={curve}
         />
       )}
     </>
@@ -259,4 +292,8 @@ function ZonedLineMarks<T>({
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot ZonedLine kind is
  * wrapped in `React.memo` to retain the auto-memoization it had as source (parity with Bars).
  */
-export const ZonedLine = memo(ZonedLineInner) as typeof ZonedLineInner
+const ZonedLineMemo = memo(ZonedLineInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+ZonedLineMemo.displayName = 'ZonedLine'
+export const ZonedLine = ZonedLineMemo as typeof ZonedLineInner