@pond-ts/charts 0.31.0

package/dist/Layers.js

@@ -0,0 +1,399 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
+import { Canvas } from './Canvas.js';
+import { drawGrid } from './grid.js';
+import { cursorParts } from './tracker.js';
+import { resolveSelection } from './select.js';
+import { panRange, zoomRange } from './viewport.js';
+import { ContainerContext, LayersContext, RowContext, } from './context.js';
+/** Gridline tick count — matches the axes (`YAxis`/`TimeAxis`) so they align. */
+const GRID_TICKS = 5;
+/** Wheel-zoom sensitivity: `factor = exp(deltaY * k)` (one ~100px notch ≈ ±15%). */
+const ZOOM_SENSITIVITY = 0.0015;
+/** Pointer slop (px): a drag must exceed this before it pans, and a click within
+ *  it still selects. One threshold for both so a click never also nudges the pan
+ *  (and never hit-tests against a shifted scale). */
+const DRAG_SLOP = 4;
+/** Past this fraction of the plot, a readout label flips left of its dot so it
+ *  doesn't overflow the right edge. */
+const LABEL_FLIP_FRACTION = 0.85;
+/**
+ * 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 function Layers({ children }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<Layers> must be rendered inside a <ChartContainer>');
+    }
+    const row = useContext(RowContext);
+    if (row === null) {
+        throw new Error('<Layers> must be rendered inside a <ChartRow>');
+    }
+    const registry = useMemo(() => ({
+        registerLayer: row.registerLayer,
+        unregisterLayer: row.unregisterLayer,
+    }), [row.registerLayer, row.unregisterLayer]);
+    const background = container.theme.background;
+    const { grid: gridColor, gridDash } = container.theme.axis;
+    const { layers, yScales, formats, defaultAxisId } = row;
+    // x geometry is shared and lives on the container (uniform across rows).
+    const { xScale, plotWidth } = container;
+    const draw = useCallback((ctx, w, h) => {
+        if (background !== undefined) {
+            ctx.fillStyle = background;
+            ctx.fillRect(0, 0, w, h);
+        }
+        // Gridlines behind the data, from the same ticks the axes label: vertical
+        // from the shared time scale, horizontal from the row's default y-axis.
+        const gridY = yScales.get(defaultAxisId);
+        const xTicks = xScale.ticks(GRID_TICKS).map((d) => xScale(d));
+        const yTicks = gridY ? gridY.ticks(GRID_TICKS).map((t) => gridY(t)) : [];
+        drawGrid(ctx, xTicks, yTicks, w, h, gridColor, gridDash);
+        for (const entry of layers) {
+            const yScale = yScales.get(entry.axisId ?? defaultAxisId);
+            if (yScale === undefined)
+                continue;
+            entry.layer.draw(ctx, xScale, yScale);
+        }
+    }, [layers, yScales, xScale, defaultAxisId, background, gridColor, gridDash]);
+    // Interaction overlay: the cursor marks live on a DOM/SVG overlay above the
+    // data, so hovering never repaints the data canvas (whose `draw` doesn't depend
+    // on the cursor). Reading the container's cursorX — set by whichever row the
+    // pointer is over — syncs the cursor across every row for free. cursorX is a
+    // *pixel*, so it stays put while a live window slides; the time + values under
+    // it derive from the current xScale.
+    const { cursorX, cursorTime: showCursorTime, formatTime } = container;
+    // Cursor mode: the row's override, else the container default. One mode per
+    // row (the synced vertical line is shared across rows); each layer renders the
+    // mode in its own way. `parts` decomposes it into {line, dots, chip}.
+    const parts = cursorParts(row.cursor ?? container.cursor);
+    const cursorColor = container.theme.cursor ?? container.theme.axis.label;
+    // Only read a time when the cursor is within the plot. An out-of-bounds
+    // controlled trackerPosition hides the cursor, so the dots + chips hide too —
+    // gating cursorTime makes trackerSamples empty, which drives both the SVG marks
+    // and the DOM chip branches.
+    const cursorTime = cursorX !== null && cursorX >= 0 && cursorX <= plotWidth
+        ? +xScale.invert(cursorX)
+        : null;
+    // Per-layer readout samples at the cursor time (nearest data point) — pixel
+    // position + value + colour. Drives the overlay dots and the DOM value labels;
+    // recomputes as the cursor moves or the window slides under it. Empty when not
+    // hovering, so the data canvas is never touched.
+    const trackerSamples = useMemo(() => {
+        // Only needed for the in-chart dots / chips; skip the per-layer walk when the
+        // mode shows neither (the off-chart readout fans in separately on the container).
+        if (cursorTime === null || (!parts.dots && parts.chip === 'none'))
+            return [];
+        const out = [];
+        for (const entry of layers) {
+            // A layer with a consolidated flag (BoxPlot) renders that, not per-sample
+            // dots/chips — skip it here (its values still fan to the off-chart readout
+            // via sampleAt on the container).
+            if (entry.layer.cursorFlag)
+                continue;
+            const axisId = entry.axisId ?? defaultAxisId;
+            const yScale = yScales.get(axisId);
+            if (yScale === undefined)
+                continue;
+            // The chip uses this layer's axis formatter, so a readout value reads
+            // exactly as the axis labels it.
+            const fmt = formats.get(axisId) ?? String;
+            for (const s of entry.layer.sampleAt(cursorTime)) {
+                out.push({
+                    px: xScale(s.x),
+                    py: yScale(s.value),
+                    value: s.value,
+                    color: s.color,
+                    format: fmt,
+                });
+            }
+        }
+        return out;
+    }, [
+        cursorTime,
+        layers,
+        yScales,
+        formats,
+        xScale,
+        defaultAxisId,
+        parts.dots,
+        parts.chip,
+    ]);
+    // Consolidated multi-value flags (BoxPlot) — one flag per such layer, only in
+    // `flag` mode: all the box's values on one chip, anchored at its top-centre
+    // (`px`, `topPy`). Rendered as one staff + one multi-line chip (vs the
+    // per-sample dots/chips above), the values each coloured to their box piece.
+    const trackerFlags = useMemo(() => {
+        if (cursorTime === null || parts.chip !== 'flag')
+            return [];
+        const out = [];
+        for (const entry of layers) {
+            const flagOf = entry.layer.cursorFlag;
+            if (flagOf === undefined)
+                continue;
+            const axisId = entry.axisId ?? defaultAxisId;
+            const yScale = yScales.get(axisId);
+            if (yScale === undefined)
+                continue;
+            const fmt = formats.get(axisId) ?? String;
+            // `cursorFlag` is an arrow (captures bx/style, no `this`), so a detached
+            // call is safe — and avoids re-reading the optional method.
+            const f = flagOf(cursorTime);
+            if (f === null)
+                continue;
+            out.push({
+                px: xScale(f.x),
+                topPy: yScale(f.topValue),
+                lines: f.lines.map((l) => ({ text: fmt(l.value), color: l.color })),
+            });
+        }
+        return out;
+    }, [cursorTime, layers, yScales, formats, xScale, defaultAxisId, parts.chip]);
+    // Pan/zoom + tracker share the plot's event surface. Container fields are read
+    // through a ref so the handlers + the (once-attached) wheel listener always see
+    // the latest frame without re-subscribing. Written after commit (not in render)
+    // so a wheel/pointer event can't read a frame that was abandoned mid-render
+    // under concurrent rendering.
+    const containerRef = useRef(container);
+    useLayoutEffect(() => {
+        containerRef.current = container;
+    });
+    const plotRef = useRef(null);
+    const dragRef = useRef(null);
+    // Row read through a ref so the click handler hit-tests the latest layers +
+    // y-scales without re-subscribing (same after-commit discipline as containerRef).
+    const rowRef = useRef(row);
+    useLayoutEffect(() => {
+        rowRef.current = row;
+    });
+    // Pointer-down position, to tell a click (select) from the tail of a drag/pan.
+    const clickStartRef = useRef(null);
+    const handlePointerDown = useCallback((e) => {
+        clickStartRef.current = { x: e.clientX, y: e.clientY };
+        const c = containerRef.current;
+        if (!c.panZoom)
+            return;
+        const r = c.timeRange;
+        dragRef.current = { startX: e.clientX, startRange: [r[0], r[1]] };
+        c.setHoverX(null); // hide the tracker while panning
+        c.setHovered(null); // and drop any hover-highlight
+        // Capture so the pan continues outside the plot; an enhancement, not
+        // critical — guard the throw for synthetic / already-released pointers.
+        try {
+            e.currentTarget.setPointerCapture(e.pointerId);
+        }
+        catch {
+            /* ignore */
+        }
+    }, []);
+    const handlePointerMove = useCallback((e) => {
+        const c = containerRef.current;
+        const drag = dragRef.current;
+        if (drag) {
+            // Pan from the start range by the total drag — right → earlier (−dt).
+            const dx = e.clientX - drag.startX;
+            // Don't pan until past the slop, so a click's 1–4px jitter neither moves
+            // the view nor shifts the scale the click then hit-tests against.
+            if (Math.abs(dx) <= DRAG_SLOP)
+                return;
+            const span = drag.startRange[1] - drag.startRange[0];
+            const dt = c.plotWidth > 0 ? -dx * (span / c.plotWidth) : 0;
+            c.applyRange(panRange(drag.startRange, dt));
+            return; // tracker suppressed during a pan
+        }
+        const rect = e.currentTarget.getBoundingClientRect();
+        const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+        c.setHoverX(px);
+        // Hover-highlight: hit-test the row's selectable layers (Bar) under the
+        // pointer and set the hovered mark. Deduped in the container, so the data
+        // canvas repaints only on a mark transition — not every move (the move just
+        // slides the SVG cursor). A row with no selectable layer (line/area/band)
+        // resolves to null → a no-op.
+        const r = rowRef.current;
+        const hit = resolveSelection(r.layers, px, e.clientY - rect.top, c.xScale, (axisId) => r.yScales.get(axisId ?? r.defaultAxisId));
+        c.setHovered(hit);
+    }, []);
+    const handlePointerUp = useCallback((e) => {
+        if (dragRef.current) {
+            dragRef.current = null;
+            try {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }, []);
+    const handlePointerLeave = useCallback(() => {
+        const c = containerRef.current;
+        c.setHoverX(null);
+        c.setHovered(null);
+    }, []);
+    // Click selection: ignore the click that ends a drag/pan (moved past a few px),
+    // else hit-test the row's layers top-down and select — or clear on a miss.
+    const handleClick = useCallback((e) => {
+        const start = clickStartRef.current;
+        if (start &&
+            Math.hypot(e.clientX - start.x, e.clientY - start.y) > DRAG_SLOP)
+            return;
+        const c = containerRef.current;
+        const r = rowRef.current;
+        const rect = e.currentTarget.getBoundingClientRect();
+        const hit = resolveSelection(r.layers, e.clientX - rect.left, e.clientY - rect.top, c.xScale, (axisId) => r.yScales.get(axisId ?? r.defaultAxisId));
+        c.select(hit);
+    }, []);
+    // Wheel-zoom — a native non-passive listener so `preventDefault` works (React's
+    // onWheel is passive). Attached once; no-ops (and lets the page scroll) when
+    // panZoom is off.
+    useEffect(() => {
+        const el = plotRef.current;
+        if (el === null)
+            return;
+        const onWheel = (e) => {
+            const c = containerRef.current;
+            if (!c.panZoom)
+                return;
+            e.preventDefault();
+            const rect = el.getBoundingClientRect();
+            const localX = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+            const pivot = +c.xScale.invert(localX);
+            const factor = Math.exp(e.deltaY * ZOOM_SENSITIVITY);
+            c.applyRange(zoomRange(c.timeRange, pivot, factor, c.minDuration));
+        };
+        el.addEventListener('wheel', onWheel, { passive: false });
+        return () => el.removeEventListener('wheel', onWheel);
+    }, []);
+    // Cursor presentation is a DOM/SVG overlay (no cursor canvas): an SVG holds the
+    // line / dots / flag staffs; these value chips (DOM, crisp text) sit beside each
+    // dot ('inline', clamped within the row) or stack at the top of the flag staff
+    // ('flag'). line / point / none draw no chips — surface values off-chart.
+    const flagLineHeight = container.theme.font.size + 5;
+    const chipStyle = {
+        position: 'absolute',
+        background: container.theme.chip?.background,
+        border: `1px solid ${gridColor}`,
+        borderRadius: '3px',
+        padding: '0 4px',
+        fontFamily: container.theme.font.family,
+        fontSize: `${container.theme.font.size}px`,
+        fontVariantNumeric: 'tabular-nums',
+        whiteSpace: 'nowrap',
+        pointerEvents: 'none',
+        lineHeight: 1.5,
+    };
+    // Show the cursor's time atop the readout (opt-in via `cursorTime`), whenever
+    // the cursor is active (any mode that draws marks). A single chip at the cursor
+    // x, top of the row; for `flag` it sits above the value chips (which shift down).
+    // The time is shared across rows (one cursor, one time), so it shows **once**,
+    // atop the first row — not repeated per row. (Gating it here also drops the
+    // top-of-stack space reservation on the other rows, see `flagBase`.)
+    const showTime = showCursorTime &&
+        cursorTime !== null &&
+        (parts.line || parts.dots) &&
+        row.isFirstRow;
+    // Flag stacking geometry: chips stack from `flagBase` (below the time chip when
+    // shown); each staff rises from its dot up to `stackBottom` (the stack's foot).
+    const flagTop = 2;
+    const flagBase = flagTop + (showTime ? flagLineHeight : 0);
+    const stackBottom = flagBase + trackerSamples.length * flagLineHeight;
+    // The cursor-time chip caps the readout. In `flag` mode it tops the flag stack,
+    // so anchor it to the stack's x (the nearest sample's point) so time + flag +
+    // staff + dot read as one column; otherwise it labels the cursor line at cursorX.
+    const timeX = parts.chip === 'flag' && trackerSamples.length > 0
+        ? trackerSamples[0].px
+        : cursorX;
+    // Inject each draw layer's JSX position so it registers its declaration order
+    // (z-stack: lower index at the back), independent of mount timing.
+    const indexedChildren = Children.map(children, (child, index) => isValidElement(child)
+        ? cloneElement(child, { index })
+        : child);
+    return (_jsxs(LayersContext.Provider, { value: registry, children: [_jsxs("div", { ref: plotRef, style: {
+                    position: 'relative',
+                    width: `${plotWidth}px`,
+                    height: `${row.height}px`,
+                    cursor: 'crosshair',
+                    // Let pan/zoom own touch gestures (no native scroll) when enabled.
+                    touchAction: container.panZoom ? 'none' : 'auto',
+                }, onPointerMove: handlePointerMove, onPointerDown: handlePointerDown, onPointerUp: handlePointerUp, onPointerCancel: handlePointerUp, onPointerLeave: handlePointerLeave, onClick: handleClick, children: [_jsx(Canvas, { width: plotWidth, height: row.height, draw: draw }), _jsxs("svg", { width: plotWidth, height: row.height, style: {
+                            position: 'absolute',
+                            top: 0,
+                            left: 0,
+                            pointerEvents: 'none',
+                        }, children: [parts.line &&
+                                cursorX !== null &&
+                                cursorX >= 0 &&
+                                cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&
+                                trackerSamples.map((s, i) => s.py > stackBottom ? (_jsx("line", { x1: s.px, y1: stackBottom, x2: s.px, y2: s.py, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `staff-${i}`)) : null), parts.chip === 'flag' &&
+                                trackerFlags.map((f, i) => {
+                                    // One horizontal row of values → a single-line chip.
+                                    const flagBottom = flagBase + flagLineHeight;
+                                    return f.topPy > flagBottom ? (_jsx("line", { x1: f.px, y1: flagBottom, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null;
+                                }), parts.dots &&
+                                trackerSamples.map((s, i) => (_jsx("circle", { cx: s.px, cy: s.py, r: 3, fill: s.color, stroke: background, strokeWidth: background ? 1 : 0 }, `dot-${i}`)))] }), showTime && timeX !== null && cursorTime !== null && (_jsx("div", { style: {
+                            ...chipStyle,
+                            top: `${flagTop}px`,
+                            left: timeX > plotWidth * LABEL_FLIP_FRACTION
+                                ? undefined
+                                : `${timeX + 4}px`,
+                            right: timeX > plotWidth * LABEL_FLIP_FRACTION
+                                ? `${plotWidth - timeX + 4}px`
+                                : undefined,
+                            color: cursorColor,
+                        }, children: formatTime(cursorTime) })), parts.chip === 'inline' &&
+                        trackerSamples.map((s, i) => {
+                            // Flip the chip left of its dot near the right edge so it stays in-plot.
+                            const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;
+                            // Clamp within the row so a chip near the top/bottom isn't clipped by
+                            // (or spilling into) the neighbouring row. Chip-vs-chip de-overlap is
+                            // a later refinement; this keeps each chip inside its own row.
+                            const top = Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, s.py));
+                            return (_jsx("div", { style: {
+                                    ...chipStyle,
+                                    top: `${top}px`,
+                                    transform: 'translateY(-50%)',
+                                    left: flip ? undefined : `${s.px + 8}px`,
+                                    right: flip ? `${plotWidth - s.px + 8}px` : undefined,
+                                    color: s.color,
+                                }, children: s.format(s.value) }, i));
+                        }), parts.chip === 'flag' &&
+                        cursorX !== null &&
+                        trackerSamples.map((s, i) => {
+                            // Each flag caps its own staff — anchored to the data point's x
+                            // (`s.px`), riding the point with the dot + staff, not the cursor.
+                            // Flip left near the right edge so it stays in-plot.
+                            const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;
+                            return (_jsx("div", { style: {
+                                    ...chipStyle,
+                                    top: `${flagBase + i * flagLineHeight}px`,
+                                    left: flip ? undefined : `${s.px + 4}px`,
+                                    right: flip ? `${plotWidth - s.px + 4}px` : undefined,
+                                    color: s.color,
+                                }, children: s.format(s.value) }, i));
+                        }), parts.chip === 'flag' &&
+                        trackerFlags.map((f, i) => {
+                            const flip = f.px > plotWidth * LABEL_FLIP_FRACTION;
+                            return (_jsx("div", { style: {
+                                    ...chipStyle,
+                                    top: `${flagBase}px`,
+                                    left: flip ? undefined : `${f.px + 4}px`,
+                                    right: flip ? `${plotWidth - f.px + 4}px` : undefined,
+                                    display: 'flex',
+                                    flexDirection: 'row',
+                                    gap: '6px',
+                                }, children: f.lines.map((l, j) => (_jsx("span", { style: { color: l.color }, children: l.text }, j))) }, `boxflag-${i}`));
+                        })] }), indexedChildren] }));
+}
+//# sourceMappingURL=Layers.js.map

package/dist/LineChart.d.ts

@@ -0,0 +1,60 @@
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import { type Curve } from './curve.js';
+import { type GapMode } from './gaps.js';
+export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` plots against the time axis; a
+     * `ValueSeries` (`series.byValue('cumDist')`) against its value axis — the
+     * container infers which from the data, no axis-type prop. Either way the key
+     * / axis column supplies x and `column` supplies y.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
+    /** Name of the numeric value column to plot. */
+    column: string;
+    /**
+     * The series' semantic identifier — what the data _is_ / how it should read
+     * (e.g. `heartrate`, `power`, or a role name like `foam`). The theme maps it
+     * to a {@link LineStyle} (`theme.line[as] ?? theme.line.default`). **Omitted ⇒
+     * the `default` style** — `column` is the data, `as` is the identity, and
+     * there's no per-component colour/width override (that second styling channel
+     * is what bred react-timeseries-charts' styling bugs; restyle via the theme).
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this line scales against — picks the *scale*,
+     * where `as` picks the *style* (separate concerns). **Omitted ⇒ the row's
+     * default axis** (the first declared, or the implicit auto-domain axis).
+     */
+    axis?: string;
+    /**
+     * Render-time path interpolation between points — a view concern (denoise the
+     * data with pond's `smooth()` upstream). **Omitted ⇒ `'linear'`** (straight
+     * segments). `'monotone'` is a smooth line that still passes through points.
+     */
+    curve?: Curve;
+    /**
+     * How a **gap** (a coast / dropout — a run of NaN in `column`) is rendered (a
+     * {@link GapMode}). **Omitted ⇒ `'empty'`**: the line breaks at the gap and
+     * leaves a hole (the honest default). `'none'` bridges straight across;
+     * `'dashed'` adds a faint dashed bridge over the break; `'step'` adds a faint
+     * flat dashed line at the average of the two edge values; `'fade'` is estela's
+     * fade-to-baseline at each gap edge. Shared with `<AreaChart>` — one concept.
+     * (The `'dashed'` / `'step'` connector faintness is the theme's
+     * `gap.connectorOpacity`.)
+     */
+    gaps?: GapMode;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A line draw layer. Reads `column` from `series` into a {@link ChartSeries}
+ * (columnar, gaps as NaN), registers itself into the enclosing {@link Layers}
+ * (scaling against its `axis`), and renders nothing to the DOM — the row draws
+ * it. The line breaks at gaps rather than spanning them.
+ */
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, index, }: LineChartProps<S, VS>): null;
+//# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -0,0 +1,105 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { ValueSeries } from 'pond-ts';
+import { fromTimeSeries, fromValueSeries } from './data.js';
+import { drawLine, yExtent } from './line.js';
+import { resolveCurve } from './curve.js';
+import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+import { ContainerContext, LayersContext } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A line draw layer. Reads `column` from `series` into a {@link ChartSeries}
+ * (columnar, gaps as NaN), registers itself into the enclosing {@link Layers}
+ * (scaling against its `axis`), and renders nothing to the DOM — the row draws
+ * it. The line breaks at gaps rather than spanning them.
+ */
+export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<LineChart> must be rendered inside a <Layers>');
+    }
+    const cs = useMemo(() => series instanceof ValueSeries
+        ? fromValueSeries(series, column)
+        : fromTimeSeries(series, column), [series, column]);
+    // Styling: semantic identifier → theme style. The single styling channel.
+    const { line } = container.theme;
+    const style = (semantic !== undefined ? line[semantic] : undefined) ?? line.default;
+    // Series identity for the readout (the `as` role, else the column name).
+    const label = semantic ?? column;
+    const curveFactory = resolveCurve(curve);
+    // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
+    // falling back to the shared default so a theme without it still renders faint.
+    const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => yExtent(cs),
+            // The container infers the shared x scale's kind + auto-fit domain from
+            // its layers: a ValueSeries plots on a value axis, a TimeSeries on time.
+            xKind: series instanceof ValueSeries ? 'value' : 'time',
+            xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
+            sampleAt: (x) => {
+                // No readout past the data (tracker policy — nearest clamps to an
+                // endpoint outside the span); bounds from the columnar x axis.
+                if (cs.length === 0 || x < cs.x[0] || x > cs.x[cs.length - 1]) {
+                    return [];
+                }
+                if (series instanceof ValueSeries) {
+                    // Value axis: bisect the axis for the nearest row, read y from `cs`.
+                    const i = series.nearestIndex(x);
+                    if (i < 0)
+                        return [];
+                    const v = cs.y[i];
+                    return Number.isFinite(v)
+                        ? [{ x: cs.x[i], value: v, color: style.color, label }]
+                        : [];
+                }
+                const e = series.nearest(x);
+                if (e === undefined)
+                    return [];
+                // get() wants a literal key; column is a runtime string. Cast the
+                // *event* (not the method — that would detach `this`) to a
+                // string-keyed get; runtime-safe read + guard.
+                const v = e.get(column);
+                return typeof v === 'number' && Number.isFinite(v)
+                    ? [{ x: e.begin(), value: v, color: style.color, label }]
+                    : [];
+            },
+            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity),
+        },
+        axisId: axis,
+        index,
+    }), [
+        cs,
+        series,
+        column,
+        style,
+        label,
+        curveFactory,
+        gaps,
+        gapConnectorOpacity,
+        axis,
+        index,
+    ]);
+    // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
+    // fixed: a series or style change updates the slot in place rather than
+    // re-appending (which would jump the layer to the front of the z-stack on
+    // every live update).
+    const slot = useSlotKey();
+    // Unregister on unmount only (stable deps); register + update in place.
+    useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
+    useEffect(() => {
+        layers.registerLayer(slot, entry);
+    }, [layers, slot, entry]);
+    // Also register as a tracker source so the container can fan in this series'
+    // value at the cursor for the (outside-the-chart) readout.
+    const { registerTrackerSource, unregisterTrackerSource } = container;
+    useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
+    useEffect(() => {
+        registerTrackerSource(slot, entry.layer);
+    }, [registerTrackerSource, slot, entry.layer]);
+    return null;
+}
+//# sourceMappingURL=LineChart.js.map

package/dist/ScatterChart.d.ts

@@ -0,0 +1,84 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type ColorEncoding, type RadiusEncoding } from './encoding.js';
+export interface ScatterChartProps<S extends SeriesSchema> {
+    /** The source series. Its key column supplies the time axis (each point's x). */
+    series: TimeSeries<S>;
+    /** Name of the numeric value column — each point's y. */
+    column: string;
+    /**
+     * The scatter's semantic identifier — what the marks _are_ / how they should
+     * read. The theme maps it to a {@link ScatterStyle} (`theme.scatter[as] ??
+     * theme.scatter.default`) — the **base** fill, radius, outline, and label
+     * colour. **Omitted ⇒ the `default` style.** This is the single styling
+     * channel for the base mark; per-point size / colour come from the data-driven
+     * `radius` / `color` encodings below (the deliberate, signed-off scatter
+     * exception), not a per-component style override.
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this scatter scales against — picks the
+     * *scale*, where `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * **Data-driven point radius** — the signed-off exception to one-channel
+     * styling. Either a fixed px radius, or `{ column, range }` to size each point
+     * from a numeric column (its finite extent → `[minR, maxR]` px via a linear
+     * scale). A point whose radius column is non-finite falls back to the base
+     * radius. **Omitted ⇒ the style's base radius.** The encoding is a column +
+     * range, *not* a per-datum callback — there's no place for a styling bug to
+     * hide (the trap the package avoids).
+     */
+    radius?: RadiusEncoding;
+    /**
+     * **Data-driven point colour** — `{ column, range }`: colour each point from a
+     * numeric column (its finite extent → a two-stop hex ramp via a linear scale).
+     * A point whose colour column is non-finite falls back to the base colour.
+     * **Omitted ⇒ the style's base colour** for every point (the single styling
+     * channel). Same discipline as `radius`: a column + range, not a callback.
+     */
+    color?: ColorEncoding;
+    /**
+     * An optional per-point text label, drawn just right of each mark, in the
+     * style's `label` colour + the theme font. Two forms:
+     * - **a column name** ⇒ that column's value at each point, stringified;
+     * - **`true`** ⇒ the plotted `column`'s value, stringified.
+     *
+     * **Omitted / `false` ⇒ no labels.** Keep it sparse — a label per point on a
+     * dense scatter is noise; this is for a handful of called-out marks.
+     */
+    label?: string | boolean;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * with **data-driven radius + colour** (the signed-off exception — encode from
+ * columns via scales, not a per-event style callback). Reads `column` into a
+ * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
+ * {@link Layers} (scaling against its `axis`), and renders nothing to the DOM —
+ * the row draws it.
+ *
+ * **Interactions.** Hover snaps the tracker dot to the nearest point
+ * (`sampleAt`), and that sample flows to the container's `onTrackerChanged` —
+ * the nearest-point readout. Scatter reuses the shared tracker rather than
+ * adding a separate `onNearest` channel, so a scatter reads out exactly like a
+ * line. Click selection hit-tests each point's disc (`hitTest`); the selected
+ * point (matching both its key and this series' label) gets a highlight ring.
+ *
+ * ```tsx
+ * <Layers>
+ *   <ScatterChart
+ *     series={s}
+ *     column="price"
+ *     radius={{ column: 'volume', range: [3, 14] }}
+ *     color={{ column: 'change', range: ['#e8836b', '#15B3A6'] }}
+ *   />
+ * </Layers>
+ * ```
+ */
+export declare function ScatterChart<S extends SeriesSchema>({ series, column, as: semantic, axis, radius, color, label, index, }: ScatterChartProps<S>): null;
+//# sourceMappingURL=ScatterChart.d.ts.map