@pond-ts/charts 0.55.0 → 0.57.0

package/dist/BarChart.js

@@ -1,7 +1,8 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
 import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
-import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { isDev } from './dev.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
@@ -24,14 +25,21 @@ import { useSlotKey } from './use-slot-key.js';
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -48,7 +56,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -232,6 +240,87 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // The stacked path's bar-thickness floor comes from `bar.default` (not the `as`
     // role — `as` is single-series only), matching how `gapPx` sources its default.
     const stackMinWidth = bar.default.minWidth;
+    // ── Threshold ladder ([PND-BANDBAR2]) ────────────────────────────────────
+    // Resolved once here rather than per bar per frame: normalize the breakpoints
+    // (sort, drop non-finite), then pair them with `bandColors` → the role's
+    // `BarStyle.bands`. Everything that can go wrong with the pairing is a
+    // *silent* wrong-looking chart, so each case dev-warns — this feature exists
+    // because a quietly-unbanded bar was the workaround's failure mode.
+    // Value-compare the two array props rather than relying on their identity.
+    // `thresholds={[1, 2]}` inline is the documented usage and the shape every
+    // story and doc example uses — and a fresh array each render would rebuild
+    // the ladder, hence the layer `entry` below, hence a `registerLayer` call
+    // **every render**. That is a repaint treadmill, not just a noisy warning.
+    // The same value-compare-on-registration reasoning `<YAxis ticks>` already
+    // applies.
+    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
+    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
+    const bandLadder = useMemo(() => {
+        const steps = normalizeThresholds(thresholds);
+        if (steps === null) {
+            if (isDev && thresholds !== undefined && thresholds.length > 0) {
+                console.warn('<BarChart thresholds>: no usable breakpoints, so no banding was ' +
+                    'applied — each must be finite and greater than zero. Bars draw ' +
+                    'in the flat fill.');
+            }
+            return undefined;
+        }
+        // Some, but not all, entries dropped. Silently banding on a subset of what
+        // the caller wrote is exactly the class of quiet wrongness this feature is
+        // meant to remove, so say so.
+        if (isDev && thresholds !== undefined && steps.length < thresholds.length) {
+            console.warn(`<BarChart thresholds>: dropped ${thresholds.length - steps.length} ` +
+                'breakpoint(s) that were not finite and greater than zero. The ' +
+                'ladder is walked on the magnitude and mirrored onto whichever side ' +
+                'of zero a bar is on, so a negative breakpoint has no meaning; ' +
+                `banding on [${steps.join(', ')}].`);
+        }
+        const want = steps.length + 1;
+        const supplied = bandColors ?? singleStyle.bands;
+        if (supplied === undefined || supplied.length === 0) {
+            if (isDev) {
+                console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                    'band colours, but neither `bandColors` nor the theme role’s ' +
+                    '`BarStyle.bands` supplies any. Bars draw in the flat fill.');
+            }
+            return undefined;
+        }
+        if (supplied.length < want && isDev) {
+            console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                `band colours but only ${supplied.length} were supplied; bands ` +
+                'above the last colour fall back to the flat fill.');
+        }
+        // Pad a short ladder with the flat fill so the draw path can index freely.
+        const resolved = supplied.length >= want
+            ? supplied.slice(0, want)
+            : [
+                ...supplied,
+                ...Array.from({ length: want - supplied.length }, () => singleStyle.fill),
+            ];
+        return { thresholds: steps, colors: resolved };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `thresholdKey` /
+        // `bandColorKey` are the value-compared stand-ins for the array props.
+    }, [thresholdKey, bandColorKey, singleStyle]);
+    // Conflicts between the ladder and the shapes it can't apply to. In an effect
+    // so a re-render doesn't re-log; each fires once per genuinely new pairing.
+    const multiGroup = shape.kind === 'stacked' && shape.ss.groups.length > 1;
+    const hasLadder = bandLadder !== undefined;
+    const hasBinColors = binColors !== undefined;
+    useEffect(() => {
+        if (!isDev || !hasLadder)
+            return;
+        if (hasBinColors) {
+            console.warn('<BarChart>: `thresholds` and `binColors` are both set. They are two ' +
+                'answers to “what colour is this bar”; `binColors` wins as the more ' +
+                'specific one, and the threshold bands are ignored.');
+        }
+        if (multiGroup) {
+            console.warn('<BarChart>: `thresholds` is ignored on a multi-group stack — a ' +
+                'segment that is already one slice of a total has no defined ' +
+                'banding. Threshold bands apply to single-value bars (`series` / ' +
+                '`bins` / `categories`), in either orientation.');
+        }
+    }, [hasLadder, hasBinColors, multiGroup]);
     // Stacked style: per-group fills (colors override → theme role → default),
     // plus the shared opacity / outline from the default bar style. Memoized on the
     // groups + colours so a selection change doesn't rebuild it.
@@ -243,6 +332,17 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             fills,
             opacity: base.opacity,
             outlineWidth: base.outlineWidth,
+            // [PND-CATEMPH] Forward the themed emphasis so the category / horizontal
+            // path can read the same `fill → hover → highlight` channel every other
+            // bar does, instead of accepting those theme values and ignoring them.
+            highlight: base.highlight,
+            ...(base.hover !== undefined ? { hover: base.hover } : {}),
+            ...(base.selectedOutline !== undefined
+                ? { selectedOutline: base.selectedOutline }
+                : {}),
+            ...(base.emphasisOpacity !== undefined
+                ? { emphasisOpacity: base.emphasisOpacity }
+                : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
     }, [bar, groups, colors, binColors]);
@@ -331,7 +431,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 };
                             },
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder),
                 },
                 axisId: axis,
                 index,
@@ -391,7 +491,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                             };
                         },
                     }),
-                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover),
+                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover, bandLadder),
             },
             axisId: axis,
             index,
@@ -405,6 +505,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         singleStyle,
         stackStyle,
         binColors,
+        bandLadder,
         label,
         id,
         gapPx,

package/dist/ChartContainer.d.ts

@@ -14,6 +14,49 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * **Cap the slot pitch** on a **category** x axis, in CSS pixels
+     * ([PND-BANDPACK]). A band scale otherwise spreads its categories across the
+     * full plot width, so three categories in a 900px panel become three 300px
+     * bars and thirty become thirty 30px ones — the same chart in the same panel
+     * reading as two different charts depending on how many categories the data
+     * happened to return.
+     *
+     * That is fine for a static chart with a known domain and wrong for a **live**
+     * one: when the category count moves over a session, bar width becomes a
+     * meaningless variable that moves on its own, and a reader can't compare the
+     * chart to what it looked like a minute ago or to the same chart on another
+     * screen. Capping the pitch keeps bar width constant and comparable, and the
+     * empty space left over is itself information — it shows the set is small.
+     *
+     * Omitted ⇒ slots fill the plot (unchanged). When `n × maxBandWidth` exceeds
+     * the plot, the cap can't bind and the slots fill as before, so this degrades
+     * correctly as categories accumulate. Use {@link bandAlign} to say where the
+     * capped block sits.
+     *
+     * **This caps the slot, not the bar.** `<BarChart gap>` still insets the bar
+     * within its slot, and the two compose — one knob for pitch, one for ink,
+     * neither doing the other's job. (Inverting `gap` against a measured plot
+     * width was the workaround this replaces for the width half; the packing half
+     * had no workaround at all.)
+     *
+     * **Vertical / x-axis categories only.** A `orientation="horizontal"`
+     * categorical chart puts its categories on the **y** axis as unit slots,
+     * which is a different mechanism and is not capped by this.
+     */
+    maxBandWidth?: number;
+    /**
+     * Where the capped category block sits in the plot when {@link maxBandWidth}
+     * binds. **Default `'start'`** — pack from the left, leaving the far side
+     * empty. `'center'` and `'end'` place it otherwise.
+     *
+     * A no-op without `maxBandWidth`, or when the cap doesn't bind: the block
+     * fills the plot and there is no slack to place. (There is deliberately no
+     * `'fill'` member — "fill" is what *omitting* `maxBandWidth` means, and a
+     * `fill` value alongside a pitch cap would be a contradiction rather than a
+     * choice.)
+     */
+    bandAlign?: 'start' | 'center' | 'end';
     /**
      * A **trading-calendar** discontinuity provider — closed-market time
      * (weekends, holidays, overnight, lunch breaks) collapsed. Supply it to turn
@@ -419,5 +462,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -45,7 +45,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
     // Normalize the `panZoom` mode (boolean shorthand or the three-way string)
     // into the two gesture flags the event surface reads. `true` ⇒ both; `'pan'`
     // ⇒ drag only; `false`/`'none'` ⇒ neither. Zoom implies pan (there is no
@@ -414,7 +414,21 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             // reads by **name** — `cursorFormat` has nothing to format, so the
             // readout channel stays unset.
             const cats = categories ?? [];
-            const s = scaleBand(cats).domain([0, cats.length]).range([0, plotWidth]);
+            // [PND-BANDPACK] Cap the slot pitch, then place the resulting block. With
+            // no cap (or one too loose to bind) `packed === plotWidth` and `offset`
+            // is 0, so the range is `[0, plotWidth]` exactly as before — the whole
+            // feature collapses to the shipped behaviour when unused.
+            const n = cats.length;
+            const pitch = n > 0 ? plotWidth / n : plotWidth;
+            const capped = maxBandWidth !== undefined && maxBandWidth > 0
+                ? Math.min(pitch, maxBandWidth)
+                : pitch;
+            const packed = n > 0 ? capped * n : plotWidth;
+            const slack = Math.max(0, plotWidth - packed);
+            const offset = bandAlign === 'center' ? slack / 2 : bandAlign === 'end' ? slack : 0;
+            const s = scaleBand(cats)
+                .domain([0, n])
+                .range([offset, offset + packed]);
             return {
                 xScale: s,
                 formatTime: (v) => s.label(v),
@@ -555,6 +569,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [
         resolvedKind,
         categories,
+        maxBandWidth,
+        bandAlign,
         d0,
         d1,
         plotWidth,

package/dist/ChartRow.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
-import { scaleLinear } from 'd3-scale';
-import { resolveYDomain } from './domain.js';
+import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { scaleLinear, scaleLog } from 'd3-scale';
+import { isDev } from './dev.js';
+import { logAxisWarning, needsExtents, resolveYDomain } from './domain.js';
 import { resolveAxisFormat } from './format.js';
 import { resolveYTickCount } from './yticks.js';
 import { placeAxisSlots } from './slots.js';
@@ -39,6 +40,7 @@ function axisSpecEqual(a, b) {
     return (a.id === b.id &&
         a.side === b.side &&
         a.width === b.width &&
+        a.scale === b.scale &&
         // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
         // doesn't re-register every render.
         Object.is(a.min, b.min) &&
@@ -171,6 +173,7 @@ export function ChartRow({ height, cursor, children }) {
                 id: IMPLICIT_AXIS_ID,
                 side: 'left',
                 width: 0,
+                scale: 'linear',
                 min: undefined,
                 max: undefined,
                 pad: 0,
@@ -222,20 +225,68 @@ export function ChartRow({ height, cursor, children }) {
     const yScales = useMemo(() => {
         const map = new Map();
         for (const ax of effectiveAxes) {
-            const extents = ax.min === undefined || ax.max === undefined
+            const extents = needsExtents(ax)
                 ? layerList
                     .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
                     .map((entry) => entry.layer.yExtent())
                 : [];
-            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad);
+            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad, ax.scale);
             // Reserve a header band at the top when any axis draws a `'top'` title,
             // so the title clears the top tick + plot (the whole row shifts down
             // uniformly, keeping stacked axes aligned). No top titles ⇒ range top 0,
             // so nothing changes for existing charts.
-            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, topHeader]));
+            // `scaleLog` and `scaleLinear` share the call/ticks/tickFormat/invert
+            // surface every consumer uses (see `YScale`), so choosing between them
+            // here is the whole of log support — no draw layer branches on it.
+            const base = ax.scale === 'log' ? scaleLog() : scaleLinear();
+            map.set(ax.id, base.domain([lo, hi]).range([height, topHeader]));
         }
         return map;
     }, [effectiveAxes, layerList, height, defaultAxisId, topHeader]);
+    // Dev-mode diagnostics for a `scale="log"` axis (see `logAxisWarning`). Three
+    // things about *where* this sits are load-bearing, each of them a bug the
+    // first version shipped:
+    //
+    //  - **An effect, not the scale memo.** Warning from inside `useMemo` is a
+    //    side effect in a function React may call speculatively — and does call
+    //    twice under StrictMode.
+    //  - **Deduplicated by message, in a ref.** The comment on the original said
+    //    "warn once per offending axis" and nothing implemented it, so a live
+    //    chart re-warned on every appended sample. Keying on the message (not a
+    //    bare "already warned" flag) still reports a *different* complaint if the
+    //    data changes shape.
+    //  - **`height` is not a dependency.** It is one for the scales, which is why
+    //    the warning must not ride along: a drag-resize would otherwise emit a
+    //    line per animation frame.
+    //
+    // Gated on `isDev` **and** on some axis actually being logarithmic, so a
+    // production build and every linear chart skip the extent walk entirely.
+    const warnedRef = useRef(new Map());
+    useEffect(() => {
+        if (!isDev || !effectiveAxes.some((ax) => ax.scale === 'log'))
+            return;
+        const warned = warnedRef.current;
+        for (const ax of effectiveAxes) {
+            // A linear axis in the same row has nothing to say and must not pay the
+            // O(points) walk below just because a sibling is logarithmic.
+            if (ax.scale !== 'log')
+                continue;
+            // Always walk the extents here, even for a fully-explicit domain the
+            // scale memo skips them for: data that cannot be drawn is worth saying so
+            // about whether or not it happened to constrain the bounds — and the
+            // both-explicit axis was exactly the case the first version stayed silent
+            // about.
+            const message = logAxisWarning(ax, layerList
+                .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
+                .map((entry) => entry.layer.yExtent()));
+            if (message === null)
+                warned.delete(ax.id);
+            else if (warned.get(ax.id) !== message) {
+                warned.set(ax.id, message);
+                console.warn(message);
+            }
+        }
+    }, [effectiveAxes, layerList, defaultAxisId]);
     // Resolved auto-tick count per axis — explicit `<YAxis tickCount>` else
     // height-derived (see resolveYTickCount). The single source the `<YAxis>`
     // labels, the readout formatter (below), and the `Layers` gridlines all read,

package/dist/Layers.js

@@ -5,6 +5,7 @@ import { drawGrid, drawDividers, dividerAlphas, thinPixels } from './grid.js';
 import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
+import { yTickValues } from './yticks.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, CursorContext, LayersContext, RowContext, } from './context.js';
 /** Fallback **y**-gridline tick count, used only before the row publishes its
@@ -116,7 +117,7 @@ export function Layers({ children }) {
             // a gridline sits under every `<YAxis>` label and no more.
             const yCount = tickCounts.get(defaultAxisId) ?? GRID_TICKS;
             const yTicks = gridY && !(yIsCategory && explicitY === undefined)
-                ? (explicitY ?? gridY.ticks(yCount)).map((t) => gridY(t))
+                ? (explicitY ?? yTickValues(gridY, yCount)).map((t) => gridY(t))
                 : [];
             // On a calendar axis the verticals are the FULL grain populations —
             // every day in the month, every month in the year, every aligned
@@ -267,6 +268,18 @@ export function Layers({ children }) {
         // a full replot per mousemove.
         container.timeRange,
         container.reportDrawStats,
+        // Read inside `draw`, so they have to invalidate it. Omitting `grid` meant
+        // toggling `<ChartContainer grid>` changed nothing until some *other*
+        // dep moved — pan the plot a pixel and the gridlines you switched off
+        // finally vanished. All primitives, so no per-frame identity churn.
+        container.grid,
+        container.sessionDividers,
+        container.xKind,
+        // `container.theme` is read too. It is deliberately NOT listed: it is the
+        // caller's prop and an inline object literal would rebuild `draw` every
+        // render (a full replot per frame). The values `draw` actually takes from
+        // it — `background`, `gridColor`, `gridDash` — are extracted above and
+        // listed individually, so a theme swap still invalidates.
         row.rowKey,
     ]);
     // Interaction overlay: the cursor marks live on a DOM/SVG overlay above the

package/dist/YAxis.d.ts

@@ -20,6 +20,34 @@ export interface YAxisProps {
      *   that has headroom (auto-fit / padded) so it doesn't crowd the top tick.
      */
     labelPlacement?: 'rotated' | 'top';
+    /**
+     * Which scale the axis maps its domain through. **Default `'linear'`.**
+     *
+     * `'log'` gives a base-10 logarithmic axis — for data spanning orders of
+     * magnitude, where a linear axis flattens everything below the top decade
+     * onto the baseline. Ticks land on the decades, and `format` still formats
+     * the **value**, so a readout says `1.2 PB`, not its logarithm.
+     *
+     * A log domain cannot contain zero or negative numbers — d3 maps them to
+     * `NaN`, which has no position on the plot. So:
+     *
+     * - **Auto-fit ignores non-positive extents** when picking the low end (a
+     *   `BarChart`, whose extent always reaches zero so its bars can meet their
+     *   baseline, can therefore share the axis), and rounds the domain out to
+     *   whole powers of ten.
+     * - **An explicit `min`/`max` that is not positive is refused**, and that
+     *   side auto-fits instead. A positive bound is always honoured exactly; when
+     *   only one side is given and the domain would invert, the *auto* side moves
+     *   — the same policy a linear axis follows.
+     * - **Layers that fill to a baseline** (`AreaChart`, `BarChart`, a stacked
+     *   histogram) rest it on the bottom of the domain rather than on zero.
+     * - **A value with no position gaps the line**, rather than its neighbours
+     *   being joined straight across it.
+     *
+     * A dev-mode warning fires for the cases that are unambiguously a mistake: a
+     * refused bound, negative data, or an axis with no positive data at all.
+     */
+    scale?: 'linear' | 'log';
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
@@ -78,6 +106,33 @@ export interface YAxisProps {
     boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
+    /**
+     * **Keep the scale, draw no gutter.** The axis still registers its domain
+     * (`min`/`max`/`scale`/`pad`) and layers still bind to it by `id`, but it
+     * renders nothing and reserves **no width** — the plot gets the space.
+     *
+     * A `<YAxis>` does two jobs: it *holds the scale* and it *renders a gutter*.
+     * Without this there was no way to ask for the first without the second, so a
+     * chart with a **fixed** domain whose scale is already explained by its
+     * chrome (threshold band lines, a legend, a panel header) had two reachable
+     * options and needed a third:
+     *
+     * | | auto domain | explicit domain |
+     * |---|---|---|
+     * | **gutter** | `<YAxis />` | `<YAxis min max />` |
+     * | **no gutter** | omit the axis | ← this prop |
+     *
+     * Omitting the axis is not the same thing: the row then supplies an implicit
+     * auto-domain axis, and the fixed domain is exactly what must not be given
+     * up. `width={0}` is not it either — the labels still draw, now over the
+     * plot.
+     *
+     * **Gridlines are unaffected.** They belong to the plot, not the gutter, and
+     * `<ChartContainer grid>` already controls them — so a hidden axis can still rule
+     * its own gridlines, which is usually what a "the shape matters, the numbers
+     * don't" chart wants. Turn them off there if you want neither.
+     */
+    hide?: boolean;
     /**
      * This axis instance's colour — tick labels and the axis title take it,
      * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
@@ -100,5 +155,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -3,6 +3,7 @@ import { useContext, useEffect, useMemo } from 'react';
 import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
 import { useSlotKey } from './use-slot-key.js';
+import { yTickValues } from './yticks.js';
 const DEFAULT_WIDTH = 50;
 /** Fallback tick count before the row has published its resolved count (the
  *  first render, pre-registration). The row's height-derived value takes over
@@ -16,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, 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>');
@@ -28,7 +29,12 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
     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,
         pad,
@@ -41,6 +47,8 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
         id,
         side,
         width,
+        hide,
+        scale,
         min,
         max,
         pad,
@@ -62,6 +70,23 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
     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
@@ -87,7 +112,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
         ? ticks.map((t) => ({ value: t.at, label: t.label }))
         : layerCategories !== null
             ? layerCategories.map((label, i) => ({ value: i + 0.5, label }))
-            : (yScale ? yScale.ticks(count) : []).map((t) => ({
+            : (yScale ? yTickValues(yScale, count) : []).map((t) => ({
                 value: t,
                 label: fmt(t),
             }));

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;