@pond-ts/charts 0.57.0 → 0.59.0

package/dist/box.js

@@ -1,8 +1,28 @@
+import { NO_SPANS, spanMatchesAny } from './span.js';
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
 import { decimateBox } from './decimate.js';
 /** Fraction of the box width the whisker end-caps span (centred on the stem). */
 const WHISKER_CAP_FRACTION = 0.5;
+/** Stable identity for "no keys" — the common resting case, so a caller that
+ *  narrows an empty set doesn't hand `drawBox` a fresh array every frame. */
+const NO_KEYS = [];
+/**
+ * Is `key` one of `keys`? The set form of the `key === selectedKey` check
+ * {@link drawBox} used to make ([PND-MULTISEL] / RFC A4.3).
+ *
+ * Linear over the set on purpose, the same reasoning `barMatchesAny` records: a
+ * selection is a handful of marks a person clicked, not a data structure, so
+ * building a `Set` per draw would cost more than it saves — and the common cases
+ * (0 or 1 members) short-circuit immediately.
+ */
+function includesKey(keys, key) {
+    for (let i = 0; i < keys.length; i += 1) {
+        if (keys[i] === key)
+            return true;
+    }
+    return false;
+}
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
  * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
@@ -110,10 +130,22 @@ export function boxAt(box, px, py, xScale, yScale, gapPx, minWidthPx, offsetPx =
  */
 export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true, offsetPx = 0, capWidthPx, 
 // Selection / hover highlight, keyed by the box's `x` (its `begin`, matched to
-// the container selection's `key` by the caller). `null` ⇒ none. A selected
-// box gets a full-strength bounding outline; a hovered one a fainter one —
-// the box analog of the bar highlight, drawn without a new theme token.
-selectedKey = null, hoveredKey = null, decimate = true) {
+// the container selection's `key` by the caller). **Sets** — every box whose
+// key is named lights, so a multi-mark selection or a drag-sweep hover shows
+// all of it, not just its first member ([PND-MULTISEL] / RFC A4.3). Empty ⇒
+// none. A selected box gets a full-strength bounding outline; a hovered one a
+// fainter one — the box analog of the bar highlight, drawn without a new theme
+// token. A box in **both** sets reads as selected (selected outranks hovered,
+// the precedence `drawBars` / `drawStacks` share).
+selectedKeys = NO_KEYS, hoveredKeys = NO_KEYS, decimate = true, 
+// Span descriptors covering this layer (interaction RFC A5.2), already
+// narrowed to its `id` (and constant-label `rows` resolved) by the component
+// — see `spansForLayer`. A box is selected when its key is named OR a span
+// contains it: the O(1) half-open test of its `x` (its key) against the
+// span's `x`, and — mirroring the hit's `value` provenance — its `upper`
+// against `y` when present. Suppressed while decimated, like the key match:
+// an aggregate column is not a source box and must not light as one.
+spans = NO_SPANS) {
     const sourceCount = box.length; // pre-cull, pre-decimation (for draw stats)
     // Viewport cull first (Phase 2): the [vStart, vEnd) boxes whose span overlaps
     // the window (+1 each side). Full range when `xScale` has no domain (a stub);
@@ -153,16 +185,91 @@ selectedKey = null, hoveredKey = null, decimate = true) {
         // q1/q3 are NaN on a range-only box — read them only when there's a body.
         const yQ1 = hasBox ? yScale(box.q1[i]) : 0;
         const yQ3 = hasBox ? yScale(box.q3[i]) : 0;
+        // The mark's interaction state, resolved **before** the shape branch: a
+        // solid box paints it as its fill (bar parity), every shape paints it as
+        // the outline below. A decimated aggregate box carries synthetic keys a
+        // mark entry can't name — but a span's interval WOULD contain them, so it
+        // is gated off explicitly (per-box highlight is meaningless at decimation
+        // density, and lighting an aggregate column would claim marks the
+        // selection never held).
+        const key = box.x[i];
+        const isSelected = includesKey(selectedKeys, key) ||
+            (!decimated &&
+                spans.length > 0 &&
+                spanMatchesAny(spans, key, box.upper[i]));
+        // Selected outranks hovered on a box that is both — the same precedence the
+        // bar paths document, and what the `key === selectedKey` test did before.
+        const isHovered = !isSelected && includesKey(hoveredKeys, key);
+        // Recede the rest, exactly as `drawBars` does: only with a real selection
+        // (marks or spans) in play.
+        const dimming = selectedKeys.length > 0 || spans.length > 0;
+        // **The tint ladder.** One four-step ladder per state, so a state change is
+        // a single palette swap and every mark keeps its position in the quantile
+        // read (step 0 body/outer · 1 inner · 2 stroke+whisker · 3 median). The
+        // ladder carries meaning in *lightness*, so rotating its hue leaves every
+        // relationship between the marks intact — which is why a box can do the
+        // plain teal→blue shift a multi-hue stacked bar cannot.
+        //
+        // Dimming is opacity alone. A single-hue ladder has nothing to muddy into,
+        // so there is no desaturated companion of the kind `bar.groupsDimmed` is.
+        const states = style.states;
+        const ladder = states
+            ? isSelected
+                ? states.selected
+                : isHovered
+                    ? states.hover
+                    : states.rest
+            : undefined;
+        // Applied to *every* mark of the box, so the whole ladder recedes together.
+        const stateAlpha = states !== undefined && dimming && !isSelected && !isHovered
+            ? states.dimmedOpacity
+            : 1;
+        // A hairline can't carry a state in hue: at 1px a colour change is nearly
+        // invisible, so selection bumps the weight too.
+        const strokeW = isSelected && style.selectedStrokeWidth !== undefined
+            ? style.selectedStrokeWidth
+            : style.strokeWidth;
+        const whiskerW = isSelected && style.selectedStrokeWidth !== undefined
+            ? style.selectedStrokeWidth
+            : style.whiskerWidth;
+        // Bracket an op group **only** when the alpha actually differs from 1.
+        // Without this every box would emit two extra canvas ops per group even on
+        // the legacy path, where `stateAlpha` is always 1 — a draw-sequence change
+        // for every existing consumer in exchange for nothing.
+        const dimmed = stateAlpha !== 1;
+        const withAlpha = (fn) => {
+            if (!dimmed)
+                return fn();
+            ctx.save();
+            ctx.globalAlpha = stateAlpha;
+            fn();
+            ctx.restore();
+        };
+        // Ladder steps, falling back to the flat tokens when no ladder is set.
+        const cFill = ladder?.[0] ?? style.fill;
+        const cInner = ladder?.[1] ?? style.fill;
+        const cStroke = ladder?.[2] ?? style.stroke;
+        const cMedian = ladder?.[3] ?? style.median;
+        const cWhisker = ladder?.[2] ?? style.whisker;
+        // With a ladder the step colours are opaque by design (lightness is the
+        // encoding, not alpha); the legacy path keeps its translucent fill.
+        const baseFillAlpha = ladder !== undefined ? 1 : style.fillOpacity;
         if (shape === 'solid') {
             // Candlestick: a light outer bar over the full lower→upper spread, then —
             // when there's a body — a more-prominent inner q1→q3 box on top (same fill
             // at rising opacity). No stems, no outline.
+            // With a ladder the two tiers are two *steps* (0 outer, 1 inner), which
+            // is what keeps the tier read identical in every state. Without one they
+            // are one colour at two alphas, as before.
             ctx.save();
-            ctx.fillStyle = style.fill;
-            ctx.globalAlpha = style.fillOpacity;
+            ctx.fillStyle = cFill;
+            ctx.globalAlpha = baseFillAlpha * stateAlpha;
             ctx.fillRect(x0, yUpper, x1 - x0, yLower - yUpper);
             if (hasBox) {
-                ctx.globalAlpha = Math.min(1, style.fillOpacity * 2);
+                ctx.fillStyle = cInner;
+                ctx.globalAlpha =
+                    (ladder !== undefined ? 1 : Math.min(1, style.fillOpacity * 2)) *
+                        stateAlpha;
                 ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
             }
             ctx.restore();
@@ -171,13 +278,15 @@ selectedKey = null, hoveredKey = null, decimate = true) {
             // `whisker` / `none`: the graded q1→q3 box fill + outline (body only).
             if (hasBox) {
                 ctx.save();
-                ctx.fillStyle = style.fill;
-                ctx.globalAlpha = style.fillOpacity;
+                ctx.fillStyle = cFill;
+                ctx.globalAlpha = baseFillAlpha * stateAlpha;
                 ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
                 ctx.restore();
-                ctx.strokeStyle = style.stroke;
-                ctx.lineWidth = style.strokeWidth;
-                ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+                withAlpha(() => {
+                    ctx.strokeStyle = cStroke;
+                    ctx.lineWidth = strokeW;
+                    ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+                });
             }
             if (shape === 'whisker') {
                 // Whiskers with end-caps. With a body: two stems (q3→upper, q1→lower).
@@ -188,45 +297,54 @@ selectedKey = null, hoveredKey = null, decimate = true) {
                 const capHalf = capWidthPx !== undefined
                     ? Math.min(capWidthPx, x1 - x0) / 2
                     : ((x1 - x0) * WHISKER_CAP_FRACTION) / 2;
-                ctx.strokeStyle = style.whisker;
-                ctx.lineWidth = style.whiskerWidth;
-                ctx.beginPath();
-                // Upper stem: from the box top (q3) or, range-only, from lower.
-                ctx.moveTo(mid, hasBox ? yQ3 : yLower);
-                ctx.lineTo(mid, yUpper);
-                ctx.moveTo(mid - capHalf, yUpper);
-                ctx.lineTo(mid + capHalf, yUpper);
-                // Lower cap (and, with a body, the lower stem q1→lower).
-                if (hasBox) {
-                    ctx.moveTo(mid, yQ1);
-                    ctx.lineTo(mid, yLower);
-                }
-                ctx.moveTo(mid - capHalf, yLower);
-                ctx.lineTo(mid + capHalf, yLower);
-                ctx.stroke();
+                withAlpha(() => {
+                    ctx.strokeStyle = cWhisker;
+                    ctx.lineWidth = whiskerW;
+                    ctx.beginPath();
+                    // Upper stem: from the box top (q3) or, range-only, from lower.
+                    ctx.moveTo(mid, hasBox ? yQ3 : yLower);
+                    ctx.lineTo(mid, yUpper);
+                    ctx.moveTo(mid - capHalf, yUpper);
+                    ctx.lineTo(mid + capHalf, yUpper);
+                    // Lower cap (and, with a body, the lower stem q1→lower).
+                    if (hasBox) {
+                        ctx.moveTo(mid, yQ1);
+                        ctx.lineTo(mid, yLower);
+                    }
+                    ctx.moveTo(mid - capHalf, yLower);
+                    ctx.lineTo(mid + capHalf, yLower);
+                    ctx.stroke();
+                });
             }
         }
         // The median line across the box, on top — drawn only when the box carries a
         // median column and `showMedian` is on.
         if (drawMedian) {
             const yMedian = yScale(box.median[i]);
-            ctx.strokeStyle = style.median;
-            ctx.lineWidth = style.medianWidth;
-            ctx.beginPath();
-            ctx.moveTo(x0, yMedian);
-            ctx.lineTo(x1, yMedian);
-            ctx.stroke();
+            withAlpha(() => {
+                ctx.strokeStyle = cMedian;
+                ctx.lineWidth = style.medianWidth;
+                ctx.beginPath();
+                ctx.moveTo(x0, yMedian);
+                ctx.lineTo(x1, yMedian);
+                ctx.stroke();
+            });
         }
         // Selection / hover: outline the whole mark (x-slot × whisker extent) so a
         // click / pointer-over reads back on the canvas. Selected = full strength;
-        // hovered = fainter. Bracketed so alpha/width don't leak to the next box.
-        const key = box.x[i];
-        if (key === selectedKey || key === hoveredKey) {
+        // hovered = fainter. **Every** named box lights, not only the first — so a
+        // set of pinned boxes, or a sweep hovering several at once, all read back.
+        // Bracketed so alpha/width don't leak to the next box.
+        // **Without a ladder**, the bounding outline is the whole state cue — the
+        // shipped behaviour, kept for any theme that sets no `states`. With one it
+        // is superseded and deliberately not drawn: the ladder already moved every
+        // mark, and a bounding rect on top would claim the empty slot around a
+        // whisker as part of the mark.
+        if (ladder === undefined && (isSelected || isHovered)) {
             ctx.save();
             ctx.strokeStyle = style.stroke;
-            ctx.lineWidth =
-                key === selectedKey ? style.strokeWidth + 1 : style.strokeWidth;
-            ctx.globalAlpha = key === selectedKey ? 1 : 0.5;
+            ctx.lineWidth = isSelected ? style.strokeWidth + 1 : style.strokeWidth;
+            ctx.globalAlpha = isSelected ? 1 : 0.5;
             ctx.strokeRect(x0, yUpper, x1 - x0, yLower - yUpper);
             ctx.restore();
         }

package/dist/brush.d.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from 'react';
+import type { ContainerFrame, CursorEntry, ResolvedCursorFrame } from './context.js';
+/**
+ * The **brush recognizer** — the one engine that arbitrates every drag claim
+ * on the plot surface (interaction RFC A1.5 / A2.7).
+ *
+ * A drag on the plot has several would-be owners, and before this module the
+ * ordering that resolved them lived implicitly in `Layers.handlePointerDown`'s
+ * statement order. Turning claimants into mounted components
+ * (`<RangeCursor>`, later `<MultiSelector>`) makes that ordering **public
+ * API**, so it is written down once, here, and `Layers` routes on the answer.
+ *
+ * ## Precedence — highest claim wins
+ *
+ * 0. **Mark-edit** (`DragArea` in `annotations.tsx`). DOM-level: an editable
+ *    annotation's handles sit *above* the plot surface and stop propagation,
+ *    so the engine never sees the press. Listed so the full order is in one
+ *    place; it is not a case this resolver returns.
+ * 1. **Annotation-create capture** — an armed `creating` tool owns the whole
+ *    surface (the press starts a draw, never a pan or a range drag).
+ * 2. **The sweep** — a mounted `<MultiSelector>` in scope (RFC §8), when the
+ *    row has a sweep-capable layer. A *selection* gesture is the most
+ *    specific intent a drag can carry (the selector was deliberately
+ *    mounted), so it preempts both the range drag and pan; a drag-enabled
+ *    `<RangeCursor>` competing in the same scope is shadowed, and
+ *    {@link warnSweepShadowsRangeDrag} says so (A1.5 asked for the
+ *    arbitration to be written down, not implied). The sweep arms behind
+ *    `DRAG_SLOP` — a plain click stays a click and selects one mark (§8.1:
+ *    the two are separated by movement, not modifier).
+ * 3. **The range drag** ({@link resolveRangeDrag}) — a drag-enabled
+ *    `<RangeCursor>` in the hovered row's effective cursor set, else the
+ *    legacy `cursor="region"` + `onRegionSelect` container props. Preempts
+ *    pan — unless a `dragModifier` is declared **and pan is enabled**, in
+ *    which case a plain drag falls through to pan and only a modifier-held
+ *    drag brushes. (With pan off there is no gesture to share, so the
+ *    modifier is not enforced.)
+ * 4. **Pan** — armed behind `DRAG_SLOP`, so a click never nudges the view.
+ * 5. **Nothing** — the press is a potential click; hover/select handle it.
+ *
+ * The recognizer resolves the claim **at pointer-down**; the per-claim
+ * sessions (create preview, range anchor, sweep session, pan anchor) stay in
+ * `Layers`, keyed off the refs the claim seeds. `<RangeCursor>` and
+ * `<MultiSelector>` both drive the same range-drag session — anchor, bucket
+ * snap, the shared band — only what fires on release differs (a span vs.
+ * marks), which is A1.5's "one brush engine, two components".
+ */
+/** What a completed range drag calls with the released `[start, end]`
+ *  (axis units, `start ≤ end`). Resolved once at pointer-down — the component
+ *  path wraps `onDragRelease` (the `{ x }` payload), the legacy path wraps
+ *  `onRegionSelect` (the bare pair). */
+export interface RangeDrag {
+    readonly release: (start: number, end: number) => void;
+    /** The modifier the drag needs — only enforced while pan is enabled. */
+    readonly modifier: 'shift' | undefined;
+}
+/**
+ * Resolve whether a press could start a **range drag**, and who gets the
+ * released span. Two sources, component first:
+ *
+ * 1. **A mounted `<RangeCursor>`** — the hovered row's effective
+ *    gesture-owning cursor (`owner`), when it carries `onDragRelease` and is
+ *    not frozen (`enableDrag={false}` — the OFF switch, which also suppresses
+ *    the legacy fallback: the consumer wired the new API and asked for no
+ *    gesture). A `<RangeCursor>` without `onDragRelease` has nothing to fire,
+ *    so it does not claim — the legacy props keep working underneath it
+ *    during the deprecation window (exactly the step-2 behaviour).
+ * 2. **The legacy container props** — `cursor="region"` + `onRegionSelect`
+ *    (+ `regionSelectModifier`), byte-for-byte today's semantics, including
+ *    the bare-pair payload.
+ *
+ * Continuous x only (time or value): a category axis has no span to drag
+ * (an ordinal-slot select is a different gesture), so both paths gate on it.
+ */
+export declare function resolveRangeDrag(c: Pick<ContainerFrame, 'cursor' | 'onRegionSelect' | 'regionSelectModifier' | 'xKind'>, owner: CursorEntry | undefined): RangeDrag | null;
+/** Who owns the drag a pointer-down might start (see the module doc's
+ *  precedence order). `'none'` = the press is a potential click only. */
+export type BrushClaim = {
+    readonly kind: 'create';
+} | {
+    readonly kind: 'sweep';
+} | {
+    readonly kind: 'range';
+    readonly drag: RangeDrag;
+} | {
+    readonly kind: 'pan';
+} | {
+    readonly kind: 'none';
+};
+/**
+ * The claim decision at pointer-down — pure, so the precedence order is
+ * testable without a DOM. Inputs are the already-resolved facts:
+ *
+ * - `creating` — an annotation tool is armed (claim 1).
+ * - `sweep` — a mounted `<MultiSelector>` is in scope AND the row has a
+ *   sweep-capable layer (claim 2). The sweep preempts the range drag and pan
+ *   unconditionally — mounting the selector is the intent, and it carries no
+ *   modifier gate of its own.
+ * - `drag` — {@link resolveRangeDrag}'s answer (claim 3), whose `modifier`
+ *   gates it behind the key **only while pan is enabled**.
+ * - `canPan` — this surface has a pan to arm (claim 4): x-pan on a
+ *   continuous axis, or any y-pan.
+ */
+export declare function resolveBrushClaim(opts: {
+    readonly creating: boolean;
+    readonly sweep?: boolean;
+    readonly drag: RangeDrag | null;
+    readonly shiftKey: boolean;
+    readonly panEnabled: boolean;
+    readonly canPan: boolean;
+}): BrushClaim;
+/**
+ * Dev-warn (once per plot surface) when a press found BOTH a mounted
+ * `<MultiSelector>` and a live range drag (a drag-enabled `<RangeCursor>`, or
+ * the legacy region props) competing for it — the sweep wins (see the module
+ * doc's precedence), and a silent shadow would hide the loser exactly the way
+ * A1.5 said docs alone couldn't.
+ */
+export declare function warnSweepShadowsRangeDrag(warned: {
+    current: boolean;
+}): void;
+/**
+ * The **shared band renderer** — the brush's one visual, so the components
+ * driving the engine cannot drift apart (RFC A1.5): `<RangeCursor>` renders
+ * it via its spec's `renderPlot` slot, and `<MultiSelector>`'s sweep renders
+ * the *same function* from `Layers` while a sweep is live (§8.1 — identical
+ * pixels is the design, so there is exactly one place that draws them). The
+ * container resolves `f.band` / `f.bandLine`; this only draws them.
+ */
+export declare function renderBrushBand(f: ResolvedCursorFrame): ReactNode;
+/**
+ * The **2-D brush renderer** — the rect a sweep paints over a `twoD` layer
+ * (a scatter, a heat map), the counterpart of {@link renderBrushBand} and
+ * drawn from the same `theme.brush` tokens so the two brushes read as one
+ * gesture in two dimensionalities.
+ *
+ * A small `+` sits on each end of the drag diagonal: the corner the press
+ * anchored and the corner under the pointer. That is the whole reason
+ * {@link ResolvedCursorFrame.rect} arrives unsorted — sorting first would put
+ * both crosses on the same diagonal regardless of which way the drag went.
+ */
+export declare function renderBrushRect(f: ResolvedCursorFrame): ReactNode;
+//# sourceMappingURL=brush.d.ts.map

package/dist/brush.js

@@ -0,0 +1,179 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Resolve whether a press could start a **range drag**, and who gets the
+ * released span. Two sources, component first:
+ *
+ * 1. **A mounted `<RangeCursor>`** — the hovered row's effective
+ *    gesture-owning cursor (`owner`), when it carries `onDragRelease` and is
+ *    not frozen (`enableDrag={false}` — the OFF switch, which also suppresses
+ *    the legacy fallback: the consumer wired the new API and asked for no
+ *    gesture). A `<RangeCursor>` without `onDragRelease` has nothing to fire,
+ *    so it does not claim — the legacy props keep working underneath it
+ *    during the deprecation window (exactly the step-2 behaviour).
+ * 2. **The legacy container props** — `cursor="region"` + `onRegionSelect`
+ *    (+ `regionSelectModifier`), byte-for-byte today's semantics, including
+ *    the bare-pair payload.
+ *
+ * Continuous x only (time or value): a category axis has no span to drag
+ * (an ordinal-slot select is a different gesture), so both paths gate on it.
+ */
+export function resolveRangeDrag(c, owner) {
+    if (c.xKind !== 'time' && c.xKind !== 'value')
+        return null;
+    if (owner !== undefined && !owner.legacy && owner.onDragRelease) {
+        // Frozen: the gesture is off without unwiring the callback (§6's
+        // `enableDrag`-as-disabler) — and the legacy fallback stays off too.
+        if (owner.enableDrag === false)
+            return null;
+        const cb = owner.onDragRelease;
+        return {
+            release: (start, end) => cb({ x: [start, end] }),
+            modifier: owner.dragModifier,
+        };
+    }
+    if (c.cursor === 'region' && c.onRegionSelect !== undefined) {
+        const cb = c.onRegionSelect;
+        return {
+            release: (start, end) => cb([start, end]),
+            modifier: c.regionSelectModifier,
+        };
+    }
+    return null;
+}
+/**
+ * The claim decision at pointer-down — pure, so the precedence order is
+ * testable without a DOM. Inputs are the already-resolved facts:
+ *
+ * - `creating` — an annotation tool is armed (claim 1).
+ * - `sweep` — a mounted `<MultiSelector>` is in scope AND the row has a
+ *   sweep-capable layer (claim 2). The sweep preempts the range drag and pan
+ *   unconditionally — mounting the selector is the intent, and it carries no
+ *   modifier gate of its own.
+ * - `drag` — {@link resolveRangeDrag}'s answer (claim 3), whose `modifier`
+ *   gates it behind the key **only while pan is enabled**.
+ * - `canPan` — this surface has a pan to arm (claim 4): x-pan on a
+ *   continuous axis, or any y-pan.
+ */
+export function resolveBrushClaim(opts) {
+    if (opts.creating)
+        return { kind: 'create' };
+    if (opts.sweep === true)
+        return { kind: 'sweep' };
+    if (opts.drag !== null) {
+        const needsShift = opts.drag.modifier === 'shift' && opts.panEnabled;
+        if (!needsShift || opts.shiftKey)
+            return { kind: 'range', drag: opts.drag };
+        // Modifier required but not held → the press falls through to pan.
+    }
+    if (opts.canPan)
+        return { kind: 'pan' };
+    return { kind: 'none' };
+}
+/**
+ * Dev-warn (once per plot surface) when a press found BOTH a mounted
+ * `<MultiSelector>` and a live range drag (a drag-enabled `<RangeCursor>`, or
+ * the legacy region props) competing for it — the sweep wins (see the module
+ * doc's precedence), and a silent shadow would hide the loser exactly the way
+ * A1.5 said docs alone couldn't.
+ */
+export function warnSweepShadowsRangeDrag(warned) {
+    if (warned.current)
+        return;
+    warned.current = true;
+    console.warn('[pond-charts] a <MultiSelector> and a drag-enabled <RangeCursor> (or ' +
+        'the legacy onRegionSelect props) are both in scope for this plot — ' +
+        'the sweep claims the drag and the range drag never fires. Mount one ' +
+        'drag owner per scope, or freeze the cursor with enableDrag={false}. ' +
+        'See docs/rfcs/interaction.md A1.5 / §8.1.');
+}
+/**
+ * The **shared band renderer** — the brush's one visual, so the components
+ * driving the engine cannot drift apart (RFC A1.5): `<RangeCursor>` renders
+ * it via its spec's `renderPlot` slot, and `<MultiSelector>`'s sweep renders
+ * the *same function* from `Layers` while a sweep is live (§8.1 — identical
+ * pixels is the design, so there is exactly one place that draws them). The
+ * container resolves `f.band` / `f.bandLine`; this only draws them.
+ */
+export function renderBrushBand(f) {
+    // The cursor ink — the theme's cursor colour, else the axis label colour
+    // (same resolution as the cursor presets' `cursorInk`).
+    const ink = f.theme.cursor ?? f.theme.axis.label;
+    // The band's own colours come from `theme.brush` when the theme sets it.
+    // With no `brush` this is the pre-token look exactly: cursor ink at 0.12,
+    // no edges — so an existing hand-built theme's band does not shift.
+    const brush = f.theme.brush;
+    const bandFill = brush?.fill ?? ink;
+    const bandOpacity = brush === undefined ? 0.12 : 1;
+    const edge = brush?.edge;
+    // The transposed band (`sweepAxis: 'y'` — a horizontal bar's bins run down
+    // the screen). Same tokens, same two-edges-while-dragging rule, geometry
+    // rotated: full width, bounded on y. Rendered from this function rather than
+    // a sibling so the promise that there is exactly one brush visual survives
+    // the second orientation.
+    // Truthiness rather than `!== null`, so a hand-built frame that predates
+    // this field (several tests, and any consumer's) keeps the x behaviour
+    // instead of crashing on an absent one.
+    const by = f.bandY;
+    if (by) {
+        const y0 = Math.min(by.y0, by.y1);
+        const y1 = Math.max(by.y0, by.y1);
+        return (_jsxs(_Fragment, { children: [_jsx("rect", { x: 0, y: y0, width: f.plotWidth, height: y1 - y0, fill: bandFill, opacity: bandOpacity }), f.bandDragging &&
+                    edge !== undefined &&
+                    [y0, y1].map((y, i) => (_jsx("line", { x1: 0, y1: Math.round(y), x2: f.plotWidth, y2: Math.round(y), stroke: edge, strokeWidth: 1, shapeRendering: "crispEdges" }, i)))] }));
+    }
+    return (_jsxs(_Fragment, { children: [f.band !== null && (_jsx("rect", { x: f.band.x0, y: 0, width: f.band.x1 - f.band.x0, height: f.rowHeight, fill: bandFill, opacity: bandOpacity })), f.band !== null &&
+                f.bandDragging &&
+                edge !== undefined &&
+                [f.band.x0, f.band.x1].map((x, i) => (_jsx("line", { x1: Math.round(x), y1: 0, x2: Math.round(x), y2: f.rowHeight, stroke: edge, strokeWidth: 1, shapeRendering: "crispEdges" }, i))), f.bandLine && f.cursorX !== null && (_jsx("line", { x1: Math.round(f.cursorX), y1: 0, x2: Math.round(f.cursorX), y2: f.rowHeight, stroke: ink, strokeWidth: 1, shapeRendering: "crispEdges" }))] }));
+}
+/** Half-length of a brush crosshair's arms, in pixels. Small on purpose — it
+ *  marks a corner, and a full-plot rule at each end of the diagonal would put
+ *  four lines across a plot the rect is already dividing. */
+const BRUSH_CROSS_PX = 5;
+/** One brush crosshair — the same `+` at rest and at each end of a drag's
+ *  diagonal, so the resting mark reads as the thing the drag then picks up. */
+function brushCross(key, cx, cy, stroke) {
+    const x = Math.round(cx);
+    const y = Math.round(cy);
+    return (_jsxs("g", { stroke: stroke, strokeWidth: 1, shapeRendering: "crispEdges", children: [_jsx("line", { x1: x - BRUSH_CROSS_PX, y1: y, x2: x + BRUSH_CROSS_PX, y2: y }), _jsx("line", { x1: x, y1: y - BRUSH_CROSS_PX, x2: x, y2: y + BRUSH_CROSS_PX })] }, key));
+}
+/**
+ * The **2-D brush renderer** — the rect a sweep paints over a `twoD` layer
+ * (a scatter, a heat map), the counterpart of {@link renderBrushBand} and
+ * drawn from the same `theme.brush` tokens so the two brushes read as one
+ * gesture in two dimensionalities.
+ *
+ * A small `+` sits on each end of the drag diagonal: the corner the press
+ * anchored and the corner under the pointer. That is the whole reason
+ * {@link ResolvedCursorFrame.rect} arrives unsorted — sorting first would put
+ * both crosses on the same diagonal regardless of which way the drag went.
+ */
+export function renderBrushRect(f) {
+    const ink = f.theme.cursor ?? f.theme.axis.label;
+    const r = f.rect;
+    if (r === null) {
+        // At rest: one grey `+` at the pointer, in the hovered row only. It is
+        // the same mark the drag then pins at its anchor — the gesture reads as
+        // picking up what was already under the cursor, rather than swapping one
+        // kind of cursor for another.
+        return f.restingCross &&
+            f.cursorX !== null &&
+            f.cursorY !== null &&
+            f.rowKey === f.hoveredRowKey
+            ? brushCross('rest', f.cursorX, f.cursorY, ink)
+            : null;
+    }
+    const brush = f.theme.brush;
+    const fill = brush?.fill ?? ink;
+    const opacity = brush === undefined ? 0.12 : 1;
+    const edge = brush?.edge ?? ink;
+    const x = Math.min(r.x0, r.x1);
+    const y = Math.min(r.y0, r.y1);
+    const w = Math.abs(r.x1 - r.x0);
+    const h = Math.abs(r.y1 - r.y0);
+    return (_jsxs(_Fragment, { children: [_jsx("rect", { x: x, y: y, width: w, height: h, fill: fill, opacity: opacity }), _jsx("rect", { x: Math.round(x) + 0.5, y: Math.round(y) + 0.5, width: Math.max(0, Math.round(w) - 1), height: Math.max(0, Math.round(h) - 1), fill: "none", stroke: edge, strokeWidth: 1 }), [
+                [r.x0, r.y0],
+                [r.x1, r.y1],
+            ].map(([cx, cy], i) => brushCross(i, cx, cy, edge))] }));
+}
+//# sourceMappingURL=brush.js.map

package/dist/child-index.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+/**
+ * Inject each child's JSX position as an `index` prop, so a child registers its
+ * **declaration order** rather than its mount order — and warn (dev, once per
+ * component instance) when a `<Fragment>` child swallows that injection.
+ *
+ * Two components inject this way — `<ChartRow>` into its axes, `<Layers>` into
+ * its draw layers — and both are defeated the same way: a fragment accepts no
+ * props, so the index stops there and every element inside falls back to its
+ * `index = 0` default. What makes it worth a warning rather than a doc note is
+ * that the failure is **silent and plausible**: the sort is stable, so the
+ * resulting tie resolves to mount order, which on a synchronous tree matches
+ * declaration order. The stack looks correct right up to the case the injection
+ * exists for — an element toggled on between two others, which lands on top
+ * instead of slotting into place.
+ *
+ * The fragment is deliberately **not** cloned. Cloning it makes React emit its
+ * own, vaguer "invalid prop `index` supplied to `React.Fragment`" on top of
+ * ours, which is how this class of bug hid in plain sight: the message named the
+ * prop but not the consequence, so it read as cosmetic.
+ *
+ * @param children the component's `children`
+ * @param owner the component name, for the warning (e.g. `'<Layers>'`)
+ * @param consequence what breaks, in one clause — the part a reader acts on
+ */
+export declare function useIndexedChildren(children: ReactNode, owner: string, consequence: string): readonly ReactNode[] | null | undefined;
+//# sourceMappingURL=child-index.d.ts.map