@pond-ts/charts 0.56.2 → 0.58.0

package/dist/selection-stories.js

@@ -0,0 +1,301 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { cloneElement, useMemo, useState, } from 'react';
+import { ChartContainer } from './ChartContainer.js';
+import { ChartRow } from './ChartRow.js';
+import { Layers } from './Layers.js';
+import { YAxis } from './YAxis.js';
+import { Selector, MultiSelector } from './selectors.js';
+import { isSpanSelection, sameMark, selectionContains } from './span.js';
+import { RangeCursor } from './cursors.js';
+import { caption } from './selection-fixtures.js';
+const H = 240;
+/**
+ * The chart under test, wired identically in every cell. `children` are
+ * non-wrapping registrants rendered before the row (e.g. `<Cursor/>`);
+ * `selector`, when given, is a `<Selector>`/`<MultiSelector>` element that
+ * WRAPS the row instead (A10.1) — `Chart` clones it with the row as its
+ * children, so a story only ever writes the selector element itself and never
+ * has to hand-nest `<ChartRow>` inside it.
+ */
+function Chart({ fx, children, height = H, selector, ...container }) {
+    const row = (_jsxs(ChartRow, { height: height, children: [_jsx(YAxis, { id: fx.axis.id, label: fx.axis.label, min: fx.axis.min, max: fx.axis.max }), _jsx(Layers, { children: fx.renderLayer('svc') })] }));
+    return (_jsxs(ChartContainer, { width: 640, ...fx.container, ...container, children: [children, selector ? cloneElement(selector, undefined, row) : row] }));
+}
+const list = (fx, sel) => sel.map((m) => fx.describe(m)).join(', ') || '—';
+export function makeSelectorStories(fx) {
+    const Cursor = () => (fx.rangeCursor ? _jsx(RangeCursor, {}) : null);
+    return {
+        /** **Mounted at the container** — the ordinary case: one `<Selector>` as a
+         *  child of `<ChartContainer>`, enabling the click for every row. It
+         *  reports; this story's `useState` is the selection. */
+        MountedAtContainer: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, selector: _jsx(Selector, { selected: sel, onSelect: (h) => setSel(h === null ? [] : [h]) }), children: _jsx(Cursor, {}) }), _jsxs("p", { style: caption, children: ["Click a mark to select it, empty space to clear.", ' ', _jsx("strong", { children: "selected:" }), " ", list(fx, sel)] })] }));
+            },
+        },
+        /** **Mounted inside a row** — nearest mount wins, mirroring the cursor
+         *  components. The top row selects; the bottom row's clicks are inert even
+         *  though its layer carries an `id`. */
+        MountedInRow: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                return (_jsxs("div", { children: [_jsxs(ChartContainer, { width: 640, ...fx.container, children: [_jsxs(ChartRow, { height: 150, children: [_jsx(YAxis, { id: fx.axis.id, label: fx.axis.label || 'primary', min: fx.axis.min, max: fx.axis.max }), _jsx(Cursor, {}), _jsx(Selector, { selected: sel, onSelect: (h) => setSel(h === null ? [] : [h]), children: _jsx(Layers, { children: fx.renderLayer('svc') }) })] }), _jsxs(ChartRow, { height: 110, children: [_jsx(YAxis, { id: fx.secondary.axis.id, label: fx.secondary.axis.label, min: fx.secondary.axis.min, max: fx.secondary.axis.max }), _jsx(Layers, { children: fx.secondary.renderLayer('err') })] })] }), _jsxs("p", { style: caption, children: ["The top row selects; the bottom row has no", ' ', _jsx("code", { children: "<Selector>" }), " in scope. ", _jsx("strong", { children: "selected:" }), ' ', list(fx, sel)] })] }));
+            },
+        },
+        /** **No selector — the plot is inert.** An id-bearing, hit-testable layer
+         *  whose clicks go nowhere: what a chart that selected on click *before*
+         *  §7.1 now looks like until one is mounted. In dev the first such click
+         *  logs a one-time migration warning. */
+        NoSelector: {
+            render: () => (_jsxs("div", { children: [_jsx(Chart, { fx: fx, children: _jsx(Cursor, {}) }), _jsx("p", { style: caption, children: "Click anywhere \u2014 nothing selects. Check the console for the one-time migration warning." })] })),
+        },
+        /** **Controlled selection, gesture disabled** — `enabled={false}` exists
+         *  to protect. The buttons stand in for the legend chip / filter list that
+         *  really drives this: the chart *displays* a selection owned elsewhere,
+         *  and the plot is deliberately inert. This is also why §7.1's warning
+         *  suppresses whenever controlled `selected` is in effect (A2.6). */
+        ControlledNoSelector: {
+            render: function Render() {
+                const [sel, setSel] = useState([
+                    fx.picks[0].info,
+                ]);
+                const btn = {
+                    font: '13px system-ui',
+                    padding: '4px 10px',
+                    marginRight: 6,
+                    cursor: 'pointer',
+                };
+                return (_jsxs("div", { children: [_jsx("div", { style: { marginBottom: 8 }, children: fx.picks.map((p) => (_jsx("button", { style: btn, onClick: () => setSel((cur) => cur.some((m) => sameMark(m, p.info))
+                                    ? cur.filter((m) => !sameMark(m, p.info))
+                                    : [...cur, p.info]), children: p.label }, p.label))) }), _jsx(Chart, { fx: fx, selector: _jsx(Selector, { enabled: false, selected: sel }) }), _jsxs("p", { style: caption, children: ["The buttons drive the highlight; clicking the plot does nothing.", ' ', _jsx("strong", { children: "selected:" }), " ", list(fx, sel)] })] }));
+            },
+        },
+        /** **The modifiers are reported; the policy is yours.** `onSelect`'s second
+         *  argument carries `additive` (⌘ on macOS, Ctrl elsewhere) plus the raw
+         *  keys. pond applies no policy and holds no set — the toggle below is this
+         *  story's few lines, not the library's. */
+        ModifiersReported: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [last, setLast] = useState('—');
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, selector: _jsx(Selector, { selected: sel, onSelect: (hit, mods) => {
+                                    setLast(hit === null
+                                        ? 'null hit → clear'
+                                        : `${fx.describe(hit)} · additive=${mods?.additive ?? false}` +
+                                            ` shift=${mods?.shiftKey ?? false}` +
+                                            ` alt=${mods?.altKey ?? false}`);
+                                    setSel((cur) => {
+                                        if (hit === null)
+                                            return [];
+                                        if (!(mods?.additive ?? false))
+                                            return [hit];
+                                        return cur.some((m) => sameMark(m, hit))
+                                            ? cur.filter((m) => !sameMark(m, hit))
+                                            : [...cur, hit];
+                                    });
+                                } }), children: _jsx(Cursor, {}) }), _jsxs("p", { style: caption, children: ["\u2318/Ctrl-click to add or remove; try shift and alt too.", ' ', _jsx("strong", { children: "reported:" }), " ", last, _jsx("br", {}), _jsx("strong", { children: "selected:" }), " ", list(fx, sel)] })] }));
+            },
+        },
+        /** **`onHover` only** — the readout-driving case. The click still selects
+         *  (the *mount* is the enablement, not the callback), driving the
+         *  container's own uncontrolled highlight since no `selected` is supplied. */
+        HoverOnly: {
+            render: function Render() {
+                const [hov, setHov] = useState(null);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, selector: _jsx(Selector, { hovered: hov, onHover: setHov }), children: _jsx(Cursor, {}) }), _jsxs("p", { style: caption, children: [_jsx("strong", { children: "hovered:" }), ' ', hov === null ? '—' : `${fx.describe(hov)} (${hov.value})`] })] }));
+            },
+        },
+        /** **A bare `<Selector />`** — no callbacks at all; the mount is the whole
+         *  statement. With no `selected` prop the container keeps the selection
+         *  itself: the smallest working chart under the new model. */
+        BareSelector: {
+            render: () => (_jsxs("div", { children: [_jsx(Chart, { fx: fx, selector: _jsx(Selector, {}), children: _jsx(Cursor, {}) }), _jsxs("p", { style: caption, children: ["Uncontrolled: ", _jsx("code", { children: "<Selector />" }), " with no props, no", ' ', _jsx("code", { children: "selected" }), "."] })] })),
+        },
+    };
+}
+// ── <MultiSelector> ────────────────────────────────────────────────────────
+const describeEntries = (fx, sel) => {
+    if (sel.length === 0)
+        return '—';
+    return sel
+        .map((e) => 'kind' in e && e.kind === 'span'
+        ? `span [${fx.describe({ key: e.x[0] })} → ${fx.describe({ key: e.x[1] })})`
+        : fx.describe(e))
+        .join(', ');
+};
+export function makeMultiSelectorStories(fx) {
+    if (!fx.sweep)
+        return null;
+    const stories = {
+        /** **Sweep, freeform.** Drag across the marks: the shared brush band
+         *  tracks the drag (bin-snapped — a bar layer's own bins feed the snap
+         *  channel), release reports the covered marks plus the span, and the
+         *  consumer feeds the **span** back as `selected` — one compact entry
+         *  however many marks it covers. A click still selects one. */
+        SweepMarks: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [count, setCount] = useState(0);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, onSelect: (hits, _mods, spans) => {
+                                    setCount(hits.length);
+                                    setSel(spans.length > 0 ? [...spans] : hits.slice(0, 1));
+                                } }) }), _jsxs("p", { style: caption, children: ["Drag to sweep \u00B7 click one mark to select just it \u00B7 click away to clear.", _jsx("br", {}), _jsx("strong", { children: "selected:" }), " ", describeEntries(fx, sel), " (", count, ' ', "marks)"] })] }));
+            },
+        },
+        /** **A click still selects one.** `<MultiSelector>` is a *superset* of
+         *  `<Selector>`: below `DRAG_SLOP` the gesture is a click and reports
+         *  `([hit], modifiers, null)` — a null span, since there is no range. */
+        ClickStillSelectsOne: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [shape, setShape] = useState('—');
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, onSelect: (hits, _mods, spans) => {
+                                    setShape(spans.length === 0
+                                        ? `click → ${hits.length} hit, no span`
+                                        : `sweep → ${hits.length} hits, ${spans.length} span(s)`);
+                                    setSel(spans.length > 0 ? [...spans] : hits);
+                                } }) }), _jsxs("p", { style: caption, children: ["Click, then drag, and watch the shape of the report change.", ' ', _jsx("strong", { children: "last:" }), " ", shape] })] }));
+            },
+        },
+        /** **Live preview.** Every covered mark lights through the plural
+         *  `hovered` while the drag is in flight — and at rest the block a drag
+         *  *would* select is already previewed. The count tracks the band before
+         *  release; on release the commit equals what was lit. */
+        LivePreviewDuringDrag: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [preview, setPreview] = useState(0);
+                const [committed, setCommitted] = useState(0);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, onHover: (hits) => setPreview(hits.length), onSelect: (hits, _mods, spans) => {
+                                    setCommitted(hits.length);
+                                    setSel(spans.length > 0 ? [...spans] : hits);
+                                } }) }), _jsxs("p", { style: caption, children: ["Hover, then drag, and watch the count track the band before you release.", _jsx("br", {}), _jsx("strong", { children: "previewing:" }), " ", preview, " marks \u00B7", ' ', _jsx("strong", { children: "last commit:" }), " ", committed, " marks"] })] }));
+            },
+        },
+        /** **Additive sweep, then edit.** ⌘/Ctrl-drag adds a span to the
+         *  selection. The policy is the consumer's — and note it must handle the
+         *  **click** case too: click and sweep arrive through one callback, so a
+         *  policy that only handles spans deletes the selection on the very
+         *  gesture meant to extend it. */
+        SweepAdditive: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, onSelect: (hits, mods, spans) => {
+                                    const add = mods?.additive ?? false;
+                                    if (spans.length > 0) {
+                                        setSel((cur) => (add ? [...cur, ...spans] : [...spans]));
+                                        return;
+                                    }
+                                    if (hits.length === 0)
+                                        return setSel([]);
+                                    setSel((cur) => (add ? [...cur, hits[0]] : [hits[0]]));
+                                } }) }), _jsxs("p", { style: caption, children: ["Sweep a range, then \u2318/Ctrl-click a mark to add it \u2014 and plain-click to replace. ", _jsx("strong", { children: "selected:" }), ' ', describeEntries(fx, sel)] })] }));
+            },
+        },
+        /** **Demote on edit (RFC A5.2).** A span is editable only *as a whole*; to
+         *  edit inside one, swap the span entry for the marks stashed at commit
+         *  time and filter. Plain array arithmetic — pond computes no policy, which
+         *  is exactly why the descriptor has this shape. */
+        DemoteOnEdit: {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [stash, setStash] = useState([]);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, onSelect: (hits, mods, spans) => {
+                                    if (spans.length > 0) {
+                                        setStash(hits);
+                                        setSel([...spans]);
+                                        return;
+                                    }
+                                    const hit = hits[0];
+                                    if (hit === undefined)
+                                        return setSel([]);
+                                    if (!(mods?.additive ?? false))
+                                        return setSel([hit]);
+                                    // The ⌘-click policy `selectionContains`' doc describes,
+                                    // written out in full: a mark already in the selection comes
+                                    // OUT, one that isn't goes in. The demote is the extra step
+                                    // a span needs before it can lose a member — it becomes the
+                                    // marks it covered, minus this one.
+                                    //
+                                    // Two mistakes this has already made, both worth the words:
+                                    //
+                                    // - **`sameMark`, not `m.key !== hit.key`.** A key IS a
+                                    //   bar's identity, so the shorter test looks right — and on
+                                    //   a stack or a heat map it knocks out every mark in the
+                                    //   bin, which showed up as a column-shaped hole.
+                                    // - **Handle the MARK arm too.** Demoting only rewrote the
+                                    //   span entries, so once the span was gone every later
+                                    //   ⌘-click fell through the `flatMap` unchanged and the
+                                    //   second knock-out silently did nothing.
+                                    setSel((cur) => selectionContains(cur, hit)
+                                        ? cur.flatMap((e) => isSpanSelection(e)
+                                            ? stash.filter((m) => !sameMark(m, hit))
+                                            : sameMark(e, hit)
+                                                ? []
+                                                : [e])
+                                        : [...cur, hit]);
+                                } }) }), _jsxs("p", { style: caption, children: ["Sweep a run, then \u2318/Ctrl-click marks inside it to knock them out one by one \u2014 the span demotes to its marks on the first, and every \u2318-click after that toggles. ", _jsx("strong", { children: "selected:" }), ' ', describeEntries(fx, sel)] })] }));
+            },
+        },
+    };
+    if (fx.sequence !== undefined) {
+        const seq = fx.sequence;
+        /** **Sweep, snapped to a sequence.** The band, the preview and the
+         *  committed span all snap to whole buckets — at rest the block under the
+         *  pointer is already previewed, so what will be selected is visible before
+         *  the drag starts. Only fixtures with a time bucketing generate this. */
+        stories.SweepWithSequence = {
+            render: function Render() {
+                const [sel, setSel] = useState([]);
+                const [count, setCount] = useState(0);
+                return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, sequence: seq(), onSelect: (hits, _mods, spans) => {
+                                    setCount(hits.length);
+                                    setSel(spans.length > 0 ? [...spans] : hits);
+                                } }) }), _jsxs("p", { style: caption, children: ["The sweep snaps to whole buckets \u2014 hover first and the whole block previews. ", _jsx("strong", { children: "selected:" }), " ", describeEntries(fx, sel), " (", count, " marks)"] })] }));
+            },
+        };
+    }
+    return stories;
+}
+export function makeSessionStories(fx) {
+    const sessions = fx.sessions;
+    if (sessions === undefined)
+        return null;
+    /** Both cells are the same chart under a different bucketing — the only
+     *  variable is the sequence, which is the whole comparison. */
+    const cell = (sequence, note) => ({
+        render: function Render() {
+            const [sel, setSel] = useState([]);
+            const [count, setCount] = useState(0);
+            const [preview, setPreview] = useState(0);
+            const seq = useMemo(sequence, []);
+            return (_jsxs("div", { children: [_jsx(Chart, { fx: fx, height: 220, selector: _jsx(MultiSelector, { selected: sel, sequence: seq, onHover: (hits) => setPreview(hits.length), onSelect: (hits, _mods, spans) => {
+                                setCount(hits.length);
+                                setSel(spans.length > 0 ? [...spans] : hits);
+                            } }) }), _jsxs("p", { style: caption, children: [note, _jsx("br", {}), _jsx("strong", { children: "previewing:" }), " ", preview, " bars \u00B7", ' ', _jsx("strong", { children: "selected:" }), " ", describeEntries(fx, sel), " (", count, ' ', "bars)"] })] }));
+        },
+    });
+    return {
+        /** **The bucketing agrees with the sessions.** One block per session, so
+         *  every block edge lands exactly on a divider and no block spans a
+         *  collapsed gap. Hover a bar and its whole session lights; a click
+         *  commits that session. */
+        SequenceConformsToSessions: cell(sessions.conforming, _jsxs(_Fragment, { children: ["One bucket ", _jsx("em", { children: "per session" }), ": the band's edges land on the dividers, and no block ever spans a break."] })),
+        /**
+         * **The bucketing doesn't.** A wall-clock day anchored mid-session, so a
+         * block is the afternoon of one session plus the morning of the next, and
+         * the band crosses a divider. The collapsed gap has zero width, so the
+         * block still draws as one rectangle — what it *contains* is two runs of
+         * bars from different days.
+         *
+         * The weekend is where that stops being cosmetic. Wall-clock buckets keep
+         * marching through Saturday and Sunday while the axis has no sessions to
+         * give them, so the uniform run of 7-bar blocks breaks into **4, then an
+         * empty bucket with no trading time in it at all, then 3** — a bucketing
+         * that ignores the session grid cannot keep its blocks the same size.
+         */
+        SequenceCrossesSessions: cell(sessions.crossing, _jsxs(_Fragment, { children: ["A wall-clock day anchored ", _jsx("em", { children: "mid-session" }), ": each block takes one afternoon plus the next morning, so the band crosses a divider. Hover either side of the ", _jsx("strong", { children: "weekend" }), " divider \u2014 the blocks there are 4 bars and 3, not 7, and the bucket between them holds no trading time at all."] })),
+    };
+}
+//# sourceMappingURL=selection-stories.js.map

package/dist/selectors.d.ts

@@ -0,0 +1,316 @@
+import { type ReactNode } from 'react';
+import type { Sequence, BoundedSequence } from 'pond-ts';
+import { type SelectInfo, type SelectModifiers, type SelectionEntry, type SelectorEntry, type SpanSelection } from './context.js';
+export interface SelectorProps {
+    /**
+     * `false` disables the **gesture** — no hit-testing, `onHover`/`onSelect`
+     * never fire, a plot click behaves as if `<Selector>` weren't mounted at
+     * all. **Omitted ⇒ `true`.**
+     *
+     * `<Selector enabled={false} selected={sel} />` is controlled highlighting
+     * with no plot gesture — a legend chip or an external filter list driving
+     * the chart, deliberately inert on click (interaction RFC A10.2).
+     */
+    enabled?: boolean;
+    /**
+     * Controlled selection — the selected mark(s) (echo `onSelect`'s hit 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.
+     *
+     * **Accepts a set**: an array lights several marks at once, and array
+     * entries may be {@link SpanSelection}s (a swept range, demoted to one
+     * entry instead of enumerating every covered mark). A single `SelectInfo`
+     * still works and means exactly what it did.
+     */
+    selected?: SelectInfo | readonly SelectionEntry[] | null;
+    /**
+     * Controlled hover-highlight — the transiently lit mark(s), or `null`.
+     * **Omitted ⇒ uncontrolled.** The hover analog of {@link selected}: pass it
+     * to pin lit marks from outside the chart (e.g. hovering a legend / list row
+     * lights the matching bar). Accepts a single mark or a set, the same union
+     * `selected` takes.
+     */
+    hovered?: SelectInfo | readonly SelectInfo[] | null;
+    /**
+     * What is under the pointer — one {@link SelectInfo}, or `null` on leaving
+     * every mark. Deduped by the mark's full identity, so it fires on a mark
+     * transition rather than on every pointer move.
+     */
+    onHover?: (hit: SelectInfo | null) => void;
+    /**
+     * What was clicked — one {@link SelectInfo}, or `null` for a click that hit
+     * no mark (the deselect path) — plus the modifiers held.
+     *
+     * **The library reports; you decide.** `modifiers.additive` is the
+     * platform-idiomatic add chord (⌘ on macOS, Ctrl elsewhere); pond applies no
+     * policy to it and holds no set. Compute the next selection yourself and
+     * feed it back as this same component's `selected`:
+     *
+     * ```tsx
+     * <Selector
+     *   selected={sel}
+     *   onSelect={(hit, mods) =>
+     *     setSel(
+     *       hit === null ? [] : mods?.additive ? toggle(sel, hit) : [hit],
+     *     )
+     *   }
+     * />
+     * ```
+     *
+     * `modifiers` is absent for a **programmatic** select (a `<Legend>` chip),
+     * which carries no keyboard state.
+     */
+    onSelect?: (hit: SelectInfo | null, modifiers?: SelectModifiers) => void;
+    /**
+     * What it applies to (interaction RFC A10.1): every `<ChartRow>` when
+     * mounted as a direct child of `<ChartContainer>`, or just one row when
+     * mounted inside that `<ChartRow>`. Optional — `<Selector />` with no
+     * children keeps working exactly as it always has.
+     *
+     * **Row-scoped, wrap the row's `<Layers>` — not its axes.** `<ChartRow>`
+     * places axes into gutters by matching its *own* children against `<YAxis>`,
+     * so an axis nested inside this component is invisible to that sort and
+     * renders in the plot column instead. Dev warns if you do.
+     *
+     * ```tsx
+     * <ChartRow height={180}>
+     *   <YAxis id="v" />                  // stays a direct child of the row
+     *   <Selector selected={sel} onSelect={setSel}>
+     *     <Layers>…</Layers>
+     *   </Selector>
+     * </ChartRow>
+     * ```
+     */
+    children?: ReactNode;
+}
+/**
+ * Mount it to make the plot **click-selectable** (RFC §7.1) and to hold the
+ * selection state that produces — wrap every `<ChartRow>` as a direct child of
+ * `<ChartContainer>`, or wrap one row's **`<Layers>`** to scope the *gesture*
+ * to that row (interaction RFC A10.1; see {@link SelectorProps.children} for
+ * why the axes stay outside).
+ *
+ * **Placement scopes the gesture, not the state.** A {@link SelectInfo} names a
+ * *layer*, not a row, so `selected` / `hovered` apply chart-wide wherever this
+ * sits — one selector should own each per chart (first registered wins, dev
+ * warns otherwise).
+ *
+ * ```tsx
+ * <ChartContainer>
+ *   <Selector
+ *     selected={sel}
+ *     hovered={hov}
+ *     onSelect={(hit, mods) => …}
+ *     onHover={setHov}
+ *   >
+ *     <ChartRow>…</ChartRow>
+ *   </Selector>
+ * </ChartContainer>
+ * ```
+ *
+ * `value`/`onChange`, one component: `selected` is what's lit, `onSelect`
+ * reports what changes it, and the mount itself is what makes a plot click do
+ * anything. Need controlled highlighting with **no** plot click at all?
+ * `enabled={false}`.
+ */
+export declare function Selector({ enabled, selected, hovered, onHover, onSelect, children, }?: SelectorProps): import("react/jsx-runtime").JSX.Element;
+export interface MultiSelectorProps {
+    /**
+     * `false` disables the gesture — no hit-testing, no armed sweep, callbacks
+     * never fire. **Omitted ⇒ `true`.** See {@link SelectorProps.enabled};
+     * applies identically here.
+     */
+    enabled?: boolean;
+    /**
+     * Controlled selection — the state half of what `onSelect` reports. See
+     * {@link SelectorProps.selected}; `<MultiSelector>` additionally accepts
+     * {@link SpanSelection} entries directly, which is exactly the shape a
+     * sweep's `onSelect` hands back.
+     */
+    selected?: SelectInfo | readonly SelectionEntry[] | null;
+    /** Controlled hover-highlight — see {@link SelectorProps.hovered}. Accepts
+     *  a set, since a sweep's live preview lights several marks at once. */
+    hovered?: SelectInfo | readonly SelectInfo[] | null;
+    /**
+     * Snap the sweep to buckets — a pond `Sequence` (realized over the view) or
+     * `BoundedSequence` (used as-is; a trading calendar's sessions). A drag
+     * extends **bucket by bucket** over these, capturing every mark the snapped
+     * window covers. **Omit ⇒ freeform**: the sweep covers the raw drag span (a
+     * bar/histogram layer's bins still snap it when present — the same shared
+     * snap-bucket channel `<RangeCursor sequence>` feeds). Pass a stable
+     * reference (the realized buckets memoize on it).
+     */
+    sequence?: Sequence | BoundedSequence;
+    /**
+     * The marks the gesture currently covers — or **would** cover:
+     *
+     * - **At rest**, the marks of the **snap block under the pointer** (the
+     *   `sequence` bucket, else the layer's own bin/slot), reported once per
+     *   block transition. This is the resting preview: hovering ANY mark of a
+     *   block reports the whole block, because that is exactly the set a drag
+     *   begun and released there would select.
+     * - **During a sweep**, every covered mark, updated as the drag crosses
+     *   marks (coalesced to animation frames past the first cut).
+     *
+     * Echo it back as this component's `hovered` only when you control hover —
+     * uncontrolled, the covered marks already light through the container's
+     * own hover state (RFC A3.4: the library owns the state, each layer draws
+     * its own hover treatment).
+     */
+    onHover?: (hits: readonly SelectInfo[]) => void;
+    /**
+     * The committed selection, on release (RFC A5.2's signature):
+     *
+     * - **A sweep** reports every covered mark, the modifiers held, and the
+     *   {@link SpanSelection}s the coverage demotes to — `hits` are the
+     *   materialised live preview (no fresh range query), `spans` are the
+     *   snapped-outward extents whose `selectionContains` test reproduces
+     *   exactly `hits`. Feed `[...others, ...spans]` back as this component's
+     *   `selected` and stash `hits` for A5.2's demote-on-edit: to edit *inside*
+     *   a span later, swap that span entry for the stashed hits and filter —
+     *   plain array arithmetic, no interval math.
+     * - **A click** (no movement past the drag slop) is `<Selector>`'s gesture
+     *   in this currency: one hit (or none — the deselect path), the modifiers,
+     *   and an **empty** `spans`. Clicks produce marks; only sweeps produce
+     *   spans.
+     *
+     * **`spans` is plural because one sweep can commit several.** A trace sweep
+     * produces one span per trace ([PND-TRACESEL]): every trace shares the swept
+     * x window, so singling one out by z-order would be arbitrary to the reader.
+     * Mark layers keep topmost-wins, so there it holds exactly one. **Topmost
+     * layer first**, and compare spans by `id` rather than identity — each
+     * span-only layer clamps the window to *its own* key range, so two traces of
+     * different extents report different `x` for one drag.
+     *
+     * `modifiers` is absent for a **programmatic** select (a `<Legend>` chip),
+     * as on `<Selector onSelect>`. **The library reports; you decide** — pond
+     * applies no policy to the modifiers and holds no set.
+     */
+    onSelect?: (hits: readonly SelectInfo[], modifiers: SelectModifiers | undefined, spans: readonly SpanSelection[]) => void;
+    /** What it applies to — see {@link SelectorProps.children} (interaction RFC
+     *  A10.1); identical scoping rule. */
+    children?: ReactNode;
+}
+/**
+ * `<MultiSelector>` — **sweep-select as a mounted component** (interaction RFC
+ * §8 / A4.2 / A10), a superset of `<Selector>`: a click still selects one mark,
+ * and a drag past the slop **sweeps** — the band extends (bucket by bucket
+ * with a {@link MultiSelectorProps.sequence}, freeform without), every
+ * covered mark lights through the plural `hovered` as the drag moves, and
+ * release commits `(hits, modifiers, spans)` once. The gesture rides the
+ * shared brush recognizer (`brush.tsx`) and draws the same band `<RangeCursor>`
+ * does — identical pixels, different currency (§8.1): the range cursor
+ * releases an extent, this releases **marks** (which is what folds the
+ * category axis in — ordinal and continuous are the same gesture when nobody
+ * sees a numeric range).
+ *
+ * ```tsx
+ * <ChartContainer>
+ *   <MultiSelector
+ *     selected={sel}
+ *     sequence={daily}
+ *     onSelect={(hits, mods, spans) => …}
+ *   >
+ *     <ChartRow>…</ChartRow>
+ *   </MultiSelector>
+ * </ChartContainer>
+ * ```
+ *
+ * Wraps what it applies to, same as `<Selector>`; `selected` / `hovered` live
+ * here too. The sweep captures marks from the row's **topmost** sweep-capable
+ * layer (the z-order rule a click already follows); a layer without an `id`
+ * is never swept (Q8).
+ *
+ * **Mounting also changes the row's RESTING state** — the grey band and the
+ * hover are a live preview of the block a drag would select:
+ *
+ * - The shared brush band becomes the **resting cursor**, spanning the snap
+ *   block under the pointer (the `sequence` bucket, else the layer's own
+ *   bin/slot), replacing the container's implicit `'line'` default. An
+ *   explicitly chosen cursor — a mounted component, or a legacy `cursor`
+ *   string the consumer actually set — still wins the surface.
+ * - Hover is **block-scoped**: pointing at any one mark of a block lights
+ *   (and reports) every mark in it. Rest and drag share one code path — the
+ *   same snap buckets, the same layer session — so what the rest previews and
+ *   what a drag commits cannot disagree; the drag just grows the same band.
+ */
+export declare function MultiSelector({ enabled, selected, hovered, sequence, onHover, onSelect, children, }?: MultiSelectorProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * **Value-equality for a registered selector — the guard that stops a
+ * controlled selection from looping.** `registerSelector` must no-op when the
+ * incoming entry is value-equal to the stored one, exactly as `registerAxis`
+ * does via `axisSpecEqual` (`ChartRow.tsx`), and for the same reason spelled
+ * out there: register → `setState` → re-render → register is a
+ * "Maximum update depth exceeded" spin.
+ *
+ * A10.3 made this guard load-bearing rather than defensive. The entry now
+ * carries the controlled *values*, and a consumer writing
+ * `selected={[hit]}` — or `selected={[{ id, key, … }]}` — mints a fresh
+ * reference every render. On its own that is survivable, because a
+ * container-only state update does not re-run the consumer's JSX. **But a
+ * descendant that consumes the container context and renders that inline
+ * array does re-run** — `useChartLegend()` is a supported example — so the
+ * chain became: registry update → new frame → context change → descendant
+ * re-render → fresh array → register → registry update, without end. Compare
+ * by value and the cycle closes on the first iteration. (Codex finding on
+ * #638; the reference-only guard it replaces was mine.)
+ *
+ * Cost: the common case is a stable array from `useState`, which hits the
+ * reference fast path. A fresh array costs one element-wise pass with no
+ * allocation, which is the right trade against an unbounded render loop.
+ */
+export declare function selectorEntryEqual(a: SelectorEntry, b: SelectorEntry): boolean;
+/**
+ * The selectors in effect for a row's GESTURE: the row's own mounts when it has
+ * any (the per-row scope — nearest mount wins, mirroring
+ * `effectiveCursorEntries`), else the container-scoped mounts. A
+ * `gestureEnabled: false` entry (`<Selector enabled={false}>`) is filtered out
+ * entirely — it behaves as unmounted for click/hover/sweep purposes, exactly
+ * as `enabled` promises.
+ *
+ * `rowKey` of `null` asks for the **container** scope only — the programmatic
+ * (legend) path, which belongs to no row.
+ *
+ * Controlled-state resolution does **not** use this function — state is
+ * chart-wide, not row-scoped, and a disabled selector may still own it. See
+ * {@link resolveControlledSelected} / {@link resolveControlledHovered}.
+ */
+export declare function effectiveSelectorEntries(all: readonly SelectorEntry[], rowKey: symbol | null): readonly SelectorEntry[];
+/**
+ * Resolve the chart-wide controlled `selected`, from whichever registered
+ * selector declared it. Not row-scoped — selection identity spans every row
+ * (a `SelectInfo.id` names a layer, not a row) — and not filtered on
+ * `gestureEnabled`: `<Selector enabled={false} selected={…}>` is exactly the
+ * "state, no gesture" configuration `enabled` exists for.
+ */
+export declare function resolveControlledSelected(all: readonly SelectorEntry[], warned: {
+    current: boolean;
+}): {
+    readonly present: boolean;
+    readonly value: SelectInfo | readonly SelectionEntry[] | null;
+};
+/** As {@link resolveControlledSelected}, for `hovered`. */
+export declare function resolveControlledHovered(all: readonly SelectorEntry[], warned: {
+    current: boolean;
+}): {
+    readonly present: boolean;
+    readonly value: SelectInfo | readonly SelectInfo[] | null;
+};
+/**
+ * RFC §7.1's softening: a plot click resolved to a real mark and there was no
+ * `<Selector>` to tell — the exact path that goes silently inert on upgrade.
+ *
+ * **Suppressed when controlled `selected` is in effect** (A2.6) — that is the
+ * runtime signature of the *endorsed* controlled-highlight setup
+ * (`<Selector enabled={false} selected={…}>`, plot deliberately inert), and
+ * the warning should not spend its loudness on people already doing that.
+ *
+ * Not permanent: once mounting is the established model, an `id` without a
+ * `<Selector>` is a legitimate configuration (Q8) and warning on it forever
+ * would flag a supported setup. Fires once per container.
+ */
+export declare function warnInertClick(warned: {
+    current: boolean;
+}): void;
+//# sourceMappingURL=selectors.d.ts.map