@pond-ts/charts 0.56.2 → 0.57.0

package/dist/bars.js

@@ -81,6 +81,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
@@ -159,7 +277,7 @@ 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) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
     const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
@@ -177,8 +295,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) {
@@ -228,13 +352,46 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             // 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;
+            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.strokeStyle = style.selectedOutline ?? fill;
+                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            }
+            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];
+            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.lineWidth = style.outlineWidth;
+                ctx.strokeStyle = style.selectedOutline ?? topFill;
                 ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
             }
             continue;
@@ -244,7 +401,8 @@ 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 —
@@ -264,7 +422,7 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             // 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.strokeStyle = style.selectedOutline ?? style.highlight;
             ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
         }
     }
@@ -386,21 +544,28 @@ export function barAt(cs, px, py, xScale, yScale, baseline, minWidthPx) {
 }
 /**
  * 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 +578,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 +644,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 +686,32 @@ 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) {
     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;
     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;
@@ -533,16 +726,63 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
                     : 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;
+            // 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.
+                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) {
+                    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);
+                }
+                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.
+            const emphasised = style.binFills === undefined
+                ? selected
+                    ? (style.highlight ?? fill)
+                    : isHovered
+                        ? (style.hover ?? style.highlight ?? fill)
+                        : fill
+                : fill;
+            ctx.fillStyle = emphasised;
             ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
             if (selected) {
                 ctx.lineWidth = style.outlineWidth;
-                ctx.strokeStyle = fill;
+                ctx.strokeStyle = style.selectedOutline ?? emphasised;
                 ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
             }
         }
@@ -564,12 +804,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;

package/dist/context.d.ts

@@ -349,6 +349,15 @@ export interface ContainerFrame {
 }
 /** The kind of an annotation, and of a creation tool. */
 export type AnnotationKind = 'region' | 'marker' | 'baseline';
+/**
+ * The kind of a **registered** mark — wider than {@link AnnotationKind}.
+ *
+ * A `<Zone>` is a mark you place in JSX but **not** a create *tool*: there is no
+ * draw gesture for it and no {@link CreateSpec} variant, so it registers under
+ * its own kind without widening the toolbar vocabulary (which would let
+ * `creating="zone"` type-check and then silently never fire `onCreate`).
+ */
+export type AnnotationSpecKind = AnnotationKind | 'zone';
 /** What a completed create gesture reports to {@link ContainerFrame.onCreate} —
  *  the new mark's kind + position in axis units (+ the y-axis id for a baseline).
  *  (Which row a mark lands on is the consumer's call for now; multi-row routing is
@@ -376,14 +385,14 @@ export interface AnnotationSpec {
      *  double-click reports via {@link ContainerFrame.onSelectAnnotation}, so the
      *  consumer knows which mark to select. */
     readonly id: string | undefined;
-    readonly kind: AnnotationKind;
+    readonly kind: AnnotationSpecKind;
     /** The row it lives on (its `<ChartRow>`'s key), so a row skips its own marks
      *  when drawing guides. */
     readonly rowKey: symbol;
     /**
      * Its vertical-guide x-position(s) in **axis units** (the shared x): a marker's
-     * `[at]`, a region's `[from, to]`. Empty for a baseline — a horizontal line
-     * casts no vertical guide.
+     * `[at]`, a region's `[from, to]`. Empty for a baseline or a zone — a
+     * horizontal line (or band) casts no vertical guide.
      */
     readonly xs: readonly number[];
     /** Whether it's currently selected (controlled by the consumer). */

package/dist/index.d.ts

@@ -64,8 +64,8 @@ export { scaleTradingTime } from './tradingTimeScale.js';
 export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';
 export type { ScaleBand } from './bandScale.js';
-export { Region, Baseline, Marker } from './annotations.js';
-export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
+export { Region, Baseline, Marker, Zone } from './annotations.js';
+export type { RegionProps, BaselineProps, MarkerProps, ZoneProps, } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';

package/dist/index.js

@@ -51,8 +51,9 @@ export { scaleTradingTime } from './tradingTimeScale.js';
 // The ordinal category (band) scale — the transpose view's "columns on x" axis.
 export { scaleBand } from './bandScale.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the
-// data): a shaded span, a horizontal value line, a vertical x line.
-export { Region, Baseline, Marker } from './annotations.js';
+// data): a shaded x span, a horizontal value line, a vertical x line, and a
+// shaded y span (`<Zone>` — value-axis classifications: AQI categories, HR zones).
+export { Region, Baseline, Marker, Zone } from './annotations.js';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';

package/dist/theme.d.ts

@@ -179,20 +179,36 @@ export interface ChartTheme {
         readonly color: string;
         readonly fillOpacity: number;
         readonly depth: readonly [number, number, number];
+        /**
+         * Optional dash pattern for the register's **lines** — px on/off lengths,
+         * the same shape as {@link LineStyle.dash} (`[6, 4]` = 6 on, 4 off). Omit or
+         * `[]` for solid strokes. Applies to a marker's / baseline's line and to
+         * region + zone boundaries; fills are never dashed.
+         *
+         * Worth reaching for when marks share a plot with data lines: a *dashed*
+         * reference line reads as placed rather than measured, doing the "this isn't
+         * data" work that colour alone can't when the register hue is near a series
+         * hue. Set it per {@link roles | role} to dash one kind of mark only.
+         */
+        readonly dash?: readonly number[];
         /**
          * **Optional per-role overrides** — a small map from a role name to its
-         * `color` (and optionally `fillOpacity`), so distinct marks can be styled
-         * at once without splitting the whole register: a `<Baseline role="atm">`
-         * green, a `<Marker role="ref">` in another hue, each still drawn through
+         * `color` (and optionally `fillOpacity` / `dash`), so distinct marks can be
+         * styled at once without splitting the whole register: a `<Baseline
+         * role="atm">` green, a `<Marker role="ref">` in another hue, a `<Zone
+         * role="good">` per band of a value-axis scale — each still drawn through
          * the shared {@link depth} ramp. A mark's `role` resolves
-         * `roles[role] ?? { color, fillOpacity }` (an unknown/unset role is the
-         * base register). Colour stays a **theme** concern — there is no per-mark
-         * colour prop (the one-styling-channel discipline).
+         * `roles[role] ?? { color, fillOpacity, dash }` (an unknown/unset role is
+         * the base register). Colour stays a **theme** concern — there is no
+         * per-mark colour prop (the one-styling-channel discipline), which is why a
+         * *scale* of bands (AQI categories, HR zones) is a role map and not six
+         * colours at the call site.
          */
         readonly roles?: {
             readonly [role: string]: {
                 readonly color: string;
                 readonly fillOpacity?: number;
+                readonly dash?: readonly number[];
             };
         };
     };
@@ -372,6 +388,45 @@ export interface BarStyle {
      * already did for `highlight`.
      */
     readonly hover?: string;
+    /**
+     * The **threshold-band ladder** — ordered fills for a bar coloured *along its
+     * length* against `<BarChart thresholds>`: `bands[0]` up to the first
+     * threshold, `bands[1]` between the first and second, and so on. A ladder of
+     * `n` thresholds reads `n + 1` entries.
+     *
+     * This lives on `BarStyle` rather than as a `theme.bar.bands` sibling because
+     * `theme.bar` is a semantic **map** (`{ default, [semantic]: BarStyle }`) — a
+     * top-level key would collide with a role of that name. Per-role is also the
+     * more useful shape: `bar.default.bands` and `bar.capacity.bands` can differ,
+     * and the ladder resolves through the same `bar[semantic] ?? bar.default`
+     * lookup as every other bar colour.
+     *
+     * **Overridden by `<BarChart bandColors>`** at the call site. If neither
+     * resolves enough entries for the ladder, the bar falls back to its flat
+     * {@link fill} and (in dev) warns — a silently-unbanded bar is exactly the
+     * failure mode [PND-BANDBAR2] exists to remove.
+     *
+     * Read by the single-series `drawBars` path and by the `G === 1` stacked path
+     * (which is where `categories` and every horizontal bar live). A genuine
+     * **multi-group stack** ignores it and warns: banding a segment that is
+     * already one slice of a total has no defined meaning.
+     */
+    readonly bands?: readonly string[];
+    /**
+     * Stroke for a **selected** bar's outline, where the default is the bar's own
+     * resolved fill. The one selection cue that still works when the fill cannot
+     * change — a `binColors` bar keeps its own colour by design, so without this
+     * the alpha pop was the whole signal and nothing about it was themeable
+     * ([PND-CATEMPH]).
+     */
+    readonly selectedOutline?: string;
+    /**
+     * The alpha a hovered / selected bar pops to. **Default `1`** (the shipped
+     * behaviour). Previously the pop was hard-coded, so a theme could set the
+     * resting {@link opacity} floor but not the *difference* between resting and
+     * live — which is the part that reads as emphasis.
+     */
+    readonly emphasisOpacity?: number;
 }
 /**
  * The neutral default theme. `default` / `primary` match the M1 `LineChart`

package/dist/theme.js

@@ -109,6 +109,11 @@ export const defaultTheme = {
             gap: 1,
             minWidth: 1,
             outlineWidth: 1.5,
+            // The default threshold ladder: the bar's own blue as the in-range band,
+            // then amber, then red. Three entries serves the common two-threshold
+            // ok/warning/alarm ladder out of the box; a longer `thresholds` needs a
+            // longer ladder from the theme or `bandColors`.
+            bands: ['#2563eb', '#e8a13c', '#d64545'],
         },
         secondary: {
             fill: '#e8836b',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.56.2",
+  "version": "0.57.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.56.2",
-    "pond-ts": "^0.56.2",
+    "@pond-ts/react": "^0.57.0",
+    "pond-ts": "^0.57.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {