@pond-ts/charts 0.55.0 → 0.57.0

package/dist/annotations.js

@@ -6,7 +6,8 @@ import { useSlotKey } from './use-slot-key.js';
 /**
  * User-authored **annotations** — marks you place *on* a chart, in a register
  * deliberately distinct from the data: `<Region>` (a shaded x-span), `<Baseline>`
- * (a horizontal value line), and `<Marker>` (a vertical x line). All three render
+ * (a horizontal value line), `<Marker>` (a vertical x line), and `<Zone>` (a
+ * shaded y-span — `<Region>`'s counterpart on the value axis). All four render
  * in the theme's turquoise {@link ChartTheme.annotation} register so a placed mark
  * never reads as data ("the data stays foam; the marks you place are turquoise").
  *
@@ -101,7 +102,7 @@ const overlayStyle = {
  * Read the container + row frames an annotation needs (throw if misplaced), and
  * resolve the mark's annotation style for its optional `role`. A `role` recolors
  * *this* mark from the theme's `annotation.roles[role]` map (`color`, and
- * optionally `fillOpacity`) while keeping the shared depth ramp — so a smile can
+ * optionally `fillOpacity` / `dash`) while keeping the shared depth ramp — so a smile can
  * place a green ATM baseline, a neutral vertical, and a distinct marker at once
  * without splitting the whole register. An unknown / unset role falls back to
  * the base `annotation` register (`roles[role] ?? annotation`).
@@ -117,17 +118,23 @@ function useAnnotationFrame(name, role) {
     }
     const base = container.theme.annotation ?? DEFAULT_ANNOTATION;
     const roleStyle = role !== undefined ? base.roles?.[role] : undefined;
-    // The role overrides only colour (+ optional fill); depth stays the shared
-    // ramp, so selection / hover / edit levels read identically per role.
+    // The role overrides only colour (+ optional fill / dash); depth stays the
+    // shared ramp, so selection / hover / edit levels read identically per role.
     const ann = roleStyle
         ? {
             ...base,
             color: roleStyle.color,
             fillOpacity: roleStyle.fillOpacity ?? base.fillOpacity,
+            dash: roleStyle.dash ?? base.dash,
         }
         : base;
     return { container, row, ann };
 }
+/** The register's dash as an SVG `stroke-dasharray`, or `undefined` for solid
+ *  (an empty pattern means solid, matching `LineStyle.dash`). */
+function dashArray(dash) {
+    return dash === undefined || dash.length === 0 ? undefined : dash.join(' ');
+}
 /** Register this annotation with the container (so it can draw the mark's guide on
  *  other rows, order regions, and serve snap targets), keyed by the caller's stable
  *  per-instance slot key; unregister on unmount. `xs` should be memoised by the
@@ -504,7 +511,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     // The staff (vertical line) hangs from the top of its flag — so a flag stacked
     // into a lower lane doesn't leave line poking above it. No label ⇒ full height.
     const staffTop = text ? FLAG_TOP + lane * LANE_H : 0;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
                             +container.xScale.invert(px)) }))] }), chipLabel && x >= 0 && x <= container.plotWidth && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
                     ...flagChipX(x, container.plotWidth),
@@ -552,7 +559,7 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
     const text = label === false ? '' : (label ?? (fmt ? fmt(value) : String(value)));
     // Handle pill near the right end (clears the left-anchored label).
     const handleX = w - 14;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${y}px`,
                     [labelSide === 'right' ? 'right' : 'left']: '2px',
                     // `center` rides on the line; `above` sits its bottom edge on the line.
@@ -570,6 +577,89 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
                         }, children: fmt ? fmt(value) : String(value) }));
                 })()] }));
 }
+/**
+ * A shaded band between two **y values**, spanning the full plot width — the
+ * y-axis counterpart of `<Region>`. The mark for a **classification of the value
+ * axis**: US EPA AQI categories, heart-rate / power zones, a control chart's
+ * spec limits, an SLO band.
+ *
+ * Being a `<Layers>` child it lives in its row and is scaled by that row's y
+ * axis — pass `axis` to pick one on a dual-axis row. Like every annotation it
+ * paints in the SVG overlay **above** the data canvas, so keep the fill light
+ * (the register's `fillOpacity`, ~0.1–0.2) and the trace reads cleanly through
+ * it. A zone set is a wash of colour behind the story, not a layer competing
+ * with it.
+ *
+ * Zones are **background context by default** (`selectable={false}`,
+ * `edges={false}`, no label) because that is what a tiled zone set is; see
+ * {@link ZoneProps.selectable} for why the family's usual defaults invert here.
+ * Colour comes from the theme's {@link ZoneProps.role | role} map, so a palette
+ * is a theme, not six call-site colours.
+ *
+ * Unlike the other marks a zone has **no `onChange`** — dragging zone edges
+ * (a zone editor) is a real feature but has no consumer yet; the band is
+ * declarative until one arrives.
+ */
+export function Zone({ from, to, axis, label, labelSide = 'left', id, selected = false, selectable = false, hovered, role, edges = false, }) {
+    const { container, row, ann } = useAnnotationFrame('Zone', role);
+    const selfKey = useSlotKey();
+    const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
+    // A horizontal band casts no vertical guide (like a baseline) — register with
+    // no xs, so it's tracked for ordering but offers no snap target.
+    const xs = useMemo(() => [], []);
+    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'zone', xs, selected, selectable, false, // zones aren't editable — no single-annotation edit state
+    label ?? '', false);
+    // No select while a create tool is armed — the chart is in draw mode then.
+    const select = id !== undefined && container.creating === null
+        ? () => container.onSelectAnnotation?.(id)
+        : undefined;
+    const axisId = axis ?? row.defaultAxisId;
+    const yScale = row.yScales.get(axisId);
+    // The axis may not have resolved yet (a layer mounts before its <YAxis>); skip
+    // until its scale exists rather than guessing a domain.
+    if (yScale === undefined)
+        return null;
+    const h = row.height;
+    const w = container.plotWidth;
+    // A NaN bound has no position to draw at — cull rather than let it fall
+    // through the finite check below and silently become the domain's low end.
+    if (Number.isNaN(from) || Number.isNaN(to))
+        return null;
+    // Open-ended bounds resolve against the axis **domain** before scaling, not
+    // after: d3's interpolator is `a·(1−t) + b·t`, so an infinite `t` yields
+    // `0 · Infinity` = NaN rather than an off-plot pixel. Substituting the domain
+    // end is also exactly the intent — an open band reaches the plot edge.
+    const [d0, d1] = yScale.domain();
+    const dLo = Math.min(d0 ?? 0, d1 ?? 0);
+    const dHi = Math.max(d0 ?? 0, d1 ?? 0);
+    const bound = (v) => (Number.isFinite(v) ? v : v > 0 ? dHi : dLo);
+    // Order + clamp to the plot: a band may run past the axis domain (the AQI
+    // 151–200 band on an axis topping out at 120). Clamping keeps the rect inside
+    // its row; a band entirely outside culls.
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    const loY = yScale(bound(lo));
+    const hiY = yScale(bound(hi));
+    const top = Math.max(Math.min(loY, hiY), 0);
+    const bottom = Math.min(Math.max(loY, hiY), h);
+    if (bottom <= top)
+        return null;
+    const bandH = bottom - top;
+    // Edit is never on (no onChange) — the levels reduce to selected / hover /
+    // resting, and to a flat level 3 when the band is inert background.
+    const edgeOpacity = rampAt(ann.depth, lineLevel(selectable, false, hovering, selected));
+    const fillOpacity = ann.fillOpacity *
+        rampAt(FILL_MULT, bodyLevel(selectable, false, hovering, selected));
+    /** A boundary line — drawn only where the band has a *real*, in-plot edge. An
+     *  open-ended bound has no boundary at all, and a bound the clamp cut off would
+     *  otherwise draw its line on the plot border, reading as chrome. */
+    const boundary = (v, aty) => edges && Number.isFinite(v) && aty >= 0 && aty <= h ? (_jsx("line", { x1: 0, y1: aty, x2: w, y2: aty, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" })) : null;
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: h, style: overlayStyle, children: [_jsx("rect", { x: 0, y: top, width: w, height: bandH, fill: ann.color, opacity: fillOpacity }), boundary(lo, loY), boundary(hi, hiY), selectable && (_jsx(DragArea, { x: 0, y: top, w: w, h: bandH, cursor: "inherit", editable: false, onHover: reportHover, onSelect: select, onDrag: () => { } }))] }), label !== undefined && label !== '' && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                    top: `${top + bandH / 2}px`,
+                    [labelSide === 'right' ? 'right' : 'left']: '2px',
+                    transform: 'translateY(-50%)',
+                }, children: label }))] }));
+}
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
 export function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, edges = true, role, }) {
@@ -616,7 +706,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     // even after the dragged edge crosses it — {@link orderRegion} then re-opens the
     // region the other way instead of dead-ending at zero width.
     const edgeRef = useRef(null);
-    const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, shapeRendering: "crispEdges" }));
+    const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }));
     return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edges && edge(xa), edges && edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: (px) => {
                                     dragRef.current = { from, to, startPx: px };
                                 }, onDrag: (px) => {

package/dist/area.js

@@ -1,6 +1,6 @@
 import { area as d3area, curveLinear } from 'd3-shape';
 import { strokeAffinePolyline } from './line.js';
-import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, gapUnscalable, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { cullChartSeries } from './culling.js';
 import { decimateM4Cached } from './decimate.js';
 import { affineOf } from './affine.js';
@@ -191,6 +191,15 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     else {
         cs = cullChartSeries(source, xScale);
     }
+    // Values with no position on the y scale (zero / negative on a log axis)
+    // become ordinary NaN gaps, so the fill and outline break at them rather than
+    // bridging over a dropped `lineTo(x, NaN)`. Deliberately **after** the
+    // gradient above: that reads the pre-cull buffer, whose finite extent is
+    // memoized per `Float64Array` ([PND-GRADX]), and a fresh array here would miss
+    // that cache on every frame. A no-op on an affine (linear) y scale.
+    const scaledY = gapUnscalable(cs.y, cs.length, yScale);
+    if (scaledY !== cs.y)
+        cs = { ...cs, y: scaledY };
     // `none` interpolates interior gaps so the fill + outline bridge them; every
     // other mode keeps NaN so d3 breaks both (the inferred line bridge, if any, is
     // a separate overlay pass below).
@@ -277,20 +286,42 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
 function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
     if (valueExtent === null)
         return style.fill; // no finite values (caller no-ops)
-    // The pixel extent is the two value extremes mapped through the (monotonic,
-    // always-`scaleLinear`) y scale; min/max them so the result is flip-agnostic,
-    // exactly as the former per-point pixel scan produced. [PND-GRADX] moved the
-    // O(N) walk into the memoized {@link columnFiniteExtent}.
-    const pa = yScale(valueExtent[0]);
-    const pb = yScale(valueExtent[1]);
-    const topPx = Math.min(pa, pb); // smallest pixel y (highest on screen)
-    const bottomPx = Math.max(pa, pb); // largest pixel y (lowest on screen)
-    // The drawn region runs from the topmost of {values, baseline} to the
-    // bottommost — the fill reaches the baseline, so include it.
-    const regionTop = Math.min(topPx, baselinePx);
-    const regionBottom = Math.max(bottomPx, baselinePx);
-    if (regionBottom - regionTop < 1e-6)
-        return style.fill; // degenerate height
+    // Stacked areas opt out of the grade entirely: a band that fades to
+    // transparent at the baseline shows every band beneath it (see AreaStyle).
+    if (style.flatFill === true)
+        return style.fill;
+    // The pixel extent is the two value extremes mapped through the (monotonic)
+    // y scale; min/max them so the result is flip-agnostic, exactly as the former
+    // per-point pixel scan produced. [PND-GRADX] moved the O(N) walk into the
+    // memoized {@link columnFiniteExtent}.
+    //
+    // **An extreme with no position on the scale is dropped**, not min/maxed in.
+    // `valueExtent` is the data's own `[min, max]`, and on a **log** axis a
+    // non-positive extreme — a series that touches zero, which is the ordinary
+    // shape of traffic or storage data — maps to `NaN`. `Math.min(NaN, pb)` is
+    // `NaN`, `NaN` propagates to the height, and `NaN < 1e-6` is **false**, so the
+    // degenerate guard below waved it through to `createLinearGradient(0, NaN, 0,
+    // NaN)` — which throws `IndexSizeError` on a real canvas and takes the whole
+    // chart down. The region is seeded from the baseline pixel (always in-domain,
+    // via `resolveAreaBaseline`) and widened only by extremes that have a
+    // position, so the grade still spans the part of the series that draws.
+    let regionTop = baselinePx;
+    let regionBottom = baselinePx;
+    const widen = (px) => {
+        if (!Number.isFinite(px))
+            return;
+        if (px < regionTop)
+            regionTop = px;
+        if (px > regionBottom)
+            regionBottom = px;
+    };
+    widen(yScale(valueExtent[0]));
+    widen(yScale(valueExtent[1]));
+    // `!(… >= 1e-6)` rather than `< 1e-6`, so a non-finite height — a baseline
+    // that somehow has no position either, leaving nothing finite to anchor on —
+    // falls back to the flat fill instead of reaching the gradient calls.
+    if (!(regionBottom - regionTop >= 1e-6))
+        return style.fill; // degenerate
     const opaque = style.fill;
     const transparent = withAlpha(style.fill, 0);
     const grad = ctx.createLinearGradient(0, regionTop, 0, regionBottom);

package/dist/band.js

@@ -1,6 +1,7 @@
 import { area as d3area, curveLinear } from 'd3-shape';
 import { cullBandSeries } from './culling.js';
 import { decimateBand } from './decimate.js';
+import { gapUnscalable } from './gaps.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
  * and highest `upper` over samples where both edges are finite — or `null` if
@@ -60,6 +61,18 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
         band = decimateBand(band, xScale, ctx, k);
         decimated = band !== before;
     }
+    // An edge with no position on the y scale becomes an ordinary NaN gap, so the
+    // envelope breaks there rather than emitting dropped path ops that stitch the
+    // neighbouring samples together. A `lower` of `0` is the common shape — a band
+    // measured from nothing — and on a log axis zero has no position, so without
+    // this the fill silently spanned the samples it could not draw. Gapping either
+    // edge gaps the sample, which is already the band's contract: a sample counts
+    // only where **both** edges do. A no-op on an affine (linear) y scale.
+    const gapLower = gapUnscalable(band.lower, band.length, yScale);
+    const gapUpper = gapUnscalable(band.upper, band.length, yScale);
+    if (gapLower !== band.lower || gapUpper !== band.upper) {
+        band = { ...band, lower: gapLower, upper: gapUpper };
+    }
     const gen = d3area()
         .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
         .x((_, i) => xScale(band.x[i]))

package/dist/bars.d.ts

@@ -56,6 +56,84 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * separates columns visually without carving a dead channel out of the target.
  */
 export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+/**
+ * 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 declare function bandSpan(base: number, v: number, thresholds: readonly number[], k: number): [lo: number, hi: number] | null;
+/**
+ * A resolved threshold ladder: ascending `thresholds` (from
+ * {@link normalizeThresholds}) paired with the `colors` each band draws in,
+ * `colors[k]` for the band above `thresholds[k - 1]`. Assembled by `BarChart`
+ * from `<BarChart bandColors>` → {@link BarStyle.bands}, so — like
+ * {@link StackStyle} — the draw layer stays theme-free and unit-testable.
+ *
+ * `colors` is guaranteed `thresholds.length + 1` long by the time it reaches a
+ * draw path; a short ladder is resolved (and warned about) at the boundary.
+ */
+export interface BandLadder {
+    readonly thresholds: readonly number[];
+    readonly colors: readonly string[];
+}
+/**
+ * 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 declare function normalizeThresholds(thresholds: readonly number[] | undefined): readonly number[] | null;
 /**
  * The narrowed selection / hover identity a **single-series** bar matches
  * against: the layer's series `id`, the sample's `key` (its `begin`), and — when
@@ -120,7 +198,7 @@ export interface BarMark {
  * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
  * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: BarMark | null, hovered: BarMark | null, decimate?: DecimateOption, binFills?: readonly (string | undefined)[]): LayerDrawStats;
+export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: BarMark | null, hovered: BarMark | null, decimate?: DecimateOption, binFills?: readonly (string | undefined)[], banding?: BandLadder): LayerDrawStats;
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar
  * **under the cursor** — or `-1` if `time` falls in no bar's span. This is the
@@ -222,6 +300,41 @@ export interface StackStyle {
      * falls back to the group fill.
      */
     readonly binFills?: readonly (string | undefined)[];
+    /**
+     * The **selected** segment's fill, and `hover` the pointer-over one — the
+     * three-step `fill → hover → highlight` emphasis {@link BarStyle} has always
+     * carried and this path used to ignore ([PND-CATEMPH]).
+     *
+     * **Only applied when there is no meaning-carrying colour to destroy**, i.e.
+     * when {@link binFills} is unset. A per-bin-coloured bar keeps its own colour
+     * and pops {@link emphasisOpacity} instead — swapping a zone-coloured or
+     * direction-coloured bar to one highlight hue would erase what the colour
+     * encodes, which is the one *design* exclusion rather than a path accident.
+     *
+     * The friction this closes wasn't the behaviour, which is defensible: it was
+     * that `theme.bar.hover` / `.highlight` were typed, settable, documented as
+     * the emphasis channel, and silently did nothing on the most common
+     * categorical chart. A theme author set them, saw no change, and had no way
+     * to tell whether they were wrong about the colour or about the mechanism.
+     */
+    readonly highlight?: string;
+    /** See {@link highlight}. Falls back to `highlight` when unset. */
+    readonly hover?: string;
+    /**
+     * Stroke for the selected segment's outline. Defaults to the segment's own
+     * resolved fill (the shipped behaviour). Set it to give the category path a
+     * themed selection cue that works even where the fill can't change — the
+     * `binFills` case, where the alpha pop is otherwise the only signal.
+     */
+    readonly selectedOutline?: string;
+    /**
+     * The alpha a hovered / selected segment pops to. **Default `1`** (the
+     * shipped behaviour). Lower it for a subtler emphasis on a dense stack —
+     * previously the pop was hard-coded and the only tunable was the resting
+     * {@link opacity}, so a theme could not adjust the *difference* between
+     * resting and live, only the floor.
+     */
+    readonly emphasisOpacity?: number;
 }
 /** The narrowed selection / hover identity a stacked segment matches against:
  *  the series `id`, the bin's `begin` (its `key`), and the group (its `label`).
@@ -235,14 +348,20 @@ export interface StackMark {
 }
 /**
  * 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 declare function stackValueExtent(ss: StackedBarSeries): [number, number];
 /**
@@ -251,6 +370,22 @@ export declare function stackValueExtent(ss: StackedBarSeries): [number, number]
  * the x auto-fit for a vertical histogram, the y auto-fit for a horizontal one.
  */
 export declare function stackBinExtent(ss: StackedBarSeries): [number, number] | null;
+/**
+ * The value a stack's **first** segment rests on, in data units — the same
+ * `0`-clamped-into-the-domain rule {@link resolveBarBaseline} applies to a plain
+ * bar, read off whichever scale carries the stacked value (`yScale` when the
+ * bars grow up, `xScale` when they grow right).
+ *
+ * Both stack walks used to start at a literal `0`, which is right only while the
+ * domain contains zero — and a **log** domain never can. `yScale(0)` on a log
+ * scale is `NaN`, `fillRect` with a `NaN` argument is a silent canvas no-op, and
+ * the same rect feeds {@link stackAt} — so the bottom segment of every stack
+ * both vanished *and* became unhittable, with nothing to see but a stack that
+ * starts one segment up. The linear case is unaffected: the value extents pull
+ * `0` into the domain, so this returns exactly `0` and the geometry is
+ * unchanged.
+ */
+export declare function stackBase(orientation: Orientation, xScale: Scale, yScale: Scale): number;
 /**
  * The pixel rect `[x0, x1, yTop, yBottom]` (ascending on both axes) of bin `b`'s
  * segment `g`, stacked so it sits atop `cumBefore` (the summed value of the
@@ -283,7 +418,7 @@ export declare function segmentRect(ss: StackedBarSeries, b: number, g: number,
  *
  * O(N·G) over bins × groups, one fill (+ optional stroke) per drawn segment.
  */
-export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: StackMark | null, hover: StackMark | null): void;
+export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: StackMark | null, hover: StackMark | null, banding?: BandLadder): void;
 /**
  * Hit-test plot-pixel `(px, py)` against `ss`'s stacked segments — the **first**
  * segment whose rect contains the point, or `null`. The geometry is