@pond-ts/charts 0.57.0 → 0.59.0

package/dist/bars.js

@@ -1,6 +1,7 @@
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
 import { decimateBars } from './decimate.js';
+import { NO_SPANS, spanMatchesAny } from './span.js';
 /**
  * The `[min, max]` vertical extent the bars occupy — the finite values of `cs.y`
  * **widened to include `0`**, since a bar spans from its value to the baseline
@@ -72,11 +73,11 @@ export function resolveBarBaseline(yScale) {
  * hit region are deliberately *not* the same geometry: the `gapPx` inset
  * separates columns visually without carving a dead channel out of the target.
  */
-export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
+export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx, maxWidthPx) {
     const v = cs.y[i];
     if (!Number.isFinite(v))
         return null;
-    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx);
+    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx, maxWidthPx);
     const yValue = yScale(v);
     const yBase = yScale(baseline);
     return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
@@ -225,6 +226,78 @@ function barMatches(m, seriesId, stable, begin) {
         ? m.mark === stable
         : m.key === begin;
 }
+/**
+ * Does **any** member of the selection set identify this bar? The set form of
+ * {@link barMatches} ([PND-MULTISEL]).
+ *
+ * Linear over the set on purpose: a selection is a handful of marks a person
+ * clicked, not a data structure — building a Set per draw would cost more than
+ * it saves at these sizes, and the common cases are 0 or 1 members, which this
+ * short-circuits on.
+ *
+ * **The `<MultiSelector>` sweep broke that assumption for large sets** (RFC
+ * §8): a live preview can put every visible bar in `hovered`, and a
+ * demoted-on-edit selection can hold as many mark entries — V visible bars ×
+ * C entries is quadratic-shaped (measured: 2.6k×2.6k ≈ 4.5 ms/frame, 10k×10k
+ * ≈ 64 ms). Past {@link MARK_INDEX_THRESHOLD} the draw builds
+ * {@link buildBarMarkIndex} once — the *same* match, O(1) per bar — and small
+ * sets keep this scan (cheaper than a Set at click sizes).
+ */
+function barMatchesAny(sel, seriesId, stable, begin) {
+    for (let i = 0; i < sel.length; i += 1) {
+        if (barMatches(sel[i], seriesId, stable, begin))
+            return true;
+    }
+    return false;
+}
+/** Past this many entries, a per-draw set index beats the linear scan. Small
+ *  enough that a sweep preview always indexes; big enough that a clicked
+ *  handful never pays a Set build. */
+const MARK_INDEX_THRESHOLD = 16;
+/**
+ * Stroke a selected mark's outline **inside** its ink rect. Canvas strokes
+ * centre on the path, so a plain `strokeRect(x0, yTop, …)` paints
+ * `lineWidth / 2` *outside* the rect — which, with the default
+ * `outlineWidth: 1.5` against the default `gap: 1`, is enough to bridge the
+ * whole inter-bar gap from both sides: a swept run of selected bars fused
+ * into one unreadable block (you could not count them). Insetting the path by
+ * half the line width keeps every stroked pixel within the bar's own ink, so
+ * adjacent selected marks stay separated by exactly the gap the resting bars
+ * show. A mark too thin to contain its outline (either dimension
+ * `<= lineWidth`) skips the stroke — the highlight fill is already the
+ * signal, and an outline wider than the bar would only smear into the
+ * neighbours this exists to keep distinct.
+ */
+export function strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, lineWidth) {
+    const w = x1 - x0;
+    const h = yBottom - yTop;
+    if (w <= lineWidth || h <= lineWidth)
+        return;
+    const inset = lineWidth / 2;
+    ctx.lineWidth = lineWidth;
+    ctx.strokeRect(x0 + inset, yTop + inset, w - lineWidth, h - lineWidth);
+}
+function buildBarMarkIndex(sel, seriesId) {
+    const marks = new Set();
+    const keysMarkless = new Set();
+    const keysAll = new Set();
+    for (let i = 0; i < sel.length; i += 1) {
+        const m = sel[i];
+        if (m.id !== seriesId)
+            continue;
+        keysAll.add(m.key);
+        if (m.mark !== undefined)
+            marks.add(m.mark);
+        else
+            keysMarkless.add(m.key);
+    }
+    return { marks, keysMarkless, keysAll };
+}
+function indexMatches(ix, stable, begin) {
+    return stable !== undefined
+        ? ix.marks.has(stable) || ix.keysMarkless.has(begin)
+        : ix.keysAll.has(begin);
+}
 /**
  * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
  * (inset by `gapPx`) from the resolved `baseline` to the value.
@@ -277,7 +350,16 @@ function barMatches(m, seriesId, stable, begin) {
  * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
  * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered, decimate = true, binFills, banding) {
+export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered, decimate = true, binFills, banding, 
+// 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 bar is selected when a mark entry names it OR a
+// span covers it: an O(1)-per-bar half-open test of `begin` against the
+// span's `x` (and the bar's value against `y` when present), so a span over
+// ten thousand bars costs each one interval test, not a scan. Like the mark
+// highlight, spans are ignored on the decimated envelope path (aggregate
+// columns have no per-bar identity).
+spans = NO_SPANS) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
     const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
@@ -286,6 +368,12 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
     // the `begin[i]` selection/hover match stays correct; full range when `xScale`
     // has no domain (a test stub). A selected/hovered bar off-screen isn't drawn
     // (its highlight would be off-screen anyway).
+    // Dim only when a selection actually exists AND the theme opted in: with an
+    // empty set there is nothing to recede from, and with no `dimmed` value the
+    // library never invents one (RFC A2.3). A span is a selection too — a swept
+    // range recedes the bars outside it exactly as a clicked set does.
+    const hasSpans = spans.length > 0;
+    const dimming = style.dimmed !== undefined && (selection.length > 0 || hasSpans);
     const [vStart, vEnd] = visibleSpanRange(cs.begin, cs.end, cs.length, xScale);
     // Decimate the visible bars to per-column envelope rects once dense (see the
     // header). `null` below the visible-density threshold ⇒ the full per-bar loop.
@@ -328,12 +416,21 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
     // may already have: an interactive layer echoes the hovered bar's mark on
     // every pointer move. See BarSeries.marks — this hoist keeps the draw path
     // clean, it doesn't make the channel free.)
-    const marks = selection?.mark !== undefined || hovered?.mark !== undefined
+    const marks = selection.some((m) => m.mark !== undefined) ||
+        hovered.some((m) => m.mark !== undefined)
         ? cs.marks
         : undefined;
+    // Large sets (a sweep preview in `hovered`, a demoted sweep in `selection`)
+    // switch to the O(1)-per-bar set index; a clicked handful keeps the scan.
+    const selIndex = selection.length > MARK_INDEX_THRESHOLD
+        ? buildBarMarkIndex(selection, seriesId)
+        : null;
+    const hovIndex = hovered.length > MARK_INDEX_THRESHOLD
+        ? buildBarMarkIndex(hovered, seriesId)
+        : null;
     let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
-        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
+        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth, style.maxWidth);
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;
@@ -345,22 +442,28 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         // sets one and `highlight` otherwise, always without the outline — so hover
         // reads as a lighter "this bar is live" and select as the committed pick.
         const stable = marks?.[i];
-        const selected = barMatches(selection, seriesId, stable, cs.begin[i]);
-        const isHovered = barMatches(hovered, seriesId, stable, cs.begin[i]);
+        const selected = (selIndex !== null
+            ? indexMatches(selIndex, stable, cs.begin[i])
+            : barMatchesAny(selection, seriesId, stable, cs.begin[i])) ||
+            (hasSpans && spanMatchesAny(spans, cs.begin[i], cs.y[i]));
+        const isHovered = hovIndex !== null
+            ? indexMatches(hovIndex, stable, cs.begin[i])
+            : barMatchesAny(hovered, seriesId, stable, cs.begin[i]);
         if (fills !== undefined) {
             // Per-bar fills: the bar keeps its own colour under hover / selection —
             // highlight pops the alpha to 1 and outlines the selection in the bar's
             // own fill (the drawStacks binFills convention; see the header).
-            const fill = fills[i] ?? style.fill;
+            const fill = dimming && !selected && !isHovered
+                ? style.dimmed
+                : (fills[i] ?? style.fill);
             ctx.globalAlpha =
                 selected || isHovered ? (style.emphasisOpacity ?? 1) : style.opacity;
             ctx.fillStyle = fill;
             ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
             drawn += 1;
             if (selected) {
-                ctx.lineWidth = style.outlineWidth;
                 ctx.strokeStyle = style.selectedOutline ?? fill;
-                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
             }
             continue;
         }
@@ -373,6 +476,15 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             ctx.globalAlpha =
                 selected || isHovered ? (style.emphasisOpacity ?? 1) : style.opacity;
             const v = cs.y[i];
+            if (dimming && !selected && !isHovered) {
+                // A dimmed banded bar draws flat: the ladder encodes *where the value
+                // sits*, which is exactly what a receded bar should stop competing
+                // over. Painting a dim gradient just lowers its voice.
+                ctx.fillStyle = style.dimmed;
+                ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+                drawn += 1;
+                continue;
+            }
             let topFill = ladder.colors[0];
             for (let bk = 0; bk < ladder.colors.length; bk += 1) {
                 if (!bandSpanInto(baseline, v, ladder.thresholds, bk))
@@ -390,9 +502,8 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
                 // Outline the whole bar (not the last band) in the colour of the band
                 // the value reached — the one colour that means something for a bar
                 // painted in several.
-                ctx.lineWidth = style.outlineWidth;
                 ctx.strokeStyle = style.selectedOutline ?? topFill;
-                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
             }
             continue;
         }
@@ -407,11 +518,17 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         // selected. Selection outranks hover on a bar that is both (as the outline
         // already did). With no `hover` colour this is the shipped two-step —
         // `highlight` for either state (see BarStyle.hover).
+        // Precedence, shared with `drawStacks`: selected > hovered > dimmed > rest.
+        // Hover outranks dim deliberately — dim says "this is not in your
+        // selection", hover says "your pointer is here now", and suppressing live
+        // pointer feedback to keep a bar receded makes the chart feel broken.
         ctx.fillStyle = selected
             ? style.highlight
             : isHovered
                 ? (style.hover ?? style.highlight)
-                : style.fill;
+                : dimming
+                    ? style.dimmed
+                    : style.fill;
         ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
         drawn += 1;
         if (selected) {
@@ -421,9 +538,8 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             // fill, so only the half-stroke falling outside the rect reads. A theme
             // that needs the two states clearly apart sets `BarStyle.hover` (#577);
             // the outline is the shape cue, not the whole signal.
-            ctx.lineWidth = style.outlineWidth;
             ctx.strokeStyle = style.selectedOutline ?? style.highlight;
-            ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
         }
     }
     ctx.restore();
@@ -542,6 +658,29 @@ export function barAt(cs, px, py, xScale, yScale, baseline, minWidthPx) {
     }
     return null;
 }
+function buildStackMarkIndex(sel, seriesId) {
+    const marks = new Set();
+    const labelsByKey = new Map();
+    for (let i = 0; i < sel.length; i += 1) {
+        const m = sel[i];
+        if (m.id !== seriesId)
+            continue;
+        if (m.mark !== undefined)
+            marks.add(m.mark);
+        let labels = labelsByKey.get(m.key);
+        if (labels === undefined) {
+            labels = new Set();
+            labelsByKey.set(m.key, labels);
+        }
+        labels.add(m.label);
+    }
+    return { marks, labelsByKey };
+}
+function stackIndexMatches(ix, stableMark, begin, group) {
+    return stableMark !== undefined
+        ? ix.marks.has(stableMark)
+        : (ix.labelsByKey.get(begin)?.has(group) ?? false);
+}
 /**
  * The `[min, max]` extent of the **value (stacked) axis**. For a true multi-group
  * stack it is `[minNegTotal, maxPosTotal]` — each bin's positive segments summed
@@ -640,7 +779,7 @@ export function stackBase(orientation, xScale, yScale) {
  * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
  * and the hit rect are identical.
  */
-export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx) {
+export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx, maxSpanPx) {
     const G = ss.groups.length;
     const v = ss.values[b * G + g];
     // Skip non-finite (a gap) or zero (a zero-extent rect that can't draw or be
@@ -662,12 +801,12 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
     if (!Number.isFinite(v) || v === 0)
         return null;
     if (orientation === 'vertical') {
-        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
+        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx, maxSpanPx);
         const yA = yScale(cumBefore);
         const yB = yScale(cumBefore + v);
         return [x0, x1, Math.min(yA, yB), Math.max(yA, yB)];
     }
-    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx);
+    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx, maxSpanPx);
     const xA = xScale(cumBefore);
     const xB = xScale(cumBefore + v);
     return [Math.min(xA, xB), Math.max(xA, xB), y0, y1];
@@ -686,7 +825,15 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
  *
  * O(N·G) over bins × groups, one fill (+ optional stroke) per drawn segment.
  */
-export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, minSpanPx, seriesId, selection, hover, banding) {
+export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, minSpanPx, seriesId, selection, hover, banding, 
+// Span descriptors covering this layer (interaction RFC A5.2), already
+// narrowed to its `id` by the component (`spansForLayer`). A segment is
+// selected when a mark entry names it OR a span covers it — the O(1) test of
+// the bin `begin` against the half-open `x` interval, the segment's own
+// value against `y` when present, and its group against `rows` when present
+// (the group is this layer's label channel, so `rows` stays testable per
+// segment where `drawBars`' constant label lets the component resolve it).
+spans = NO_SPANS) {
     const G = ss.groups.length;
     const base = stackBase(orientation, xScale, yScale);
     // Threshold banding applies to a **plain** bar only. `G === 1` is exactly the
@@ -695,6 +842,19 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
     // each segment is already a slice of a total — so the ladder is dropped here
     // and warned about at the prop boundary rather than half-applied.
     const ladder = G === 1 && style.binFills === undefined ? banding : undefined;
+    // See `drawBars` — dim only with a real selection (marks or spans) and an
+    // opted-in theme.
+    const hasSpans = spans.length > 0;
+    const dimming = (style.dimmed !== undefined || style.dimmedFills !== undefined) &&
+        (selection.length > 0 || hasSpans);
+    // The large-set switch (see barMatchesAny): a sweep preview / demoted sweep
+    // indexes once, a clicked handful keeps the linear scan.
+    const selIndex = selection.length > MARK_INDEX_THRESHOLD
+        ? buildStackMarkIndex(selection, seriesId)
+        : null;
+    const hovIndex = hover.length > MARK_INDEX_THRESHOLD
+        ? buildStackMarkIndex(hover, seriesId)
+        : null;
     ctx.save();
     ctx.globalAlpha = style.opacity;
     for (let b = 0; b < ss.length; b += 1) {
@@ -705,7 +865,7 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, style.maxWidth);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;
@@ -724,8 +884,42 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
                 (stableMark !== undefined
                     ? m.mark === stableMark
                     : m.key === ss.begin[b] && m.label === ss.groups[g]);
-            const selected = matches(selection);
-            const isHovered = matches(hover);
+            // Indexed rather than `.some(cb)` — this is the inner loop of the draw,
+            // and a closure per segment per frame is avoidable garbage.
+            let selected = false;
+            if (selIndex !== null) {
+                selected = stackIndexMatches(selIndex, stableMark, ss.begin[b], ss.groups[g]);
+            }
+            else {
+                for (let si = 0; si < selection.length; si += 1) {
+                    if (matches(selection[si])) {
+                        selected = true;
+                        break;
+                    }
+                }
+            }
+            // A span covers this segment when the bin's `begin` is inside its
+            // half-open `x` (and its `y` / `rows` channels pass — see the param doc).
+            // The label channel is what the hit reports: the stable per-bin `mark`
+            // (a categorical bar's category name) when the series carries marks,
+            // else the group — `hitTest` builds `label: stableMark ?? name`, and the
+            // span test must read the same field or `selectionContains` and the
+            // canvas disagree on every categorical bar.
+            if (!selected && hasSpans) {
+                selected = spanMatchesAny(spans, ss.begin[b], v, stableMark ?? ss.groups[g]);
+            }
+            let isHovered = false;
+            if (hovIndex !== null) {
+                isHovered = stackIndexMatches(hovIndex, stableMark, ss.begin[b], ss.groups[g]);
+            }
+            else {
+                for (let hi = 0; hi < hover.length; hi += 1) {
+                    if (matches(hover[hi])) {
+                        isHovered = true;
+                        break;
+                    }
+                }
+            }
             // A hovered / selected segment pops its alpha; a resting one draws at the
             // shared one. `emphasisOpacity` makes the *difference* themeable, where
             // before only the resting floor was.
@@ -738,6 +932,11 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
                 // the bar's length at the ladder boundaries, transposing on
                 // orientation — vertical bars band along y, horizontal along x, while
                 // the bin span (the other axis) is shared by every band.
+                if (dimming && !selected && !isHovered) {
+                    ctx.fillStyle = style.dimmedFills?.[g] ?? style.dimmed ?? fill;
+                    ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+                    continue;
+                }
                 let topFill = ladder.colors[0];
                 for (let bk = 0; bk < ladder.colors.length; bk += 1) {
                     if (!bandSpanInto(base, v, ladder.thresholds, bk))
@@ -758,11 +957,10 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
                     topFill = ladder.colors[bk];
                 }
                 if (selected) {
-                    ctx.lineWidth = style.outlineWidth;
                     // A themed outline if the theme sets one, else the band the value
                     // reached — the one colour that means anything on a banded bar.
                     ctx.strokeStyle = style.selectedOutline ?? topFill;
-                    ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                    strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
                 }
                 continue;
             }
@@ -771,19 +969,32 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
             // selected segment takes `highlight` and a hovered one `hover`, exactly
             // as the single-series path does. With `binFills` the bar keeps its own
             // colour (the design exclusion) and the alpha pop above is the signal.
-            const emphasised = style.binFills === undefined
-                ? selected
-                    ? (style.highlight ?? fill)
-                    : isHovered
-                        ? (style.hover ?? style.highlight ?? fill)
-                        : fill
-                : fill;
+            // Same precedence as `drawBars`: selected > hovered > dimmed > rest.
+            const emphasised = dimming && !selected && !isHovered
+                ? (style.dimmedFills?.[g] ?? style.dimmed ?? fill)
+                : style.binFills !== undefined
+                    ? fill
+                    : selected
+                        ? // A group ramp is meaning-carrying colour, so a selected
+                            // segment keeps it: the outline and the receded neighbours are
+                            // the cue. Same exclusion `binFills` gets, one line up.
+                            style.groupColored
+                                ? fill
+                                : (style.highlight ?? fill)
+                        : isHovered
+                            ? // Per-group where the ramp supplies one, so hovering
+                                // brightens the segment instead of recolouring it out of
+                                // its group.
+                                (style.hoverFills?.[g] ??
+                                    style.hover ??
+                                    style.highlight ??
+                                    fill)
+                            : fill;
             ctx.fillStyle = emphasised;
             ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
             if (selected) {
-                ctx.lineWidth = style.outlineWidth;
                 ctx.strokeStyle = style.selectedOutline ?? emphasised;
-                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
             }
         }
     }
@@ -800,7 +1011,11 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
  * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
  * small; click / hover are cheap events).
  */
-export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx) {
+export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx, 
+/** Must match the draw's cap ([PND-BARWIDTH]) — this function's whole
+ *  contract is that its rect is the drawn rect, so a cap applied to one and
+ *  not the other silently drifts the hit target off the ink. */
+maxSpanPx) {
     const G = ss.groups.length;
     const base = stackBase(orientation, xScale, yScale);
     for (let b = 0; b < ss.length; b += 1) {
@@ -810,7 +1025,7 @@ export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanP
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, maxSpanPx);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;

package/dist/box.d.ts

@@ -1,7 +1,7 @@
 import type { BoxSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BoxStyle } from './theme.js';
-import type { LayerDrawStats } from './context.js';
+import type { LayerDrawStats, SpanSelection } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
@@ -79,7 +79,7 @@ export type BoxShape = 'whisker' | 'solid' | 'none';
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number, selectedKey?: number | null, hoveredKey?: number | null, decimate?: DecimateOption): LayerDrawStats;
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number, selectedKeys?: readonly number[], hoveredKeys?: readonly number[], decimate?: DecimateOption, spans?: readonly SpanSelection[]): LayerDrawStats;
 /**
  * This key is drawable — the quantiles it actually carries are all finite at `i`.
  * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the