@pond-ts/charts 0.41.0 → 0.43.0

package/dist/ChartContainer.js

@@ -1,6 +1,9 @@
 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 { scaleTradingTime, } from './tradingTimeScale.js';
+import { scaleBand } from './bandScale.js';
+import { Sequence } from 'pond-ts';
 import { ContainerContext, } from './context.js';
 import { maxSlotWidths, sum } from './slots.js';
 import { computeLabelLanes } from './annotations.js';
@@ -31,7 +34,7 @@ function normalizeRange(range) {
  * {@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, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, discontinuities, calendar, spacing, 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.
@@ -77,6 +80,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // still cursor stays put while a live window slides under it; a controlled
     // `trackerPosition` resolves to a pixel below.
     const [hoverX, setHoverX] = useState(null);
+    // The region-cursor drag anchor (epoch ms) — set on press, cleared on release.
+    const [regionAnchor, setRegionAnchor] = useState(null);
     // The free-form crosshair also needs the pointer's y + which row (row-specific,
     // unlike the shared x). One state object so a move updates both atomically.
     const [hoverPoint, setHoverPoint] = useState(null);
@@ -99,6 +104,29 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             return next;
         });
     }, []);
+    // Selectable-layer registry: an id-bearing Bar/Scatter registers here (keyed
+    // by its slot) so the container knows whether *any* series is selectable. Only
+    // used to power the dev-warn below — selection resolution itself walks the
+    // rows' layers, not this set. Backed by a **ref** (the synchronous source of
+    // truth) mirrored to state: a child layer's register effect runs before this
+    // parent's dev-warn effect in the same commit, so the ref is already settled
+    // there (reading state would lag a render). State only triggers the re-check.
+    const selectableRef = useRef(new Set());
+    const [selectableKeys, setSelectableKeys] = useState(selectableRef.current);
+    const registerSelectable = useCallback((key) => {
+        if (selectableRef.current.has(key))
+            return;
+        selectableRef.current = new Set(selectableRef.current).add(key);
+        setSelectableKeys(selectableRef.current);
+    }, []);
+    const unregisterSelectable = useCallback((key) => {
+        if (!selectableRef.current.has(key))
+            return;
+        const next = new Set(selectableRef.current);
+        next.delete(key);
+        selectableRef.current = next;
+        setSelectableKeys(next);
+    }, []);
     // Annotations register here so the container can do what a mark can't in
     // isolation: draw its guide line across other rows, order regions, serve snap
     // targets. Keyed by per-instance slot key (same discipline as the sources).
@@ -127,11 +155,31 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             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).`);
+                    `kind (all time-keyed, all value-keyed, or all category).`);
             }
         }
         return kind ?? 'time';
     }, [sources]);
+    // A `'category'` container's ordered category names — the ordinal axis domain.
+    // Every category layer must agree on the same list (a mix is an error, like the
+    // kind), so the shared band scale has one authoritative slot order. `null` when
+    // no category layer has registered (or the kind isn't category).
+    const categories = useMemo(() => {
+        let cats = null;
+        for (const s of sources.values()) {
+            const c = s.xCategories?.() ?? null;
+            if (c === null)
+                continue;
+            if (cats === null)
+                cats = c;
+            else if (cats.length !== c.length || cats.some((v, i) => v !== c[i])) {
+                throw new Error(`ChartContainer: category rows disagree on the axis categories. ` +
+                    `Every category layer in one container must share the same ordered ` +
+                    `column set (got [${cats.join(', ')}] and [${c.join(', ')}]).`);
+            }
+        }
+        return cats;
+    }, [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.)
@@ -174,6 +222,26 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         if (!controlledSelectionRef.current)
             setInternalSelected(hit);
     }, []);
+    // Dev-warn: selection is wired (`selected` and/or `onSelect`) but no layer
+    // carries an `id`, so nothing is selectable — `id` gates interactivity, so a
+    // consumer who forgot it gets a silent no-op click without this nudge. Fires
+    // once per wired-but-empty transition (guarded by a ref); child layers
+    // register before this parent effect runs, so the set is settled here.
+    const selectionWired = controlledSelection || onSelect !== undefined;
+    const warnedNoSelectableRef = useRef(false);
+    useEffect(() => {
+        if (selectionWired && selectableRef.current.size === 0) {
+            if (!warnedNoSelectableRef.current) {
+                warnedNoSelectableRef.current = true;
+                console.warn('[pond-charts] `selected`/`onSelect` is set but no layer has an `id` — ' +
+                    'nothing is selectable. Give a <BarChart>/<ScatterChart> an `id` to ' +
+                    'make it interactive (an `id` gates selection + hover).');
+            }
+        }
+        else {
+            warnedNoSelectableRef.current = false;
+        }
+    }, [selectionWired, selectableKeys]);
     // Hover-highlight: the transient mark under the pointer (distinct from the
     // committed selection). Controlled (`hovered` prop) or uncontrolled (internal),
     // mirroring selection; `onHover` notifies in both modes. Deduped by key+label
@@ -197,8 +265,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         const same = prev === hit ||
             (prev !== null &&
                 hit !== null &&
-                prev.key === hit.key &&
-                prev.label === hit.label);
+                prev.id === hit.id &&
+                prev.key === hit.key);
         if (same)
             return;
         lastHoverRef.current = hit;
@@ -239,7 +307,34 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // 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.)
+    // The trading-time provider only applies to a **time** axis — a value axis is
+    // always a plain `scaleLinear`. Gate it once here so the scale branch AND the
+    // frame (which pan/zoom read) agree: on a value axis the provider is dropped,
+    // so interactions use continuous value math, not trading-time math.
+    // Resolve the trading-time provider: the low-level `discontinuities` prop wins;
+    // otherwise derive it from the high-level `calendar` sugar at the chosen
+    // `spacing`. Memoized on `(calendar, spacing)` so a stable calendar yields a
+    // stable provider (the scale + frame only rebuild when it actually changes) —
+    // pan/zoom read the same provider identity as the low-level path would. Gated
+    // on a time axis so a value-axis chart never calls `calendar.discontinuities`.
+    const calendarProvider = useMemo(() => resolvedKind === 'time' &&
+        discontinuities === undefined &&
+        calendar !== undefined
+        ? calendar.discontinuities(spacing ? { spacing } : undefined)
+        : undefined, [resolvedKind, discontinuities, calendar, spacing]);
+    const xDiscontinuities = resolvedKind === 'time' ? (discontinuities ?? calendarProvider) : undefined;
     const { xScale, formatTime } = useMemo(() => {
+        if (resolvedKind === 'category') {
+            // Ordinal column-domain axis: a band scale over the category slots. The
+            // domain is **always** `[0, n]` (one unit slot per category) — NOT the
+            // resolved `[d0, d1]`: a category axis ignores an explicit `range` (its
+            // slots are absolute `0..n`, matching `categoryStack`), so an out-of-`[0,n]`
+            // range can't silently offset the labels from the bars. The pixel mapping
+            // stays linear; the formatter is the category-name lookup.
+            const cats = categories ?? [];
+            const s = scaleBand(cats).domain([0, cats.length]).range([0, plotWidth]);
+            return { xScale: s, formatTime: (v) => s.label(v) };
+        }
         if (resolvedKind === 'value') {
             const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
             return {
@@ -247,17 +342,58 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
                 formatTime: resolveAxisFormat(s, TIME_TICK_COUNT, timeFormat),
             };
         }
+        if (xDiscontinuities !== undefined) {
+            // Trading-time axis: closed-market gaps collapse, time proportional within
+            // sessions. Same tickFormat surface as scaleTime, so the readout is shared.
+            const s = scaleTradingTime(xDiscontinuities)
+                .domain([d0, d1])
+                .range([0, plotWidth]);
+            return {
+                xScale: s,
+                formatTime: resolveTimeFormat(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]);
+    }, [
+        resolvedKind,
+        categories,
+        d0,
+        d1,
+        plotWidth,
+        timeFormat,
+        xDiscontinuities,
+    ]);
     // 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);
+    // `cursor="region"` buckets: realize the `cursorSequence` over the current view
+    // (a `Sequence` → `.bounded`; a `BoundedSequence` used as-is), so the band can
+    // find the interval under the pointer. Memoized on the sequence + view range;
+    // a coarse sequence (days / sessions) is a handful of intervals.
+    // A `Sequence` bucket is a **time** interval, so gate it to a time axis — on a
+    // value axis (a horizontal histogram, a value-keyed chart) the value domain is
+    // not epoch-ms, so realizing time buckets over it is meaningless (it would
+    // shade the whole plot). Region cursor is time-axis only.
+    const cursorBuckets = useMemo(() => {
+        if (cursorSequence === undefined || resolvedKind !== 'time')
+            return undefined;
+        if (!(cursorSequence instanceof Sequence))
+            return cursorSequence.intervals();
+        // `bounded` (sample 'begin') drops a partial *leading* bucket — the one that
+        // contains the view start begins before it. Widen the realized range back by
+        // one bucket width so that covering bucket is included (a coarse calendar
+        // unit is bounded at ~a year; a fixed step uses its own width).
+        const back = cursorSequence.kind() === 'fixed'
+            ? cursorSequence.stepMs()
+            : 366 * 86_400_000;
+        return cursorSequence.bounded({ start: d0 - back, end: d1 }).intervals();
+    }, [cursorSequence, d0, d1, resolvedKind]);
     // 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
@@ -298,6 +434,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         cursorRowKey: hoverPoint?.rowKey ?? null,
         setHoverY,
         crosshairSnap,
+        cursorBuckets,
+        regionAnchor,
+        setRegionAnchor,
+        onRegionSelect,
+        regionSelectModifier,
         draggingKey,
         setDragging,
         selected: selectedValue,
@@ -316,12 +457,15 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         formatTime,
         registerTrackerSource,
         unregisterTrackerSource,
+        registerSelectable,
+        unregisterSelectable,
         registerAnnotation,
         unregisterAnnotation,
         annotations,
         labelLanes,
         xScale,
         xKind: resolvedKind,
+        discontinuities: xDiscontinuities,
         panZoom,
         minDuration,
         applyRange,
@@ -343,6 +487,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         hoverPoint,
         setHoverY,
         crosshairSnap,
+        cursorBuckets,
+        regionAnchor,
+        setRegionAnchor,
+        onRegionSelect,
+        regionSelectModifier,
         draggingKey,
         setDragging,
         selectedValue,
@@ -361,12 +510,15 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         formatTime,
         registerTrackerSource,
         unregisterTrackerSource,
+        registerSelectable,
+        unregisterSelectable,
         registerAnnotation,
         unregisterAnnotation,
         annotations,
         labelLanes,
         xScale,
         resolvedKind,
+        xDiscontinuities,
         panZoom,
         minDuration,
         applyRange,

package/dist/Layers.js

@@ -1,14 +1,21 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
-import { drawGrid } from './grid.js';
-import { cursorParts } from './tracker.js';
+import { drawGrid, drawDividers, thinPixels } from './grid.js';
+import { TimeRange } from 'pond-ts';
+import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
-import { panRange, zoomRange } from './viewport.js';
+import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, LayersContext, RowContext, } from './context.js';
-/** Gridline tick count — matches the axes (`YAxis`/`TimeAxis`) so they align. */
+/** Gridline tick count. **Must match the axis label counts** (`XAxis`
+ *  `TICK_COUNT`, `ChartContainer` `TIME_TICK_COUNT`, `YAxis`) — the grid, the
+ *  session dividers, and the axis labels are all derived from `ticks(count)`, so
+ *  they only line up while the counts agree. Kept at 5 across all four. */
 const GRID_TICKS = 5;
+/** Minimum px between session dividers — thins dense collapse points (e.g. a
+ *  daily chart where every candle is a new session) so the axis never crowds. */
+const MIN_DIVIDER_PX = 40;
 /** 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
@@ -63,11 +70,31 @@ export function Layers({ children }) {
         // Explicit `<YAxis ticks>` drive the gridlines too, so they align with the
         // axis labels; otherwise d3 auto-picks (the default).
         const explicitY = tickValues.get(defaultAxisId);
-        const xTicks = xScale.ticks(GRID_TICKS).map((d) => xScale(d));
+        // A category axis draws no vertical gridlines — a line through each bar
+        // centre reads as noise; the bars are the structure.
+        const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(GRID_TICKS);
+        const xTicks = xTickVals.map((d) => xScale(+d));
         const yTicks = gridY
             ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
             : [];
         drawGrid(ctx, xTicks, yTicks, w, h, gridColor, gridDash);
+        // Session dividers: solid verticals at the trading calendar's collapse
+        // points (session/day opens), where closed time was removed from the axis.
+        // Draw them at the axis ticks that are collapse points — the same
+        // calendar-coarsened instants the axis labels — so a divider sits under
+        // each date/month/year label, not at every session (which crowds).
+        const disc = container.discontinuities;
+        if (disc?.boundaries) {
+            const [d0, d1] = container.timeRange;
+            // Call as a method (not a detached reference) so a class-based provider
+            // whose `boundaries` reads `this` keeps its receiver.
+            const collapse = new Set(disc.boundaries(d0, d1));
+            const bx = xTickVals
+                .filter((t) => collapse.has(+t))
+                .map((t) => xScale(+t));
+            const dividerColor = container.theme.axis.sessionDivider ?? gridColor;
+            drawDividers(ctx, thinPixels(bx, MIN_DIVIDER_PX), h, dividerColor);
+        }
         for (const entry of layers) {
             const yScale = yScales.get(entry.axisId ?? defaultAxisId);
             if (yScale === undefined)
@@ -83,6 +110,8 @@ export function Layers({ children }) {
         background,
         gridColor,
         gridDash,
+        container.discontinuities,
+        container.timeRange,
     ]);
     // 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
@@ -231,7 +260,29 @@ export function Layers({ children }) {
             }
             return;
         }
-        if (!c.panZoom)
+        // Region-cursor drag-select (opt-in via `onRegionSelect`, time axis only):
+        // anchor the selection at the press; the band then extends as the pointer
+        // moves (bucket by bucket with a sequence, freeform without), and release
+        // commits the range. A `regionSelectModifier` (only while `panZoom` is on)
+        // gates it behind the key so plain drag can still pan; otherwise it preempts
+        // pan (returns before the pan is armed below).
+        if (c.cursor === 'region' && c.onRegionSelect && c.xKind === 'time') {
+            const needsShift = c.regionSelectModifier === 'shift' && c.panZoom;
+            if (!needsShift || e.shiftKey) {
+                const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+                c.setRegionAnchor(+c.xScale.invert(px));
+                c.setHoverX(px);
+                try {
+                    e.currentTarget.setPointerCapture(e.pointerId);
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            // Modifier required but not held → fall through to pan.
+        }
+        if (!c.panZoom || c.xKind === 'category')
             return;
         const r = c.timeRange;
         // Arm a potential pan: record the anchor, but DON'T capture the pointer or
@@ -261,6 +312,13 @@ export function Layers({ children }) {
             c.setHoverX(px); // share the preview x so other rows draw a guide there
             return;
         }
+        // Region drag in progress: just track the pointer x (the band spans from the
+        // anchor bucket to here); no pan, no hover hit-test.
+        if (c.regionAnchor !== null) {
+            const rect = e.currentTarget.getBoundingClientRect();
+            c.setHoverX(Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left)));
+            return;
+        }
         // A pan is only live while a button is held. A move with no buttons means
         // the press already ended without us seeing the pointerup — which the
         // deferred-capture path allows: an uncommitted (sub-slop) potential-pan
@@ -296,9 +354,17 @@ export function Layers({ children }) {
                     /* ignore (synthetic / already-released pointer) */
                 }
             }
-            const span = drag.startRange[1] - drag.startRange[0];
-            const dt = c.plotWidth > 0 ? -dx * (span / c.plotWidth) : 0;
-            c.applyRange(panRange(drag.startRange, dt));
+            if (c.discontinuities) {
+                // Trading-time axis: pan by an equal amount of *trading* time so the
+                // drag feels uniform across collapsed gaps (a raw-ms shift jumps).
+                const fraction = c.plotWidth > 0 ? -dx / c.plotWidth : 0;
+                c.applyRange(panRangeTrading(drag.startRange, fraction, c.discontinuities));
+            }
+            else {
+                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();
@@ -338,6 +404,22 @@ export function Layers({ children }) {
     }, []);
     const handlePointerUp = useCallback((e) => {
         const c = containerRef.current;
+        // End a region drag: commit the anchor→pointer span as a one-shot range,
+        // then clear the anchor (the cursor reverts to the single-bucket highlight).
+        if (c.regionAnchor !== null) {
+            const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+            const span = regionSpan(c.cursorBuckets ?? [], c.regionAnchor, +c.xScale.invert(px));
+            c.setRegionAnchor(null);
+            try {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+            if (span)
+                c.onRegionSelect?.(new TimeRange({ start: span.start, end: span.end }));
+            return;
+        }
         if (c.creating !== null) {
             const rect = e.currentTarget.getBoundingClientRect();
             const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
@@ -405,6 +487,10 @@ export function Layers({ children }) {
             c.setHoverY(null, null);
             return;
         }
+        // Cancel a region-drag on leave (no commit) — a safety net for the rare case
+        // where the pointer capture didn't take, so the anchor can't get stuck.
+        if (c.regionAnchor !== null)
+            c.setRegionAnchor(null);
         c.setHoverX(null);
         c.setHoverY(null, null);
         c.setHovered(null);
@@ -444,14 +530,19 @@ export function Layers({ children }) {
             return;
         const onWheel = (e) => {
             const c = containerRef.current;
-            if (!c.panZoom)
+            if (!c.panZoom || c.xKind === 'category')
                 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));
+            c.applyRange(c.discontinuities
+                ? // minDuration is the zoom-in floor; on a trading-time axis it caps
+                    // the minimum visible *trading* time (ms of open-market time) rather
+                    // than wall-clock ms — the sensible meaning for this axis.
+                    zoomRangeTrading(c.timeRange, pivot, factor, c.discontinuities, c.minDuration)
+                : zoomRange(c.timeRange, pivot, factor, c.minDuration));
         };
         el.addEventListener('wheel', onWheel, { passive: false });
         return () => el.removeEventListener('wheel', onWheel);
@@ -532,6 +623,22 @@ export function Layers({ children }) {
             side: axisSides.get(defaultAxisId) ?? 'left',
         };
     })();
+    // `region` cursor (time axis only): shade the span under the pointer. With a
+    // `cursorSequence` the band snaps to the bucket (and extends bucket by bucket
+    // under a drag); with none it's the **freeform** case — a bare hover draws a
+    // plain line (`regionLine`), a drag shades the raw `[anchor, pointer]`. Edges
+    // map through `xScale`, so on a trading-time axis the band crops to live time.
+    const regionActive = parts.band && container.xKind === 'time';
+    const band = regionActive && cursorTime !== null
+        ? bandRect(container.cursorBuckets ?? [], cursorTime, (v) => xScale(v), plotWidth, container.regionAnchor ?? undefined)
+        : null;
+    // Degenerate region cursor (no sequence, not mid-drag): a plain vertical line.
+    const regionLine = regionActive &&
+        container.cursorBuckets === undefined &&
+        container.regionAnchor === null &&
+        cursorX !== null &&
+        cursorX >= 0 &&
+        cursorX <= plotWidth;
     // Cross-row guide lines: the x-positions of annotations on the OTHER rows
     // (markers + region edges), so a mark on one row reads against this row's data +
     // the shared x axis. A mark's own row skips itself; baselines cast no vertical
@@ -599,7 +706,7 @@ export function Layers({ children }) {
                         top: 0,
                         left: 0,
                         pointerEvents: 'none',
-                    }, children: [parts.line &&
+                    }, children: [band !== null && (_jsx("rect", { x: band.x0, y: 0, width: band.x1 - band.x0, height: row.height, fill: cursorColor, opacity: 0.12 })), regionLine && cursorX !== null && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), 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' &&

package/dist/ScatterChart.d.ts

@@ -15,6 +15,17 @@ export interface ScatterChartProps<S extends SeriesSchema> {
      * exception), not a per-component style override.
      */
     as?: string;
+    /**
+     * The **stable series identity** for selection + hover. **Optional, and it
+     * gates interactivity:** the scatter is selectable/hoverable only when given an
+     * `id` — omit it and the points render + read out but can't be clicked (a click
+     * on them reads as empty space ⇒ deselect). Distinct from `as` (a theme role
+     * that can repeat): `id` must be unique among the selectable layers, and it is
+     * the key the controlled `selected` echo, dedup, and (later) multi-select all
+     * match on — so a selection survives a data update where a sample `key` goes
+     * stale.
+     */
+    id?: string;
     /**
      * Which `<YAxis>` (by its `id`) this scatter scales against — picks the
      * *scale*, where `as` picks the *style*. **Omitted ⇒ the row's default axis.**
@@ -66,8 +77,9 @@ export interface ScatterChartProps<S extends SeriesSchema> {
  * (`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.
+ * line. Click selection hit-tests each point's disc (`hitTest`) — **opt-in via
+ * `id`**; the selected point (matching the selection's series `id` and the sample
+ * `key`) gets a highlight ring. Without an `id` the scatter is display-only.
  *
  * ```tsx
  * <Layers>
@@ -80,5 +92,5 @@ export interface ScatterChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function ScatterChart<S extends SeriesSchema>({ series, column, as: semantic, axis, radius, color, label, index, }: ScatterChartProps<S>): null;
+export declare function ScatterChart<S extends SeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, index, }: ScatterChartProps<S>): null;
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/ScatterChart.js

@@ -16,8 +16,9 @@ import { useSlotKey } from './use-slot-key.js';
  * (`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.
+ * line. Click selection hit-tests each point's disc (`hitTest`) — **opt-in via
+ * `id`**; the selected point (matching the selection's series `id` and the sample
+ * `key`) gets a highlight ring. Without an `id` the scatter is display-only.
  *
  * ```tsx
  * <Layers>
@@ -30,7 +31,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function ScatterChart({ series, column, as: semantic, axis, radius, color, label, index = 0, }) {
+export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
@@ -101,8 +102,15 @@ export function ScatterChart({ series, column, as: semantic, axis, radius, color
                     },
                 ];
             },
-            hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, seriesLabel),
-            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, seriesLabel),
+            // `id` gates interactivity: only an id-bearing layer wires a hitTest, so
+            // a no-id scatter is display-only (a click on it resolves to empty space).
+            // Omit the key entirely when there's no id (exactOptionalPropertyTypes).
+            ...(id === undefined
+                ? {}
+                : {
+                    hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel),
+                }),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id),
         },
         axisId: axis,
         index,
@@ -112,6 +120,7 @@ export function ScatterChart({ series, column, as: semantic, axis, radius, color
         column,
         style,
         seriesLabel,
+        id,
         encoding,
         keyAt,
         labelAt,
@@ -134,6 +143,15 @@ export function ScatterChart({ series, column, as: semantic, axis, radius, color
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // Advertise selectability (only when an `id` was given) so the container can
+    // warn if selection is wired but nothing is selectable.
+    const { registerSelectable, unregisterSelectable } = container;
+    useEffect(() => {
+        if (id === undefined)
+            return;
+        registerSelectable(slot);
+        return () => unregisterSelectable(slot);
+    }, [registerSelectable, unregisterSelectable, slot, id]);
     return null;
 }
 //# sourceMappingURL=ScatterChart.js.map