@pond-ts/charts 0.31.0

package/dist/ChartContainer.js

@@ -0,0 +1,306 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { scaleLinear, scaleTime } from 'd3-scale';
+import { ContainerContext, } from './context.js';
+import { maxSlotWidths, sum } from './slots.js';
+import { resolveCursorX, DEFAULT_CURSOR_MODE } from './tracker.js';
+import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
+import { TimeAxis } from './TimeAxis.js';
+import { defaultTheme } from './theme.js';
+/** Time-axis tick count — matches `<TimeAxis>` so the cursor-time formatter is
+ *  calibrated as the time-axis labels are. */
+const TIME_TICK_COUNT = 5;
+/**
+ * Normalize the `range` prop — a `[begin, end]` tuple or a `TimeRange` — to a
+ * plain `[number, number]`, or `undefined` when omitted (→ auto-fit). The
+ * `'begin' in range` check distinguishes the `TimeRange` from the tuple (a
+ * tuple has no `begin` key).
+ */
+function normalizeRange(range) {
+    if (range === undefined)
+        return undefined;
+    return 'begin' in range ? [range.begin(), range.end()] : [range[0], range[1]];
+}
+/**
+ * The top of the chart layout (react-timeseries-charts-style). Owns the shared
+ * **x geometry**: it collects each row's per-slot gutter widths, reserves each
+ * slot's max across rows (so the innermost axis aligns column-by-column and
+ * every row's plot left-aligns), and from the slot sums derives `plotWidth` and
+ * the shared time `xScale`. It renders its rows (separated by `rowGap`) then one
+ * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
+ * (`<YAxis>`).
+ */
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, timeFormat, theme, children, }) {
+    // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
+    // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
+    // is the placeholder while auto-fitting.
+    const explicitDomain = normalizeRange(range);
+    const seed = explicitDomain ?? [0, 1];
+    // View range: pan/zoom moves it. Controlled (onTimeRangeChange) reads the prop
+    // and routes gestures back through the callback; uncontrolled holds it
+    // internally. With panZoom off, the seed is used directly — so a static or live
+    // (sliding-prop) chart tracks the prop as before.
+    const [internalRange, setInternalRange] = useState([
+        seed[0],
+        seed[1],
+    ]);
+    const uncontrolled = panZoom && onTimeRangeChange === undefined;
+    // While the internal view isn't in use (not uncontrolled), keep it synced to
+    // the prop — so *entering* uncontrolled pan/zoom (toggling panZoom on, or a
+    // controlled→uncontrolled switch) starts from the current range, not the
+    // mount-time one. While uncontrolled, leave it alone so a range change
+    // can't fight the user's pan. (Adjusting state during render — React re-renders
+    // before commit, no extra paint; the guard makes it converge in one step.)
+    if (!uncontrolled &&
+        (internalRange[0] !== seed[0] || internalRange[1] !== seed[1])) {
+        setInternalRange([seed[0], seed[1]]);
+    }
+    const view = uncontrolled ? internalRange : seed;
+    const t0 = view[0];
+    const t1 = view[1];
+    // Latest onTimeRangeChange in a ref so applyRange stays stable. Written after
+    // commit (not in render) so a gesture never reads a callback from a frame that
+    // was abandoned under concurrent rendering.
+    const onRangeRef = useRef(onTimeRangeChange);
+    useLayoutEffect(() => {
+        onRangeRef.current = onTimeRangeChange;
+    });
+    const applyRange = useCallback((range) => {
+        const cb = onRangeRef.current;
+        if (cb)
+            cb(range);
+        else
+            setInternalRange(range);
+    }, []);
+    // Cross-row tracker. We store the cursor's plot-pixel x (not a timestamp), so a
+    // still cursor stays put while a live window slides under it; a controlled
+    // `trackerPosition` resolves to a pixel below.
+    const [hoverX, setHoverX] = useState(null);
+    // Draw layers register as tracker sources; on hover we fan in their values at
+    // the cursor and hand them out via onTrackerChanged (held in a ref so an
+    // inline callback doesn't churn the frame). This powers a readout rendered
+    // *outside* the chart — the preferred surface for hover values.
+    const [sources, setSources] = useState(() => new Map());
+    const registerTrackerSource = useCallback((key, source) => setSources((m) => new Map(m).set(key, source)), []);
+    const unregisterTrackerSource = useCallback((key) => {
+        setSources((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    // The shared x scale's kind, **inferred from the registered layers**: a
+    // ValueSeries row plots on a value axis, a TimeSeries on time. A container
+    // has one shared x (the synced cursor's whole point), so the rows must agree
+    // — a mix is a hard error. Defaults to `'time'` until a layer registers (the
+    // two-pass: register → re-resolve → rescale).
+    const resolvedKind = useMemo(() => {
+        let kind;
+        for (const s of sources.values()) {
+            if (kind === undefined)
+                kind = s.xKind;
+            else if (kind !== s.xKind) {
+                throw new Error(`ChartContainer: rows mix x-axis kinds ('${kind}' and '${s.xKind}'). ` +
+                    `A container has one shared x axis — every row must plot the same ` +
+                    `kind (all time-keyed, or all value-keyed).`);
+            }
+        }
+        return kind ?? 'time';
+    }, [sources]);
+    // Auto-fit extent — the union of the layers' x extents — used as the domain
+    // when no explicit `range` is given. (Same source registry as the kind; the
+    // two-pass register→resolve applies.)
+    const autoExtent = useMemo(() => {
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (const s of sources.values()) {
+            const e = s.xExtent();
+            if (e) {
+                if (e[0] < lo)
+                    lo = e[0];
+                if (e[1] > hi)
+                    hi = e[1];
+            }
+        }
+        return lo <= hi ? [lo, hi] : null;
+    }, [sources]);
+    const onTrackerRef = useRef(onTrackerChanged);
+    onTrackerRef.current = onTrackerChanged;
+    // Selection: controlled (`selected` prop) or uncontrolled (internal). A click
+    // on a selectable layer calls `select()` after hit-testing; `onSelect` notifies
+    // in both modes, the internal state is managed only when uncontrolled. The full
+    // SelectInfo is the identity (key + series), so multi-series marks at one
+    // timestamp stay distinct. Refs written after commit (not in render) so the
+    // click handler never reads a callback / mode from a frame abandoned under
+    // concurrent rendering.
+    const [internalSelected, setInternalSelected] = useState(null);
+    const controlledSelection = selected !== undefined;
+    const selectedValue = controlledSelection
+        ? (selected ?? null)
+        : internalSelected;
+    const onSelectRef = useRef(onSelect);
+    const controlledSelectionRef = useRef(controlledSelection);
+    useLayoutEffect(() => {
+        onSelectRef.current = onSelect;
+        controlledSelectionRef.current = controlledSelection;
+    });
+    const select = useCallback((hit) => {
+        onSelectRef.current?.(hit);
+        if (!controlledSelectionRef.current)
+            setInternalSelected(hit);
+    }, []);
+    // Hover-highlight: the transient mark under the pointer (distinct from the
+    // committed selection). Deduped by key+label so the data canvas repaints only
+    // when the hovered mark changes — not on every pointer move (the move itself
+    // just slides the SVG cursor, which never touches the data canvas).
+    const [hovered, setHoveredState] = useState(null);
+    const setHovered = useCallback((hit) => {
+        setHoveredState((prev) => prev === hit ||
+            (prev !== null &&
+                hit !== null &&
+                prev.key === hit.key &&
+                prev.label === hit.label)
+            ? prev
+            : hit);
+    }, []);
+    // Rows report their per-slot gutter widths; we reserve each slot's max.
+    const [gutters, setGutters] = useState([]);
+    const registerGutter = useCallback((req) => {
+        setGutters((g) => [...g, req]);
+        return () => setGutters((g) => g.filter((x) => x !== req));
+    }, []);
+    // Rows register on mount so we can mark the first (topmost) one — the shared
+    // cursor-time chip shows there only. Effect order = mount order = top-to-bottom
+    // for siblings, so the first row registers first (`rowKeys[0]`); this is robust
+    // even when rows are wrapped in a fragment/helper component, where an index
+    // injected into our direct children wouldn't reach through the wrapper.
+    const [rowKeys, setRowKeys] = useState([]);
+    const registerRow = useCallback((key) => {
+        setRowKeys((k) => (k.includes(key) ? k : [...k, key]));
+        return () => setRowKeys((k) => k.filter((x) => x !== key));
+    }, []);
+    const firstRowKey = rowKeys[0] ?? null;
+    const leftSlots = useMemo(() => maxSlotWidths(gutters.map((g) => g.left)), [gutters]);
+    const rightSlots = useMemo(() => maxSlotWidths(gutters.map((g) => g.right)), [gutters]);
+    const leftGutter = sum(leftSlots);
+    const rightGutter = sum(rightSlots);
+    const plotWidth = Math.max(0, width - leftGutter - rightGutter);
+    // The resolved x domain: while panning an explicit domain it's the live view
+    // (t0/t1); otherwise the auto-fit extent (→ [0, 1] before any layer registers,
+    // the two-pass settle). This is what the scale + cursor + axis read.
+    const [d0, d1] = explicitDomain !== undefined ? [t0, t1] : (autoExtent ?? [0, 1]);
+    // The shared x scale + the formatter for its ticks / cursor readout, built
+    // together so each branch keeps its concrete scale type (no casts): a value
+    // axis is a `scaleLinear` formatted by `resolveAxisFormat`, time is a
+    // `scaleTime` formatted by d3's multi-scale `resolveTimeFormat`. `formatTime`
+    // is the one formatter <TimeAxis> + the cursor readout share, so a tick and
+    // the cursor read identically. (The `formatTime` name predates the value axis
+    // — on a value axis it formats the value, not a time.)
+    const { xScale, formatTime } = useMemo(() => {
+        if (resolvedKind === 'value') {
+            const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
+            return {
+                xScale: s,
+                formatTime: resolveAxisFormat(s, TIME_TICK_COUNT, timeFormat),
+            };
+        }
+        const s = scaleTime().domain([d0, d1]).range([0, plotWidth]);
+        return {
+            xScale: s,
+            formatTime: resolveTimeFormat(s, TIME_TICK_COUNT, timeFormat),
+        };
+    }, [resolvedKind, d0, d1, plotWidth, timeFormat]);
+    // The crosshair pixel (see resolveCursorX). A stored hoverX is a *plot* pixel;
+    // if plotWidth changes mid-hover (a gutter reserving, or a width change) it's
+    // briefly stale until the next pointer move — rare, and the bounds check below
+    // hides an out-of-plot crosshair meanwhile.
+    const cursorX = resolveCursorX(trackerPosition, hoverX, xScale);
+    // Emit { time, values } for an outside readout — recomputed as the cursor moves
+    // *or* the window slides under it (xScale change → new time at the same pixel).
+    // Out of the plot (null, or a controlled trackerPosition d3 extrapolated past
+    // the edges) → no readout, matching the hidden overlay; the ref guard keeps a
+    // not-hovering live chart from spamming `null`.
+    const lastNullRef = useRef(false);
+    useEffect(() => {
+        const cb = onTrackerRef.current;
+        if (cb === undefined)
+            return;
+        if (cursorX === null || cursorX < 0 || cursorX > plotWidth) {
+            if (!lastNullRef.current)
+                cb(null);
+            lastNullRef.current = true;
+            return;
+        }
+        lastNullRef.current = false;
+        const time = +xScale.invert(cursorX);
+        const values = Array.from(sources.values()).flatMap((s) => s.sampleAt(time));
+        cb({ time, values });
+    }, [cursorX, xScale, sources, plotWidth]);
+    const frame = useMemo(() => ({
+        timeRange: [d0, d1],
+        width,
+        theme: theme ?? defaultTheme,
+        plotWidth,
+        leftSlots,
+        rightSlots,
+        leftGutter,
+        rightGutter,
+        rowGap,
+        cursorX,
+        setHoverX,
+        selected: selectedValue,
+        select,
+        hovered,
+        setHovered,
+        cursor,
+        cursorTime,
+        formatTime,
+        registerTrackerSource,
+        unregisterTrackerSource,
+        xScale,
+        xKind: resolvedKind,
+        panZoom,
+        minDuration,
+        applyRange,
+        registerGutter,
+        registerRow,
+        firstRowKey,
+    }), [
+        d0,
+        d1,
+        width,
+        theme,
+        plotWidth,
+        leftSlots,
+        rightSlots,
+        leftGutter,
+        rightGutter,
+        rowGap,
+        cursorX,
+        selectedValue,
+        select,
+        hovered,
+        setHovered,
+        cursor,
+        cursorTime,
+        formatTime,
+        registerTrackerSource,
+        unregisterTrackerSource,
+        xScale,
+        resolvedKind,
+        panZoom,
+        minDuration,
+        applyRange,
+        registerGutter,
+        registerRow,
+        firstRowKey,
+    ]);
+    return (_jsx(ContainerContext.Provider, { value: frame, children: _jsxs("div", { style: { width: `${width}px` }, children: [_jsx("div", { style: {
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: `${rowGap}px`,
+                    }, children: children }), showAxis && _jsx(TimeAxis, {})] }) }));
+}
+//# sourceMappingURL=ChartContainer.js.map

package/dist/ChartRow.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import { type CursorMode } from './context.js';
+export interface ChartRowProps {
+    /** Row height in CSS pixels. */
+    height: number;
+    /** Cursor presentation for this row, overriding the container's default
+     *  ({@link ChartContainerProps.cursor}). Omit to inherit. See {@link CursorMode}. */
+    cursor?: CursorMode;
+    children?: ReactNode;
+}
+/**
+ * A horizontal band sharing the container's time axis. `ChartRow` owns the
+ * **horizontal layout** (axes left/right around a `<Layers>` plot area) and
+ * coordinates the row's two registries — axes (`<YAxis>`) and draw layers
+ * (`<LineChart>`, registered through `<Layers>`). From the layers it derives a
+ * y-scale **per axis** (each axis auto-fits the layers linked to it, or uses its
+ * explicit `[min, max]`), and provides them via context.
+ *
+ * The x geometry (plot width, time scale) is shared and lives on the
+ * {@link ChartContainer}: the row reports its per-slot gutter widths so the
+ * container can reserve each slot's max, then sizes each axis to its slot and
+ * pads the outer slots it lacks, so its plot left-aligns with every other row
+ * under the one time axis.
+ *
+ * Children lay out left-to-right in author order, so `<YAxis side="left"/>` goes
+ * before `<Layers/>` and `<YAxis side="right"/>` after.
+ */
+export declare function ChartRow({ height, cursor, children }: ChartRowProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ChartRow.d.ts.map

package/dist/ChartRow.js

@@ -0,0 +1,215 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import { scaleLinear } from 'd3-scale';
+import { resolveYDomain } from './domain.js';
+import { resolveAxisFormat } from './format.js';
+import { placeAxisSlots } from './slots.js';
+import { useSlotKey } from './use-slot-key.js';
+import { YAxis } from './YAxis.js';
+import { ContainerContext, RowContext, } from './context.js';
+/** Sentinel id for the implicit axis a row gets when no `<YAxis>` is declared. */
+const IMPLICIT_AXIS_ID = '__default__';
+/** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
+ *  so the readout formatter is calibrated exactly as the labels are. */
+const AXIS_TICK_COUNT = 5;
+/**
+ * A horizontal band sharing the container's time axis. `ChartRow` owns the
+ * **horizontal layout** (axes left/right around a `<Layers>` plot area) and
+ * coordinates the row's two registries — axes (`<YAxis>`) and draw layers
+ * (`<LineChart>`, registered through `<Layers>`). From the layers it derives a
+ * y-scale **per axis** (each axis auto-fits the layers linked to it, or uses its
+ * explicit `[min, max]`), and provides them via context.
+ *
+ * The x geometry (plot width, time scale) is shared and lives on the
+ * {@link ChartContainer}: the row reports its per-slot gutter widths so the
+ * container can reserve each slot's max, then sizes each axis to its slot and
+ * pads the outer slots it lacks, so its plot left-aligns with every other row
+ * under the one time axis.
+ *
+ * Children lay out left-to-right in author order, so `<YAxis side="left"/>` goes
+ * before `<Layers/>` and `<YAxis side="right"/>` after.
+ */
+export function ChartRow({ height, cursor, children }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<ChartRow> must be rendered inside a <ChartContainer>');
+    }
+    // Register on mount so the container can mark the first (topmost) row by
+    // mount order — the shared cursor-time chip renders there only.
+    const rowKey = useSlotKey();
+    const { registerRow } = container;
+    useEffect(() => registerRow(rowKey), [registerRow, rowKey]);
+    const isFirstRow = container.firstRowKey === rowKey;
+    // Keyed by a stable per-instance id (Map preserves insertion order; setting an
+    // existing key updates in place). So a re-register on a prop change keeps the
+    // entry's slot — the axis-default (first axis) and layer z-order stay stable
+    // across updates; only mount/unmount reorders. (registerAxis/Layer return
+    // void and update in place — *not* unregister-and-append, which would let a
+    // min/max or series change silently rebind axes / reorder the z-stack.)
+    const [axes, setAxes] = useState(() => new Map());
+    const [layers, setLayers] = useState(() => new Map());
+    const registerAxis = useCallback((key, spec) => {
+        setAxes((m) => new Map(m).set(key, spec));
+    }, []);
+    const unregisterAxis = useCallback((key) => {
+        setAxes((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const registerLayer = useCallback((key, entry) => {
+        setLayers((m) => new Map(m).set(key, entry));
+    }, []);
+    const unregisterLayer = useCallback((key) => {
+        setLayers((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    // Layers in declaration order (the z-stack) — sorted by their injected JSX
+    // index, so order follows the markup regardless of mount timing.
+    const layerList = useMemo(() => Array.from(layers.values()).sort((a, b) => a.index - b.index), [layers]);
+    // Real declared axes in declaration order (by injected index) — the rendered
+    // <YAxis> children, as [slot key, spec] so layout can key off the per-instance
+    // symbol (not the data id, which may repeat across a mirror). A row with none
+    // gets a single implicit auto-domain axis, for *scaling* only (zero width, not
+    // rendered), so it still has a default.
+    const realEntries = useMemo(() => Array.from(axes.entries()).sort((a, b) => a[1].index - b[1].index), [axes]);
+    const realAxes = useMemo(() => realEntries.map(([, spec]) => spec), [realEntries]);
+    const effectiveAxes = useMemo(() => realAxes.length > 0
+        ? realAxes
+        : [
+            {
+                id: IMPLICIT_AXIS_ID,
+                side: 'left',
+                width: 0,
+                min: undefined,
+                max: undefined,
+                format: undefined,
+                index: 0,
+            },
+        ], [realAxes]);
+    const defaultAxisId = effectiveAxes[0].id;
+    // This row's axes per side (as {key, width}), in slot order (slot 0 = innermost,
+    // nearest the plot). Left axes are authored outer→inner so reverse them; right
+    // axes are authored inner→outer already. Reported to the container as the
+    // per-slot widths it maxes across rows.
+    const { leftAxes, rightAxes, ownLeftSlots, ownRightSlots } = useMemo(() => {
+        const l = [];
+        const r = [];
+        for (const [key, spec] of realEntries) {
+            (spec.side === 'left' ? l : r).push({ key, width: spec.width });
+        }
+        return {
+            leftAxes: l,
+            rightAxes: r,
+            ownLeftSlots: l.map((a) => a.width).reverse(),
+            ownRightSlots: r.map((a) => a.width),
+        };
+    }, [realEntries]);
+    const { registerGutter } = container;
+    const gutterReq = useMemo(() => ({ left: ownLeftSlots, right: ownRightSlots }), [ownLeftSlots, ownRightSlots]);
+    // Depend on the *stable* registerGutter (a useCallback) + the memoized req —
+    // not the container frame, which is recreated whenever the reservation
+    // changes (depending on it would loop register → re-render → re-register).
+    useEffect(() => registerGutter(gutterReq), [registerGutter, gutterReq]);
+    // Map each axis id to its reserved slot width + the outer-slot padding this
+    // row lacks (see placeAxisSlots — slot 0 nearest the plot, pad keeps the plot
+    // aligned). Falls back to own width until the container has reserved.
+    const containerLeftSlots = container.leftSlots;
+    const containerRightSlots = container.rightSlots;
+    const { axisSlots, leftPad, rightPad } = useMemo(() => placeAxisSlots(leftAxes, rightAxes, containerLeftSlots, containerRightSlots), [leftAxes, rightAxes, containerLeftSlots, containerRightSlots]);
+    // One y-scale per axis. A layer counts toward an axis when its (late-resolved)
+    // axis id matches; `resolveYDomain` handles the auto-fit + empty/flat/inverted
+    // edges. yExtent() is O(points), so only walk the layers when a bound auto-fits.
+    const yScales = useMemo(() => {
+        const map = new Map();
+        for (const ax of effectiveAxes) {
+            const extents = ax.min === undefined || ax.max === undefined
+                ? layerList
+                    .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
+                    .map((entry) => entry.layer.yExtent())
+                : [];
+            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents);
+            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, 0]));
+        }
+        return map;
+    }, [effectiveAxes, layerList, height, defaultAxisId]);
+    // A value formatter per axis (its `format` resolved against its scale) — shared
+    // by the axis tick labels and the cursor readout so a value reads the same.
+    const formats = useMemo(() => {
+        const map = new Map();
+        for (const ax of effectiveAxes) {
+            const sc = yScales.get(ax.id);
+            if (sc)
+                map.set(ax.id, resolveAxisFormat(sc, AXIS_TICK_COUNT, ax.format));
+        }
+        return map;
+    }, [effectiveAxes, yScales]);
+    const frame = useMemo(() => ({
+        height,
+        cursor,
+        isFirstRow,
+        yScales,
+        formats,
+        defaultAxisId,
+        axisSlots,
+        registerAxis,
+        unregisterAxis,
+        registerLayer,
+        unregisterLayer,
+        layers: layerList,
+    }), [
+        height,
+        cursor,
+        isFirstRow,
+        yScales,
+        formats,
+        defaultAxisId,
+        axisSlots,
+        registerAxis,
+        unregisterAxis,
+        registerLayer,
+        unregisterLayer,
+        layerList,
+    ]);
+    // Inject each direct child's JSX position so axes register their declaration
+    // order (the default-axis source). `<Layers>` receives an index too (harmless
+    // — it's not an axis) and injects its own into the draw layers.
+    const indexedChildren = Children.map(children, (child, index) => isValidElement(child)
+        ? cloneElement(child, { index })
+        : child);
+    // Place axes by their `side`, not by JSX author position — so a `side="right"`
+    // axis always renders right of the plot (and a left axis left), **consistent
+    // with the side-based gutter reservation above**. (Author position only
+    // injects the index, which still drives slot order within a side + the
+    // default-axis pick.) This makes `side` the single source of truth for both
+    // placement *and* reserved space; mis-authoring can no longer desync them
+    // (the bug: a right axis authored before `<Layers>` rendered left while its
+    // gutter was reserved right). Non-axis children (`<Layers>`) stay in the middle.
+    const leftAxisEls = [];
+    const plotEls = [];
+    const rightAxisEls = [];
+    for (const child of indexedChildren ?? []) {
+        if (isValidElement(child) && child.type === YAxis) {
+            const side = child.props.side ?? 'left';
+            (side === 'right' ? rightAxisEls : leftAxisEls).push(child);
+        }
+        else {
+            plotEls.push(child);
+        }
+    }
+    return (_jsx(RowContext.Provider, { value: frame, children: _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'row',
+                width: `${container.width}px`,
+                height: `${height}px`,
+            }, children: [leftPad > 0 && _jsx("div", { style: { flex: `0 0 ${leftPad}px` } }), leftAxisEls, plotEls, rightAxisEls, rightPad > 0 && _jsx("div", { style: { flex: `0 0 ${rightPad}px` } })] }) }));
+}
+//# sourceMappingURL=ChartRow.js.map

package/dist/Layers.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+export interface LayersProps {
+    children?: ReactNode;
+}
+/**
+ * The plot area of a {@link ChartRow}: a single `<canvas>` plus the draw-layer
+ * registry. It is the boundary where the row's horizontal layout flips to
+ * z-stacking — child layers ({@link LineChart}, …) register here and paint into
+ * the one canvas, each with its own axis's y-scale (looked up by the layer's
+ * `axis` id, defaulting to the row's default axis).
+ *
+ * **Z-order — declaration order, last child on top** (SVG / DOM / RTC). A row is
+ * authored back-to-front: `<BandChart/>` then `<LineChart/>` puts the line over
+ * its band. Order comes from each child's **injected JSX index** (so the stack
+ * follows the markup regardless of mount timing — a layer toggled in between two
+ * others slots into place, not onto the top), and each layer keeps a stable,
+ * id-keyed slot so a series/style update holds its position (no jump to the
+ * front — the trap that bites live charts). Draw layers must be **direct
+ * children** of `<Layers>` for the index to reach them.
+ */
+export declare function Layers({ children }: LayersProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Layers.d.ts.map