basalt-ui 1.41.0 → 2.0.1

package/src/charts/primitives/CartesianChart.tsx

@@ -1,1002 +0,0 @@
-import { GridRows } from '@visx/grid'
-import { Group } from '@visx/group'
-import { scaleLinear, scaleLog, scalePoint } from '@visx/scale'
-import { useMemo, useRef, useState } from 'react'
-import type { ReactNode } from 'react'
-import type { BasaltProps } from '../../common/props'
-import { VX, alpha } from '../../tokens'
-import type { ChartMargin } from '../../tokens'
-import { classifyDomain } from '../cursor/resolve'
-import type { CursorResolution } from '../cursor/resolve'
-import { useChartCursor } from '../hooks/useChartCursor'
-import { autoMargin, probeAxisLabels } from '../layout/auto-margin'
-import type { AutoMarginInput } from '../layout/auto-margin'
-import { END_LABEL_GAP, planEndLabels } from '../layout/end-labels'
-import { logTickValues, niceLogDomain } from '../layout/log-ticks'
-import { deriveLegend, deriveTooltipRows } from '../series'
-import type { ChartLegendConfig, ChartSeries } from '../series'
-import { padAutoLower, padAutoUpper } from '../utils/domain'
-import { fmtAxisDate } from '../utils/format'
-import { rotatedXLabelPx, smartTicks, smartTicksEvery, xLabelPxFor } from '../utils/ticks'
-import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric, TICK_FONT_FAMILY } from './Axes'
-import { ChartFrame, resolveLegend } from './ChartFrame'
-import type { ResponsiveChartHeight } from './ChartFrame'
-import {
-  compactNumber,
-  isTightClass,
-  planXLabels,
-  resolveMarginFloor,
-  resolveYPlacement,
-  shouldCompactYLabels,
-  yTickCount,
-} from './chart-layout'
-import { useChartContainerClass, useChartMetrics } from './chart-tier'
-import type { ChartState } from './ChartPending'
-import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRows } from './ChartTooltip'
-import { Crosshair, SeriesDot } from './Crosshair'
-import { cursorSliderProps, HoverOverlay } from './HoverOverlay'
-import { XZoneRects } from './XZoneRects'
-import type { XZoneSpec } from './XZoneRects'
-import { ZoneRects } from './ZoneRects'
-import type { ZoneSpec } from './ZoneRects'
-
-/** Either axis kind a `y`/`y2` can resolve to. Widened from a bare `scaleLinear` return type so a
- * log axis's `scaleLog` scale keeps assigning into `PlotContext.yScale`/`y2Scale` and into every
- * mark renderer (`ZoneRects`, `refLines`, `Crosshair`/`SeriesDot`) that only ever calls `scale(v)`
- * or reads `scale.domain()` — both interfaces share that shape via d3's `ScaleContinuousNumeric`. */
-type ContinuousScale = ReturnType<typeof scaleLinear<number>> | ReturnType<typeof scaleLog<number>>
-type PointScale = ReturnType<typeof scalePoint<string>>
-
-const DEFAULT_AUTO_PAD = 1.1
-
-/** Faint tint a dual-axis chart lays over its tick labels: the series colour, kept quiet. */
-const AXIS_TINT_ALPHA = 0.8
-
-/** One y-axis, fully described. Collapses the removed `yDomain` / `yAutoMaxFloor` / `yAutoMinCeil` /
- * `yAutoPad` / `numTicksY` / `formatYTick` prop soup into a single object per axis. */
-export type AxisConfig<T> = {
-  /**
-   * `'auto'` (default) derives the domain from the VISIBLE series; a tuple fixes it; a function
-   * computes it from the data — the seam a stacked chart uses to sum its bands. The function also
-   * receives the visible series, so a stacked domain SHRINKS when the legend toggles a band off
-   * (summing `props.series` there would leave a permanent gap above the stack).
-   */
-  domain?:
-    | [number, number]
-    | 'auto'
-    | ((data: readonly T[], visible: readonly ChartSeries<T>[]) => [number, number])
-  /**
-   * When 'auto': the raw upper bound is at least this, and padding is applied AFTER — mirroring
-   * `autoMinCeil`, which clamps first and pads second. A floor that padded before the clamp used
-   * to land the axis top exactly on the floor value with zero headroom.
-   */
-  autoMaxFloor?: number
-  /** When 'auto': the lower bound is at most this. Default 0 (forced zero baseline). `Infinity`
-   * pads down from the raw data minimum instead. Ignored when `scale: 'log'` — a log axis has no
-   * zero baseline, so its floor is always the smallest positive visible value. */
-  autoMinCeil?: number
-  /** When 'auto': padding multiplier applied away from the data. Default 1.1. */
-  autoPad?: number
-  ticks?: number
-  /** Tick + tooltip formatter for this axis. Defaults to d3's own tick format. */
-  format?: (v: number) => string
-  /** Horizontal grid rules. Default: on for the left axis, off for the right. */
-  grid?: boolean
-  /**
-   * Round the scale's domain outward to nice tick values (d3's `scale.nice()`). Threaded to BOTH
-   * `probeAxisLabels` (measurement) and the real `scaleLinear` (rendering) — they must agree, or
-   * the measured margin is computed from ticks the axis never paints.
-   *
-   * Default `false`, deliberately: flipping the default would move the domain of every
-   * already-migrated chart. Opt in per axis.
-   */
-  nice?: boolean
-  /**
-   * `'linear'` (default) or `'log'`. On `'log'` the domain floor is the smallest positive VISIBLE
-   * value — `autoMinCeil` is ignored (documented there, not thrown on): a log axis has no zero
-   * baseline. `autoPad` still pads multiplicatively and `nice` still snaps to round bounds (decade
-   * powers instead of d3's linear-nice steps). Ticks are the 1-2-5 set from `logTickValues`
-   * (`$10,000 · $20,000 · $50,000 · $100,000`, never d3's own log ticks), and `format` is applied
-   * to those values — d3's `scale.tickFormat` is never used on a log axis.
-   */
-  scale?: 'linear' | 'log'
-}
-
-/** Handed to `prependRows`/`extraRows` alongside the hovered datum — the same `visible`/`hidden`
- * the plot itself draws from, so a hand-authored row can't structurally desync from legend
- * toggling. */
-export type CartesianTooltipRowContext<T> = {
-  visible: readonly ChartSeries<T>[]
-  hidden: ReadonlySet<string>
-}
-
-export type CartesianTooltipConfig<T> = {
-  /**
-   * Default true — the tooltip tracks the pointer. Set false to ANCHOR it to the crosshair at the
-   * plot's top edge instead, which reads better across a column of charts sharing one cursor
-   * (every tooltip then lines up on the same x). Anchoring costs one `getBoundingClientRect` per
-   * hovered frame, which is why following stays the default.
-   */
-  follow?: boolean
-  /** Right-aligned badge in the tooltip header (e.g. a status label). */
-  label?: (d: T) => { text: string; color: string } | null
-  /**
-   * Overrides the tooltip header's date text. Default: `TooltipHeader`'s own `fmtTooltipDate`
-   * behavior, unchanged. `fmtTooltipDate` regexes `YYYY-MM-DD` out of the domain key and builds a
-   * LOCAL `Date` from it — a UTC ISO key then names the wrong day next to `formatX`, the tooltip
-   * badge, and every sibling chart, which all resolve locally. Receives the raw `getX` key
-   * alongside the hovered datum, so a caller can format from either.
-   */
-  formatHeader?: (key: string, d: T) => string
-  /** Rows rendered BEFORE the derived per-series rows (a total, a context line). The second
-   * argument carries the same `visible`/`hidden` the plot draws from, so a hand-authored row
-   * stays in sync with legend toggling instead of naming a series the plot no longer draws. */
-  prependRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
-  /** Rows appended after the derived per-series rows. Same `ctx` as {@link prependRows}. */
-  extraRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
-  /**
-   * Render this chart's tooltip when it is a cursor FOLLOWER (the crosshair came from a sibling
-   * chart sharing the cursor), not only when this chart is the SOURCE. Default false — today's
-   * behaviour, nothing moves. A follower has no pointer under it, so its tooltip is always ANCHORED
-   * to the crosshair — the same positioning `follow: false` gives the source — regardless of what
-   * `follow` is set to on this chart: there is no other valid position for a chart nobody is
-   * hovering. `follow` keeps governing the SOURCE's own tooltip exactly as before; the two options
-   * only interact for a follower, where `onFollow` always wins on positioning. Only the SOURCE's
-   * tooltip is `aria-live` — followers announce nothing, so a shared-cursor page doesn't fire N
-   * live-region updates per pointer move.
-   *
-   * Cost, since it scales with the page rather than the chart: anchoring reads one
-   * `getBoundingClientRect` per hovered frame (the same cost `follow: false` documents), so N
-   * opted-in followers pay N of them per frame. That is the reason this is opt-in per chart rather
-   * than a page-level switch — turn it on for the charts a reader actually correlates.
-   */
-  onFollow?: boolean
-}
-
-/** Everything a mark renderer needs. Handed to `CartesianChart`'s child on every render. */
-export type PlotContext<T> = {
-  data: readonly T[]
-  /** Series minus the ones the legend has toggled off — draw THESE, not `props.series`. */
-  visible: ChartSeries<T>[]
-  hidden: ReadonlySet<string>
-  xScale: PointScale
-  yScale: ContinuousScale
-  /** Present only when a `y2` axis is configured. */
-  y2Scale: ContinuousScale | null
-  xMax: number
-  yMax: number
-  margin: ChartMargin
-  /** The point the shared cursor currently rests on, or null. */
-  cursorPoint: T | null
-  /** Series key the legend is hovering, for mark dimming. */
-  highlighted: string | null
-}
-
-export type CartesianChartProps<T> = BasaltProps & {
-  data: T[]
-  /** Stable id — identifies this chart as the cursor's source. */
-  chartId: string
-  /** Extracts the x-domain key (a date or category string) from a point. */
-  getX: (d: T) => string
-  /** The single source of truth for marks, legend entries, and tooltip rows. */
-  series: ChartSeries<T>[]
-  y?: AxisConfig<T>
-  /** Passing `y2` is what makes the chart dual-axis: it draws the right axis and widens the
-   * right margin by measurement. Series opt in with `axis: 'right'`. */
-  y2?: AxisConfig<T>
-  /** Exact number of x ticks. Default: as many as fit (`smartTicks`). Ignored when
-   * `xTickValues` is set. */
-  xTicks?: number
-  /**
-   * Which domain keys get a tick, chosen from the full key list and the resolved plot width.
-   * Takes precedence over `xTicks`; omit both for `smartTicks`.
-   *
-   * A COUNT is not always enough. `smartTicks`/`smartTicksEvery` append the final key
-   * unconditionally, so when the step does not land on the last index that appended tick sits a
-   * partial step from its neighbour — measured on a 24h window, two `DD.MM HH:MM` labels printed
-   * on top of each other at the right edge, at every tick count. The only fix a count can express
-   * is thinning the whole axis to avoid one crowded pair. A consumer whose labels are richer than
-   * the default `DD.MM` needs to pick the VALUES, which until now meant measuring the container
-   * itself with `useChartSize` to derive a count — the chart already knows its own width.
-   *
-   * `BandStrip`/`MirroredBars` take the identical prop, so the seam does not fork by kind.
-   */
-  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 by 45° or 90° (counter-clockwise, anchored at their right edge). The
-   * bottom gutter deepens by the rotated label's projected height, measured like every other side
-   * (`docs/CHARTS-SPEC.md` §1), so nothing clips.
-   *
-   * This is the phone answer to a **categorical** axis whose labels are too wide to repeat
-   * horizontally: rotating keeps every tick the axis would otherwise have to thin away — which is
-   * why, LEFT UNSET, it is now the phone tier's DEFAULT for a band domain, below
-   * `CONTAINER_CLASSES.regular` (`planXLabels`). A time or number domain never auto-rotates (or
-   * wraps) — it thins instead, however narrow the plot. Nothing changes at desktop width, and
-   * nothing changes for a chart that already passes a value.
-   *
-   * **`0` is the opt-out** — "never rotate, thin the axis instead" — and is the only way to get
-   * the pre-tier behaviour back on a phone-width categorical chart with very wide labels.
-   */
-  xLabelRotate?: 0 | 45 | 90
-  /** Value-range bands on the left scale, drawn behind the marks. */
-  zones?: ZoneSpec[]
-  /** X-range bands (time windows), drawn behind the marks. */
-  xZones?: XZoneSpec[]
-  refLines?: { value: number; color: string; dashed?: boolean; axis?: 'left' | 'right' }[]
-  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
-   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
-  height?: number | ResponsiveChartHeight
-  aspectRatio?: number
-  fill?: boolean
-  legend?: ChartLegendConfig | false
-  /** `false` disables the tooltip entirely (and with it the crosshair dots). */
-  tooltip?: CartesianTooltipConfig<T> | false
-  /** Per-side overrides of the measured margins — the escape hatch, applied last. */
-  margin?: Partial<ChartMargin>
-  /**
-   * Where this series' crosshair dot sits, as a value in the axis domain. Defaults to
-   * `series.getValue`, which is correct for every unstacked chart. A STACKED chart must override
-   * it with the cumulative band top — otherwise its dots sit at each band's raw value, off the
-   * line the reader is actually looking at.
-   */
-  cursorValue?: (
-    point: T,
-    series: ChartSeries<T>,
-    visible: readonly ChartSeries<T>[],
-  ) => number | null
-  /**
-   * How a sibling chart's broadcast cursor key resolves against THIS chart's points. Default
-   * `'nearest'`, correct when `getX` returns an instant. Pass `'leading'` when it returns a
-   * bucket's leading edge (a weekly series keyed by its Monday): under `'nearest'` a hover landing
-   * in the back half of a bucket resolves to the FOLLOWING bucket, so the shared crosshair sits
-   * one column right of the data the reader is pointing at.
-   */
-  cursorResolution?: CursorResolution
-  ariaLabel?: string
-  isPending?: boolean
-  /**
-   * The three "nothing to draw" states in one prop, forwarded to `ChartFrame` — pending → error →
-   * empty, resolved by `resolveChartState`. The Mantine-free answer to `dashboard/QueryState`,
-   * which `./charts` cannot import; `isPending` remains a supported alias for
-   * `state={{ pending: true }}`.
-   */
-  state?: ChartState
-  /** Draw ONLY the marks. Everything around them is the primitive's job. */
-  children: (ctx: PlotContext<T>) => ReactNode
-}
-
-/**
- * Resolve one axis' `[min, max]` from its {@link AxisConfig} and the VISIBLE series. Exported for
- * testing and for a hand-composed kind that needs the same auto-domain law `CartesianChart`
- * applies (rather than reinventing the padding rules per chart).
- */
-export function resolveAxisDomain<T>(
-  cfg: AxisConfig<T> | undefined,
-  data: readonly T[],
-  series: readonly ChartSeries<T>[],
-  /**
-   * Values that must stay inside the plot even though no series reports them — the bounds of the
-   * zones and reference lines pinned to THIS axis. Without them a target zone or a stretch-goal
-   * ref line sitting past the data silently clips, which is precisely the case those overlays
-   * exist for. Infinite bounds ("top/bottom of axis") are ignored: they clamp to the domain by
-   * definition and would otherwise blow it up.
-   */
-  extraBounds: readonly number[] = [],
-): [number, number] {
-  const domain = cfg?.domain ?? 'auto'
-  if (Array.isArray(domain)) return domain
-  if (typeof domain === 'function') return domain(data, series)
-
-  const isLog = cfg?.scale === 'log'
-  let min = Infinity
-  let max = -Infinity
-  for (const d of data) {
-    for (const s of series) {
-      const v = s.getValue(d)
-      if (v === null) continue
-      // A log axis has no zero and no negative half — a non-positive value can't sit on it, so it
-      // drops out of the domain instead of pulling the floor to (or past) zero.
-      if (isLog && v <= 0) continue
-      if (v < min) min = v
-      if (v > max) max = v
-    }
-  }
-  for (const v of extraBounds) {
-    if (!Number.isFinite(v)) continue
-    if (isLog && v <= 0) continue
-    if (v < min) min = v
-    if (v > max) max = v
-  }
-
-  const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD
-
-  if (isLog) {
-    // No zero baseline on a log axis: the floor is the smallest positive visible value, padded
-    // down with no `autoMinCeil` clamp (documented as ignored on `AxisConfig.autoMinCeil`).
-    if (min === Infinity) return [1, 10]
-    if (min === max) return [min / pad, max * pad]
-    const upper = padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)
-    return [min / pad, upper]
-  }
-
-  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1]
-
-  const ceil = cfg?.autoMinCeil ?? 0
-  // Symmetric with the lower bound: clamp the RAW value against the floor/ceiling first, then pad
-  // once, away from zero. Padding before the clamp (the old law) lands a floored axis top exactly
-  // on the floor with zero headroom — a target line pinned there sits glued to the plot edge.
-  const upper = padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)
-  const lower = padAutoLower(Math.min(min, ceil), pad)
-  // A flat series (every value identical, the all-zero case included) collapses to `[n, n]`,
-  // which is a scale with no extent: every point maps to the same pixel and the line renders as a
-  // dot on the axis. Give it the same usable baseline the empty-data branch above gets.
-  if (lower === upper) return [Math.min(lower, 0), upper === 0 ? 1 : upper * pad]
-  return [lower, upper]
-}
-
-/**
- * Probe one y axis' labels. With no consumer `format`, labels over 4 chars switch to the compact
- * number format (`12500` -> `12.5k`, ladder step 1); an explicit `format` is never touched.
- */
-function probeYAxis(opts: {
-  domain: [number, number]
-  ticks: number
-  nice: boolean
-  scale: 'linear' | 'log' | undefined
-  format: ((v: number) => string) | undefined
-}): { labels: string[]; format: (v: number) => string } {
-  const { domain, ticks, nice, scale, format } = opts
-  const base = probeAxisLabels({
-    domain,
-    ticks,
-    nice,
-    ...(scale !== undefined && { scale }),
-    ...(format !== undefined && { format }),
-  })
-  if (format !== undefined || !shouldCompactYLabels(base.labels)) {
-    return base
-  }
-  const compact = (v: number): string => compactNumber(v) ?? base.format(v)
-  return {
-    labels: probeAxisLabels({
-      domain,
-      ticks,
-      nice,
-      format: compact,
-      ...(scale !== undefined && { scale }),
-    }).labels,
-    format: compact,
-  }
-}
-
-/**
- * One y-axis' real scale, built from its resolved domain — shared by the left and right axis so
- * the log branch (`scaleLog` + `nice` + the 1-2-5 tick override) is written and commented exactly
- * once instead of as two independently-maintained twins.
- */
-function buildYScale<T>(
-  cfg: AxisConfig<T> | undefined,
-  domain: [number, number],
-  yMax: number,
-  ticks: number,
-): ContinuousScale {
-  if (cfg?.scale === 'log') {
-    const scale = scaleLog<number>({
-      domain,
-      range: [yMax, 0],
-      ...(cfg.nice === true && { nice: true }),
-    })
-    // Paint the 1-2-5 tick law instead of d3's own log ticks: `AxisLeftNumeric`/`GridRows` resolve
-    // ticks through visx's `getTicks(scale, numTicks)` -> `scale.ticks(numTicks)`, so overriding
-    // the method on this instance is the one seam that reaches both without a raw `<AxisLeft>`
-    // escape hatch. Nothing else calls `.ticks()` on the real scale (only `probeAxisLabels`' own
-    // throwaway probe does, and that stays untouched).
-    const tickDomain = cfg.nice === true ? niceLogDomain(domain) : domain
-    scale.ticks = () => logTickValues(tickDomain, ticks)
-    return scale
-  }
-  return scaleLinear<number>({
-    domain,
-    range: [yMax, 0],
-    ...(cfg?.nice === true && { nice: true }),
-  })
-}
-
-/**
- * The x-axis margin ladder, as one pure decision. The flat (unrotated) margin is what every case
- * resolves to except a rotated or wrapped axis, and it is what the rotation decision itself is
- * measured against — deciding needs an `xMax`, and `xMax` needs a margin, so the flat pass breaks
- * the loop. An explicit `xLabelRotate` always wins — including `0`, the documented "never rotate"
- * opt-out; unset, only a categorical (band) axis wraps, and rotates only when even wrapped it
- * doesn't fit (`planXLabels`) — a time or number domain only thins.
- *
- * Per rotation: 45° reuses its pre-measured margin and measures its tick room through
- * {@link rotatedXLabelPx} (a rotated label projects wider than its glyph box); 90° measures fresh
- * (one line box wide, so the flat label room governs its thinning); a wrapped flat axis re-measures
- * for its extra line(s) and thins by the wrapped width.
- */
-function resolveXAxisLayout(input: {
-  marginInput: AutoMarginInput
-  flatMargin: ChartMargin
-  rotated45Margin: ChartMargin
-  flatLabelPx: number
-  xLabels: string[]
-  fontPx: number
-  plotWidth: number
-  categorical: boolean
-  xLabelRotate: 0 | 45 | 90 | undefined
-}): {
-  baseMargin: ChartMargin
-  rotate: 0 | 45 | 90
-  wrapWidth: number | undefined
-  tickLabelPx: number
-} {
-  const { marginInput, flatMargin, rotated45Margin, flatLabelPx, xLabels, fontPx, categorical } =
-    input
-  const flatXMax = Math.max(input.plotWidth - flatMargin.left - flatMargin.right, 0)
-  const xPlan = planXLabels({ labels: xLabels, plotWidth: flatXMax, fontPx, categorical })
-  const rotate = input.xLabelRotate ?? (categorical ? xPlan.rotate : 0)
-  if (rotate === 45) {
-    const tickLabelPx = rotatedXLabelPx(xLabels, fontPx)
-    return { baseMargin: rotated45Margin, rotate, wrapWidth: undefined, tickLabelPx }
-  }
-  if (rotate === 90) {
-    const baseMargin = autoMargin({ ...marginInput, rotate })
-    return { baseMargin, rotate, wrapWidth: undefined, tickLabelPx: flatLabelPx }
-  }
-  if (!xPlan.wrap)
-    return { baseMargin: flatMargin, rotate, wrapWidth: undefined, tickLabelPx: flatLabelPx }
-  const baseMargin = autoMargin({ ...marginInput, bottomLines: xPlan.lines })
-  return { baseMargin, rotate, wrapWidth: xPlan.wrapPx, tickLabelPx: xPlan.labelPx }
-}
-
-/**
- * The cartesian chart primitive — the rung that was missing between `ChartFrame` and raw visx
- * (`docs/CHARTS-SPEC.md` §2).
- *
- * It owns, once, everything every chart repeated: measured margins, both y scales and their
- * domains, the x scale and its tick thinning, grid, zones, axes, the shared cursor, the crosshair
- * and its per-series dots, the hover/keyboard overlay, and the derived tooltip. The child draws
- * marks and nothing else, so two charts cannot drift apart in any of those layers — that identity
- * IS the consistency guarantee.
- *
- * Margins are MEASURED from the labels that will actually be painted, so a wide tick label widens
- * its own gutter instead of clipping or needing a hand-tuned `margin` prop.
- */
-export function CartesianChart<T>({
-  data,
-  chartId,
-  getX,
-  series,
-  y,
-  y2,
-  xTicks,
-  xTickValues,
-  formatX = fmtAxisDate,
-  xLabelRotate,
-  zones,
-  xZones,
-  refLines,
-  height,
-  aspectRatio,
-  fill,
-  legend,
-  tooltip,
-  margin: marginOverride,
-  cursorValue,
-  cursorResolution,
-  ariaLabel,
-  isPending,
-  state,
-  className,
-  style,
-  children,
-}: CartesianChartProps<T>): ReactNode {
-  const [highlighted, setHighlighted] = useState<string | null>(null)
-
-  return (
-    <ChartFrame
-      series={series}
-      chartId={chartId}
-      {...(height !== undefined && { height })}
-      {...(aspectRatio !== undefined && { aspectRatio })}
-      {...(fill !== undefined && { fill })}
-      {...(ariaLabel !== undefined && { ariaLabel })}
-      {...(isPending !== undefined && { isPending })}
-      {...(state !== undefined && { state })}
-      {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
-      legend={resolveLegend(
-        legend,
-        { highlighted, onHighlight: setHighlighted },
-        deriveLegend(series).length,
-      )}
-    >
-      {(plot) => (
-        <CartesianPlot
-          data={data}
-          chartId={chartId}
-          getX={getX}
-          series={series}
-          {...(y !== undefined && { y })}
-          {...(y2 !== undefined && { y2 })}
-          {...(xTicks !== undefined && { xTicks })}
-          {...(xTickValues !== undefined && { xTickValues })}
-          formatX={formatX}
-          {...(xLabelRotate !== undefined && { xLabelRotate })}
-          {...(zones !== undefined && { zones })}
-          {...(xZones !== undefined && { xZones })}
-          {...(refLines !== undefined && { refLines })}
-          {...(tooltip !== undefined && { tooltip })}
-          {...(marginOverride !== undefined && { marginOverride })}
-          {...(cursorValue !== undefined && { cursorValue })}
-          {...(cursorResolution !== undefined && { cursorResolution })}
-          {...(ariaLabel !== undefined && { ariaLabel })}
-          plot={plot}
-          highlighted={highlighted}
-        >
-          {children}
-        </CartesianPlot>
-      )}
-    </ChartFrame>
-  )
-}
-
-type CartesianPlotProps<T> = Omit<
-  CartesianChartProps<T>,
-  | 'height'
-  | 'aspectRatio'
-  | 'fill'
-  | 'legend'
-  | 'isPending'
-  | 'state'
-  | 'margin'
-  | 'className'
-  | 'style'
-> & {
-  plot: { width: number; height: number; hidden: ReadonlySet<string>; legendInHeader: boolean }
-  highlighted: string | null
-  marginOverride?: Partial<ChartMargin>
-}
-
-/** Split from {@link CartesianChart} so scale + margin work runs only once the frame has resolved
- * a non-empty plot rect (and so the hook order never depends on that rect). */
-function CartesianPlot<T>({
-  data,
-  chartId,
-  getX,
-  series,
-  y,
-  y2,
-  xTicks,
-  xTickValues,
-  formatX = fmtAxisDate,
-  xLabelRotate,
-  zones,
-  xZones,
-  refLines,
-  tooltip,
-  marginOverride,
-  cursorValue,
-  cursorResolution,
-  ariaLabel,
-  plot,
-  highlighted,
-  children,
-}: CartesianPlotProps<T>): ReactNode {
-  const { hidden } = plot
-  // The tier `ChartFrame` resolved from its own MEASURED width. Everything sized by it here is
-  // the half a hook cannot reach: the tick font the margins are MEASURED at, and the margin
-  // floors themselves (`docs/CHARTS-SPEC.md` §8).
-  const tier = useChartMetrics()
-  const containerClass = useChartContainerClass()
-  const tight = isTightClass(containerClass)
-
-  const visible = useMemo(() => series.filter((s) => !hidden.has(s.key)), [series, hidden])
-  const leftSeries = useMemo(() => visible.filter((s) => s.axis !== 'right'), [visible])
-  const rightSeries = useMemo(() => visible.filter((s) => s.axis === 'right'), [visible])
-
-  // Honest deps on the accessors, deliberately: a ref would keep the scales, ticks and margins
-  // keyed on `data` alone, and then swapping which field `getX` reads (a field picker over the
-  // same rows) would render marks through a new accessor against stale scales. The re-render this
-  // costs is narrower than it looks — a cursor move re-renders `CartesianPlot` without changing
-  // its props, so hover frames reuse these memos regardless.
-  const keys = useMemo(() => data.map(getX), [data, getX])
-
-  // ── Pass 1: domains + tick labels, both independent of the pixel range ──────────────────────
-  // This is what breaks the margin/scale circularity: a linear scale's tick VALUES depend only on
-  // its domain, so the labels can be measured before the plot rect exists.
-  // Overlay bounds per axis — see `resolveAxisDomain`'s `extraBounds`.
-  const [leftBounds, rightBounds] = useMemo(() => {
-    const left: number[] = []
-    const right: number[] = []
-    for (const z of zones ?? []) (z.axisSide === 'right' ? right : left).push(z.from, z.to)
-    for (const l of refLines ?? []) (l.axis === 'right' ? right : left).push(l.value)
-    return [left, right]
-  }, [zones, refLines])
-
-  const leftDomain = useMemo(
-    () => resolveAxisDomain(y, data, leftSeries, leftBounds),
-    [y, data, leftSeries, leftBounds],
-  )
-  const rightDomain = useMemo(
-    () => (y2 === undefined ? null : resolveAxisDomain(y2, data, rightSeries, rightBounds)),
-    [y2, data, rightSeries, rightBounds],
-  )
-
-  // Tick count is a law of the plot height (one per ~44px, 2 under `VX.minPlotHeight`), estimated
-  // from the token floors because the real margins depend on the labels these ticks produce. A
-  // consumer's `ticks` always wins.
-  const estimatedPlotHeight = plot.height - tier.margin.top - tier.margin.bottom
-  const leftTicks = y?.ticks ?? yTickCount(estimatedPlotHeight)
-  const rightTicks = y2?.ticks ?? yTickCount(estimatedPlotHeight)
-
-  const { labels: leftLabels, format: leftFormat } = useMemo(
-    () =>
-      probeYAxis({
-        domain: leftDomain,
-        ticks: leftTicks,
-        nice: y?.nice ?? false,
-        scale: y?.scale,
-        format: y?.format,
-      }),
-    [leftDomain, leftTicks, y?.format, y?.nice, y?.scale],
-  )
-
-  const { labels: rightLabels, format: rightFormat } = useMemo(
-    () =>
-      rightDomain === null
-        ? { labels: [], format: (v: number) => String(v) }
-        : probeYAxis({
-            domain: rightDomain,
-            ticks: rightTicks,
-            nice: y2?.nice ?? false,
-            scale: y2?.scale,
-            format: y2?.format,
-          }),
-    [rightDomain, rightTicks, y2?.format, y2?.nice, y2?.scale],
-  )
-
-  const xLabels = useMemo(() => keys.map(formatX), [keys, formatX])
-
-  // Ladder step 5: at compact/micro the y labels sit inside the plot (micro: no y axis), so the
-  // left gutter drops to its floor. An explicit `margin.left` means the consumer laid out an
-  // outside gutter — it keeps the outside axis. `CartesianChart` always has a left axis.
-  const yPlacement = resolveYPlacement(containerClass, { marginOverrideLeft: marginOverride?.left })
-  // A whitespace test misclassified any spaced date format ("Mar 01") as categorical, which then
-  // wrapped or rotated a time axis that should only ever thin (§ ladder step 4). Domain kind is
-  // the actual law: only a band (category) domain wraps or rotates; time and number domains thin.
-  const categorical = tight && classifyDomain(keys) === 'band'
-
-  // The room one flat x tick label needs at the tick font the axis will actually paint
-  // (`docs/CHARTS-SPEC.md` §8) — keyed on the labels and font alone, so a y-label or margin change
-  // never re-measures every x label.
-  const flatLabelPx = useMemo(() => xLabelPxFor(xLabels, tier.axisFont), [xLabels, tier.axisFont])
-
-  // Everything `autoMargin` measures except the rotation, measured once for every pass so a label
-  // can never differ between the one that DECIDES and the one that PAINTS — plus the 45° margin (a
-  // rotated label reaches into the left gutter).
-  const measured = useMemo(() => {
-    const marginInput: AutoMarginInput = {
-      left: yPlacement === 'outside' ? leftLabels : [],
-      right: rightLabels,
-      bottom: xLabels,
-      fontPx: tier.axisFont,
-      // An inside-placed y label paints IN the plot, so the left gutter it used to reserve
-      // (the phone tier's own margin floor) is dead space — only the inside-label floor applies.
-      floor: resolveMarginFloor(yPlacement, tier.margin),
-      anchorTerminals: tight,
-      ...(marginOverride !== undefined && { override: marginOverride }),
-    }
-    return {
-      marginInput,
-      flatMargin: autoMargin(marginInput),
-      rotated45Margin: autoMargin({ ...marginInput, rotate: 45 }),
-    }
-  }, [
-    leftLabels,
-    rightLabels,
-    xLabels,
-    tier.axisFont,
-    tier.margin,
-    marginOverride,
-    tight,
-    yPlacement,
-  ])
-  const { baseMargin, rotate, wrapWidth, tickLabelPx } = useMemo(
-    () =>
-      resolveXAxisLayout({
-        ...measured,
-        flatLabelPx,
-        xLabels,
-        fontPx: tier.axisFont,
-        plotWidth: plot.width,
-        categorical,
-        xLabelRotate,
-      }),
-    [measured, flatLabelPx, xLabels, tier.axisFont, plot.width, categorical, xLabelRotate],
-  )
-
-  // End-of-line labels are planned FIRST, against the base margin: the right gutter is reserved
-  // only when the labels will actually draw. `yScale` depends on the plot height alone, so it is
-  // safe to build before the right margin is settled.
-  const yMax = Math.max(plot.height - baseMargin.top - baseMargin.bottom, 0)
-  const yScale = useMemo(
-    () => buildYScale(y, leftDomain, yMax, leftTicks),
-    [y, leftDomain, yMax, leftTicks],
-  )
-  const endPlan = useMemo(
-    () =>
-      planEndLabels({
-        containerClass,
-        hasY2: y2 !== undefined,
-        hasMarginRight: marginOverride?.right !== undefined,
-        hasHeaderLegend: plot.legendInHeader,
-        visible,
-        data,
-        yScale,
-        yMax,
-        fontPx: tier.axisFont,
-        plotWidth: plot.width - baseMargin.left - baseMargin.right,
-      }),
-    [
-      containerClass,
-      y2,
-      marginOverride?.right,
-      plot.legendInHeader,
-      visible,
-      data,
-      yScale,
-      yMax,
-      tier.axisFont,
-      plot.width,
-      baseMargin.left,
-      baseMargin.right,
-    ],
-  )
-  const endLabels = endPlan?.labels ?? []
-  const margin = useMemo(
-    () =>
-      endPlan === null ? baseMargin : { ...baseMargin, right: baseMargin.right + endPlan.gutter },
-    [baseMargin, endPlan],
-  )
-
-  // ── Pass 2: the real scales, now that the plot rect is known ────────────────────────────────
-  const xMax = Math.max(plot.width - margin.left - margin.right, 0)
-
-  const xScale = useMemo(
-    () => scalePoint<string>({ domain: keys, range: [0, xMax], padding: 0.5 }),
-    [keys, xMax],
-  )
-  const y2Scale = useMemo(
-    () => (rightDomain === null ? null : buildYScale(y2, rightDomain, yMax, rightTicks)),
-    [y2, rightDomain, yMax, rightTicks],
-  )
-
-  // Resolution order: explicit VALUES win, then an explicit COUNT, then as many as fit.
-  const tickValues = useMemo(() => {
-    if (xTickValues !== undefined) return [...xTickValues(keys, xMax)]
-    if (xTicks !== undefined) return smartTicksEvery(keys, xTicks)
-    // Micro: the two terminals only.
-    if (containerClass === 'micro')
-      return keys.length > 1 ? [keys[0]!, keys[keys.length - 1]!] : keys
-    return smartTicks(keys, xMax, rotate === 0 || rotate === 45 ? tickLabelPx : undefined, tight)
-  }, [keys, xMax, xTicks, xTickValues, tickLabelPx, rotate, containerClass, tight])
-
-  const svgRef = useRef<SVGSVGElement>(null)
-  const cursor = useChartCursor<T>({
-    data,
-    chartId,
-    getKey: getX,
-    xScale,
-    marginLeft: margin.left,
-    boundaryRef: svgRef,
-    ...(cursorResolution !== undefined && { resolution: cursorResolution }),
-  })
-
-  const tooltipEnabled = tooltip !== false
-  const tooltipCfg = tooltip === false ? undefined : tooltip
-  const point = cursor.point
-  const cursorX = point === null ? null : (xScale(getX(point)) ?? null)
-  const badge = tooltipCfg?.label === undefined || point === null ? null : tooltipCfg.label(point)
-  const formatHeader = tooltipCfg?.formatHeader
-
-  // Each series falls back to ITS OWN axis's tick format, so a right-axis value is never
-  // formatted with the left axis's rules (an explicit per-series `formatValue` still wins).
-  const tooltipSeries = useMemo(
-    () =>
-      visible.map((s) =>
-        s.formatValue === undefined
-          ? { ...s, formatValue: s.axis === 'right' ? rightFormat : leftFormat }
-          : s,
-      ),
-    [visible, leftFormat, rightFormat],
-  )
-
-  // Dual axis with exactly one visible series per side: the tick labels carry that series' colour,
-  // so the axis says which line it reads. Any other split leaves both axes neutral.
-  const tintAxes = y2 !== undefined && leftSeries.length === 1 && rightSeries.length === 1
-  const leftTint = tintAxes ? alpha(leftSeries[0]!.color, AXIS_TINT_ALPHA) : undefined
-  const rightTint = tintAxes ? alpha(rightSeries[0]!.color, AXIS_TINT_ALPHA) : undefined
-
-  const rows =
-    tooltipEnabled && point !== null ? deriveTooltipRows(tooltipSeries, point, leftFormat) : []
-
-  // This chart renders its tooltip either as the cursor SOURCE (always) or, opted in via
-  // `onFollow`, as a FOLLOWER (a sibling owns the cursor). A follower has no pointer under it, so
-  // it is always positioned via the anchored (crosshair) path below, regardless of `follow`.
-  const isFollowerRender = !cursor.isSource && tooltipCfg?.onFollow === true
-  const showTooltip = tooltipEnabled && point !== null && (cursor.isSource || isFollowerRender)
-
-  // Anchored mode resolves the crosshair's plot-local x into viewport space; following mode uses
-  // the pointer position `useChartCursor` already recorded. A follower render always anchors, since
-  // `follow`'s pointer-tracking path has no pointer to read on this chart. An unset `follow` also
-  // anchors on touch (spec §5) — the readout would otherwise sit under the finger; an EXPLICIT
-  // `follow` (true or false) always wins over that default.
-  const useAnchoredPosition =
-    tooltipCfg?.follow === false ||
-    (tooltipCfg?.follow === undefined && cursor.isTouch) ||
-    isFollowerRender
-  const anchorX = useAnchoredPosition && point !== null && cursorX !== null ? cursorX : null
-  const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
-  const tooltipAnchor =
-    svgRect === undefined || anchorX === null
-      ? cursor.anchor
-      : { x: svgRect.left + margin.left + anchorX, y: svgRect.top + margin.top }
-
-  const ctx: PlotContext<T> = {
-    data,
-    visible,
-    hidden,
-    xScale,
-    yScale,
-    y2Scale,
-    xMax,
-    yMax,
-    margin,
-    cursorPoint: point,
-    highlighted,
-  }
-
-  return (
-    <>
-      <svg
-        ref={svgRef}
-        width={plot.width}
-        height={plot.height}
-        // `touch-action` on the plot `<svg>`, not the overlay `<rect>`: Chrome ignores it on an SVG
-        // child, so a horizontal scrub was claimed as a pan and cancelled (`R2C-2`).
-        style={{ touchAction: 'pan-y' }}
-      >
-        <Group left={margin.left} top={margin.top}>
-          {(y?.grid ?? true) && (
-            <GridRows scale={yScale} width={xMax} stroke={VX.grid} numTicks={leftTicks} />
-          )}
-          {xZones !== undefined && <XZoneRects zones={xZones} height={yMax} xScale={xScale} />}
-          {zones !== undefined && (
-            <ZoneRects zones={zones} width={xMax} leftScale={yScale} rightScale={y2Scale} />
-          )}
-
-          {children(ctx)}
-
-          {refLines?.map((line, i) => {
-            const scale = line.axis === 'right' && y2Scale !== null ? y2Scale : yScale
-            return (
-              <line
-                key={`${line.axis ?? 'left'}-${line.value}-${i}`}
-                x1={0}
-                x2={xMax}
-                y1={scale(line.value)}
-                y2={scale(line.value)}
-                stroke={line.color}
-                strokeWidth={1}
-                strokeDasharray={line.dashed === true ? VX.dashArray : undefined}
-              />
-            )
-          })}
-
-          {tooltipEnabled && point !== null && cursorX !== null && (
-            <>
-              <Crosshair x={cursorX} top={0} bottom={yMax} />
-              {visible.map((s) => {
-                // A dot on a bar is noise — the hovered column is already marked by the crosshair,
-                // and the dot would land inside the fill rather than on an edge a reader tracks.
-                if (s.mark === 'bar') return null
-                const value =
-                  cursorValue === undefined ? s.getValue(point) : cursorValue(point, s, visible)
-                if (value === null) return null
-                const scale = s.axis === 'right' && y2Scale !== null ? y2Scale : yScale
-                const cy = scale(value)
-                // A non-positive value on a log axis (or any other input a scale can't place)
-                // maps to NaN — the same guard the mark layer applies (`MultiLine`'s `LinePath
-                // defined`), so a stray crosshair dot never paints at `cy="NaN"`.
-                if (!Number.isFinite(cy)) return null
-                const marker = s.getMarker?.(point)
-                return (
-                  <SeriesDot
-                    key={s.key}
-                    cx={cursorX}
-                    cy={cy}
-                    color={marker?.color ?? s.color}
-                    {...(marker?.r !== undefined && { r: marker.r })}
-                  />
-                )
-              })}
-            </>
-          )}
-
-          {yPlacement !== 'none' && (
-            <AxisLeftNumeric
-              scale={yScale}
-              numTicks={leftTicks}
-              tickFormat={(v) => leftFormat(Number(v))}
-              inside={yPlacement === 'inside'}
-              {...(leftTint !== undefined && { tickColor: leftTint })}
-            />
-          )}
-          {y2Scale !== null && (
-            <AxisRightNumeric
-              scale={y2Scale}
-              left={xMax}
-              numTicks={rightTicks}
-              tickFormat={(v) => rightFormat(Number(v))}
-              {...(rightTint !== undefined && { tickColor: rightTint })}
-            />
-          )}
-          <AxisBottomDate
-            top={yMax}
-            scale={xScale}
-            tickValues={tickValues}
-            tickFormat={(v) => formatX(String(v))}
-            {...(rotate !== 0 && { rotate })}
-            anchorTerminals={tight && rotate === 0}
-            {...(wrapWidth !== undefined && { wrapWidth })}
-          />
-
-          {endLabels.map(({ series: s, y: labelY }) => (
-            <text
-              key={`end-${s.key}`}
-              x={xMax + END_LABEL_GAP}
-              y={labelY}
-              dy="0.35em"
-              fill={s.color}
-              fontFamily={TICK_FONT_FAMILY}
-              fontSize={tier.axisFont}
-              opacity={
-                highlighted === null || s.key === highlighted || s.parent === highlighted ? 1 : 0.25
-              }
-              pointerEvents="none"
-            >
-              {s.label}
-            </text>
-          ))}
-
-          <HoverOverlay
-            width={xMax}
-            height={yMax}
-            {...cursorSliderProps({ cursor: cursor, data: data, getX, formatX, ariaLabel })}
-          />
-        </Group>
-      </svg>
-
-      {showTooltip && (
-        <ChartTooltipFloat anchor={tooltipAnchor} ariaLive={cursor.isSource}>
-          <TooltipHeader
-            date={getX(point)}
-            {...(formatHeader !== undefined && {
-              format: (key: string) => formatHeader(key, point),
-            })}
-            {...(badge !== null && { label: badge.text, labelColor: badge.color })}
-          />
-          <TooltipBody>
-            {tooltipCfg?.prependRows?.(point, { visible, hidden })}
-            <TooltipRows rows={rows} />
-            {tooltipCfg?.extraRows?.(point, { visible, hidden })}
-          </TooltipBody>
-        </ChartTooltipFloat>
-      )}
-    </>
-  )
-}