@pond-ts/charts 0.56.2 → 0.57.0

package/dist/YAxis.js

@@ -17,7 +17,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -29,7 +29,11 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
     const spec = useMemo(() => ({
         id,
         side,
-        width,
+        // A hidden axis reserves no gutter — the row's slot placement reads this
+        // width, so zeroing it here is what gives the space back to the plot.
+        // Everything else about the spec is unchanged: the domain still resolves
+        // and layers still bind to it, which is the whole point of the prop.
+        width: hide ? 0 : width,
         scale,
         min,
         max,
@@ -43,6 +47,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         id,
         side,
         width,
+        hide,
         scale,
         min,
         max,
@@ -65,6 +70,23 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
     useEffect(() => {
         registerAxis(slot, spec);
     }, [registerAxis, slot, spec]);
+    // `hide`: everything above still runs — the axis is registered, so its scale
+    // exists and layers bind to it — and everything below (the gutter chrome)
+    // does not. Placed after the last hook so the early return can't change hook
+    // order when `hide` is toggled at runtime.
+    //
+    // It renders an **empty box at the reserved slot width**, not nothing. The
+    // container reserves each axis *column* at the widest across rows
+    // (`maxSlotWidths`), so a hidden axis sharing a column with a visible one in
+    // another row is still allotted that column's width — and drawing nothing
+    // there slides this row's plot left, out of line with its siblings and with
+    // the shared x-axis. When this axis is alone in its column the reservation is
+    // its own `width: 0`, the box is zero-wide, and the plot reclaims the space,
+    // which is the point of the prop. Both cases fall out of the same expression.
+    if (hide) {
+        const hiddenSlot = row.axisSlots.get(slot) ?? 0;
+        return hiddenSlot > 0 ? (_jsx("div", { "aria-hidden": "true", style: { flex: `0 0 ${hiddenSlot}px`, height: `${row.height}px` } })) : null;
+    }
     const { theme } = container;
     const yScale = row.yScales.get(id);
     // The auto-tick count — the row resolves it (explicit `tickCount` else

package/dist/annotations.d.ts

@@ -161,6 +161,80 @@ export interface BaselineProps {
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
 export declare function Baseline({ value, axis, label, labelSide, labelPosition, id, selected, selectable, hovered, editing, onChange, indicator, role, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
+export interface ZoneProps {
+    /** Lower bound in the linked y-axis's units. */
+    from: number;
+    /** Upper bound in the linked y-axis's units. `from`/`to` may arrive either way
+     *  round (they're ordered here), and either may be **infinite** for an
+     *  open-ended band (`to={Infinity}` — the AQI "Hazardous" tail, a
+     *  `ZoneTime.openEnded` zone): the rect clamps to the plot. */
+    to: number;
+    /** Which `<YAxis>` (by id) to measure against; omit for the row's default axis. */
+    axis?: string;
+    /** Chip label, anchored at the band's vertical centre. **Omit for no label** —
+     *  unlike `<Region>` a zone does *not* auto-label its bounds, because they're
+     *  already legible on the y axis it spans (a region's x span isn't). The label
+     *  worth showing is a **name** — `"Good"`, `"Z4 threshold"` — which only the
+     *  caller has. */
+    label?: string;
+    /** Which side of the chart the label chip sits. **Default `left`.** */
+    labelSide?: 'left' | 'right';
+    /** Stable consumer id — a click reports it via `onSelectAnnotation`. Only
+     *  meaningful with `selectable`. */
+    id?: string;
+    /** Controlled selection — brightens to the front (level 1). Ignored unless
+     *  `selectable`. */
+    selected?: boolean;
+    /**
+     * Whether the band responds to hover + selection. **Default `false`** — the
+     * opposite of the rest of the family, and deliberately so: a zone spans the
+     * **full plot width**, and a zone *set* tiles the whole y range, so the pointer
+     * is always inside one. Interactive by default, they'd light up on every
+     * mousemove and their hit rects would swallow the plot's own clicks. A zone is
+     * background context first (level 3, pointer-transparent); opt in per band when
+     * a band is genuinely a thing to point at.
+     */
+    selectable?: boolean;
+    /** Theme **role** — colours this band from `theme.annotation.roles[role]` (its
+     *  `color`, optionally `fillOpacity`), keeping the shared depth ramp. This is
+     *  how a zone set gets its **semantic palette** (`good` green, `moderate`
+     *  yellow, …): the scale lives in the theme, not at the call site. Omitted /
+     *  unknown ⇒ the base annotation colour. */
+    role?: string;
+    /** Controlled hover (OR'd with pointer hover) — lets a legend row light the
+     *  band remotely. Ignored unless `selectable`. */
+    hovered?: boolean;
+    /** Draw the horizontal **boundary lines** at `from`/`to`. **Default `false`** —
+     *  again the opposite of `<Region>`, because zone sets are usually
+     *  **contiguous**: every interior boundary is shared by two bands, so edges-on
+     *  draws each one twice at double opacity. `true` outlines an isolated band (a
+     *  target range). */
+    edges?: boolean;
+}
+/**
+ * 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 declare function Zone({ from, to, axis, label, labelSide, id, selected, selectable, hovered, role, edges, }: ZoneProps): import("react/jsx-runtime").JSX.Element | null;
 export interface RegionProps {
     /** Start x in axis units (time or value). */
     from: number;

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/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];
 /**
@@ -299,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