basalt-ui 1.41.0 → 2.0.0

package/src/charts/panel.tsx

@@ -0,0 +1,227 @@
+/**
+ * The composed-chart infrastructure `DualPanel` and `MirroredBars` share (`docs/V2-SPEC.md` § 9.2):
+ * two TanStack views composed with `composeViews` + `grid` + `alignX` into ONE definition — one
+ * host, one cursor, one tooltip — mounted by the rung's own `ChartShell`. A kind supplies a
+ * `PanelPlan` (its two panes and its tooltip rows) per legend state; everything else — size, legend,
+ * `state`, cursor binding, tooltip surface, guides — is the rung's or lives here once.
+ */
+import { crosshair } from '@tanstack/charts/crosshair'
+import { tooltip as tooltipHost } from '@tanstack/charts/tooltip'
+import { portal } from '@tanstack/charts/tooltip/portal'
+import type {
+  ChartBuildContext,
+  ChartPoint,
+  ChartTooltipRow as EngineTooltipRow,
+  ChartValue,
+  StoredChartSpec,
+} from '@tanstack/charts/types/core'
+import { alignX, composeViews, grid } from '@tanstack/charts/view'
+import type { ComposableResponsiveChartDefinition } from '@tanstack/charts/view'
+import { useCallback } from 'react'
+import type { ReactElement } from 'react'
+import { ChartShell } from './CartesianChart'
+import type { ChartShellProps, ShellContext } from './CartesianChart'
+import { defaultFormatX, utcHeaderDate, visibleSeries, xGuide, yGuide } from './compile'
+import type { CartesianDefinition } from './compile'
+import { cursorBinding, sourceOnlyFocus } from './cursor'
+import type { XScaleModel } from './scales'
+import { CHART_THEME, CROSSHAIR } from './theme'
+import type { ContainerClass } from '../tokens/size-classes'
+import type {
+  CartesianChartProps,
+  ChartMarks,
+  ChartSeries,
+  ChartTooltipRow,
+  ChartX,
+  PlotRow,
+} from './types'
+
+/** One pane, built per container class: its marks and its scales (x, y, and any helper scale). */
+export type PaneBuilder = (ctx: ChartBuildContext) => {
+  marks: ChartMarks
+  scales: StoredChartSpec['scales']
+}
+
+/** Everything a composed kind compiles for one legend state. */
+export type PanelPlan<T> = {
+  /** Every x value the cursor can land on, for snapping a foreign cursor. */
+  keys: readonly ChartX[]
+  top: PaneBuilder
+  bottom: PaneBuilder
+  /** The top pane's share of the grid, 0..1. */
+  topFraction: number
+  /** Space between the panes in px. */
+  gap: number
+  /** The per-series tooltip rows for a hovered datum; `tooltip.rows` and the title are the rung's. */
+  rows: (d: T) => readonly EngineTooltipRow[]
+}
+
+export type PanelInput = {
+  hidden: ReadonlySet<string>
+  highlighted: string | null
+  /** The measured chart width, only when the rung is asked for it (`byWidth`), otherwise 0. */
+  width: number
+}
+
+export type PanelRungProps<T, X extends ChartX> = Omit<ChartShellProps<T>, 'compile'> &
+  Pick<CartesianChartProps<T, X>, 'formatX' | 'cursorGroup' | 'cursorResolution' | 'tooltip'> & {
+    plan: (input: PanelInput) => PanelPlan<T>
+    /** Recompile on width changes: for a kind whose data depends on it (`fold`). */
+    byWidth?: boolean
+  }
+
+/** A child's theme may not carry a background or focus ring: the composed chart owns them. */
+const { background: _background, focusRing: _focusRing, ...PANE_THEME } = CHART_THEME
+
+/** The least share of the height either pane keeps: the grid needs positive tracks. */
+const MIN_PANE_SHARE = 0.02
+
+/** A pane's y axis: the scale and the rung's guide for it. */
+export const paneY = (opts: {
+  scale: ChartScale
+  domain: readonly [number, number]
+  format: (v: number) => string
+  ticks: number
+  cls: ContainerClass
+}): StoredChartSpec['scales'][string] => ({
+  scale: opts.scale,
+  ...yGuide({
+    cfg: { ticks: opts.ticks },
+    axis: { domain: opts.domain, format: opts.format },
+    cls: opts.cls,
+    side: 'left',
+    grid: true,
+  }),
+})
+
+type ChartScale = NonNullable<StoredChartSpec['scales'][string]>['scale']
+
+/** The shared x axis (drawn on the bottom pane only): the rung's ticks and format. */
+export const paneX = <X extends ChartX>(opts: {
+  scale: ChartScale
+  model: XScaleModel<X>
+  format: (v: ChartValue) => string
+  cls: ContainerClass
+}): StoredChartSpec['scales'][string] => ({
+  scale: opts.scale,
+  ...xGuide({ model: opts.model, xTicks: undefined, format: opts.format, cls: opts.cls }),
+})
+
+/** One row per datum for a series: a `null` or non-finite value is kept as a gap. */
+export function rowsOf<T, X extends ChartX>(
+  data: readonly T[],
+  x: (d: T) => X,
+  s: ChartSeries<T>,
+): PlotRow<T, X>[] {
+  return data.map((d) => {
+    const v = s.getValue(d)
+    return { x: x(d), y: v === null || !Number.isFinite(v) ? null : v, series: s.key, datum: d }
+  })
+}
+
+/** A pane as a composable view. The crosshair is per pane: together they span both. */
+function paneView(build: PaneBuilder): ComposableResponsiveChartDefinition {
+  return {
+    chart: (ctx) => {
+      const { marks, scales } = build(ctx)
+      return {
+        marks: [...marks, crosshair({ x: CROSSHAIR, y: false })],
+        scales,
+        theme: PANE_THEME,
+        clip: true,
+      }
+    },
+  }
+}
+
+/** A plotted datum is a `PlotRow` of an owned series: its source datum. Otherwise the datum is `T`. */
+function sourceOf<T>(point: ChartPoint, owned: ReadonlySet<string>): { x: ChartValue; d: T } {
+  const datum = point.datum
+  if (typeof datum === 'object' && datum !== null && 'datum' in datum && 'series' in datum) {
+    const row = datum as PlotRow<T>
+    if (owned.has(row.series)) return { x: point.xValue, d: row.datum }
+  }
+  return { x: point.xValue, d: datum as T }
+}
+
+type DefinitionProps<T, X extends ChartX> = Pick<PanelRungProps<T, X>, 'series'> & {
+  [K in 'formatX' | 'cursorGroup' | 'cursorResolution' | 'tooltip']: PanelRungProps<T, X>[K]
+}
+
+function panelDefinition<T, X extends ChartX>(
+  props: DefinitionProps<T, X>,
+  ctx: ShellContext,
+  plan: PanelPlan<T>,
+): CartesianDefinition {
+  const { series, formatX, cursorGroup, cursorResolution = 'nearest' } = props
+  const { hidden, chartId } = ctx
+  const tooltip = props.tooltip === false ? undefined : props.tooltip
+  // A share outside 0..1 (or NaN) is clamped to leave each pane a sliver rather than throw.
+  const top = Number.isFinite(plan.topFraction)
+    ? Math.min(Math.max(plan.topFraction, MIN_PANE_SHARE), 1 - MIN_PANE_SHARE)
+    : 0.5
+  const composed = composeViews({
+    views: { top: paneView(plan.top), bottom: paneView(plan.bottom) },
+    layout: grid({
+      rows: [
+        { id: 'top', grow: top },
+        { id: 'bottom', grow: 1 - top },
+      ],
+      columns: [{ id: 'main', grow: 1 }],
+      gap: plan.gap,
+      cells: { top: { row: 'top', column: 'main' }, bottom: { row: 'bottom', column: 'main' } },
+    }),
+    links: [alignX('top', 'bottom')],
+  })
+  const owned = new Set(series.map((s) => s.key))
+  const visible = visibleSeries(series, hidden)
+  const hiddenSeries = series.filter((s) => !visible.includes(s))
+  const header = (v: ChartValue, d: T): string => {
+    if (tooltip?.formatHeader) return tooltip.formatHeader(v as X, d)
+    if (v instanceof Date && !formatX) return utcHeaderDate(v)
+    return formatX ? formatX(v as X) : defaultFormatX(v)
+  }
+  return {
+    chart: () => composed,
+    focus: tooltip?.onFollow ? 'group-x' : sourceOnlyFocus(cursorGroup, chartId),
+    maxFocusDistance: Number.POSITIVE_INFINITY,
+    cursor: cursorBinding({
+      group: cursorGroup,
+      chartId,
+      keys: plan.keys,
+      mode: cursorResolution,
+      pin: ctx.coarse,
+    }),
+    tooltip:
+      props.tooltip === false
+        ? false
+        : {
+            use: tooltipHost,
+            portal,
+            anchor: 'group-center',
+            content: (points: readonly ChartPoint[]) => {
+              const primary = points[0]
+              if (!primary) return { rows: [] }
+              const { x, d } = sourceOf<T>(primary, owned)
+              const extra: readonly ChartTooltipRow[] =
+                tooltip?.rows?.(d, { visible, hidden: hiddenSeries }) ?? []
+              return { title: header(x, d), rows: [...plan.rows(d), ...extra] }
+            },
+          },
+  }
+}
+
+export function PanelRung<T, X extends ChartX>(props: PanelRungProps<T, X>): ReactElement {
+  const { plan, byWidth, formatX, cursorGroup, cursorResolution, tooltip, ...shell } = props
+  const { series } = shell
+  const compile = useCallback(
+    (ctx: ShellContext) =>
+      panelDefinition(
+        { series, formatX, cursorGroup, cursorResolution, tooltip },
+        ctx,
+        plan({ hidden: ctx.hidden, highlighted: ctx.highlighted, width: ctx.width }),
+      ),
+    [series, formatX, cursorGroup, cursorResolution, tooltip, plan],
+  )
+  return <ChartShell {...shell} compile={compile} {...(byWidth !== undefined && { byWidth })} />
+}

package/src/charts/scales.ts

@@ -0,0 +1,237 @@
+/**
+ * Scales basalt owns (`docs/V2-SPEC.md` § 9.1): every y domain, and the x scale by value type
+ * (§ 9.4). TanStack receives CONFIGURED instances, never a factory: a factory infers its domain from
+ * every scale-contributing mark (a 60–100 zone widened a 30–70 line's axis to 0–100) and cannot see
+ * a legend-hidden series.
+ */
+import { scaleBand } from '@tanstack/charts/scales/band'
+import { scaleLinear } from '@tanstack/charts/scales/linear'
+import { scalePoint } from '@tanstack/charts/scales/point'
+import { scaleLog, scaleUtc } from 'd3-scale'
+import type { ChartPositionScaleOptions } from '@tanstack/charts/types/core'
+import type { AxisConfig, ChartSeries, ChartX, XZoneSpec } from './types'
+
+const DEFAULT_AUTO_PAD = 1.1
+
+/** Pad AWAY from zero: a positive floor moves down, a negative one further down; zero stays. */
+export function padAutoLower(candidate: number, pad: number): number {
+  if (candidate === 0) return 0
+  return candidate > 0 ? candidate / pad : candidate * pad
+}
+
+/** The mirror of {@link padAutoLower}: a positive ceiling moves up, a negative one toward zero. */
+export function padAutoUpper(candidate: number, pad: number): number {
+  if (candidate === 0) return 0
+  return candidate > 0 ? candidate * pad : candidate / pad
+}
+
+/**
+ * One y axis' domain. `extraBounds` are the finite zone and reference-line values pinned to this
+ * axis — a target past the data must stay inside the plot. Infinite bounds clamp to the domain by
+ * definition and are ignored. The 1.x law, unchanged (`resolveAxisDomain`).
+ */
+export function resolveYDomain<T>(
+  cfg: AxisConfig<T> | undefined,
+  data: readonly T[],
+  series: readonly ChartSeries<T>[],
+  extraBounds: readonly number[] = [],
+): readonly [number, number] {
+  const domain = cfg?.domain ?? 'auto'
+  if (Array.isArray(domain)) return domain as readonly [number, number]
+  if (typeof domain === 'function') return domain(data, series)
+
+  const isLog = cfg?.scale === 'log'
+  let min = Infinity
+  let max = -Infinity
+  const take = (v: number | null): void => {
+    if (v === null || !Number.isFinite(v)) return
+    // A log axis has no zero and no negative half: such a value drops out of the domain.
+    if (isLog && v <= 0) return
+    if (v < min) min = v
+    if (v > max) max = v
+  }
+  for (const d of data) for (const s of series) take(s.getValue(d))
+  for (const v of extraBounds) take(v)
+
+  const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD
+  if (isLog) {
+    if (min === Infinity) return [1, 10]
+    if (min === max) return [min / pad, max * pad]
+    return [min / pad, padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)]
+  }
+  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1]
+
+  // Clamp the RAW bounds first, then pad once, away from zero: padding before the clamp lands a
+  // floored top exactly on the floor, with a target line glued to the plot edge.
+  const upper = padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)
+  const lower = padAutoLower(Math.min(min, cfg?.autoMinCeil ?? 0), pad)
+  // A flat series would be a scale with no extent: every point on one pixel.
+  if (lower === upper) return [Math.min(lower, 0), upper === 0 ? 1 : upper * pad]
+  return [lower, upper]
+}
+
+/** A configured y scale instance for a resolved domain. */
+export function yScaleFor<T>(
+  cfg: AxisConfig<T> | undefined,
+  domain: readonly [number, number],
+): ReturnType<typeof scaleLinear> | ReturnType<typeof scaleLog<number, number>> {
+  const extent: [number, number] = [domain[0], domain[1]]
+  if (cfg?.scale === 'log') {
+    const log = scaleLog().domain(extent)
+    return cfg.nice ? log.nice() : log
+  }
+  const linear = scaleLinear().domain(extent)
+  return cfg?.nice ? linear.nice() : linear
+}
+
+export type XKind = 'date' | 'number' | 'string'
+
+/** The value type `x` returns, read off the first row (a chart's x is homogeneous by type). */
+export function xKindOf(values: readonly ChartX[]): XKind {
+  const first = values[0]
+  if (first instanceof Date) return 'date'
+  if (typeof first === 'number') return 'number'
+  return 'string'
+}
+
+const keyOf = (v: ChartX): number | string => (v instanceof Date ? v.getTime() : v)
+
+/** Distinct x values in data order (dates by timestamp). */
+export function distinctX<X extends ChartX>(values: readonly X[]): X[] {
+  const seen = new Set<number | string>()
+  const out: X[] = []
+  for (const v of values) {
+    const k = keyOf(v)
+    if (seen.has(k)) continue
+    seen.add(k)
+    out.push(v)
+  }
+  return out
+}
+
+/** Point-scale padding for a categorical line: half a step at each edge. */
+const POINT_PADDING = 0.5
+/** Band padding for bars: the gap between two bars, and the inset at the plot's ends. */
+const BAND_PADDING_INNER = 0.2
+const BAND_PADDING_OUTER = 0.1
+
+/**
+ * The x scale and the normalized position of any x value inside the plot (0 = left edge, 1 = right
+ * edge). Zones and x-zones are drawn on a hidden `[0, 1]` scale from those fractions, so a band
+ * spans the plot exactly whatever the x scale is.
+ */
+export type XScaleModel<X extends ChartX> = {
+  kind: XKind
+  band: boolean
+  /** Goes straight into `scales.x.scale`. */
+  scale: ChartPositionScaleOptions['scale']
+  values: readonly X[]
+  /** Center of `x` as a plot fraction; `null` for a value the scale does not contain. */
+  fraction: (x: X) => number | null
+  /** Half a sample step, as a plot fraction (the `'edge'` widening). */
+  halfStep: number
+  /** Continuous scales: the domain as numbers (ms for dates), and the median sample step. */
+  extent?: readonly [number, number]
+  step: number
+}
+
+const DAY_MS = 86_400_000
+
+export function xScaleFor<X extends ChartX>(raw: readonly X[], band: boolean): XScaleModel<X> {
+  const values = distinctX(raw)
+  const kind = xKindOf(values)
+  const n = values.length
+
+  if (band || kind === 'string') {
+    const keys = values as X[]
+    const index = new Map(keys.map((k, i) => [keyOf(k), i] as const))
+    if (band) {
+      const step = 1 / Math.max(1, n - BAND_PADDING_INNER + 2 * BAND_PADDING_OUTER)
+      const scale = scaleBand<X>()
+        .domain(keys)
+        .paddingInner(BAND_PADDING_INNER)
+        .paddingOuter(BAND_PADDING_OUTER)
+      return {
+        kind,
+        band: true,
+        scale,
+        values: keys,
+        halfStep: step / 2,
+        step: 1,
+        fraction: (x) => {
+          const i = index.get(keyOf(x))
+          if (i === undefined) return null
+          return step * (BAND_PADDING_OUTER + i + (1 - BAND_PADDING_INNER) / 2)
+        },
+      }
+    }
+    const step = 1 / Math.max(1, n - 1 + 2 * POINT_PADDING)
+    return {
+      kind,
+      band: false,
+      scale: scalePoint<X>().domain(keys).padding(POINT_PADDING),
+      values: keys,
+      halfStep: step / 2,
+      step: 1,
+      fraction: (x) => {
+        const i = index.get(keyOf(x))
+        return i === undefined ? null : step * (POINT_PADDING + i)
+      },
+    }
+  }
+
+  const nums = values.map((v) => (v instanceof Date ? v.getTime() : (v as number)))
+  // A loop, not Math.min(...nums): a spread of a long series overflows the call stack.
+  let lo = Infinity
+  let hi = -Infinity
+  for (const v of nums) {
+    // NaN poisons the extent, as Math.min/max did: the guard below falls back to [0, 1].
+    if (Number.isNaN(v)) {
+      lo = hi = NaN
+      break
+    }
+    if (v < lo) lo = v
+    if (v > hi) hi = v
+  }
+  if (!Number.isFinite(lo)) [lo, hi] = [0, 1]
+  if (lo === hi) {
+    // One sample: give the axis a day (or a unit) of width so the point sits in the middle.
+    const half = kind === 'date' ? DAY_MS / 2 : 0.5
+    lo -= half
+    hi += half
+  }
+  const span = hi - lo
+  const sorted = nums.toSorted((a, b) => a - b)
+  const gaps = sorted.slice(1).map((v, i) => v - (sorted[i] as number))
+  const medianGap = gaps.length ? (gaps.toSorted((a, b) => a - b)[gaps.length >> 1] as number) : 0
+  const scale =
+    kind === 'date'
+      ? scaleUtc().domain([new Date(lo), new Date(hi)])
+      : scaleLinear().domain([lo, hi])
+  return {
+    kind,
+    band: false,
+    scale,
+    values,
+    halfStep: medianGap / span / 2,
+    extent: [lo, hi],
+    step: medianGap,
+    fraction: (x) => {
+      const v = x instanceof Date ? x.getTime() : (x as number)
+      return typeof v === 'number' && Number.isFinite(v) ? (v - lo) / span : null
+    },
+  }
+}
+
+/** An x-zone's [left, right] as plot fractions, clamped to the plot; `null` when it is empty. */
+export function xZoneFractions<X extends ChartX>(
+  zone: XZoneSpec<X>,
+  model: XScaleModel<X>,
+): readonly [number, number] | null {
+  const widen = zone.align === 'edge' ? model.halfStep : 0
+  const from = zone.from === undefined ? 0 : (model.fraction(zone.from) ?? 0) - widen
+  const to = zone.to === undefined ? 1 : (model.fraction(zone.to) ?? 1) + widen
+  const left = Math.max(0, Math.min(from, to))
+  const right = Math.min(1, Math.max(from, to))
+  return right > left ? [left, right] : null
+}

package/src/charts/sizing.ts

@@ -0,0 +1,47 @@
+/**
+ * The measured-width seam (`docs/V2-SPEC.md` § 9.2, § 9.6): the chart root's width, for the compiled
+ * definition's ticks and fonts. Nothing here sizes the box: `box.tsx` and `chart-box.module.css`
+ * own the height in CSS so it exists before JS runs (W10 SSR contract).
+ */
+import { useCallback, useRef, useState } from 'react'
+import type { RefCallback } from 'react'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
+import { useCoarsePointer } from '../common/use-media-query'
+
+/** Server and first-paint width before the host measures (TanStack `initialWidth`): the regular
+ * class, so SSR markup and the first client frame agree. Only the svg's internal geometry follows
+ * the real width; the box around it is already final. */
+export const INITIAL_WIDTH = 640
+
+/** Measures the width of the element `ref` lands on (`0` until measured, e.g. on the server). */
+export function useChartSize(): {
+  ref: RefCallback<HTMLElement>
+  width: number
+  coarse: boolean
+} {
+  const [width, setWidth] = useState(0)
+  const [node, setNode] = useState<HTMLElement | null>(null)
+  const coarse = useCoarsePointer()
+  const last = useRef(0)
+
+  useIsomorphicLayoutEffect(() => {
+    if (!node) return
+    const read = (w: number): void => {
+      const rounded = Math.round(w)
+      if (rounded === last.current) return
+      last.current = rounded
+      setWidth(rounded)
+    }
+    read(node.getBoundingClientRect().width)
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (entry) read(entry.contentRect.width)
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [node])
+
+  const ref = useCallback<RefCallback<HTMLElement>>((el) => setNode(el), [])
+  return { ref, width, coarse }
+}

package/src/charts/state.tsx

@@ -0,0 +1,80 @@
+/**
+ * The "nothing to draw" placeholders: pending → error → empty, in that precedence. One renderer for
+ * the chart chrome and `ChartCard`, so a pending card and a pending chart read the same.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import { toErrorMessage } from '../common/errors'
+import { VX } from '../tokens'
+import { ChartBox, stateClass } from './box'
+import type { ChartBoxHeight } from './box'
+import type { ChartState } from './types'
+
+export type ResolvedChartState = 'pending' | 'error' | 'empty' | null
+
+export function resolveChartState(state: ChartState | undefined): ResolvedChartState {
+  if (!state) return null
+  if (state.pending) return 'pending'
+  if (state.error) return 'error'
+  if (state.empty) return 'empty'
+  return null
+}
+
+const boxStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  justifyContent: 'center',
+  gap: 6,
+  color: VX.axis,
+  fontSize: VX.text.xs,
+  textAlign: 'center',
+}
+
+const pendingStyle: CSSProperties = {
+  ...boxStyle,
+  borderRadius: VX.radiusCtrl,
+  background: `linear-gradient(90deg, transparent, ${VX.surface.subtle}, transparent)`,
+}
+
+const emptyLabel = (state: ChartState | undefined): string =>
+  typeof state?.empty === 'string' ? state.empty : 'No data'
+
+/** Fills the same {@link ChartBox} the chart will, so a pending, failed or empty chart (and a
+ * `<Suspense>` fallback built from one) occupies the final chart's height. */
+export function ChartPlaceholder(props: {
+  state: ChartState | undefined
+  height?: ChartBoxHeight
+  action?: ReactNode
+}): ReactElement | null {
+  const kind = resolveChartState(props.state)
+  if (kind === null) return null
+  const style = kind === 'pending' ? pendingStyle : boxStyle
+  const fit = (node: ReactElement): ReactElement => (
+    <ChartBox height={props.height}>{node}</ChartBox>
+  )
+  if (kind === 'pending')
+    return fit(
+      <output aria-label="Loading chart" aria-busy="true" className={stateClass} style={style} />,
+    )
+  const label =
+    kind === 'error'
+      ? toErrorMessage(props.state?.error, 'The chart failed to load.')
+      : emptyLabel(props.state)
+  const body = (
+    <>
+      <span>{label}</span>
+      {props.action}
+    </>
+  )
+  if (kind === 'error')
+    return fit(
+      <div role="alert" data-basalt-chart-state={kind} className={stateClass} style={style}>
+        {body}
+      </div>,
+    )
+  return fit(
+    <output data-basalt-chart-state={kind} className={stateClass} style={style}>
+      {body}
+    </output>,
+  )
+}

package/src/charts/theme.ts

@@ -0,0 +1,65 @@
+/**
+ * The `--vx-*` → TanStack Charts bridge (`docs/V2-SPEC.md` § 9.5). Two halves, both CSS-variable
+ * references, so a scheme switch repaints without rebuilding a definition:
+ *
+ *  - `CHART_THEME` goes into every definition's `theme` (scene paint: guides, grid, focus ring).
+ *  - `CHART_ENGINE_VARS` (`--ts-chart-*`: palette, tooltip, crosshair halo) is one `:root` block
+ *    (`chartEngineCss`) inside `styles.css`. Not on the host element: the tooltip portal's fallback
+ *    reparents the tooltip under `<body>`, out of the host's inheritance. Not in `buildPaletteCss`:
+ *    that emitter stays engine-agnostic.
+ */
+import type { ChartTheme } from '@tanstack/charts/types/core'
+import { VX } from '../tokens'
+
+export const CHART_THEME: Partial<ChartTheme> = {
+  foreground: 'var(--vx-ink2)',
+  muted: 'var(--vx-axis)',
+  grid: 'var(--vx-grid)',
+  background: 'transparent',
+  palette: [
+    'var(--ts-chart-1)',
+    'var(--ts-chart-2)',
+    'var(--ts-chart-3)',
+    'var(--ts-chart-4)',
+    'var(--ts-chart-5)',
+    'var(--ts-chart-6)',
+  ],
+}
+
+export const CHART_ENGINE_VARS: Readonly<Record<`--ts-chart-${string}`, string>> = {
+  '--ts-chart-1': 'var(--vx-line)',
+  '--ts-chart-2': 'var(--vx-accent)',
+  '--ts-chart-3': 'var(--vx-fill-cyan)',
+  '--ts-chart-4': 'var(--vx-fill-orange)',
+  '--ts-chart-5': 'var(--vx-fill-grape)',
+  '--ts-chart-6': 'var(--vx-fill-lime)',
+  '--ts-chart-tooltip-background': 'var(--vx-tooltip-bg)',
+  '--ts-chart-tooltip-color': 'var(--vx-tooltip-text)',
+  '--ts-chart-tooltip-border': 'var(--vx-tooltip-border)',
+  '--ts-chart-tooltip-shadow': 'var(--vx-tooltip-shadow)',
+  '--ts-chart-tooltip-border-radius': 'var(--vx-radius-ctrl)',
+  '--ts-chart-crosshair-label-halo': 'var(--vx-surface-panel)',
+  '--ts-chart-crosshair-marker-fill': 'var(--vx-surface-panel)',
+  '--ts-chart-focus-fill': 'var(--vx-surface-panel)',
+}
+
+/**
+ * The charts layer's stylesheet block: one `:root` rule. `styles.css` carries the same declarations
+ * (formatter-laid-out) between two generated markers — `scripts/gen-chart-css.ts` writes them from this
+ * function's output, and `engine.test.tsx` fails on drift, whitespace aside — so the
+ * source tree a Vite alias or the layout fixture serves and the published `dist/styles.css` agree.
+ */
+export function chartEngineCss(): string {
+  const decls = Object.entries(CHART_ENGINE_VARS).map(([name, value]) => `${name}:${value}`)
+  return `:root{${decls.join(';')}}`
+}
+
+/** Guide paint every definition shares — the tokens are pre-mixed, so nothing dilutes them. */
+export const AXIS_LINE = { stroke: VX.axisStroke, strokeOpacity: 1 } as const
+export const GRID_LINE = { strokeDasharray: '2 3', strokeOpacity: 1 } as const
+export const CROSSHAIR = { stroke: VX.crosshair, strokeOpacity: 1, strokeDasharray: '3 3' } as const
+export const DASH = VX.dashArray
+/** The default plotted stroke: the redesign's 1.9px line overlay. */
+export const LINE_STROKE_WIDTH = 1.9
+/** A series' opacity multiplier while ANOTHER legend entry is hovered (one value for every kind). */
+export const DIMMED = 0.25