@pond-ts/charts 0.56.2 → 0.58.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
@@ -81,6 +82,124 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
     const yBase = yScale(baseline);
     return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
 }
+/**
+ * The value-space span `[lo, hi]` of **threshold band `k`** along a bar running
+ * from `base` to `v`, or `null` when the bar doesn't reach that band.
+ *
+ * A threshold ladder colours one bar **along its length** — neutral up to the
+ * first threshold, then warning, then alarm — so a long bar shows how far
+ * through the ladder it travelled rather than only which band it ended in. With
+ * `thresholds = [t0, t1]` there are three bands: `[0, t0)`, `[t0, t1)`,
+ * `[t1, ∞)`. Band `k` spans magnitudes `[thresholds[k-1] ?? 0, thresholds[k] ??
+ * ∞)`, each end clipped to the bar's own magnitude — so a bar that stops inside
+ * band 1 yields a truncated band 1 and `null` for band 2.
+ *
+ * **Breakpoints are absolute data values, not offsets from the baseline** — a
+ * `thresholds={[1, 2]}` ladder means "warning above 1, alarm above 2" in the
+ * axis's own units, which is what a threshold means everywhere else. They are
+ * matched on the **magnitude** and applied to whichever side of zero the bar
+ * is on, so a bar hanging below the baseline walks the same ladder downward
+ * and a ±3.5 diverging scale bands symmetrically without the caller supplying
+ * negative breakpoints. (An asymmetric ladder would need signed breakpoints;
+ * deferred until a consumer pulls — see [PND-BANDBAR2].)
+ *
+ * The painted span is then **clipped to what the bar actually draws**, which
+ * is what makes a domain that excludes zero behave: with `<YAxis min={10}>` a
+ * bar rests on 10, so a `[1, 2]` ladder leaves it entirely in the top band
+ * rather than banding at 11 and 12. Measuring the ladder from the *resolved
+ * baseline* instead would silently shift every breakpoint by the axis floor —
+ * exactly the class of quiet wrongness this feature exists to remove.
+ *
+ * Note this is **draw-only geometry**. Hit-testing still treats the bar as one
+ * target ({@link barSlotRect} / {@link barAt}), which is the whole reason this
+ * is a mark rather than the N-layer overpaint recipe it replaces: one bar keeps
+ * one hit region, one stable `mark`, and one legend row.
+ *
+ * `thresholds` is assumed ascending and finite — {@link normalizeThresholds}
+ * enforces that once at the prop boundary rather than per bar per frame.
+ */
+export function bandSpan(base, v, thresholds, k) {
+    return bandSpanInto(base, v, thresholds, k) ? [bandLo, bandHi] : null;
+}
+/**
+ * The band-`k` span, written to {@link bandLo} / {@link bandHi} instead of
+ * returned — `true` when the bar reaches this band, `false` when it doesn't.
+ *
+ * This is {@link bandSpan}'s implementation, split out because the tuple
+ * mattered: a K-band ladder allocates K tuples **per bar per frame**, and the
+ * bench showed that turning a banded draw from ~44% *cheaper* than the N-layer
+ * workaround it replaces into ~44% *dearer* than it. Same arithmetic, no
+ * garbage. `bandSpan` stays as the allocating wrapper so the geometry is
+ * testable as a value.
+ *
+ * Module-scope scratch is safe here: the draw path is single-threaded and reads
+ * both fields immediately after a `true`, before any other call can run.
+ */
+let bandLo = 0;
+let bandHi = 0;
+function bandSpanInto(base, v, thresholds, k) {
+    const lo = k === 0 ? 0 : thresholds[k - 1];
+    const hi = k < thresholds.length ? thresholds[k] : Infinity;
+    // The bar's drawn extent, ascending. `resolveBarBaseline` clamps 0 into the
+    // domain, so this span never straddles zero: either it starts at 0, or the
+    // whole domain sits to one side of it.
+    const sLo = base < v ? base : v;
+    const sHi = base < v ? v : base;
+    // Band `k` covers the *absolute* values `[lo, hi)`, which is two intervals —
+    // `[lo, hi]` and `[-hi, -lo]`. Pick the one on the bar's own side of zero.
+    const positive = sHi > 0;
+    let bLo = positive ? lo : -hi;
+    // `-lo` when `lo === 0` is **negative zero**, which would escape through the
+    // exported `bandSpan` and fail any consumer's `Object.is` / `toEqual` against
+    // a plain `0`. Normalize at the source rather than letting each caller cope.
+    let bHi = positive ? hi : lo === 0 ? 0 : -lo;
+    // Clip to what the bar actually draws. An empty or inverted result means this
+    // band lies outside the bar's span — either beyond its reach, or (on a domain
+    // that excludes zero) entirely below its floor.
+    if (bLo < sLo)
+        bLo = sLo;
+    if (bHi > sHi)
+        bHi = sHi;
+    if (bHi <= bLo)
+        return false;
+    bandLo = bLo;
+    bandHi = bHi;
+    return true;
+}
+/**
+ * Validate + freeze a caller's threshold ladder once, at the prop boundary.
+ * Returns the ascending, strictly-positive, finite breakpoints — or `null` when
+ * there is no usable ladder left, so the caller keeps the flat path.
+ *
+ * Sorting rather than rejecting an out-of-order ladder is deliberate — the
+ * bands are defined by their boundaries, so `[2, 1]` and `[1, 2]` describe the
+ * same three bands and there is no second reading to guess at.
+ *
+ * Three kinds of entry are **dropped**:
+ *
+ * - **non-finite** — would swallow every band above it;
+ * - **negative** — the ladder is walked on the *magnitude* and mirrored onto
+ *   whichever side of zero the bar is on, so a negative breakpoint has no
+ *   meaning. Left in, `[-2, -1]` silently clipped every lower band away and
+ *   painted the whole bar in the final colour — a one-colour bar that looks
+ *   deliberate (Codex adversarial review). Signed breakpoints are the
+ *   asymmetric-ladder feature deferred in [PND-BANDBAR2], not this;
+ * - **zero** — band 0 already starts at zero, so a `0` breakpoint describes an
+ *   empty band and shifts every colour by one.
+ *
+ * Dropping rather than throwing matches how the rest of this prop behaves
+ * (a short colour ladder degrades, it doesn't fail), and `BarChart` dev-warns
+ * whenever normalization removed anything — a silently-ignored breakpoint is
+ * the failure mode this whole feature exists to avoid.
+ */
+export function normalizeThresholds(thresholds) {
+    if (thresholds === undefined || thresholds.length === 0)
+        return null;
+    const clean = thresholds.filter((t) => Number.isFinite(t) && t > 0);
+    if (clean.length === 0)
+        return null;
+    return clean.sort((a, b) => a - b);
+}
 /**
  * Does `m` identify the bar with stable identity `stable` and key `begin`?
  * The mark decides **only when both sides have one** — `m.mark` (the selection
@@ -107,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.
@@ -159,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) {
+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)
@@ -168,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.
@@ -177,8 +383,14 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
     // *empty* colour array is "no colours" (every bar would flat-fill anyway), so
     // it stays on the legacy path end-to-end (L2 review, PR #542).
     const fills = binFills !== undefined && binFills.length > 0 ? binFills : undefined;
+    // A threshold ladder is per-*bar* colour too, so it takes the same exits as
+    // `binFills`: no envelope pass (one rect can't carry a gradient), and it
+    // yields to an explicit `binFills` when a caller sets both (warned about at
+    // the prop boundary — the two are different answers to "what colour is this
+    // bar", and per-bar is the more specific one).
+    const ladder = fills === undefined ? banding : undefined;
     const k = typeof decimate === 'object' ? decimate.threshold : undefined;
-    const envelope = decimate !== false && fills === undefined
+    const envelope = decimate !== false && fills === undefined && ladder === undefined
         ? decimateBars(cs, xScale, ctx, baseline, k, vEnd - vStart)
         : null;
     if (envelope !== null) {
@@ -204,9 +416,18 @@ 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);
@@ -221,21 +442,68 @@ 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;
-            ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
+            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 = fill;
-                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                ctx.strokeStyle = style.selectedOutline ?? fill;
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
+            }
+            continue;
+        }
+        if (ladder !== undefined) {
+            // Threshold banding: one rect per band the bar reaches, sharing the bar's
+            // x-span and slicing its length at the ladder boundaries. Like `binFills`
+            // the bar keeps its own colours when live (swapping to one `highlight`
+            // would erase the very thing the bands encode) and pops the alpha
+            // instead. The whole bar stays one hit target — see `bandSpan`.
+            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))
+                    continue;
+                const ySpanA = yScale(bandLo);
+                const ySpanB = yScale(bandHi);
+                const bandTop = ySpanA < ySpanB ? ySpanA : ySpanB;
+                const bandBottom = ySpanA < ySpanB ? ySpanB : ySpanA;
+                ctx.fillStyle = ladder.colors[bk];
+                ctx.fillRect(x0, bandTop, x1 - x0, bandBottom - bandTop);
+                topFill = ladder.colors[bk]; // the band the value actually landed in
+            }
+            drawn += 1;
+            if (selected) {
+                // 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.strokeStyle = style.selectedOutline ?? topFill;
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
             }
             continue;
         }
@@ -244,16 +512,23 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         // at the resting `style.opacity`, so on an alpha'd theme a hovered bar
         // (which has no outline) barely changed at all, and a selected one read
         // only by its outline (#576).
-        ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
+        ctx.globalAlpha =
+            selected || isHovered ? (style.emphasisOpacity ?? 1) : style.opacity;
         // Three-step emphasis when the theme opts in with `hover`: rest → hover →
         // 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) {
@@ -263,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.highlight;
-            ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            ctx.strokeStyle = style.selectedOutline ?? style.highlight;
+            strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
         }
     }
     ctx.restore();
@@ -384,23 +658,53 @@ 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 `[0, maxTotal]`, where `maxTotal` is the tallest bin's summed finite
- * non-negative segments. For a **single-group** series (`G === 1` — the plain /
+ * stack it is `[minNegTotal, maxPosTotal]` — each bin's positive segments summed
+ * upward and its negative segments summed downward, tracked separately
+ * ([PND-SIGNSTACK]). For a **single-group** series (`G === 1` — the plain /
  * categorical bar case) it spans the values' own `[min, max]`, so a **negative**
  * bar's floor is in the domain (segments below the baseline stay visible). `0` is
  * always pulled in so the bars rest on a visible baseline (the bar analog of
  * {@link barExtent}). An empty / all-gap series returns `[0, 1]` so the axis still
  * has a usable domain. Feeds the y auto-fit for a vertical histogram, the x
  * auto-fit for a horizontal one.
+ *
+ * The negative half is new: this used to sum only positives, matching a draw
+ * path that dropped negative segments outright. Both halves changed together —
+ * an extent that stopped at `0` below would clip the very segments the draw
+ * path now emits.
  */
 export function stackValueExtent(ss) {
     const G = ss.groups.length;
     let max = 0;
     let min = 0;
     for (let b = 0; b < ss.length; b += 1) {
-        let cum = 0;
+        let cumPos = 0;
+        let cumNeg = 0;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
             if (!Number.isFinite(v))
@@ -413,11 +717,16 @@ export function stackValueExtent(ss) {
                     min = v;
             }
             else if (v > 0) {
-                cum += v; // True stack: sum the positive segments.
+                cumPos += v; // True stack: positives stack up from the baseline…
+            }
+            else if (v < 0) {
+                cumNeg += v; // …negatives stack down from it.
             }
         }
-        if (cum > max)
-            max = cum;
+        if (cumPos > max)
+            max = cumPos;
+        if (cumNeg < min)
+            min = cumNeg;
     }
     // Empty / all-gap / all-zero → a usable unit domain; otherwise the real extent
     // (with 0 pulled in via the `min`/`max` seeds above).
@@ -474,13 +783,22 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
     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
-    // hit-tested). A **negative** value is a gap only in a true multi-group stack
-    // (`G > 1`) — stacking a negative segment is undefined. A **single-group**
-    // series (`G === 1`) is a plain bar: it honours its sign and draws from the
-    // baseline *down* to a negative value (the categorical row-read's P&L / delta
-    // case), so negatives are kept and the `Math.min/Math.max` below normalizes the
-    // below-baseline rect.
-    if (!Number.isFinite(v) || v === 0 || (v < 0 && G > 1))
+    // hit-tested). **Negative segments are kept, whatever `G` is** — the caller
+    // passes the downward running total for them (see {@link drawStacks}), and
+    // the `Math.min/Math.max` below normalizes the below-baseline rect.
+    //
+    // A multi-group stack used to drop them here (`v < 0 && G > 1`) on the
+    // grounds that "stacking a negative segment is undefined". That is fair for a
+    // conventional stack and wrong for the **signed stacked histogram** — several
+    // series per bin whose values may be either sign, positives stacking up from
+    // a zero line and negatives down from it (net flow by category,
+    // inflow/outflow, buy/sell pressure by venue). That is a well-defined stack:
+    // two running totals per bin instead of one. And the old behaviour failed
+    // *silently* — the dropped segments didn't clamp, warn or throw, so every
+    // remaining segment stacked up as though they had never been in the data and
+    // a mixed-sign series rendered as a confident, wrong, all-positive chart
+    // ([PND-SIGNSTACK]).
+    if (!Number.isFinite(v) || v === 0)
         return null;
     if (orientation === 'vertical') {
         const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
@@ -507,18 +825,53 @@ 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) {
+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
+    // categorical / horizontal single-value bar (`categoryStack` builds a
+    // one-group series); a genuine multi-group stack has no defined banding —
+    // 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) {
-        let cum = base;
+        // Two running totals per bin ([PND-SIGNSTACK]): positives stack upward from
+        // the baseline, negatives downward from it. A conventional all-positive
+        // stack never touches `cumNeg`, so its geometry is bit-identical to before.
+        let cumPos = base;
+        let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, cum, gapPx, minSpanPx);
             const v = ss.values[b * G + g];
-            if (Number.isFinite(v) && v > 0)
-                cum += v;
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            if (Number.isFinite(v)) {
+                if (v > 0)
+                    cumPos += v;
+                else if (v < 0)
+                    cumNeg += v;
+            }
             if (rect === null)
                 continue;
             const [x0, x1, yTop, yBottom] = rect;
@@ -531,19 +884,117 @@ 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);
-            // A hovered / selected segment pops to full opacity in its own colour; a
-            // resting one draws at the shared alpha.
-            ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
+            // 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.
+            ctx.globalAlpha =
+                selected || isHovered ? (style.emphasisOpacity ?? 1) : style.opacity;
             // A per-bin colour (the single-series band case) overrides the group fill.
             const fill = style.binFills?.[b] ?? style.fills[g];
-            ctx.fillStyle = fill;
+            if (ladder !== undefined) {
+                // Threshold banding on the plain / categorical / horizontal bar: slice
+                // 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))
+                        continue;
+                    ctx.fillStyle = ladder.colors[bk];
+                    if (orientation === 'vertical') {
+                        const a = yScale(bandLo);
+                        const c = yScale(bandHi);
+                        const top = a < c ? a : c;
+                        ctx.fillRect(x0, top, x1 - x0, (a < c ? c : a) - top);
+                    }
+                    else {
+                        const a = xScale(bandLo);
+                        const c = xScale(bandHi);
+                        const left = a < c ? a : c;
+                        ctx.fillRect(left, yTop, (a < c ? c : a) - left, yBottom - yTop);
+                    }
+                    topFill = ladder.colors[bk];
+                }
+                if (selected) {
+                    // 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;
+                    strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
+                }
+                continue;
+            }
+            // [PND-CATEMPH] The themed three-step emphasis, applied where it can be:
+            // with no `binFills` there is no meaning-carrying colour to destroy, so a
+            // 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.
+            // 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 = fill;
-                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+                ctx.strokeStyle = style.selectedOutline ?? emphasised;
+                strokeSelectedOutline(ctx, x0, x1, yTop, yBottom, style.outlineWidth);
             }
         }
     }
@@ -564,12 +1015,19 @@ export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanP
     const G = ss.groups.length;
     const base = stackBase(orientation, xScale, yScale);
     for (let b = 0; b < ss.length; b += 1) {
-        let cum = base;
+        // The same two accumulators `drawStacks` keeps — they must agree exactly or
+        // the hit rect drifts from the drawn one.
+        let cumPos = base;
+        let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, cum, gapPx, minSpanPx);
             const v = ss.values[b * G + g];
-            if (Number.isFinite(v) && v > 0)
-                cum += v;
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            if (Number.isFinite(v)) {
+                if (v > 0)
+                    cumPos += v;
+                else if (v < 0)
+                    cumNeg += v;
+            }
             if (rect === null)
                 continue;
             const [x0, x1, yTop, yBottom] = rect;