@pond-ts/charts 0.61.0 → 0.63.0

package/dist/ChartRow.d.ts

@@ -1,8 +1,44 @@
 import { type ReactNode } from 'react';
 import { type CursorMode } from './context.js';
 export interface ChartRowProps {
-    /** Row height in CSS pixels. */
-    height: number;
+    /**
+     * Row height in CSS pixels — the **fixed** sizing mode. Omit it (or pass
+     * {@link flex}) to let the row share the container's remaining height
+     * instead; a bare `<ChartRow>` means `flex={1}`.
+     */
+    height?: number;
+    /**
+     * Share of the container's **remaining** height ([PND-HEIGHT]) — the
+     * CSS-flex sizing mode, and what an omitted `height` defaults to (`1`).
+     *
+     * The remainder is what CSS flex layout says it is: the container's height
+     * minus its axis strip, minus every fixed-`height` row, minus any non-row
+     * children you placed between rows (a draggable splitter), minus `rowGap`s.
+     * That is deliberate — the row's box is `flex: <n> 1 0`, so **the browser
+     * does the subtraction** and there is no strip-height constant for a caller
+     * to know, guess, or drift on (the reporting consumer had `20` and `24` in
+     * one codebase for a strip that is actually 22 — *when it is not showing a
+     * calendar band row or marker pills, which change it*). The row then reads
+     * back the height the layout gave it and builds its y-scales from that.
+     *
+     * Mixing modes is the point, not an edge case: a price row over a volume
+     * row is `<ChartRow flex={3}>` over `<ChartRow flex={1}>`; the splitter
+     * shape is one `flex` row that absorbs slack over one fixed row the drag
+     * resizes.
+     *
+     * **Needs a container that manages height** — `<ChartContainer
+     * height={number | 'auto'}>`. Inside a container with no height, a flex
+     * row's box has nothing to flex into, collapses to zero, and stays gated
+     * out; dev builds warn.
+     *
+     * A flex row's first useful paint waits for its first measurement — by
+     * **timing**, not a gate: the first render does execute children at height
+     * 0 (a 0-height canvas draws nothing), and the layout effect's synchronous
+     * setState delivers the real height before the browser paints. Like the
+     * container's `width="auto"`, it keeps its last non-zero height while
+     * hidden, so a `display: none` tab switch does not discard its scales.
+     */
+    flex?: number;
     /**
      * Cursor presentation for this row, overriding the container's default
      * ({@link ChartContainerProps.cursor}). Omit to inherit. See {@link CursorMode}.
@@ -32,5 +68,5 @@ export interface ChartRowProps {
  * Children lay out left-to-right in author order, so `<YAxis side="left"/>` goes
  * before `<Layers/>` and `<YAxis side="right"/>` after.
  */
-export declare function ChartRow({ height, cursor, children }: ChartRowProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartRow({ height: heightProp, flex, cursor, children, }: ChartRowProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartRow.d.ts.map

package/dist/ChartRow.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, Fragment, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { Children, Fragment, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { scaleLinear, scaleLog, scaleSymlog } from 'd3-scale';
 import { isDev } from './dev.js';
 import { useIndexedChildren } from './child-index.js';
@@ -90,6 +90,11 @@ function axisSpecEqual(a, b) {
         a.labelPlacement === b.labelPlacement &&
         a.index === b.index &&
         a.tickCount === b.tickCount &&
+        // The axis-edge chrome drawn *by the row* wears this (the crosshair's value
+        // pill), so a swallowed colour change would leave the pill on the old ink
+        // while the axis's own labels repainted — the same silent-staleness the
+        // `linearWindow` note above warns about.
+        a.color === b.color &&
         Object.is(a.format, b.format) &&
         numberArraysEqual(a.tickValues, b.tickValues));
 }
@@ -134,11 +139,73 @@ const TOP_LABEL_HEADER = 16;
  * Children lay out left-to-right in author order, so `<YAxis side="left"/>` goes
  * before `<Layers/>` and `<YAxis side="right"/>` after.
  */
-export function ChartRow({ height, cursor, children }) {
+export function ChartRow({ height: heightProp, flex, cursor, children, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ChartRow> must be rendered inside a <ChartContainer>');
     }
+    // ── Sizing mode ([PND-HEIGHT]) ─────────────────────────────────────────────
+    // Fixed (`height` in px) or flex (`flex`, the default when neither is
+    // given). A flex row's box is sized by CSS (`flex: <n> 1 0` inside the
+    // container's column), and the row reads back what layout gave it — the
+    // browser subtracts the axis strip, fixed siblings, splitters and row gaps,
+    // so no caller (and no code here) ever knows what those cost.
+    const isFlex = heightProp === undefined;
+    const flexGrow = flex ?? 1;
+    const warnedSizingRef = useRef(false);
+    useEffect(() => {
+        if (!isDev || warnedSizingRef.current)
+            return;
+        if (heightProp !== undefined && flex !== undefined) {
+            // Both given is a contradiction, not a tiebreak: warn and honour
+            // `height` (the long-standing prop) so the chart renders
+            // deterministically.
+            warnedSizingRef.current = true;
+            console.warn(`[pond-charts] <ChartRow> got both height={${heightProp}} and ` +
+                `flex={${flex}} — they are alternative sizing modes. Using ` +
+                `height; drop one.`);
+        }
+    }, [heightProp, flex]);
+    const boxRef = useRef(null);
+    const [measured, setMeasured] = useState(0);
+    useLayoutEffect(() => {
+        if (!isFlex)
+            return;
+        const el = boxRef.current;
+        if (el === null)
+            return;
+        const measure = () => setMeasured((prev) => {
+            const next = Math.round(el.getBoundingClientRect().height);
+            // Latch the last non-zero height — a hidden row (display: none
+            // ancestor) is not a resized one, and writing 0 through would tear
+            // down its scales. Same rule as the container's width="auto".
+            return next > 0 ? next : prev;
+        });
+        measure();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver(measure);
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, [isFlex]);
+    // A flex row inside a container that doesn't manage height has nothing to
+    // flex into: its box is 0 and stays 0, silently. That is a wiring error the
+    // consumer should hear about now, not a slow start to wait through.
+    const warnedNoHeightRef = useRef(false);
+    useEffect(() => {
+        if (!isDev ||
+            !isFlex ||
+            container.managesHeight ||
+            warnedNoHeightRef.current) {
+            return;
+        }
+        warnedNoHeightRef.current = true;
+        console.warn(`[pond-charts] <ChartRow flex> needs a container that manages height ` +
+            `— give <ChartContainer> a height ({number | 'auto'}). Inside a ` +
+            `container with no height this row's box collapses to 0 and never ` +
+            `paints.`);
+    }, [isFlex, container.managesHeight]);
+    const height = isFlex ? measured : heightProp;
     // Register on mount so the container can mark the first (topmost) row by
     // mount order — the shared cursor-time chip renders there only.
     const rowKey = useSlotKey();
@@ -165,6 +232,33 @@ export function ChartRow({ height, cursor, children }) {
     // min/max or series change silently rebind axes / reorder the z-stack.)
     const [axes, setAxes] = useState(() => new Map());
     const [layers, setLayers] = useState(() => new Map());
+    // Per-axis pixel zoom — a drag on one gutter (see `RowFrame.axisTransforms`).
+    // Empty until an axis is actually grabbed, so a chart with no axis gestures
+    // carries no extra state and the identity branch below skips the work.
+    // Filled by the scale memo below (see `baseYScales` on the frame).
+    const baseRef = useRef(new Map());
+    const [axisTransforms, setAxisTransforms] = useState(() => new Map());
+    const applyAxisTransform = useCallback((id, next) => {
+        setAxisTransforms((prev) => {
+            const cur = prev.get(id);
+            if (cur !== undefined && cur.k === next.k && cur.ty === next.ty) {
+                return prev; // no-op: don't re-render (a wheel notch at a clamp)
+            }
+            const map = new Map(prev);
+            // Identity is the absence of a transform, not an entry recording one —
+            // so the reset genuinely returns the axis to the un-grabbed state and
+            // the scale memo's fast path applies again.
+            if (next.k === 1 && next.ty === 0) {
+                if (cur === undefined)
+                    return prev;
+                map.delete(id);
+            }
+            else {
+                map.set(id, next);
+            }
+            return map;
+        });
+    }, []);
     // Registration is idempotent under value-equality: a `<YAxis>` re-fires its
     // register effect whenever its `spec` memo yields a fresh object — which an
     // inline `ticks={[]}` / `format` or a re-rendered parent does every render. If
@@ -234,6 +328,7 @@ export function ChartRow({ height, cursor, children }) {
                 format: undefined,
                 tickValues: undefined,
                 tickCount: undefined,
+                color: undefined,
                 index: 0,
             },
         ], [realAxes]);
@@ -278,6 +373,7 @@ export function ChartRow({ height, cursor, children }) {
     const { k: yk, ty: yty } = container.yTransform;
     const yScales = useMemo(() => {
         const map = new Map();
+        const bases = new Map();
         for (const ax of effectiveAxes) {
             const extents = needsExtents(ax)
                 ? layerList
@@ -315,14 +411,43 @@ export function ChartRow({ height, cursor, children }) {
             // each other in the first cut. Narrowing the domain means ticks, padding
             // and every downstream reader see an ordinary axis over the visible
             // window, and none of them need to know a transform exists.
-            if (yk !== 1 || yty !== 0) {
-                const at = (px) => +s.invert((px - yty) / yk);
+            //
+            // The **per-axis** transform (an axis-gutter drag) is applied the same
+            // way, immediately after — so a doubly-transformed axis is still just an
+            // ordinary axis over the doubly-narrowed window. Sequential rather than
+            // pre-composed on purpose: each step inverts through the scale it is
+            // actually narrowing, which is what keeps it correct on a log / symlog
+            // axis, where pixel→value is not affine and two composed `k`s would not
+            // land where two applications do.
+            const narrow = (k, ty) => {
+                const at = (px) => +s.invert((px - ty) / k);
                 s.domain([at(height), at(topHeader)]);
+            };
+            // Snapshot before either transform: `baseYScales` is the domain the axis
+            // RESOLVED to (bounds + pad + nice), which is the space a controlled
+            // consumer's `min`/`max` live in. Reading the transformed scale instead and
+            // handing those values back re-applies the transform on top of them.
+            bases.set(ax.id, s.copy());
+            if (yk !== 1 || yty !== 0)
+                narrow(yk, yty);
+            const own = axisTransforms.get(ax.id);
+            if (own !== undefined && (own.k !== 1 || own.ty !== 0)) {
+                narrow(own.k, own.ty);
             }
             map.set(ax.id, s);
         }
+        baseRef.current = bases;
         return map;
-    }, [effectiveAxes, layerList, height, defaultAxisId, topHeader, yk, yty]);
+    }, [
+        effectiveAxes,
+        layerList,
+        height,
+        defaultAxisId,
+        topHeader,
+        yk,
+        yty,
+        axisTransforms,
+    ]);
     // 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:
@@ -451,6 +576,53 @@ export function ChartRow({ height, cursor, children }) {
             map.set(ax.id, ax.side);
         return map;
     }, [effectiveAxes]);
+    // How far out in its gutter each axis sits: the px from the plot's edge to the
+    // axis's inner edge, walking each side plot-outward and accumulating the
+    // *reserved* slot widths (what the axis boxes actually render at, so the
+    // offset lands on the axis and not between two of them). Side alone would put
+    // every pill on the innermost axis — the wrong scale as soon as a side carries
+    // two (see RowFrame.axisOffsets). Right axes are authored inner→outer, left
+    // axes outer→inner, so the left list walks in reverse.
+    //
+    // Resolved per **instance** first, then collapsed to ids by the same
+    // last-declared-wins rule `axisSides` uses — so for a mirrored id (one scale
+    // registered on both sides, or a duplicate) the side and the offset always
+    // come from the *same* axis. A different rule per map (say, keeping the
+    // smallest offset) can pair one instance's side with another's offset, which
+    // is the very "pill on an axis that didn't measure it" this fixes.
+    const axisOffsets = useMemo(() => {
+        const byInstance = new Map();
+        const walk = (side) => {
+            const inward = realEntries.filter(([, spec]) => spec.side === side);
+            if (side === 'left')
+                inward.reverse();
+            let offset = 0;
+            for (const [key, spec] of inward) {
+                byInstance.set(key, offset);
+                offset += axisSlots.get(key) ?? spec.width;
+            }
+        };
+        walk('right');
+        walk('left');
+        // realEntries is index-sorted, the order effectiveAxes (and so axisSides)
+        // walks — hence the same winner on a repeated id.
+        const map = new Map();
+        for (const [key, spec] of realEntries) {
+            map.set(spec.id, byInstance.get(key) ?? 0);
+        }
+        return map;
+    }, [realEntries, axisSlots]);
+    // Each axis's own ink (`<YAxis color>`) — the axis-edge pill that lands on an
+    // axis wears its colour, so with several axes the number says which scale it
+    // is on. Axes that set no colour are absent (the pill falls back to theme).
+    const axisColors = useMemo(() => {
+        const map = new Map();
+        for (const ax of effectiveAxes) {
+            if (ax.color !== undefined)
+                map.set(ax.id, ax.color);
+        }
+        return map;
+    }, [effectiveAxes]);
     const frame = useMemo(() => ({
         height,
         topInset: topHeader,
@@ -458,10 +630,15 @@ export function ChartRow({ height, cursor, children }) {
         isFirstRow,
         rowKey,
         yScales,
+        baseYScales: baseRef.current,
+        axisTransforms,
+        applyAxisTransform,
         formats,
         tickValues,
         tickCounts,
         axisSides,
+        axisOffsets,
+        axisColors,
         defaultAxisId,
         axisSlots,
         registerAxis,
@@ -476,10 +653,14 @@ export function ChartRow({ height, cursor, children }) {
         isFirstRow,
         rowKey,
         yScales,
+        axisTransforms,
+        applyAxisTransform,
         formats,
         tickValues,
         tickCounts,
         axisSides,
+        axisOffsets,
+        axisColors,
         defaultAxisId,
         axisSlots,
         registerAxis,
@@ -556,11 +737,17 @@ export function ChartRow({ height, cursor, children }) {
             "wrap the row's <Layers>, leaving each <YAxis> a direct child of the " +
             '<ChartRow>.');
     }, [axisInsideWrapper]);
-    return (_jsxs(RowContext.Provider, { value: frame, children: [cursor !== undefined && (_jsx(LegacyCursor, { mode: cursor, showTime: container.cursorTime, snap: container.crosshairSnap })), _jsxs("div", { style: {
+    return (_jsxs(RowContext.Provider, { value: frame, children: [cursor !== undefined && (_jsx(LegacyCursor, { mode: cursor, showTime: container.cursorTime, snap: container.crosshairSnap })), _jsxs("div", { ref: boxRef, style: {
                     display: 'flex',
                     flexDirection: 'row',
                     width: `${container.width}px`,
-                    height: `${height}px`,
+                    // Fixed rows keep their pixels; a flex row is sized by the
+                    // container's column layout and reads the result back
+                    // ([PND-HEIGHT]). `minHeight: 0` is what lets it actually shrink —
+                    // a flex child's default min-height is its content.
+                    ...(isFlex
+                        ? { flex: `${flexGrow} 1 0%`, minHeight: 0 }
+                        : { height: `${height}px` }),
                 }, children: [leftPad > 0 && _jsx("div", { style: { flex: `0 0 ${leftPad}px` } }), leftAxisEls, plotEls, rightAxisEls, rightPad > 0 && _jsx("div", { style: { flex: `0 0 ${rightPad}px` } })] })] }));
 }
 //# sourceMappingURL=ChartRow.js.map

package/dist/Layers.js

@@ -207,7 +207,7 @@ export function Layers({ children }) {
     }), [row.registerLayer, row.unregisterLayer]);
     const background = container.theme.background;
     const { grid: gridColor, gridDash } = container.theme.axis;
-    const { layers, yScales, formats, defaultAxisId, tickValues, tickCounts, axisSides, } = row;
+    const { layers, yScales, formats, defaultAxisId, tickValues, tickCounts, axisSides, axisOffsets, axisColors, } = row;
     // x geometry is shared and lives on the container (uniform across rows), and
     // so is the x tick count — vertical gridlines must sit under the `<XAxis>`
     // labels, which pass the same `xTickCount` to the same scale.
@@ -516,14 +516,20 @@ export function Layers({ children }) {
             // The chip uses this layer's axis formatter, so a readout value reads
             // exactly as the axis labels it.
             const fmt = formats.get(axisId) ?? String;
-            // Which gutter the crosshair value pill hugs (the axis's own side).
+            // Where the crosshair value pill lands, and in what ink: this axis's own
+            // side, its offset out into that gutter (so the pill sits on the axis that
+            // measured the value, not the innermost one), and its `<YAxis color>`.
             const side = axisSides.get(axisId) ?? 'left';
+            const axisOffset = axisOffsets.get(axisId) ?? 0;
+            const axisColor = axisColors.get(axisId);
             for (const s of entry.layer.sampleAt(cursorTime)) {
                 out.push({
                     px: xScale(s.x),
                     py: yScale(s.value),
                     axisId,
                     side,
+                    axisOffset,
+                    axisColor,
                     formatted: fmt(s.value),
                     color: s.color,
                     label: s.label,
@@ -538,6 +544,8 @@ export function Layers({ children }) {
         yScales,
         formats,
         axisSides,
+        axisOffsets,
+        axisColors,
         xScale,
         defaultAxisId,
     ]);
@@ -1539,6 +1547,10 @@ export function Layers({ children }) {
             py: cursor.cursorY,
             formatted: fmt(ys.invert(cursor.cursorY)),
             side: axisSides.get(defaultAxisId) ?? 'left',
+            // The free reticle reads the row's *default* axis, so its pill belongs on
+            // that axis — at its offset, in its ink — like a snapped sample's.
+            axisOffset: axisOffsets.get(defaultAxisId) ?? 0,
+            axisColor: axisColors.get(defaultAxisId),
         };
     }, [
         wantsPointer,
@@ -1548,6 +1560,8 @@ export function Layers({ children }) {
         yScales,
         formats,
         axisSides,
+        axisOffsets,
+        axisColors,
         defaultAxisId,
     ]);
     // The in-plot cursor time, readout-formatted — the `showTime` presets' chip

package/dist/XAxis.d.ts

@@ -133,6 +133,12 @@ export interface XAxisProps {
  * numbers, with no axis-type prop here; the kind follows the data.
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
+ *
+ * **Gestures.** With `<ChartContainer axisPanZoom="x">` (or `"xy"`) the strip is a
+ * second handle on the canvas gesture: it **pans on drag** and **zooms on
+ * wheel**, with double-click returning to the declared `range`. Same maths as the
+ * plot's own drag, including `bounds` / `minDuration` and the trading calendar.
+ * A category axis has no continuous domain and stays inert.
  */
 export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, onMouseEvent, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/XAxis.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useContext } from 'react';
+import { Fragment, useContext, useRef } from 'react';
 import { scaleLinear } from 'd3-scale';
 import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext, CursorContext, } from './context.js';
@@ -8,6 +8,8 @@ import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 import { axisMouseProps, axisPointerPx, } from './axis-events.js';
+import { useAxisGestures } from './use-axis-gestures.js';
+import { panRange, panRangeTrading, zoomRange, zoomRangeTrading, } from './viewport.js';
 /** Tick strip height (mark + value label) in CSS px. */
 const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
@@ -157,6 +159,12 @@ export function thinCategoryLabels(ticks, slot, plotWidth, fontSize, fontFamily)
  * numbers, with no axis-type prop here; the kind follows the data.
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
+ *
+ * **Gestures.** With `<ChartContainer axisPanZoom="x">` (or `"xy"`) the strip is a
+ * second handle on the canvas gesture: it **pans on drag** and **zooms on
+ * wheel**, with double-click returning to the declared `range`. Same maths as the
+ * plot's own drag, including `bounds` / `minDuration` and the trading calendar.
+ * A category axis has no continuous domain and stays inert.
  */
 export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', onMouseEvent, } = {}) {
     const container = useContext(ContainerContext);
@@ -417,14 +425,84 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // scale — no gutter arithmetic. The label reads the same channel a cursor
     // pill does: the band scale's category name on a category axis (a d3 number
     // format can't name one), this axis's readout format everywhere else.
+    // The view the current pan started from — see `onDragStart`.
+    const panStartRef = useRef(null);
+    // Drag pans and wheel zooms the shared x view, double-click returns to the
+    // declared range. Enabled by the container's own `panZoom` zoom-x degree of
+    // freedom — a chart that never opted in captures nothing here.
+    //
+    // A **category** axis has no continuous domain to zoom, exactly as for the
+    // plot's gesture (`Layers`' wheel makes the same exclusion), so the strip
+    // stays inert there rather than snapping between slots.
+    const gestures = useAxisGestures({
+        axis: 'x',
+        // Gated on `<ChartContainer axisPanZoom>` — the axis opt-in — and NOT on the
+        // plot's `panZoom`: inheriting that would hand every already-interactive
+        // chart gestures its author never asked for. Once opted in the strip is the
+        // canvas gesture (drag pans, wheel zooms). A category axis has no continuous
+        // domain for either.
+        drag: container.axisPanZoomX && xKind !== 'category' ? 'pan' : 'none',
+        wheel: container.axisPanZoomX && xKind !== 'category',
+        // Snapshot the view at press: the pan is re-derived from it on every move
+        // (the plot's own approach), so a long drag can't accumulate rounding, and
+        // `roundRange`'s ms snap can't ratchet the span.
+        onDragStart: () => {
+            panStartRef.current = [container.timeRange[0], container.timeRange[1]];
+        },
+        onPan: (totalDeltaPx) => {
+            const start = panStartRef.current;
+            if (start === null)
+                return;
+            // Dragging right moves the view EARLIER — the content follows the pointer,
+            // the sign the plot's drag uses.
+            if (container.discontinuities) {
+                // Trading-time axis: pan by an equal amount of *trading* time so the
+                // drag feels uniform across collapsed gaps (a raw-ms shift jumps).
+                const fraction = plotWidth > 0 ? -totalDeltaPx / plotWidth : 0;
+                container.applyRange(panRangeTrading(start, fraction, container.discontinuities));
+                return;
+            }
+            const span = start[1] - start[0];
+            const dt = plotWidth > 0 ? -totalDeltaPx * (span / plotWidth) : 0;
+            container.applyRange(panRange(start, dt, { log: container.xIsLog, snap: xKind === 'time' }));
+        },
+        onZoom: (factor, pivotPx) => {
+            const pivot = +xScale.invert(pivotPx);
+            // The same two-branch zoom the plot uses, so an axis drag and a plot
+            // wheel move the view by identical maths — including `minDuration` as the
+            // zoom-in floor and, on a trading axis, a floor in *trading* ms.
+            // `applyRange` then applies `bounds` for both.
+            container.applyRange(container.discontinuities
+                ? zoomRangeTrading(container.timeRange, pivot, factor, container.discontinuities, container.minDuration)
+                : zoomRange(container.timeRange, pivot, factor, container.minDuration, {
+                    log: container.xIsLog,
+                    snap: xKind === 'time',
+                }));
+        },
+        onReset: () => container.applyRange(container.seedRange),
+    });
     const mouse = axisMouseProps(onMouseEvent, 'x', undefined, (event) => {
+        // A zoom drag ends with a trailing `click` on the strip, which would report
+        // as "clicked the axis at the value I released on" — a value the user never
+        // aimed at. Swallow exactly that one report; every other event still flows.
+        if (event.type === 'click' && gestures.consumeDrag())
+            return null;
         const value = +xScale.invert(axisPointerPx(event, 'x', [0, plotWidth]));
         return {
             value,
             label: xKind === 'category' ? fmt(value) : readoutFmt(value),
         };
     });
-    return (_jsxs("div", { "data-axis": "x", ...mouse, style: {
+    return (_jsxs("div", { "data-axis": "x", ref: gestures.ref, ...gestures.props, ...mouse, 
+        // Both spreads carry an `onDoubleClick` — the gesture's reset and the
+        // consumer's report — and a spread silently keeps the last one. Compose
+        // them, reporting *before* the reset so the payload describes the view the
+        // user actually double-clicked in.
+        onDoubleClick: (e) => {
+            mouse.onDoubleClick?.(e);
+            gestures.props.onDoubleClick?.();
+        }, style: {
+            ...gestures.style,
             position: 'relative',
             marginLeft: `${leftGutter}px`,
             width: `${plotWidth}px`,

package/dist/YAxis.d.ts

@@ -195,7 +195,14 @@ export interface YAxisProps {
      * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
      * convention of colouring each y axis to match its series (`color`
      * matching the layer's) — busy, but standard. Omit for the theme's axis
-     * colours. Presentation-only: it never re-registers the axis.
+     * colours.
+     *
+     * **Also worn by the axis-edge chrome that lands on this axis** — a
+     * `<CrosshairCursor>`'s value pill takes it when the reticle reads a series
+     * scaled here, so with several axes the pill says *which* scale the number is
+     * on (the ChartIQ price-tag convention). That is why it rides on the
+     * registered spec: the pill is drawn by the row's cursor overlay, not by this
+     * component, so a colour it never registered could not reach it.
      */
     color?: string;
     /**
@@ -209,8 +216,57 @@ export interface YAxisProps {
      * menu, down/up, move, enter, leave — so switch on `event.type`. Nothing is
      * attached when the prop is omitted, so the move events cost nothing unless
      * you ask for them. A `hide`den axis draws no gutter and so fires nothing.
+     *
+     * A gutter that also zooms (see the component docs) still reports every event
+     * here, minus the trailing `click` a zoom drag would otherwise synthesize.
      */
     onMouseEvent?: AxisMouseHandler;
+    /**
+     * A gutter gesture scaled this axis — **the "auto vs manual" hand-off.**
+     * Fires with the `[min, max]` **bounds** the gesture arrived at, and with
+     * `null` when the axis is released back to auto-fit (double-click).
+     *
+     * Named for bounds rather than the domain because that is what it reports: with
+     * a `pad` set, the visible domain is these bounds *plus* the padding, and it is
+     * the bounds you hand back as `min`/`max`.
+     *
+     * The common shape this exists for: an auto-fitting y axis on a chart whose x
+     * is panned and zoomed. The moment the user scrolls or drags the y gutter they
+     * have overridden the fit, and a UI usually wants to *say* so — show the
+     * resulting min/max, mark the scale "manual", and offer a toggle back to auto
+     * (which is the same thing double-clicking the gutter does).
+     *
+     * ```tsx
+     * const [scale, setScale] = useState<[number, number] | null>(null); // null = auto
+     * <YAxis
+     *   id="price"
+     *   {...(scale ? { min: scale[0], max: scale[1] } : {})}
+     *   onBoundsChange={setScale}
+     * />
+     * ```
+     *
+     * **Providing it makes the axis controlled**, exactly as `onTimeRangeChange`
+     * does for the x view: the gesture then only *reports*, and what the axis draws
+     * is whatever `min`/`max` you feed back. Omit it and the axis holds the zoom
+     * itself (an internal per-axis transform) — which is the standalone behaviour,
+     * and why a chart with no scale UI needs no wiring at all.
+     *
+     * The reported pair is in data units, ready to hand straight back as
+     * `min`/`max`.
+     *
+     * **`scale="symlog"` is approximate on this path, by construction.**
+     * {@link linearWindow} is a fraction of the *domain*, so bounds fed back
+     * re-derive the knee and reshape the curve — the grabbed pixel cannot be held
+     * on a curve that moves with the bounds. (It is the same fact that makes
+     * `linearWindow` deliberately *not* recompute under a 2-D gesture.) The zoom is
+     * still monotone and well-behaved; if you need the pixel held exactly on a
+     * symlog axis, leave this callback off and let the axis hold the zoom itself,
+     * where the knee stays anchored to the resolved domain. With an active plot-level y zoom (`panZoom="panZoomY"`/`"panZoomXY"`)
+     * the two **compose**: the bounds are the axis's own, and the plot transform
+     * still narrows what is drawn on top of them. On a `log` axis it stays positive (the zoom is done in log
+     * space), so it is always a domain the axis can actually draw.
+     */
+    onBoundsChange?: (bounds: readonly [number, number] | null) => void;
     /**
      * @internal Declaration position among the row's children, injected by
      * `ChartRow` so the first-declared axis stays the default. Do not set.
@@ -224,6 +280,14 @@ export interface YAxisProps {
  * computes this axis's scale from the charts linked to it; the gutter then draws
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
+ *
+ * **Gestures.** With `<ChartContainer axisPanZoom="y">` (or `"xy"`) the gutter is
+ * grabbable: drag or wheel it to scale **this axis only**
+ * — a sibling axis on the other side, and every other row, hold still — and
+ * double-click to release it back to its fit. That per-axis scaling is what the
+ * plot's vertical gesture deliberately cannot do; see
+ * {@link RowFrame.axisTransforms}. Report it to a scale UI with
+ * {@link YAxisProps.onBoundsChange}.
  */
-export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, onMouseEvent, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, onMouseEvent, onBoundsChange, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map