@pond-ts/charts 0.57.0 → 0.59.0

package/dist/BoxList.d.ts

@@ -2,6 +2,7 @@ import { type ReactNode } from 'react';
 import type { SeriesSchema, ValueSeriesSchema } from 'pond-ts';
 import { type BoxListColumn, type ListCellSpec, type ListMarker, type ListRow, type ListSortDirection } from './list.js';
 import { type ListRowsSource, type ListSeriesSource } from './list-source.js';
+import type { SelectModifiers } from './context.js';
 import { type ChartTheme } from './theme.js';
 /** The props both BoxList source doors share. */
 export interface BoxListCommon<R extends ListRow = ListRow> {
@@ -41,10 +42,76 @@ export interface BoxListCommon<R extends ListRow = ListRow> {
     defaultExpanded?: readonly string[];
     /** Observe a toggle (`expanded` is the row's new state). */
     onExpandToggle?: (key: string, expanded: boolean) => void;
-    /** The selected row's `key` (inset accent edge). Pair with `onRowClick`. */
-    selected?: string | null;
-    /** Row click (also gates the hover affordance). */
+    /**
+     * The selected row(s), marked with an inset edge in the annotation (marks)
+     * register — selection is a user's mark, not data. Consumer-owned state:
+     * pair with {@link onRowClick}. `null` / omitted ⇒ none.
+     *
+     * **Accepts one key or a set**, the same union {@link hovered} takes
+     * ([PND-INTERACTCONF] / RFC `interaction.md` A3.1 — the list family speaks
+     * the canvas's interaction vocabulary, not a parallel one). Plural because
+     * a range of rows can be selected at once; passing a bare key still means
+     * exactly what it looks like.
+     *
+     * The library applies **no set arithmetic** — it renders what you hand back.
+     */
+    selected?: string | readonly string[] | null;
+    /** Row click (also gates the pointer affordance). */
     onRowClick?: (row: R) => void;
+    /**
+     * **Plural select** — the list's answer to `<MultiSelector>`, and how a user
+     * produces a multi-row {@link selected}.
+     *
+     * Fires with the rows the gesture took plus its modifiers:
+     *
+     * - a **click** reports `[row]` — so this is a strict *superset* of
+     *   {@link onRowClick}, the way `<MultiSelector>` is of `<Selector>`;
+     * - a **drag across rows** reports the whole inclusive run, in display
+     *   order.
+     *
+     * **Mounting it is what enables the drag** (interaction RFC A4.2 rule 1 —
+     * the same rule that makes a bare `<MultiSelector />` enable the canvas
+     * sweep). A list with only `onRowClick` behaves exactly as it always has.
+     *
+     * **Crossing into another row is what makes it a range**, not a pixel slop:
+     * a row is tall and discrete, so a press-and-release on one row is always a
+     * click, and a horizontal wobble — which on a stack of rows means nothing —
+     * can never commit one. While the drag runs, the covered rows light as
+     * *hovered*: that is the live preview of what releasing would take, and it
+     * out-ranks {@link hovered} for the duration without touching it.
+     *
+     * **The library holds no state and applies no set arithmetic.** You get the
+     * run and the modifiers; you decide whether to replace or union, and feed
+     * the result back through {@link selected}:
+     *
+     * ```tsx
+     * onRowSelect={(rows, m) =>
+     *   setSel((cur) => {
+     *     const keys = rows.map((r) => r.key);
+     *     return m.additive ? [...new Set([...cur, ...keys])] : keys;
+     *   })
+     * }
+     * ```
+     *
+     * `modifiers.additive` is the platform-idiomatic add chord already resolved
+     * (⌘ on macOS, Ctrl elsewhere). **`shiftKey` is reported but carries no
+     * built-in meaning** — an ordinal range is a gesture here, not a modifier
+     * (see `SelectModifiers`), so a shift-click extend is yours to define if you
+     * want one.
+     */
+    onRowSelect?: (rows: readonly R[], modifiers: SelectModifiers) => void;
+    /**
+     * Controlled **hover-highlight** — the lit row key(s), or `null`; **omitted
+     * ⇒ uncontrolled**. Accepts one key or a set, the same union
+     * `<Selector hovered>` takes, so an external hover (a chart mark, a map
+     * segment) lights rows from outside. See `<BarList>`'s `hovered` for the
+     * full note.
+     */
+    hovered?: string | readonly string[] | null;
+    /** Hover out: the entered row, or `null` on leaving the rows — deduped by
+     *  row key, fires controlled or uncontrolled. Pair with {@link hovered} to
+     *  sync hover both ways. */
+    onHover?: (row: R | null) => void;
     /** Each box line's height in px. **Omitted ⇒ `10`.** */
     barHeight?: number;
     /** Rule between rows. **Omitted ⇒ `true`.** */

package/dist/BoxList.js

@@ -35,7 +35,7 @@ export function BoxList(props) {
     // One normalized view of the union — `isSeriesSource` is the runtime
     // narrowing; the doors are mutually exclusive by construction now.
     const source = props;
-    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, markers, barHeight = 10, divided, baseline = true, theme = defaultTheme, } = source;
+    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, markers, barHeight = 10, divided, baseline = true, theme = defaultTheme, } = source;
     // A runtime guard for JS consumers and `any`-typed call sites — the
     // props union makes both branches unreachable from typed TS, but a
     // silently-ignored source prop is a worse failure than a throw.
@@ -58,13 +58,10 @@ export function BoxList(props) {
         frac: listFraction(m.value, scale),
         ...(m.label !== undefined ? { label: m.label } : {}),
     })), [markers, scale]);
-    return (_jsx(ListTable, { rows: sorted, kind: "box", markers: resolvedMarkers, before: before, after: after, renderExpanded: renderExpanded, defaultExpanded: defaultExpanded, onExpandToggle: onExpandToggle, selected: selected, onRowClick: onRowClick, divided: divided, baseline: baseline, theme: theme, renderGlyphs: (row) => (_jsx(_Fragment, { children: columns.map((col, ci) => (_jsx(BoxLine
-            // Index-qualified so two lines over the same quantile names
-            // (say, styled differently) never collide.
-            , { row: row, col: col, scale: scale, height: barHeight, style: theme.box[col.as ?? 'default'] ?? theme.box.default, ink: listInk(theme), fontSize: theme.font.size }, `${ci} ${col.lower} ${col.upper}`))) })) }));
+    return (_jsx(ListTable, { rows: sorted, kind: "box", markers: resolvedMarkers, before: before, after: after, renderExpanded: renderExpanded, defaultExpanded: defaultExpanded, onExpandToggle: onExpandToggle, selected: selected, onRowClick: onRowClick, onRowSelect: onRowSelect, hovered: hovered, onHover: onHover, divided: divided, baseline: baseline, theme: theme, renderGlyphs: (row, state) => (_jsx(_Fragment, { children: columns.map((col, ci) => (_jsx(BoxLine, { dimmed: state.dimmed, row: row, col: col, scale: scale, height: barHeight, style: theme.box[col.as ?? 'default'] ?? theme.box.default, ink: listInk(theme), fontSize: theme.font.size }, `${ci} ${col.lower} ${col.upper}`))) })) }));
 }
 /** One horizontal box line: range band → body → median → current tick + label. */
-function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
+function BoxLine({ row, col, scale, height, style, ink, fontSize, dimmed, }) {
     const at = (name) => name === undefined ? null : listFraction(row.values[name], scale);
     const lo = at(col.lower);
     const hi = at(col.upper);
@@ -77,6 +74,21 @@ function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
         ? col.format(raw)
         : null;
     const pct = (f) => `${f * 100}%`;
+    /**
+     * The dim multiplier for this line's **marks** — body, median, tick.
+     *
+     * Not the range band below it: that is the row's *scale*, the thing that
+     * makes one row comparable with the next, and receding it alongside the
+     * marks is exactly the mistake `ChartTheme.list`'s track rule names. It is
+     * the box list's track.
+     *
+     * **Selection is deliberately absent here.** Rule 2 is that band + rail
+     * read as selected with no help from the fill, and a box has four inks
+     * (whisker, body, median, tick) rather than the one a bar has — "the fill
+     * goes blue" has no single referent. So a selected box row is signalled by
+     * its chrome alone, which the rule says is sufficient by design.
+     */
+    const dim = dimmed ? 0.32 : 1;
     // The row keeps its slot height even when everything is missing — a gap
     // reads as an empty line, not a collapsed row.
     return (_jsxs("div", { "data-list-boxline": "", style: { position: 'relative', height: height + 4, margin: '2px 0' }, children: [lo !== null && hi !== null && (_jsx("div", { "data-list-range": "", style: {
@@ -95,7 +107,7 @@ function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
                     left: pct(q1),
                     width: pct(Math.max(q3 - q1, 0)),
                     background: style.fill,
-                    opacity: Math.min(style.fillOpacity * 2, 1),
+                    opacity: Math.min(style.fillOpacity * 2, 1) * dim,
                     borderRadius: 1,
                 } })), med !== null && (_jsx("div", { "data-list-median": "", style: {
                     position: 'absolute',
@@ -104,6 +116,7 @@ function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
                     left: `calc(${pct(med)} - ${style.medianWidth / 2}px)`,
                     width: style.medianWidth,
                     background: style.median,
+                    opacity: dim,
                 } })), tick !== null && (_jsxs(_Fragment, { children: [_jsx("div", { "data-list-tick": "", style: {
                             position: 'absolute',
                             top: 0,
@@ -112,6 +125,7 @@ function BoxLine({ row, col, scale, height, style, ink, fontSize, }) {
                             width: 3,
                             background: style.stroke,
                             borderRadius: 1,
+                            opacity: dim,
                         } }), label !== null && (_jsx("span", { "data-list-value": "", style: {
                             position: 'absolute',
                             left: `calc(${pct(tick)} + 8px)`,

package/dist/BoxPlot.d.ts

@@ -66,7 +66,8 @@ export interface BoxPlotCommon<S extends SeriesSchema = SeriesSchema, VS extends
      * contract `<BarChart>` / `<ScatterChart>` carry. With an `id`, a click on a
      * box (body or whisker — a range-only bid→ask segment included) selects it
      * (`selected`/`onSelect`) and pointer-over lights it (`hovered`/`onHover`);
-     * the box matching the selection's `(id, key)` outlines. **Omitted ⇒
+     * **every** box matching a selection member's `(id, key)` outlines, so a
+     * multi-mark `selected` set lights all of it. **Omitted ⇒
      * display-only** (a click resolves to empty space). `key` is the box's `x`
      * (its `begin`).
      */

package/dist/BoxPlot.js

@@ -1,12 +1,38 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { ValueSeries } from 'pond-ts';
+import { Interval, ValueSeries } from 'pond-ts';
+import { sweep1D } from './sweep.js';
 import { boxFromTimeSeries, boxFromValueSeries } from './data.js';
 import { boxAt, boxExtent, boxIndexAtTime, drawBox, isFiniteBox, } from './box.js';
+import { spansForLayer } from './span.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /** Whisker collapse floor (px) — a too-thin box still draws a 1px mark. */
 const MIN_BOX_WIDTH_PX = 1;
+/** Stable identity for "no keys of ours in this set" — the resting case, so the
+ *  layer doesn't re-register (and the canvas doesn't repaint) every time some
+ *  *other* layer's selection changes. */
+const NO_KEYS = [];
+/**
+ * The keys of every member of `set` naming this layer (`m.id === id`) — the
+ * narrowing that keeps `box.ts` free of the selection identity, exactly as
+ * `barAt` / `boxAt` keep it free of the theme.
+ *
+ * A box's identity within its series is its `x` (its `begin`), so the key is the
+ * whole match; a `SelectInfo.mark` is `undefined` for a box (see its docs) and
+ * has nothing to add here. Linear over the set — see `includesKey` in `box.ts`.
+ */
+function keysOf(set, id) {
+    if (id === undefined || set.length === 0)
+        return NO_KEYS;
+    const out = [];
+    for (let i = 0; i < set.length; i += 1) {
+        const m = set[i];
+        if (m.id === id)
+            out.push(m.key);
+    }
+    return out.length === 0 ? NO_KEYS : out;
+}
 /**
  * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
  * band. Reads **pre-computed quantile columns** of `series` (typically a
@@ -64,13 +90,42 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
     // The series identity for selection/legend: the `as` role, else the range
     // columns as a span (matches the legend row's label).
     const label = semantic ?? `${lower}–${upper}`;
-    // Current selection / hover narrowed to this layer's box key (its `x`), or
-    // `null` — matched by the series `id`, so a change re-registers the layer and
-    // the canvas repaints the outline. A no-`id` layer never matches.
+    // Current selection / hover narrowed to this layer's box keys (each box's
+    // `x`) — matched by the series `id`, so a change re-registers the layer and
+    // the canvas repaints the outlines. A no-`id` layer never matches.
     const sel = container.selected;
     const hov = container.hovered;
-    const selectedKey = id !== undefined && sel !== null && sel.id === id ? sel.key : null;
-    const hoveredKey = id !== undefined && hov !== null && hov.id === id ? hov.key : null;
+    // **Every** selected key belonging to this series, not just the first: the
+    // container's `selected` has been a set since [PND-MULTISEL] and `hovered`
+    // since RFC A4.3, and a draw path that reads `[0]` silently drops the rest —
+    // a consumer pinning three boxes saw one outline and no error.
+    const selectedKeys = useMemo(() => keysOf(sel, id), [sel, id]);
+    const hoveredKeys = useMemo(() => keysOf(hov, id), [hov, id]);
+    // The selection's span entries, narrowed to this layer (interaction RFC
+    // A5.2). Every box shares one label (the series label), so a span's `rows`
+    // channel resolves here once; `x`/`y` ride through for the draw's per-box
+    // test. Reference-stable when empty — see `keysOf`.
+    const layerSpans = useMemo(() => spansForLayer(container.selectedSpans, id, label), [container.selectedSpans, id, label]);
+    // The box's **column** — its `[x, xEnd)` slot, published as snap buckets
+    // exactly as a bar layer publishes its bins. A box *is* a bar that isn't
+    // grounded to the axis: an aggregation owning one interval of the key axis,
+    // drawn floating between two quantiles instead of rising from the baseline.
+    // That the ink doesn't reach the axis says nothing about which column the
+    // mark owns, so the region cursor snaps to boxes and a sweep cuts them
+    // slot-edge to slot-edge, same as bars (RFC A7.6's edge rule).
+    //
+    // Memoized off the shape alone, so a hover / selection change (which
+    // rebuilds the layer entry) doesn't re-allocate the intervals.
+    const binBuckets = useMemo(() => {
+        if (bx.length === 0)
+            return null;
+        const out = new Array(bx.length);
+        for (let i = 0; i < bx.length; i += 1) {
+            const b = bx.x[i];
+            out[i] = new Interval({ value: b, start: b, end: bx.xEnd[i] });
+        }
+        return out;
+    }, [bx]);
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
@@ -79,6 +134,7 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
             // infers the shared x kind from its layers.
             xKind: isValue ? 'value' : 'time',
             xExtent: () => bx.length === 0 ? null : [bx.x[0], bx.xEnd[bx.length - 1]],
+            ...(binBuckets !== null ? { binIntervals: () => binBuckets } : {}),
             sampleAt: (x) => {
                 // The readout reads the box **under the cursor** (boxIndexAtTime — span
                 // containment, not nearest-by-begin which flips past a wide box's
@@ -142,13 +198,48 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
                         const [, begin, value] = hit;
                         return { id, key: begin, value, color: style.whisker, label };
                     },
+                    // The `<MultiSelector>` sweep's range query, identical in shape
+                    // to the bar layer's: boxes are sorted, non-overlapping key
+                    // intervals, so the covered set is a contiguous run and
+                    // `sweep1D`'s two binary searches find it. Each materialised hit
+                    // is EXACTLY what `hitTest` reports for that box, so a swept box
+                    // and a clicked box are the same currency.
+                    beginSweep: () => bx.length === 0
+                        ? null
+                        : sweep1D({
+                            id,
+                            begin: bx.x,
+                            end: bx.xEnd,
+                            length: bx.length,
+                            // A gap box (its present quantiles not all finite) draws
+                            // nothing and owns no membership — the same rule
+                            // `hitTest` and the flag already apply.
+                            selectable: (i) => isFiniteBox(bx, i),
+                            materialize: (lo, hi) => {
+                                const out = [];
+                                for (let i = lo; i < hi; i += 1) {
+                                    if (!isFiniteBox(bx, i))
+                                        continue;
+                                    out.push({
+                                        id,
+                                        key: bx.x[i],
+                                        // `upper`, matching what `hitTest` reports.
+                                        value: bx.upper[i],
+                                        color: style.whisker,
+                                        label,
+                                    });
+                                }
+                                return out;
+                            },
+                        }),
                 }),
-            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian, offset, capWidth, selectedKey, hoveredKey, decimate),
+            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian, offset, capWidth, selectedKeys, hoveredKeys, decimate, layerSpans),
         },
         axisId: axis,
         index,
     }), [
         bx,
+        binBuckets,
         isValue,
         series,
         lower,
@@ -165,8 +256,9 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
         capWidth,
         id,
         label,
-        selectedKey,
-        hoveredKey,
+        selectedKeys,
+        hoveredKeys,
+        layerSpans,
         decimate,
         axis,
         index,

package/dist/Candlestick.d.ts

@@ -77,6 +77,18 @@ export interface CandlestickProps<S extends SeriesSchema> {
      * up/down candle pair.
      */
     legend?: boolean | string;
+    /**
+     * Stable series identity — **gates selection + hover**, the same id-gated
+     * contract `<BarChart>` / `<BoxPlot>` / `<ScatterChart>` carry. With an `id`,
+     * a click inside a candle's slot selects it (`selected`/`onSelect`),
+     * pointer-over lights it (`hovered`/`onHover`), and a `<MultiSelector>` can
+     * sweep a run of candles. **Omitted ⇒ display-only.** `key` is the candle's
+     * `x` (its slot begin).
+     *
+     * The state cues never touch the candle's colour — see {@link CandleStyle}
+     * for why a candle is the one mark whose hue cannot carry its state.
+     */
+    id?: string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -110,5 +122,5 @@ export interface CandlestickProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, decimate, legend, index, }: CandlestickProps<S>): null;
+export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, decimate, id, legend, index, }: CandlestickProps<S>): null;
 //# sourceMappingURL=Candlestick.d.ts.map

package/dist/Candlestick.js

@@ -1,9 +1,26 @@
 import { useContext, useEffect, useMemo } from 'react';
+import { Interval } from 'pond-ts';
 import { ohlcFromTimeSeries } from './data.js';
-import { drawCandles, isFiniteOhlc, ohlcExtent, ohlcIndexAtTime, resolveCandleStyle, } from './ohlc.js';
+import { drawCandles, isFiniteOhlc, ohlcAt, ohlcExtent, ohlcIndexAtTime, resolveCandleStyle, } from './ohlc.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+import { sweep1D } from './sweep.js';
+const NO_KEYS = [];
+/** This layer's keys within a selection / hover set — see `<BoxPlot>`'s twin.
+ *  Reference-stable when empty, so an untouched set doesn't rebuild the layer. */
+function keysOf(set, id) {
+    if (id === undefined || set.length === 0)
+        return NO_KEYS;
+    const out = [];
+    for (let i = 0; i < set.length; i += 1) {
+        const m = set[i];
+        if (m.id === id)
+            out.push(m.key);
+    }
+    return out.length === 0 ? NO_KEYS : out;
+}
+import { spansForLayer } from './span.js';
 /**
  * A first-class OHLC **candlestick** draw layer — the financial sibling of
  * {@link BoxPlot}. Reads four price columns (`open`/`high`/`low`/`close`) of
@@ -31,7 +48,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, decimate = true, legend, index = 0, }) {
+export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, decimate = true, id, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<Candlestick> must be rendered inside a <ChartContainer>');
@@ -47,12 +64,32 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
     // Series identity for the readout (the `as` role, else the close column name) —
     // the primary `close` pill keys on this, like every other layer.
     const label = semantic ?? close;
+    // Current selection / hover narrowed to this layer's candle keys (each
+    // candle's `x`), and the selection's span entries — the same three channels
+    // the bar and box layers narrow. A no-`id` layer never matches.
+    const selectedKeys = useMemo(() => keysOf(container.selected, id), [container.selected, id]);
+    const hoveredKeys = useMemo(() => keysOf(container.hovered, id), [container.hovered, id]);
+    const layerSpans = useMemo(() => spansForLayer(container.selectedSpans, id, label), [container.selectedSpans, id, label]);
+    // A candle owns one `[x, xEnd)` column of the key axis — an aggregation, the
+    // same as a box — so it publishes its slots as snap buckets and the region
+    // cursor / sweep band land on candle edges rather than centre-to-centre.
+    const binBuckets = useMemo(() => {
+        if (ohlc.length === 0)
+            return null;
+        const out = new Array(ohlc.length);
+        for (let i = 0; i < ohlc.length; i += 1) {
+            const b = ohlc.x[i];
+            out[i] = new Interval({ value: b, start: b, end: ohlc.xEnd[i] });
+        }
+        return out;
+    }, [ohlc]);
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
             yExtent: () => ohlcExtent(ohlc),
             xKind: 'time',
             xExtent: () => ohlc.length === 0 ? null : [ohlc.x[0], ohlc.xEnd[ohlc.length - 1]],
+            ...(binBuckets !== null ? { binIntervals: () => binBuckets } : {}),
             sampleAt: (time) => {
                 // The readout reads the candle **under the cursor** (containment span,
                 // not nearest-by-begin), anchored at the slot centre. Outside every
@@ -84,7 +121,51 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
                 ];
                 return samples;
             },
-            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap, undefined, decimate),
+            ...(id === undefined
+                ? {}
+                : {
+                    // Rect containment over the candle's slot (`ohlcAt`) — a candle
+                    // is a discrete interval mark, so this is the box's rule, not
+                    // the continuous nearest-point one. `key` is its `x`, `value`
+                    // its `close` (the price the default readout reports).
+                    hitTest: (px, py, xScale, yScale) => {
+                        const hit = ohlcAt(ohlc, px, py, xScale, yScale, gap, 1);
+                        if (hit === null)
+                            return null;
+                        const [i, begin, value] = hit;
+                        const { body } = resolveCandleStyle(style, ohlc.open[i], ohlc.close[i], colorBy);
+                        return { id, key: begin, value, color: body, label };
+                    },
+                    // Candles are sorted, non-overlapping columns, so a sweep is
+                    // `sweep1D`'s two binary searches — identical to the bar and box
+                    // layers, and each materialised hit is exactly what `hitTest`
+                    // reports for that candle.
+                    beginSweep: () => ohlc.length === 0
+                        ? null
+                        : sweep1D({
+                            id,
+                            begin: ohlc.x,
+                            end: ohlc.xEnd,
+                            length: ohlc.length,
+                            selectable: (i) => isFiniteOhlc(ohlc, i),
+                            materialize: (lo, hi) => {
+                                const out = [];
+                                for (let i = lo; i < hi; i += 1) {
+                                    if (!isFiniteOhlc(ohlc, i))
+                                        continue;
+                                    out.push({
+                                        id,
+                                        key: ohlc.x[i],
+                                        value: ohlc.close[i],
+                                        color: resolveCandleStyle(style, ohlc.open[i], ohlc.close[i], colorBy).body,
+                                        label,
+                                    });
+                                }
+                                return out;
+                            },
+                        }),
+                }),
+            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap, undefined, decimate, selectedKeys, hoveredKeys, layerSpans),
         },
         axisId: axis,
         index,
@@ -100,6 +181,11 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
         decimate,
         axis,
         index,
+        id,
+        binBuckets,
+        selectedKeys,
+        hoveredKeys,
+        layerSpans,
     ]);
     // Stable per-instance slot (see useSlotKey): keeps this candle layer's
     // z-position + identity across prop updates; the injected index drives the sort.

package/dist/ChartContainer.d.ts

@@ -2,7 +2,7 @@ import { type ReactNode } from 'react';
 import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingTimeScale.js';
 import { Sequence, BoundedSequence } from 'pond-ts';
 import type { TimeRange } from 'pond-ts';
-import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo, type DrawStatsFrame } from './context.js';
+import { type AnnotationKind, type CreateSpec, type CursorMode, type TrackerInfo, type DrawStatsFrame } from './context.js';
 import { type AxisFormat, type CursorFormat } from './format.js';
 import { type ChartTheme } from './theme.js';
 export interface ChartContainerProps {
@@ -165,6 +165,13 @@ export interface ChartContainerProps {
      * `'point'` / `'inline'` / `'flag'` add per-series marks; `'none'` hides it.
      * `'region'` shades the bucket under the pointer (needs {@link cursorSequence}).
      * See {@link CursorMode}.
+     *
+     * @deprecated Mount a **cursor component** instead — `<LineCursor>` /
+     * `<PointCursor>` / `<InlineCursor>` / `<FlagCursor>` / `<CrosshairCursor>` /
+     * `<RangeCursor>` as a child of the container (or inside a `<ChartRow>` for
+     * the per-row override); mount nothing for `'none'`. This prop keeps working
+     * for one more minor by synthesizing the equivalent preset internally; a
+     * mounted cursor component overrides it. See `docs/rfcs/interaction.md` §9.
      */
     cursor?: CursorMode;
     /**
@@ -187,6 +194,10 @@ export interface ChartContainerProps {
      * re-realizes the buckets on each pointer move (harmless for a coarse
      * day/session sequence, wasteful for a fine one over a wide view) — hoist it or
      * `useMemo` it.
+     *
+     * @deprecated Use `<RangeCursor sequence={…}>` — the prop moved onto the
+     * component that uses it, where it is no longer mode-conditional. Works for
+     * one more minor; a mounted `<RangeCursor>`'s sequence wins over this.
      */
     cursorSequence?: Sequence | BoundedSequence;
     /**
@@ -209,6 +220,12 @@ export interface ChartContainerProps {
      * domain is meaningless), so a **value** axis is always freeform. No-op unless
      * `cursor="region"` on a **time** or **value** x-axis (a **category** axis is
      * excluded — an ordinal-slot select is a different gesture).
+     *
+     * @deprecated Use `<RangeCursor onDragRelease>` — the drag moved onto the
+     * component, and the payload becomes `{ x: [lo, hi] }` (a {@link RangeSpan},
+     * forward-compatible with the 2-D drag's optional `y`) instead of the bare
+     * pair. Works for one more minor; a mounted `<RangeCursor onDragRelease>`
+     * takes over the gesture.
      */
     onRegionSelect?: (range: readonly [number, number]) => void;
     /**
@@ -219,6 +236,9 @@ export interface ChartContainerProps {
      * selects). **Omitted** ⇒ a region-drag
      * **preempts** pan (drag always selects; document that precedence for users).
      * Wheel-zoom is unaffected in every case.
+     *
+     * @deprecated Use `<RangeCursor dragModifier>` — the prop moved onto the
+     * component alongside `onDragRelease`. Works for one more minor.
      */
     regionSelectModifier?: 'shift';
     /**
@@ -237,51 +257,6 @@ export interface ChartContainerProps {
      * frame); route it to a ref/store rather than doing React state work per frame.
      */
     onDrawStats?: (frame: DrawStatsFrame) => void;
-    /**
-     * Controlled selection — the selected mark (echo the `onSelect` arg back), or
-     * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
-     * internally; pass `null` to force nothing selected). A layer is **selectable
-     * only when it carries an `id`** (the stable series identity) — `BarChart` /
-     * `ScatterChart` highlight the mark matching the selection's `id` (the series)
-     * and its `key` (the sample), so two series sharing a timestamp don't both
-     * light up, and the selection survives a data update (it keys on the stable
-     * `id`, not the sample `key`). A layer with no `id` renders + reads out but
-     * can't be selected.
-     */
-    selected?: SelectInfo | null;
-    /**
-     * Fires when a selectable layer's mark is clicked, with the hit mark, or `null`
-     * when a click misses every mark (or hits a layer with no `id` — display-only,
-     * so it reads as empty space). Notification only — works in both controlled and
-     * uncontrolled mode. If this or `selected` is set but no layer has an `id`, a
-     * dev-warning notes that nothing is selectable.
-     */
-    onSelect?: (hit: SelectInfo | null) => void;
-    /**
-     * Controlled hover-highlight — the transiently lit mark (echo the `onHover` arg
-     * back), or `null`. **Omitted ⇒ uncontrolled** (the pointer over a selectable
-     * layer manages it internally). The hover analog of {@link selected}: pass it to
-     * **pin** a lit mark from outside the chart (e.g. hovering a legend / list row
-     * lights the matching {@link BarChart} bar). Only layers with a hover-highlight
-     * (currently `BarChart`) render it; keyed by the same {@link SelectInfo} identity
-     * as selection.
-     */
-    hovered?: SelectInfo | null;
-    /**
-     * Fires when the pointer enters a selectable layer's mark (the hit mark) or
-     * leaves every mark (`null`) — the hover analog of {@link onSelect}. Notification
-     * only (works controlled or uncontrolled), and **deduped**: it fires on a mark
-     * transition, not on every pointer move. Wire it to mirror hover out-of-band
-     * (e.g. a list row ↔ the bar), pairing with {@link hovered} to sync both ways.
-     * (The annotation counterpart is {@link onHoverAnnotation}.)
-     *
-     * **Dedup key:** by the mark's `key` + `label` only (not `value`/`color`). So on
-     * a live chart where a bar's value changes while the cursor stays on it, this
-     * won't re-fire — read the current value from your series, not the last
-     * `onHover` payload. (Matches the internal hover-highlight, which repaints on
-     * key transitions.)
-     */
-    onHover?: (hit: SelectInfo | null) => void;
     /**
      * Which pan/zoom gestures the plot captures:
      *
@@ -296,7 +271,7 @@ export interface ChartContainerProps {
      * `false` ⇒ `'none'`). Bound the reachable range with {@link bounds}
      * (zoom-out / pan extent) and {@link minDuration} (zoom-in floor).
      */
-    panZoom?: boolean | 'none' | 'pan' | 'panZoom';
+    panZoom?: boolean | 'none' | 'pan' | 'panZoom' | 'panZoomX' | 'panZoomY' | 'panZoomXY';
     /**
      * **Outer pan/zoom extent** — `[min, max]` (same units as {@link range}) the
      * view can never move outside. Panning into an edge stops there (the window
@@ -327,6 +302,10 @@ export interface ChartContainerProps {
      * Show the cursor's time atop the in-chart readout (when a row's `cursor` draws
      * one). **Default `false`.** Formatted by {@link timeFormat} to match the time
      * axis.
+     *
+     * @deprecated Use `showTime` on the mounted cursor component
+     * (`<LineCursor showTime>` / `<FlagCursor showTime>` / …). Works for one
+     * more minor via the shim.
      */
     cursorTime?: boolean;
     /**
@@ -337,6 +316,10 @@ export interface ChartContainerProps {
      * the vertical line snaps its **x** to the data grid (so the time readout is
      * clean), and both draw a full-height dashed vertical + full-width dashed
      * horizontal line.
+     *
+     * @deprecated Use `<CrosshairCursor snap={…}>` — the prop moved onto the
+     * component, where it is no longer mode-conditional. Works for one more
+     * minor via the shim.
      */
     crosshairSnap?: boolean;
     /**
@@ -418,6 +401,11 @@ export interface ChartContainerProps {
      * {@link timeFormat} owns the labels. (A category axis reads names, and a
      * `transform`ed axis's pill speaks its derived unit — neither consults
      * `cursorFormat`.)
+     *
+     * @deprecated Use `format` on the mounted cursor (`<CrosshairCursor
+     * format={…}>`) — it feeds the same shared readout channel (marker
+     * indicators and annotation auto-labels included). Works for one more
+     * minor; a mounted cursor's `format` wins over this.
      */
     cursorFormat?: CursorFormat;
     /**
@@ -462,5 +450,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, panZoom, bounds, onTimeRangeChange, minDuration, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map