basalt-ui 1.27.0 → 1.28.0

package/src/charts/kinds/Heatmap.tsx

@@ -1,6 +1,8 @@
 import { Group } from '@visx/group'
 import type { PointerEvent, ReactNode } from 'react'
 import { memo, useMemo, useState } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -8,6 +10,10 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import { useChartTierMetrics } from '../primitives/chart-tier'
+import type { ChartState } from '../primitives/ChartPending'
+import { maxTextWidth } from '../utils/measure-text'
+import { thinLabels, xLabelPxFor } from '../utils/ticks'
 import { VX, alpha } from '../../tokens'
 
 /** A single resolved heatmap cell — the unit the tooltip and hover operate on. */
@@ -16,7 +22,7 @@ type HeatmapCell = { row: string; col: string; value: number }
 /** A hovered cell plus the viewport anchor `ChartTooltipFloat` positions against. */
 type HeatmapTip = HeatmapCell & { anchor: { x: number; y: number } }
 
-export type HeatmapProps<T> = {
+export type HeatmapProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
   height?: number
@@ -57,6 +63,9 @@ export type HeatmapProps<T> = {
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — 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
 }
 
 /** Build a first-seen-ordered list of unique keys from data via an accessor. */
@@ -85,6 +94,10 @@ const LABEL_FONT_FAMILY = 'var(--basalt-font-mono)'
 const PAD_LEFT = 44
 const PAD_BOTTOM = 24
 const PAD_TOP = 8
+
+/** Line box of one category label at `fontPx` — the vertical room a row label needs, and so the
+ * pitch below which the row labels thin (`thinLabels`). Same 1.35em line box `autoMargin` uses. */
+const labelLineHeight = (fontPx: number): number => Math.ceil(fontPx * 1.35)
 // Height of the optional gradient legend strip (+ its label line).
 const LEGEND_H = 8
 const LEGEND_LABEL_H = 16
@@ -94,14 +107,22 @@ const LEGEND_LABEL_H = 16
  * color at an opacity derived from its value; empty cells stay a faint neutral track.
  * Generalizes argo's day-of-week × hour-of-day heatmap. Categorical axes are rendered as
  * plain themed `<text>` (cells are not date-categorical, so there's no shared cursor here) —
- * per-cell hover drives the local tooltip directly.
+ * per-cell hover drives the local tooltip directly. Painting them outside the `Axis*` primitives
+ * does NOT exempt them from §1's measured law: both runs thin through {@link thinLabels} and the
+ * right gutter reserves half the widest column label, so no two painted labels overlap and the
+ * last one cannot clip.
  *
  * Composes `ChartFrame` purely for measuring (`height`/`aspectRatio`/`fill`, the same three
  * sizing modes every other kind exposes) — `legend={false}` and an empty `series` opt out of
  * `ChartFrame`'s own derived legend, since Heatmap already ships its own gradient strip.
  */
 function HeatmapInner<T>(props: HeatmapProps<T>) {
-  const { chartId, height, aspectRatio, fill, 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('Heatmap', props, ['data', 'getRow', 'getCol', 'getValue'])
+  const { chartId, height, aspectRatio, fill, ariaLabel, isPending, state, className, style } =
+    props
 
   return (
     <ChartFrame
@@ -113,6 +134,9 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
       {...(fill !== undefined && { fill })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(plot) => <HeatmapPlot {...props} plot={plot} />}
     </ChartFrame>
@@ -147,6 +171,11 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
   } = props
   const { width, height } = plot
 
+  // The row/column labels and the gradient legend's endpoints read like axis ticks, so they take
+  // the tier's tick font for the same reason `Axes.tsx` does — a 360px heatmap that painted its
+  // categories at the desktop size would be the one chart still ignoring §8.
+  const { axisFont } = useChartTierMetrics()
+
   const [tip, setTip] = useState<HeatmapTip | null>(null)
 
   const rows = useMemo(() => rowsProp ?? firstSeen(data, getRow), [rowsProp, data, getRow])
@@ -164,13 +193,33 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
     return { lookup: map, max: m }
   }, [data, getRow, getCol, getValue])
 
+  const rowLabels = useMemo(() => rows.map(rowLabel), [rows, rowLabel])
+  const colLabels = useMemo(() => cols.map(colLabel), [cols, colLabel])
+
   const legendH = legend ? LEGEND_H + LEGEND_LABEL_H : 0
-  const gridW = Math.max(0, width - PAD_LEFT)
+  // The last column label is CENTRED on the last cell, so half of it hangs past the grid — the
+  // same reason `autoMargin` reserves half the widest x label on the right. Measured, not a
+  // constant: at 390px `19:00` used to print straight off the SVG's own clip edge.
+  const padRight = Math.ceil(maxTextWidth(colLabels, axisFont) / 2)
+  const gridW = Math.max(0, width - PAD_LEFT - padRight)
   const gridH = Math.max(0, height - PAD_TOP - PAD_BOTTOM - legendH)
   const cellW = cols.length > 0 ? gridW / cols.length : 0
   const cellH = rows.length > 0 ? gridH / rows.length : 0
   const legendGradientId = `${chartId}-heat-legend`
 
+  // §1's measured law, applied to the one kind that paints its labels as plain `<text>` rather
+  // than through the `Axis*` primitives: a label every `ceil(labelPx / cellPitch)` bands, so two
+  // painted neighbours can never overlap. Columns thin horizontally by the widest label, rows
+  // vertically by the line box.
+  const keptCols = useMemo(
+    () => thinLabels(colLabels, cellW, xLabelPxFor(colLabels, axisFont)),
+    [colLabels, cellW, axisFont],
+  )
+  const keptRows = useMemo(
+    () => thinLabels(rowLabels, cellH, labelLineHeight(axisFont)),
+    [rowLabels, cellH, axisFont],
+  )
+
   const show = (row: string, col: string, value: number, event: PointerEvent<SVGRectElement>) => {
     setTip({ row, col, value, anchor: { x: event.clientX, y: event.clientY } })
   }
@@ -206,36 +255,40 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
 
         {/* Row labels (left). */}
         <Group left={0} top={PAD_TOP}>
-          {rows.map((row, ri) => (
-            <text
-              key={row}
-              x={PAD_LEFT - 6}
-              y={ri * cellH + cellH / 2 + 4}
-              textAnchor="end"
-              fontSize={VX.axisFont}
-              fontFamily={LABEL_FONT_FAMILY}
-              fill={VX.faint}
-            >
-              {rowLabel(row)}
-            </text>
-          ))}
+          {rows.map((row, ri) =>
+            keptRows.has(ri) ? (
+              <text
+                key={row}
+                x={PAD_LEFT - 6}
+                y={ri * cellH + cellH / 2 + 4}
+                textAnchor="end"
+                fontSize={axisFont}
+                fontFamily={LABEL_FONT_FAMILY}
+                fill={VX.faint}
+              >
+                {rowLabels[ri]}
+              </text>
+            ) : null,
+          )}
         </Group>
 
         {/* Column labels (bottom). */}
         <Group left={PAD_LEFT} top={PAD_TOP + gridH}>
-          {cols.map((col, ci) => (
-            <text
-              key={col}
-              x={ci * cellW + cellW / 2}
-              y={16}
-              textAnchor="middle"
-              fontSize={VX.axisFont}
-              fontFamily={LABEL_FONT_FAMILY}
-              fill={VX.faint}
-            >
-              {colLabel(col)}
-            </text>
-          ))}
+          {cols.map((col, ci) =>
+            keptCols.has(ci) ? (
+              <text
+                key={col}
+                x={ci * cellW + cellW / 2}
+                y={16}
+                textAnchor="middle"
+                fontSize={axisFont}
+                fontFamily={LABEL_FONT_FAMILY}
+                fill={VX.faint}
+              >
+                {colLabels[ci]}
+              </text>
+            ) : null,
+          )}
         </Group>
 
         {/* Optional gradient legend strip below the grid. */}
@@ -252,7 +305,7 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
               x={0}
               y={LEGEND_H + 12}
               textAnchor="start"
-              fontSize={VX.axisFont}
+              fontSize={axisFont}
               fontFamily={LABEL_FONT_FAMILY}
               fill={VX.faint}
             >
@@ -262,7 +315,7 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
               x={gridW}
               y={LEGEND_H + 12}
               textAnchor="end"
-              fontSize={VX.axisFont}
+              fontSize={axisFont}
               fontFamily={LABEL_FONT_FAMILY}
               fill={VX.faint}
             >
@@ -294,4 +347,8 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot Heatmap kind is
  * wrapped in `React.memo` to retain auto-memoization (parity with ZonedLine / Bars).
  */
-export const Heatmap = memo(HeatmapInner) as typeof HeatmapInner
+const HeatmapMemo = memo(HeatmapInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+HeatmapMemo.displayName = 'Heatmap'
+export const Heatmap = HeatmapMemo as typeof HeatmapInner

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 '../../utils/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