basalt-ui 1.13.0 → 1.15.0

package/dist/charts/layout/auto-margin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Plot-rect margins derived from the labels that will actually be painted.
+ *
+ * `VX.margin` is a static token, so charts used to clip (or get hand-nudged) whenever a tick label
+ * outgrew it — the "I always push the charts around" failure mode. Here the token becomes a
+ * FLOOR: a measured side may only ever grow past it, never shrink below it, so no chart gets
+ * tighter than it was, and a wide label widens its own gutter automatically.
+ *
+ * See `docs/CHARTS-SPEC.md` §1.
+ */
+import type { ChartMargin } from '../../tokens/index.js';
+export type AutoMarginInput = {
+    /** Left-axis tick labels, already formatted. */
+    left?: readonly string[];
+    /** Right-axis tick labels, already formatted. Presence (not a flag) is what widens `right`. */
+    right?: readonly string[];
+    /** X-axis tick labels, already formatted. */
+    bottom?: readonly string[];
+    /** Degrees of counter-clockwise rotation applied to the x tick labels. Default 0. */
+    rotate?: number;
+    /** Tick-label font size. Default `VX.axisFont`. */
+    fontPx?: number;
+    /** Explicit per-side overrides — applied LAST, so an escape hatch always wins. */
+    override?: Partial<ChartMargin>;
+};
+/**
+ * Resolve the four margins from measured labels.
+ *
+ * Law, per side:
+ * - `left` — widest left label + gap, floored at `VX.margin.left`.
+ * - `right` — with a right axis: widest right label + gap. Without one: half the widest x label,
+ *   so the LAST x tick (centered on the plot's right edge) cannot clip. Both floored at
+ *   `VX.margin.right`.
+ * - `bottom` — one label line (or the rotated bounding height) + gap, floored at
+ *   `VX.margin.bottom`.
+ * - `top` — `VX.margin.top`. Nothing measures into it; a chart that draws into the top gutter
+ *   passes an override.
+ */
+export declare function autoMargin(input?: AutoMarginInput): ChartMargin;
+/**
+ * The tick labels a linear axis WILL paint, derived before the plot rect exists.
+ *
+ * This is what breaks the margin/scale circularity: a linear scale's tick VALUES depend only on
+ * its domain, so a throwaway-range probe yields the exact label strings {@link autoMargin} needs
+ * to measure — and returning the resolved `format` alongside them guarantees the measured string
+ * and the painted string are the same one. Shared by `CartesianChart` and by hand-composed kinds
+ * (`DualPanel`) so the two can't drift.
+ */
+export declare function probeAxisLabels(opts: {
+    domain: [number, number];
+    ticks: number;
+    /** Overrides d3's own tick format. */
+    format?: (v: number) => string;
+    /** Must match the real scale's `nice` — niceing changes which ticks exist. */
+    nice?: boolean;
+}): {
+    labels: string[];
+    format: (v: number) => string;
+};
+//# sourceMappingURL=auto-margin.d.ts.map

package/dist/charts/layout/auto-margin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-margin.d.ts","sourceRoot":"","sources":["../../../src/charts/layout/auto-margin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAa/C,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,GAAE,eAAoB,GAAG,WAAW,CA6BnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,CAQtD"}

package/dist/charts/layout/auto-margin.js

@@ -0,0 +1,37 @@
+import { scaleLinear } from "@visx/scale";
+import { VX } from "../../tokens/index.js";
+import { maxTextWidth } from "../utils/measure-text.js";
+const AXIS_TICK_GAP = 12;
+const lineHeight = (fontPx) => Math.ceil(fontPx * 1.35);
+function autoMargin(input = {}) {
+  const fontPx = input.fontPx ?? VX.axisFont;
+  const { left = [], right = [], bottom = [], rotate = 0, override } = input;
+  const leftWidth = maxTextWidth(left, fontPx);
+  const rightWidth = maxTextWidth(right, fontPx);
+  const bottomWidth = maxTextWidth(bottom, fontPx);
+  const radians = rotate * Math.PI / 180;
+  const bottomExtent = rotate === 0 ? lineHeight(fontPx) : Math.ceil(
+    Math.abs(bottomWidth * Math.sin(radians)) + Math.abs(lineHeight(fontPx) * Math.cos(radians))
+  );
+  return {
+    top: override?.top ?? VX.margin.top,
+    right: override?.right ?? Math.ceil(
+      Math.max(VX.margin.right, right.length > 0 ? rightWidth + AXIS_TICK_GAP : bottomWidth / 2)
+    ),
+    bottom: override?.bottom ?? Math.ceil(Math.max(VX.margin.bottom, bottomExtent + AXIS_TICK_GAP)),
+    left: override?.left ?? Math.ceil(Math.max(VX.margin.left, left.length > 0 ? leftWidth + AXIS_TICK_GAP : 0))
+  };
+}
+function probeAxisLabels(opts) {
+  const probe = scaleLinear({
+    domain: opts.domain,
+    range: [1, 0],
+    ...opts.nice === true && { nice: true }
+  });
+  const format = opts.format ?? probe.tickFormat(opts.ticks);
+  return { labels: probe.ticks(opts.ticks).map(format), format };
+}
+export {
+  autoMargin,
+  probeAxisLabels
+};

package/dist/charts/layout/auto-margin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auto-margin.test.d.ts.map

package/dist/charts/layout/auto-margin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-margin.test.d.ts","sourceRoot":"","sources":["../../../src/charts/layout/auto-margin.test.ts"],"names":[],"mappings":""}

package/dist/charts/primitives/CartesianChart.d.ts

@@ -0,0 +1,143 @@
+import { scaleLinear, scalePoint } from '@visx/scale';
+import type { ReactNode } from 'react';
+import type { ChartMargin } from '../../tokens/index.js';
+import type { ChartLegendConfig, ChartSeries } from '../series.js';
+import type { XZoneSpec } from './XZoneRects.js';
+import type { ZoneSpec } from './ZoneRects.js';
+type LinearScale = ReturnType<typeof scaleLinear<number>>;
+type PointScale = ReturnType<typeof scalePoint<string>>;
+/** 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 upper bound is at least this. */
+    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. */
+    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;
+};
+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;
+    /** Rows rendered BEFORE the derived per-series rows (a total, a context line). */
+    prependRows?: (d: T) => ReactNode;
+    /** Rows appended after the derived per-series rows. */
+    extraRows?: (d: T) => ReactNode;
+};
+/** 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: LinearScale;
+    /** Present only when a `y2` axis is configured. */
+    y2Scale: LinearScale | 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> = {
+    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`). */
+    xTicks?: number;
+    /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
+    formatX?: (key: string) => string;
+    /** 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?: number;
+    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;
+    ariaLabel?: string;
+    isPending?: boolean;
+    /** 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 declare 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];
+/**
+ * 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 declare function CartesianChart<T>({ data, chartId, getX, series, y, y2, xTicks, formatX, zones, xZones, refLines, height, aspectRatio, fill, legend, tooltip, margin: marginOverride, cursorValue, ariaLabel, isPending, children, }: CartesianChartProps<T>): ReactNode;
+export {};
+//# sourceMappingURL=CartesianChart.d.ts.map

package/dist/charts/primitives/CartesianChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartesianChart.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/CartesianChart.tsx"],"names":[],"mappings":"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"}

package/dist/charts/primitives/CartesianChart.js

@@ -0,0 +1,349 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { GridRows } from "@visx/grid";
+import { Group } from "@visx/group";
+import { scaleLinear, scalePoint } from "@visx/scale";
+import { useMemo, useRef, useState } from "react";
+import { VX } from "../../tokens/index.js";
+import { useChartCursor } from "../hooks/useChartCursor.js";
+import { autoMargin, probeAxisLabels } from "../layout/auto-margin.js";
+import { deriveTooltipRows } from "../series.js";
+import { padAutoLower } from "../utils/domain.js";
+import { fmtAxisDate } from "../utils/format.js";
+import { smartTicks, smartTicksEvery } from "../utils/ticks.js";
+import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from "./Axes.js";
+import { ChartFrame, resolveLegend } from "./ChartFrame.js";
+import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from "./ChartTooltip.js";
+import { Crosshair, SeriesDot } from "./Crosshair.js";
+import { HoverOverlay } from "./HoverOverlay.js";
+import { XZoneRects } from "./XZoneRects.js";
+import { ZoneRects } from "./ZoneRects.js";
+const DEFAULT_TICKS = 5;
+const DEFAULT_AUTO_PAD = 1.1;
+function resolveAxisDomain(cfg, data, series, extraBounds = []) {
+  const domain = cfg?.domain ?? "auto";
+  if (Array.isArray(domain)) return domain;
+  if (typeof domain === "function") return domain(data, series);
+  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;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  for (const v of extraBounds) {
+    if (!Number.isFinite(v)) continue;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  if (min === Infinity) return [0, cfg?.autoMaxFloor ?? 1];
+  const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD;
+  const ceil = cfg?.autoMinCeil ?? 0;
+  const paddedMax = max > 0 ? max * pad : max < 0 ? max / pad : 0;
+  const upper = Math.max(paddedMax, cfg?.autoMaxFloor ?? -Infinity);
+  const lower = padAutoLower(Math.min(min, ceil), pad);
+  if (lower === upper) return [Math.min(lower, 0), upper === 0 ? 1 : upper * pad];
+  return [lower, upper];
+}
+function CartesianChart({
+  data,
+  chartId,
+  getX,
+  series,
+  y,
+  y2,
+  xTicks,
+  formatX = fmtAxisDate,
+  zones,
+  xZones,
+  refLines,
+  height,
+  aspectRatio,
+  fill,
+  legend,
+  tooltip,
+  margin: marginOverride,
+  cursorValue,
+  ariaLabel,
+  isPending,
+  children
+}) {
+  const [highlighted, setHighlighted] = useState(null);
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      series,
+      chartId,
+      ...height !== void 0 && { height },
+      ...aspectRatio !== void 0 && { aspectRatio },
+      ...fill !== void 0 && { fill },
+      ...ariaLabel !== void 0 && { ariaLabel },
+      ...isPending !== void 0 && { isPending },
+      legend: resolveLegend(legend, { highlighted, onHighlight: setHighlighted }),
+      children: (plot) => /* @__PURE__ */ jsx(
+        CartesianPlot,
+        {
+          data,
+          chartId,
+          getX,
+          series,
+          ...y !== void 0 && { y },
+          ...y2 !== void 0 && { y2 },
+          ...xTicks !== void 0 && { xTicks },
+          formatX,
+          ...zones !== void 0 && { zones },
+          ...xZones !== void 0 && { xZones },
+          ...refLines !== void 0 && { refLines },
+          ...tooltip !== void 0 && { tooltip },
+          ...marginOverride !== void 0 && { marginOverride },
+          ...cursorValue !== void 0 && { cursorValue },
+          ...ariaLabel !== void 0 && { ariaLabel },
+          plot,
+          highlighted,
+          children
+        }
+      )
+    }
+  );
+}
+function CartesianPlot({
+  data,
+  chartId,
+  getX,
+  series,
+  y,
+  y2,
+  xTicks,
+  formatX = fmtAxisDate,
+  zones,
+  xZones,
+  refLines,
+  tooltip,
+  marginOverride,
+  cursorValue,
+  ariaLabel,
+  plot,
+  highlighted,
+  children
+}) {
+  const { hidden } = plot;
+  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]);
+  const keys = useMemo(() => data.map(getX), [data, getX]);
+  const [leftBounds, rightBounds] = useMemo(() => {
+    const left = [];
+    const right = [];
+    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 === void 0 ? null : resolveAxisDomain(y2, data, rightSeries, rightBounds),
+    [y2, data, rightSeries, rightBounds]
+  );
+  const leftTicks = y?.ticks ?? DEFAULT_TICKS;
+  const rightTicks = y2?.ticks ?? DEFAULT_TICKS;
+  const { labels: leftLabels, format: leftFormat } = useMemo(
+    () => probeAxisLabels({
+      domain: leftDomain,
+      ticks: leftTicks,
+      ...y?.format !== void 0 && { format: y.format }
+    }),
+    [leftDomain, leftTicks, y?.format]
+  );
+  const { labels: rightLabels, format: rightFormat } = useMemo(
+    () => rightDomain === null ? { labels: [], format: (v) => String(v) } : probeAxisLabels({
+      domain: rightDomain,
+      ticks: rightTicks,
+      ...y2?.format !== void 0 && { format: y2.format }
+    }),
+    [rightDomain, rightTicks, y2?.format]
+  );
+  const xLabels = useMemo(() => keys.map(formatX), [keys, formatX]);
+  const margin = useMemo(
+    () => autoMargin({
+      left: leftLabels,
+      right: rightLabels,
+      bottom: xLabels,
+      ...marginOverride !== void 0 && { override: marginOverride }
+    }),
+    [leftLabels, rightLabels, xLabels, marginOverride]
+  );
+  const xMax = Math.max(plot.width - margin.left - margin.right, 0);
+  const yMax = Math.max(plot.height - margin.top - margin.bottom, 0);
+  const xScale = useMemo(
+    () => scalePoint({ domain: keys, range: [0, xMax], padding: 0.5 }),
+    [keys, xMax]
+  );
+  const yScale = useMemo(
+    () => scaleLinear({ domain: leftDomain, range: [yMax, 0] }),
+    [leftDomain, yMax]
+  );
+  const y2Scale = useMemo(
+    () => rightDomain === null ? null : scaleLinear({ domain: rightDomain, range: [yMax, 0] }),
+    [rightDomain, yMax]
+  );
+  const tickValues = useMemo(
+    () => xTicks === void 0 ? smartTicks(keys, xMax) : smartTicksEvery(keys, xTicks),
+    [keys, xMax, xTicks]
+  );
+  const cursor = useChartCursor({
+    data,
+    chartId,
+    getKey: getX,
+    xScale,
+    marginLeft: margin.left
+  });
+  const svgRef = useRef(null);
+  const tooltipEnabled = tooltip !== false;
+  const tooltipCfg = tooltip === false ? void 0 : tooltip;
+  const point = cursor.point;
+  const cursorX = point === null ? null : xScale(getX(point)) ?? null;
+  const badge = tooltipCfg?.label === void 0 || point === null ? null : tooltipCfg.label(point);
+  const tooltipSeries = useMemo(
+    () => visible.map(
+      (s) => s.formatValue === void 0 ? { ...s, formatValue: s.axis === "right" ? rightFormat : leftFormat } : s
+    ),
+    [visible, leftFormat, rightFormat]
+  );
+  const rows = tooltipEnabled && point !== null ? deriveTooltipRows(tooltipSeries, point, leftFormat) : [];
+  const anchorX = tooltipCfg?.follow === false && point !== null && cursorX !== null ? cursorX : null;
+  const svgRect = anchorX === null ? void 0 : svgRef.current?.getBoundingClientRect();
+  const tooltipAnchor = svgRect === void 0 || anchorX === null ? cursor.anchor : { x: svgRect.left + margin.left + anchorX, y: svgRect.top + margin.top };
+  const ctx = {
+    data,
+    visible,
+    hidden,
+    xScale,
+    yScale,
+    y2Scale,
+    xMax,
+    yMax,
+    margin,
+    cursorPoint: point,
+    highlighted
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("svg", { ref: svgRef, width: plot.width, height: plot.height, children: /* @__PURE__ */ jsxs(Group, { left: margin.left, top: margin.top, children: [
+      (y?.grid ?? true) && /* @__PURE__ */ jsx(GridRows, { scale: yScale, width: xMax, stroke: VX.grid, numTicks: leftTicks }),
+      xZones !== void 0 && /* @__PURE__ */ jsx(XZoneRects, { zones: xZones, height: yMax, xScale }),
+      zones !== void 0 && /* @__PURE__ */ jsx(ZoneRects, { zones, width: xMax, leftScale: yScale, rightScale: y2Scale }),
+      children(ctx),
+      refLines?.map((line) => {
+        const scale = line.axis === "right" && y2Scale !== null ? y2Scale : yScale;
+        return /* @__PURE__ */ jsx(
+          "line",
+          {
+            x1: 0,
+            x2: xMax,
+            y1: scale(line.value),
+            y2: scale(line.value),
+            stroke: line.color,
+            strokeWidth: 1,
+            strokeDasharray: line.dashed === true ? VX.dashArray : void 0
+          },
+          `${line.axis ?? "left"}-${line.value}`
+        );
+      }),
+      tooltipEnabled && point !== null && cursorX !== null && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Crosshair, { x: cursorX, top: 0, bottom: yMax }),
+        visible.map((s) => {
+          if (s.mark === "bar") return null;
+          const value = cursorValue === void 0 ? s.getValue(point) : cursorValue(point, s, visible);
+          if (value === null) return null;
+          const scale = s.axis === "right" && y2Scale !== null ? y2Scale : yScale;
+          const marker = s.getMarker?.(point);
+          return /* @__PURE__ */ jsx(
+            SeriesDot,
+            {
+              cx: cursorX,
+              cy: scale(value),
+              color: marker?.color ?? s.color,
+              ...marker?.r !== void 0 && { r: marker.r }
+            },
+            s.key
+          );
+        })
+      ] }),
+      /* @__PURE__ */ jsx(
+        AxisLeftNumeric,
+        {
+          scale: yScale,
+          numTicks: leftTicks,
+          tickFormat: (v) => leftFormat(Number(v))
+        }
+      ),
+      y2Scale !== null && /* @__PURE__ */ jsx(
+        AxisRightNumeric,
+        {
+          scale: y2Scale,
+          left: xMax,
+          numTicks: rightTicks,
+          tickFormat: (v) => rightFormat(Number(v))
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        AxisBottomDate,
+        {
+          top: yMax,
+          scale: xScale,
+          tickValues,
+          tickFormat: (v) => formatX(String(v))
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        HoverOverlay,
+        {
+          width: xMax,
+          height: yMax,
+          onMove: cursor.onPointerMove,
+          onLeave: cursor.onPointerLeave,
+          onKeyDown: cursor.onKeyDown,
+          onBlur: cursor.onBlur,
+          valueMax: Math.max(data.length - 1, 0),
+          ...point !== null && {
+            valueNow: data.indexOf(point),
+            valueText: formatX(getX(point))
+          },
+          ...ariaLabel !== void 0 && { ariaLabel }
+        }
+      )
+    ] }) }),
+    tooltipEnabled && cursor.isSource && point !== null && /* @__PURE__ */ jsxs(ChartTooltipFloat, { anchor: tooltipAnchor, children: [
+      /* @__PURE__ */ jsx(
+        TooltipHeader,
+        {
+          date: getX(point),
+          ...badge !== null && { label: badge.text, labelColor: badge.color }
+        }
+      ),
+      /* @__PURE__ */ jsxs(TooltipBody, { children: [
+        tooltipCfg?.prependRows?.(point),
+        rows.map((row) => /* @__PURE__ */ jsx(
+          TooltipRow,
+          {
+            color: row.color,
+            label: row.label,
+            value: row.value,
+            shape: row.shape,
+            dashed: row.dashed,
+            ...row.strokeWidth !== void 0 && { strokeWidth: row.strokeWidth }
+          },
+          row.key
+        )),
+        tooltipCfg?.extraRows?.(point)
+      ] })
+    ] })
+  ] });
+}
+export {
+  CartesianChart,
+  resolveAxisDomain
+};

package/dist/charts/primitives/CartesianChart.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CartesianChart.test.d.ts.map

package/dist/charts/primitives/CartesianChart.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartesianChart.test.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/CartesianChart.test.ts"],"names":[],"mappings":""}

package/dist/charts/primitives/ChartFrame.d.ts

@@ -12,6 +12,13 @@ export type ChartFrameLegend = {
     /** Hover-dim wiring lifted from the kind — optional. */
     highlighted?: string | null;
     onHighlight?: (key: string | null) => void;
+    /**
+     * Clicking a legend entry hides that series. Defaults to true whenever there is more than one
+     * entry to toggle between — hiding the only series a chart draws is never useful. The hidden
+     * key set reaches the marks through the `children` render prop, so a hidden series leaves the
+     * plot, the tooltip, and the auto domain together (`docs/CHARTS-SPEC.md` §5).
+     */
+    toggle?: boolean;
 };
 export type ChartFrameProps = {
     /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
@@ -41,11 +48,15 @@ export type ChartFrameProps = {
      * kind composing `ChartFrame` should accept and forward this from its own props.
      */
     ariaLabel?: string;
-    /** Draw the SVG marks given the plot rect that already excludes the legend band. */
-    children: (plot: {
-        width: number;
-        height: number;
-    }) => ReactNode;
+    /** Draw the SVG marks given the plot rect that already excludes the legend band, plus the set
+     * of series keys the legend has toggled off. */
+    children: (plot: PlotRect) => ReactNode;
+};
+/** What `ChartFrame` hands its child: the resolved plot rect plus legend-toggle state. */
+export type PlotRect = {
+    width: number;
+    height: number;
+    hidden: ReadonlySet<string>;
 };
 /** A kind's own hover-dim wiring, merged into the resolved `ChartFrameLegend`. Kinds without
  * per-series highlight state (single-series `ZonedLine`, `DualPanel`) omit this. */

package/dist/charts/primitives/ChartFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC3C,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,QAAQ,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,SAAS,CAAA;CACjE,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,GAC5B,gBAAgB,GAAG,KAAK,CAQ1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAmD7B"}
+{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAOhF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oDACgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAA;CACxC,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,GAC5B,gBAAgB,GAAG,KAAK,CAS1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAsE7B"}