@pond-ts/charts 0.55.0 → 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).
@@ -435,6 +605,24 @@ export function stackBinExtent(ss) {
         return null;
     return [ss.begin[0], ss.end[ss.length - 1]];
 }
+/**
+ * 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 function stackBase(orientation, xScale, yScale) {
+    return resolveBarBaseline(orientation === 'vertical' ? yScale : xScale);
+}
 /**
  * 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
@@ -456,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);
@@ -489,17 +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 = 0;
+        // 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;
@@ -514,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);
             }
         }
@@ -543,13 +802,21 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
  */
 export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx) {
     const G = ss.groups.length;
+    const base = stackBase(orientation, xScale, yScale);
     for (let b = 0; b < ss.length; b += 1) {
-        let cum = 0;
+        // 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

@@ -1,4 +1,4 @@
-import type { ScaleLinear, ScaleTime } from 'd3-scale';
+import type { ScaleContinuousNumeric, ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
 import type { LegendItemSpec } from './swatch.js';
@@ -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). */
@@ -761,11 +770,27 @@ export interface LayerEntry {
     readonly index: number;
 }
 /** A y-axis declared in a {@link ChartRow} via `<YAxis>`. */
+/** Which scale a y axis maps its domain through. */
+export type YScaleKind = 'linear' | 'log';
+/**
+ * A row's resolved y scale — d3's `scaleLinear()`, or `scaleLog()` when the
+ * axis asks for `scale="log"`.
+ *
+ * Deliberately the **continuous-numeric** supertype rather than `ScaleLinear`:
+ * every consumer (the axis labels, the row's gridlines, the cursor readout, and
+ * every draw layer) only ever calls it, or reads `domain` / `range` / `ticks` /
+ * `tickFormat` / `invert` — the surface both scales share. Keeping the shared
+ * type here is what lets a log axis be transparent to the draw layers instead
+ * of every layer growing a branch.
+ */
+export type YScale = ScaleContinuousNumeric<number, number>;
 export interface AxisSpec {
     readonly id: string;
     readonly side: 'left' | 'right';
     /** Gutter width in CSS pixels. */
     readonly width: number;
+    /** Which scale the axis maps its domain through ({@link YAxisProps.scale}). */
+    readonly scale: YScaleKind;
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;
@@ -799,7 +824,7 @@ export interface AxisSpec {
  */
 export interface RowFrame {
     readonly height: number;
-    readonly yScales: ReadonlyMap<string, ScaleLinear<number, number>>;
+    readonly yScales: ReadonlyMap<string, YScale>;
     /** Value formatter per axis id (resolved from the axis's {@link AxisSpec.format}
      *  against its scale) — used by both the tick labels and the cursor readout, so
      *  a value reads identically in both. */

package/dist/dev.d.ts

@@ -0,0 +1,2 @@
+export declare const isDev: boolean;
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.js

@@ -0,0 +1,2 @@
+export const isDev = typeof process === 'undefined' || process?.env?.NODE_ENV !== 'production';
+//# sourceMappingURL=dev.js.map

package/dist/domain.d.ts

@@ -1,3 +1,4 @@
+import type { YScaleKind } from './context.js';
 /**
  * Resolve a y-axis `[lo, hi]` domain from its explicit bounds and the extents of
  * the layers linked to it. An `undefined` bound auto-fits the data: with no
@@ -19,6 +20,58 @@
  * `pad × span` on each side — headroom without hand-computing bounds, useful to
  * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
  * domain was resolved (explicit or auto); `0` is a no-op.
+ *
+ * `scale` selects the spacing. `'log'` delegates to {@link resolveLogDomain},
+ * which applies **every policy above** — verbatim explicit bounds, an auto-fit
+ * side that moves rather than a caller's bound being discarded, `.nice()` on a
+ * fully auto-fit domain — and differs only where a log axis forces it to: a
+ * non-positive bound has no position and is refused, and `pad` is a fraction of
+ * the *decades* spanned rather than of the difference.
+ */
+export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>, pad?: number, scale?: YScaleKind): [number, number];
+/**
+ * Does resolving this axis's domain need its layers' extents walked?
+ * `yExtent()` is O(points) per layer, so the caller only pays it when a side
+ * actually auto-fits.
+ *
+ * A log axis **refuses a non-positive bound** ({@link resolveLogDomain}), which
+ * means such a bound is not a bound: that side auto-fits and needs the data. The
+ * naive `min === undefined || max === undefined` test misses this, and the miss
+ * is silent — `<YAxis scale="log" min={0} max={1e6}>` looked fully explicit, so
+ * no extents were gathered, so the refused floor fell back to the empty-data
+ * placeholder instead of the data's own floor. (`resolveLogDomain`'s unit tests
+ * passed throughout: they hand it the extents directly, which is precisely what
+ * the component was not doing.)
+ */
+export declare function needsExtents(axis: {
+    readonly scale: YScaleKind;
+    readonly min: number | undefined;
+    readonly max: number | undefined;
+}): boolean;
+/**
+ * The dev-mode complaint a `scale="log"` axis has about its own bounds and the
+ * data linked to it, or `null` when it has none. Pure, so the policy is unit
+ * tested directly rather than through a rendered console spy.
+ *
+ * **Every case here is unambiguous**, which is the whole design constraint. The
+ * previous version warned whenever a linked extent reached zero, and that fires
+ * on *every* `BarChart` — `barExtent` always widens its low end to `0` so a bar
+ * can reach its baseline, whether or not the data goes anywhere near it. So the
+ * `WithBars` story warned, on strictly positive data, with text asserting
+ * something false about it. A dev warning that cries wolf gets muted, and then
+ * the real ones are lost too.
+ *
+ * The cost of that precision is the one genuinely ambiguous shape: an extent of
+ * exactly `[0, hi]`, which is what a line touching zero *and* a bar layer on
+ * positive data both report. It is not warned about. That case is no longer
+ * silent, though — a sample with no position on the axis now renders as a
+ * **gap** rather than being bridged straight over, so the picture itself says
+ * the data is missing there.
  */
-export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>, pad?: number): [number, number];
+export declare function logAxisWarning(axis: {
+    readonly id: string;
+    readonly scale: YScaleKind;
+    readonly min: number | undefined;
+    readonly max: number | undefined;
+}, extents: readonly (readonly [number, number] | null)[]): string | null;
 //# sourceMappingURL=domain.d.ts.map