@pond-ts/charts 0.57.0 → 0.59.0

package/dist/selectors.js

@@ -0,0 +1,391 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useMemo, useRef, } from 'react';
+import { isDev } from './dev.js';
+import { isSpanSelection } from './span.js';
+import { ContainerContext, RowContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * Register a selector with the container, scoped to the enclosing `<ChartRow>`
+ * when there is one (that row's clicks only) else the container (every row).
+ *
+ * The registered entry is memoized on which callbacks are *present* (not their
+ * identity — read through a ref at report time) and on the controlled state
+ * values — a consumer writing `<Selector onSelect={(hit) => …} />` passes a
+ * fresh function every render, and re-registering on each one would thrash the
+ * container's registry state (and, since the registry is `useState`, loop).
+ */
+function useSelectorMount(opts) {
+    const { cb, gestureEnabled, multi = false, sequence, declaresSelected, selected, declaresHovered, hovered, } = opts;
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<Selector> must be mounted inside a <ChartContainer> (as a direct ' +
+            'child, or inside a <ChartRow> to scope it to that row)');
+    }
+    const row = useContext(RowContext);
+    const rowKey = row?.rowKey ?? null;
+    const key = useSlotKey();
+    const cbRef = useRef(cb);
+    useLayoutEffect(() => {
+        cbRef.current = cb;
+    });
+    const hasHover = cb.onHover !== undefined;
+    const hasSelect = cb.onSelect !== undefined;
+    const hasHoverMany = cb.onHoverMany !== undefined;
+    const hasSelectMany = cb.onSelectMany !== undefined;
+    const entry = useMemo(() => ({
+        onHover: gestureEnabled && hasHover
+            ? (hit) => cbRef.current.onHover?.(hit)
+            : undefined,
+        // Forward the modifiers with the arity we were called with. `select()`
+        // omits them for a programmatic (legend) select, and passing an
+        // explicit `undefined` there would change the observed arity for every
+        // consumer asserting `toHaveBeenCalledWith(hit)`.
+        onSelect: gestureEnabled && hasSelect
+            ? (hit, modifiers) => {
+                if (modifiers === undefined)
+                    cbRef.current.onSelect?.(hit);
+                else
+                    cbRef.current.onSelect?.(hit, modifiers);
+            }
+            : undefined,
+        multi,
+        onHoverMany: gestureEnabled && hasHoverMany
+            ? (hits) => cbRef.current.onHoverMany?.(hits)
+            : undefined,
+        onSelectMany: gestureEnabled && hasSelectMany
+            ? (hits, modifiers, spans) => cbRef.current.onSelectMany?.(hits, modifiers, spans)
+            : undefined,
+        sequence: gestureEnabled ? sequence : undefined,
+        rowKey,
+        gestureEnabled,
+        declaresSelected,
+        selected,
+        declaresHovered,
+        hovered,
+    }), [
+        gestureEnabled,
+        hasHover,
+        hasSelect,
+        hasHoverMany,
+        hasSelectMany,
+        multi,
+        sequence,
+        rowKey,
+        declaresSelected,
+        selected,
+        declaresHovered,
+        hovered,
+    ]);
+    const { registerSelector, unregisterSelector } = container;
+    // **`useLayoutEffect`, not `useEffect`** — this registration is the path
+    // controlled `selected` / `hovered` now travel (A10.3), and a passive effect
+    // would make them a commit late: the first paint after a `selected` change
+    // would show the *previous* selection, and a mount with `selected` already
+    // set would flash unselected before lighting up. The old container props were
+    // render-synchronous, so anything slower here is a visible regression rather
+    // than a micro-optimisation. (Reviewer finding on #638.)
+    useLayoutEffect(() => {
+        registerSelector(key, entry);
+    }, [registerSelector, key, entry]);
+    // Unregistration is a LAYOUT cleanup too, and the symmetry is load-bearing.
+    // With a passive cleanup the two halves ran in different phases, so removing
+    // a selector left its entry in the registry for one commit — the container
+    // drew once from a dead owner — and a keyed remount registered the new owner
+    // (layout) *before* the old one was dropped (passive), which put both in the
+    // Map at once and let "first registered wins" hand the old value out until
+    // cleanup caught up. Fixing the read path (above) without fixing the teardown
+    // just moved the stale window. (Codex finding on #638.)
+    useLayoutEffect(() => () => unregisterSelector(key), [unregisterSelector, key]);
+}
+/**
+ * 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 function Selector({ enabled = true, selected, hovered, onHover, onSelect, children, } = {}) {
+    useSelectorMount({
+        cb: { onHover, onSelect },
+        gestureEnabled: enabled,
+        declaresSelected: selected !== undefined,
+        selected,
+        declaresHovered: hovered !== undefined,
+        hovered,
+    });
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * `<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 function MultiSelector({ enabled = true, selected, hovered, sequence, onHover, onSelect, children, } = {}) {
+    useSelectorMount({
+        cb: {
+            onHover: undefined,
+            onSelect: undefined,
+            onHoverMany: onHover,
+            onSelectMany: onSelect,
+        },
+        gestureEnabled: enabled,
+        multi: true,
+        sequence,
+        declaresSelected: selected !== undefined,
+        selected,
+        declaresHovered: hovered !== undefined,
+        hovered,
+    });
+    return _jsx(_Fragment, { children: children });
+}
+/** One controlled entry — a mark or a span — compared by the fields that carry
+ *  its identity, so a freshly-built object literal equals the one it replaces. */
+function entryValueEqual(a, b) {
+    if (a === b)
+        return true;
+    const aSpan = isSpanSelection(a);
+    if (aSpan !== isSpanSelection(b))
+        return false;
+    if (aSpan) {
+        const x = a;
+        const y = b;
+        if (x.id !== y.id)
+            return false;
+        if (x.x[0] !== y.x[0] || x.x[1] !== y.x[1])
+            return false;
+        if ((x.y === undefined) !== (y.y === undefined))
+            return false;
+        if (x.y && y.y && (x.y[0] !== y.y[0] || x.y[1] !== y.y[1]))
+            return false;
+        if ((x.rows === undefined) !== (y.rows === undefined))
+            return false;
+        if (x.rows && y.rows) {
+            if (x.rows.length !== y.rows.length)
+                return false;
+            for (let i = 0; i < x.rows.length; i += 1)
+                if (x.rows[i] !== y.rows[i])
+                    return false;
+        }
+        return true;
+    }
+    const m = a;
+    const n = b;
+    return (m.id === n.id &&
+        Object.is(m.key, n.key) &&
+        Object.is(m.value, n.value) &&
+        m.label === n.label &&
+        m.mark === n.mark &&
+        m.color === n.color);
+}
+/** Value-equality for a controlled `selected` / `hovered`, over all three of
+ *  its accepted shapes (a single mark, a set, or nothing). */
+function controlledValueEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || a === undefined || b === null || b === undefined)
+        return false;
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (!aArr)
+        return entryValueEqual(a, b);
+    const x = a;
+    const y = b;
+    if (x.length !== y.length)
+        return false;
+    for (let i = 0; i < x.length; i += 1)
+        if (!entryValueEqual(x[i], y[i]))
+            return false;
+    return true;
+}
+/**
+ * **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 function selectorEntryEqual(a, b) {
+    if (a === b)
+        return true;
+    return (a.rowKey === b.rowKey &&
+        a.multi === b.multi &&
+        a.gestureEnabled === b.gestureEnabled &&
+        a.sequence === b.sequence &&
+        a.declaresSelected === b.declaresSelected &&
+        a.declaresHovered === b.declaresHovered &&
+        // The callbacks are stable wrappers over a ref, so their *presence* is
+        // what can change, and presence is what the entry is memoized on.
+        (a.onSelect === undefined) === (b.onSelect === undefined) &&
+        (a.onHover === undefined) === (b.onHover === undefined) &&
+        (a.onSelectMany === undefined) === (b.onSelectMany === undefined) &&
+        (a.onHoverMany === undefined) === (b.onHoverMany === undefined) &&
+        controlledValueEqual(a.selected, b.selected) &&
+        controlledValueEqual(a.hovered, b.hovered));
+}
+/**
+ * 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 function effectiveSelectorEntries(all, rowKey) {
+    const active = all.filter((e) => e.gestureEnabled);
+    if (rowKey !== null) {
+        const rowEntries = active.filter((e) => e.rowKey === rowKey);
+        if (rowEntries.length > 0)
+            return rowEntries;
+    }
+    return active.filter((e) => e.rowKey === null);
+}
+/** Fires once per container: more than one registered selector declared the
+ *  same controlled state, which is ambiguous — the first registered wins and
+ *  every other declaration is silently ignored until this is resolved. */
+function warnAmbiguousControlledState(prop) {
+    console.warn(`[pond-charts] more than one mounted <Selector>/<MultiSelector> declares ` +
+        `\`${prop}\` in the same chart — only the first registered is used, the ` +
+        `rest are ignored. One selector should own \`${prop}\` per chart.`);
+}
+/**
+ * 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 function resolveControlledSelected(all, warned) {
+    const owner = pickControlledOwner(all, (e) => e.declaresSelected, warned, 'selected');
+    return owner
+        ? { present: true, value: owner.selected ?? null }
+        : { present: false, value: null };
+}
+/** As {@link resolveControlledSelected}, for `hovered`. */
+export function resolveControlledHovered(all, warned) {
+    const owner = pickControlledOwner(all, (e) => e.declaresHovered, warned, 'hovered');
+    return owner
+        ? { present: true, value: owner.hovered ?? null }
+        : { present: false, value: null };
+}
+function pickControlledOwner(all, has, warned, prop) {
+    const owners = all.filter(has);
+    if (owners.length === 0)
+        return null;
+    if (isDev && owners.length > 1 && !warned.current) {
+        warned.current = true;
+        warnAmbiguousControlledState(prop);
+    }
+    return owners[0];
+}
+/**
+ * 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 function warnInertClick(warned) {
+    if (warned.current)
+        return;
+    warned.current = true;
+    console.warn('[pond-charts] a click hit a mark but no <Selector> is mounted (or the ' +
+        'one in scope has `enabled={false}`), so nothing happened. Mount ' +
+        '`<Selector onSelect={…}>` wrapping the chart (or one <ChartRow> to ' +
+        'scope it to that row) — click-select is no longer implied by giving a ' +
+        'layer an `id`. See docs/rfcs/interaction.md §7.1. (Silent if ' +
+        'controlled `selected` is in effect: controlled highlighting with an ' +
+        'inert plot is a supported setup.)');
+}
+//# sourceMappingURL=selectors.js.map

package/dist/span.d.ts

@@ -0,0 +1,122 @@
+import type { SelectInfo, SelectionEntry, SpanSelection } from './context.js';
+/**
+ * Span-selection membership — the one place the containment rule lives
+ * (interaction RFC A5.2/A5.3, edge rule A7.6).
+ *
+ * `selectionContains` is the **public** predicate, and it is deliberately the
+ * same code every layer's draw runs per mark ({@link spanContainsPoint} for
+ * span entries): a consumer asking "is this hit already selected?" must get
+ * exactly the answer the canvas paints, or the boundary marks disagree with
+ * the span that swept them — the inverse-band-scale friction the marks
+ * currency was built to kill (`selection.md` A4.2) re-imported through the
+ * back door.
+ *
+ * Pure, DOM-free, theme-free — unit-tests like `select.ts` does.
+ */
+/** Stable identity for "no spans" — the resting case, shared by the container
+ *  normalization and every layer's narrowing, so a spanless render never hands
+ *  a draw (or a memo dep) a fresh empty array. */
+export declare const NO_SPANS: readonly SpanSelection[];
+/**
+ * Is this `selected` entry a span descriptor rather than a single mark? The
+ * discriminant is the `kind` field, which {@link SelectInfo} does not have —
+ * useful to a consumer editing a mixed selection (RFC A5.2's demote-on-edit:
+ * filter the span out, splice in the marks it stashed at commit time).
+ */
+export declare function isSpanSelection(entry: SelectionEntry): entry is SpanSelection;
+/**
+ * Does `span` contain the mark with these channels? The containment rule of
+ * {@link SpanSelection}, minus the layer-`id` gate (the caller has already
+ * matched it — a layer narrows the set to its own `id` once per render, not
+ * once per mark):
+ *
+ * - `key` in the **half-open** `x` interval — `x[0] <= key < x[1]`;
+ * - `value` in the half-open `y` interval, when the span has one;
+ * - `label` a member of `rows`, when the span has one.
+ *
+ * Each channel is the mark's own {@link SelectInfo} field, so the test is
+ * answerable from a hit alone *and* from a draw loop's per-mark scalars — the
+ * property RFC A5.3 requires (nothing here reads a slot index or a pixel).
+ * `NaN` in any tested channel fails its comparison, so a series-scoped entry
+ * (`key: NaN`) or a gap value is never inside any span. A span carrying `rows`
+ * tested against a caller with no label channel (`label === undefined`)
+ * matches nothing — a row-set has to be checked, not skipped.
+ *
+ * O(1) per mark (plus O(|rows|) for the label set, which is a handful of row
+ * names) — the whole point of the descriptor: a span covering ten thousand
+ * marks costs each of them one interval test, not a ten-thousand-entry scan.
+ */
+export declare function spanContainsPoint(span: SpanSelection, key: number, value: number, label: string | undefined): boolean;
+/**
+ * Does **any** of `spans` contain the mark with these channels? The set form of
+ * {@link spanContainsPoint}, for the draw loops — `spans` is the layer's
+ * already-`id`-narrowed list (see {@link spansForLayer}), so this is pure
+ * channel tests. Linear over the spans for the reason `barMatchesAny` records
+ * about mark sets: a selection is a handful of entries, and the common cases
+ * (0 or 1) short-circuit.
+ */
+export declare function spanMatchesAny(spans: readonly SpanSelection[], key: number, value: number, label?: string): boolean;
+/**
+ * Narrow the container's span set to one layer — the span analog of the
+ * per-layer mark narrowing every chart component already does (`keysOf`,
+ * `marksOf`): drop the spans naming other layers, and — when the layer's marks
+ * all share **one** label (`label` given: a single-series bar, scatter or box,
+ * whose `SelectInfo.label` is the series label) — resolve the `rows` channel
+ * here, once, instead of per mark: a row set that excludes the constant label
+ * can never match and is dropped; one that includes it always matches and is
+ * stripped. Layers whose label varies per mark (a stack's groups, a heat map's
+ * rows) pass no `label` and keep `rows` for the draw to test per mark.
+ *
+ * Returns {@link NO_SPANS} when nothing survives, so the resting case keeps a
+ * stable identity (no re-registered layer, no repaint, when some *other*
+ * layer's spans change).
+ */
+export declare function spansForLayer(spans: readonly SpanSelection[], id: string | undefined, label?: string): readonly SpanSelection[];
+/**
+ * **Are these the same mark?** The full mark identity, matching the
+ * container's own hover dedup: same layer `id`, same per-mark handle — the
+ * stable `mark` when **both** sides carry one, else the sample `key` (the
+ * `barMatches` fallback rule) — and same `label`, which on a grouped layer
+ * (stack segment, heat cell) is the half of the identity that separates two
+ * marks sharing a bin. `NaN` keys never match (`NaN !== NaN`), so a
+ * series-scoped legend entry names no mark, deliberately.
+ *
+ * Exported as the companion to {@link selectionContains}, whose doc has
+ * always told a consumer to write `remove(cur, hit)` without giving them
+ * anything to write it with. **`key` alone is not identity**, and reaching
+ * for it is the natural mistake: it is right for a bar, a box and a candle,
+ * and on a stack or a heat map it silently takes out every mark in the bin.
+ * `<MultiSelector>`'s own demote-on-edit stories made exactly that error, in
+ * three places, in the file that is supposed to be the worked example —
+ * which is why this is a library export and not a docs note.
+ */
+export declare function sameMark(a: SelectInfo, b: SelectInfo): boolean;
+/**
+ * Is `hit` inside the selection — named by a mark entry, or covered by a span
+ * (interaction RFC A5.2)? **The same predicate the layers run**, exported so a
+ * consumer implementing click-policy over a mixed selection (toggle a mark out,
+ * ⌘-click-add next to a swept span) never re-implements the interval test in
+ * axis units — the exact friction `selection.md` A4.2's marks currency exists
+ * to eliminate.
+ *
+ * ```tsx
+ * onSelect={(hit, mods) =>
+ *   setSelected((cur) =>
+ *     hit === null ? []
+ *     : mods?.additive
+ *       ? selectionContains(cur, hit)
+ *         ? cur.filter((e) => isSpanSelection(e) || !sameMark(e, hit))
+ *         : [...cur, hit]
+ *       : [hit],
+ *   )
+ * }
+ * ```
+ *
+ * Span entries use {@link SpanSelection}'s containment rule (half-open `x`/`y`
+ * intervals on the hit's `key`/`value`, `rows` membership on its `label`);
+ * mark entries use the full mark identity (`id`, `mark`-or-`key`, `label`).
+ * Entries naming another layer's `id` never match. O(|sel|) with O(1) per
+ * entry, spans included.
+ */
+export declare function selectionContains(sel: readonly SelectionEntry[], hit: SelectInfo): boolean;
+//# sourceMappingURL=span.d.ts.map