basalt-ui 1.14.0 → 1.16.0

package/dist/charts/kinds/ZonedLine.js

@@ -1,216 +1,136 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { curveMonotoneX } from "@visx/curve";
-import { GridRows } from "@visx/grid";
-import { Group } from "@visx/group";
-import { scaleLinear, scalePoint } from "@visx/scale";
 import { AreaClosed, LinePath } from "@visx/shape";
 import { Threshold } from "@visx/threshold";
 import { memo, useMemo } from "react";
 import { AreaGradient, areaFillUrl } from "../primitives/AreaGradient.js";
-import { AxisBottomDate, AxisLeftNumeric } from "../primitives/Axes.js";
-import {
-  ChartTooltip,
-  TooltipBody,
-  TooltipHeader,
-  TooltipRow,
-  useTooltipStyles
-} from "../primitives/ChartTooltip.js";
-import { ChartFrame, resolveLegend } from "../primitives/ChartFrame.js";
-import { Crosshair, SeriesDot } from "../primitives/Crosshair.js";
-import { HoverOverlay } from "../primitives/HoverOverlay.js";
-import { ZoneRects } from "../primitives/ZoneRects.js";
-import { useHoverSync } from "../hooks/useHoverSync.js";
-import { deriveTooltipRows, LINE_OVERLAY_STROKE_WIDTH } from "../series.js";
+import { CartesianChart } from "../primitives/CartesianChart.js";
+import { LINE_OVERLAY_STROKE_WIDTH } from "../series.js";
 import { VX } from "../../tokens/index.js";
-import { padAutoLower } from "../utils/domain.js";
-import { smartTicks, smartTicksEvery } from "../utils/ticks.js";
+function validPoints(series, data) {
+  if (!series) return [];
+  const out = [];
+  for (const d of data) {
+    const y = series.getValue(d);
+    if (y !== null && y !== void 0 && !Number.isNaN(y)) {
+      out.push(Object.assign({}, d, { __y: y }));
+    }
+  }
+  return out;
+}
 function ZonedLineInner(props) {
-  const { series, chartId, height, legend, ariaLabel, isPending } = props;
+  const {
+    data,
+    chartId,
+    getX,
+    series,
+    y,
+    zones,
+    xZones,
+    thresholds,
+    refLines,
+    xTicks,
+    tooltip,
+    areaFill,
+    height,
+    legend,
+    ariaLabel,
+    isPending
+  } = props;
   const styledSeries = useMemo(
-    () => series.map((s) => ({ ...s, strokeWidth: s.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH })),
+    () => series.map((s) => ({
+      ...s,
+      strokeWidth: s.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH
+    })),
     [series]
   );
   return /* @__PURE__ */ jsx(
-    ChartFrame,
+    CartesianChart,
     {
-      series: styledSeries,
+      data,
       chartId,
+      getX,
+      series: styledSeries,
+      ...y !== void 0 && { y },
+      ...zones !== void 0 && { zones },
+      ...xZones !== void 0 && { xZones },
+      ...refLines !== void 0 && { refLines },
+      ...xTicks !== void 0 && { xTicks },
+      ...tooltip !== void 0 && { tooltip },
       ...height !== void 0 && { height },
+      ...legend !== void 0 && { legend },
       ...ariaLabel !== void 0 && { ariaLabel },
       ...isPending !== void 0 && { isPending },
-      legend: resolveLegend(legend),
-      children: (plot) => /* @__PURE__ */ jsx(ZonedLinePlot, { ...props, series: styledSeries, plot })
+      children: (ctx) => /* @__PURE__ */ jsx(
+        ZonedLineMarks,
+        {
+          getX,
+          chartId,
+          thresholds: thresholds ?? [],
+          areaFill,
+          ctx
+        }
+      )
     }
   );
 }
-function ZonedLinePlot(props) {
-  const {
-    data,
-    chartId,
-    getX,
-    series,
-    yDomain,
-    yAutoPad = 1.1,
-    yAutoMaxFloor,
-    yAutoMinCeil = 0,
-    zones = [],
-    thresholds = [],
-    refLines = [],
-    numTicksY = 5,
-    numTicksX,
-    tooltipLabel,
-    formatValue,
-    renderExtraTooltipRows,
-    areaFill,
-    plot
-  } = props;
-  const primary = series[0];
-  const MARGIN = VX.margin;
-  const xMax = plot.width - MARGIN.left - MARGIN.right;
-  const yMax = plot.height - MARGIN.top - MARGIN.bottom;
+function ZonedLineMarks({
+  getX,
+  chartId,
+  thresholds,
+  areaFill,
+  ctx
+}) {
+  const { data, visible, xScale, yScale, yMax } = ctx;
+  const primary = visible[0];
+  const valid = useMemo(() => validPoints(primary, data), [primary, data]);
   const showArea = areaFill !== void 0 && areaFill !== false;
   const areaColor = typeof areaFill === "string" ? areaFill : primary?.color;
   const areaId = `${chartId}-area`;
-  const valid = useMemo(() => {
-    const out = [];
-    for (const d of data) {
-      const y = primary?.getValue(d) ?? null;
-      if (y !== null && y !== void 0 && !Number.isNaN(y)) {
-        out.push(Object.assign({}, d, { __y: y }));
-      }
-    }
-    return out;
-  }, [data, primary]);
-  const xScale = useMemo(
-    () => scalePoint({
-      // Full calendar — axis does not compress across nulls.
-      domain: data.map(getX),
-      range: [0, xMax],
-      padding: 0.3
-    }),
-    [data, xMax, getX]
-  );
-  const yScale = useMemo(() => {
-    if (yDomain === "auto") {
-      const ys = valid.map((d) => d.__y);
-      const dataMax = ys.length ? Math.max(...ys) : 0;
-      const dataMin = ys.length ? Math.min(...ys) : 0;
-      const upper = Math.max(dataMax, yAutoMaxFloor ?? dataMax) * yAutoPad;
-      const lower = padAutoLower(Math.min(dataMin, yAutoMinCeil), yAutoPad);
-      return scaleLinear({ domain: [lower, upper], range: [yMax, 0], nice: true });
-    }
-    return scaleLinear({ domain: yDomain, range: [yMax, 0] });
-  }, [valid, yDomain, yMax, yAutoPad, yAutoMaxFloor, yAutoMinCeil]);
-  const tooltipStyles = useTooltipStyles();
-  const { tip, tooltipRef, syncedPoint, isDirectHover, handleMouse, handleLeave } = useHoverSync({
-    data: valid,
-    chartId,
-    getKey: getX,
-    xScale,
-    marginLeft: MARGIN.left
-  });
-  const tickValues = useMemo(
-    () => numTicksX ? smartTicksEvery(data.map(getX), numTicksX) : smartTicks(data.map(getX), xMax),
-    [data, xMax, getX, numTicksX]
-  );
-  const tooltipLbl = tip ? tooltipLabel?.(tip.data) ?? null : null;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx("svg", { width: plot.width, height: plot.height, children: /* @__PURE__ */ jsxs(Group, { left: MARGIN.left, top: MARGIN.top, children: [
-      /* @__PURE__ */ jsx(GridRows, { scale: yScale, width: xMax, stroke: VX.grid, numTicks: numTicksY }),
-      /* @__PURE__ */ jsx(ZoneRects, { zones, width: xMax, leftScale: yScale }),
-      thresholds.map((t, i) => /* @__PURE__ */ jsx(
-        Threshold,
-        {
-          id: `${chartId}-thr-${i}`,
-          data: valid,
-          x: (d) => xScale(getX(d)) ?? 0,
-          y0: () => yScale(t.value),
-          y1: (d) => yScale(d.__y),
-          clipAboveTo: 0,
-          clipBelowTo: yMax,
-          curve: curveMonotoneX,
-          belowAreaProps: { fill: t.side === "above" ? t.fill : "transparent" },
-          aboveAreaProps: { fill: t.side === "below" ? t.fill : "transparent" }
-        },
-        `thr-${i}`
-      )),
-      showArea && areaColor !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx(AreaGradient, { id: areaId, color: areaColor }) }),
-        /* @__PURE__ */ jsx(
-          AreaClosed,
-          {
-            data: valid,
-            x: (d) => xScale(getX(d)) ?? 0,
-            y: (d) => yScale(d.__y),
-            yScale,
-            curve: curveMonotoneX,
-            fill: areaFillUrl(areaId)
-          }
-        )
-      ] }),
-      refLines.map((r, i) => /* @__PURE__ */ jsx(
-        "line",
-        {
-          x1: 0,
-          x2: xMax,
-          y1: yScale(r.value),
-          y2: yScale(r.value),
-          stroke: r.color,
-          strokeDasharray: r.dashed ? VX.dashArray : void 0
-        },
-        `ref-${i}`
-      )),
-      primary && /* @__PURE__ */ jsx(
-        LinePath,
+    thresholds.map((t, i) => /* @__PURE__ */ jsx(
+      Threshold,
+      {
+        id: `${chartId}-thr-${i}`,
+        data: valid,
+        x: (d) => xScale(getX(d)) ?? 0,
+        y0: () => yScale(t.value),
+        y1: (d) => yScale(d.__y),
+        clipAboveTo: 0,
+        clipBelowTo: yMax,
+        curve: curveMonotoneX,
+        belowAreaProps: { fill: t.side === "above" ? t.fill : "transparent" },
+        aboveAreaProps: { fill: t.side === "below" ? t.fill : "transparent" }
+      },
+      `thr-${i}`
+    )),
+    showArea && areaColor !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx(AreaGradient, { id: areaId, color: areaColor }) }),
+      /* @__PURE__ */ jsx(
+        AreaClosed,
         {
           data: valid,
           x: (d) => xScale(getX(d)) ?? 0,
           y: (d) => yScale(d.__y),
-          stroke: primary.color,
-          strokeWidth: primary.strokeWidth ?? VX.lineWidth,
-          strokeDasharray: primary.dash === "dashed" ? VX.dashArray : void 0,
-          curve: curveMonotoneX
-        }
-      ),
-      syncedPoint && primary && /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(Crosshair, { x: xScale(getX(syncedPoint)) ?? 0, top: 0, bottom: yMax }),
-        /* @__PURE__ */ jsx(
-          SeriesDot,
-          {
-            cx: xScale(getX(syncedPoint)) ?? 0,
-            cy: yScale(syncedPoint.__y),
-            color: primary.color
-          }
-        )
-      ] }),
-      /* @__PURE__ */ jsx(AxisLeftNumeric, { scale: yScale, numTicks: numTicksY }),
-      /* @__PURE__ */ jsx(AxisBottomDate, { top: yMax, scale: xScale, tickValues }),
-      /* @__PURE__ */ jsx(HoverOverlay, { width: xMax, height: yMax, onMove: handleMouse, onLeave: handleLeave })
-    ] }) }),
-    /* @__PURE__ */ jsx(ChartTooltip, { tip: isDirectHover ? tip : null, tooltipRef, styles: tooltipStyles, children: tip && isDirectHover && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(
-        TooltipHeader,
-        {
-          date: getX(tip.data),
-          ...tooltipLbl !== null && { label: tooltipLbl.text, labelColor: tooltipLbl.color }
+          yScale,
+          curve: curveMonotoneX,
+          fill: areaFillUrl(areaId)
         }
-      ),
-      /* @__PURE__ */ jsxs(TooltipBody, { children: [
-        deriveTooltipRows(series, tip.data, formatValue).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
-        )),
-        renderExtraTooltipRows?.(tip.data)
-      ] })
-    ] }) })
+      )
+    ] }),
+    primary && /* @__PURE__ */ jsx(
+      LinePath,
+      {
+        data: valid,
+        x: (d) => xScale(getX(d)) ?? 0,
+        y: (d) => yScale(d.__y),
+        stroke: primary.color,
+        strokeWidth: primary.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH,
+        strokeDasharray: primary.dash === "dashed" ? VX.dashArray : void 0,
+        strokeOpacity: primary.strokeOpacity ?? 1,
+        curve: curveMonotoneX
+      }
+    )
   ] });
 }
 const ZonedLine = memo(ZonedLineInner);

package/dist/charts/kinds/ZonedLine.test.d.ts

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

package/dist/charts/kinds/ZonedLine.test.d.ts.map

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

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,161 @@
+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;
+    /**
+     * 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;
+};
+/** 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;
+    /** 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;
+};
+/** 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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"}