@pond-ts/charts 0.62.0 → 0.63.0

package/dist/YAxis.js

@@ -2,9 +2,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo } from 'react';
 import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
+import { unpadDomain } from './domain.js';
 import { useSlotKey } from './use-slot-key.js';
 import { tickValues } from './yticks.js';
 import { axisMouseProps, axisPointerPx, } from './axis-events.js';
+import { useAxisGestures } from './use-axis-gestures.js';
+/**
+ * Clamp on a gutter drag's own zoom factor. Unlike the container's uniform
+ * transform (floored at `k ≥ 1` so a plot gesture can't zoom every axis out into
+ * blank canvas) an axis you deliberately grabbed may squash as well as stretch —
+ * `k < 1` widens the domain, which costs nothing. The bounds exist only so a
+ * flick of the wheel can't strand the axis at a factor no further gesture can
+ * recover from.
+ */
+const MIN_AXIS_K = 0.02;
+const MAX_AXIS_K = 50;
+/** The un-grabbed transform — also what clears an axis's entry (see `ChartRow`). */
+const IDENTITY_TRANSFORM = { k: 1, ty: 0 };
 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
@@ -17,8 +31,16 @@ const DEFAULT_TICK_COUNT = 5;
  * 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 function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, onMouseEvent, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, onMouseEvent, onBoundsChange, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -44,6 +66,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
         format,
         tickValues: ticks?.map((t) => t.at),
         tickCount,
+        color,
         index,
     }), [
         id,
@@ -59,6 +82,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
         format,
         ticks,
         tickCount,
+        color,
         index,
     ]);
     // A stable per-instance slot (see useSlotKey) keeps this axis in a fixed
@@ -66,13 +90,116 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
     // re-appending (which would move the first axis behind a later one and
     // silently rebind the row's default-axis charts).
     const slot = useSlotKey();
-    const { registerAxis, unregisterAxis } = row;
+    const { registerAxis, unregisterAxis, applyAxisTransform } = row;
     // Unregister on unmount only (deps are stable, so cleanup never runs early).
-    useEffect(() => () => unregisterAxis(slot), [unregisterAxis, slot]);
+    useEffect(() => () => {
+        unregisterAxis(slot);
+        // Drop any gutter zoom with the axis. The row keys transforms by axis id
+        // (as it keys scales), so an entry left behind would be inherited by a
+        // later axis that happens to reuse the id.
+        applyAxisTransform(id, IDENTITY_TRANSFORM);
+    }, [unregisterAxis, slot, applyAxisTransform, id]);
     // Register on mount + update in place on every spec change — no reorder.
     useEffect(() => {
         registerAxis(slot, spec);
     }, [registerAxis, slot, spec]);
+    // Drag / wheel to zoom **this** axis, double-click to release it back to the
+    // row's own fit. Enabled by the container's `panZoom` zoom-y degree of freedom.
+    // The gesture writes this axis's entry in `row.axisTransforms`, so only the
+    // gutter you grabbed rescales — the sibling axis, and every other row, hold
+    // still (see `RowFrame.axisTransforms` for why that needs its own transform).
+    const gestures = useAxisGestures({
+        axis: 'y',
+        // Gated on `<ChartContainer axisPanZoom>` (its `'y'` / `'xy'` values) — the
+        // axis opt-in, deliberately independent of the plot's `panZoom`. That is what
+        // lets the canonical setup work — an auto-fitting y on a chart whose *x* is
+        // panned and zoomed — without either inheriting gestures silently or opting
+        // the plot into vertical drags (a different feature: the uniform 2-D
+        // transform a scatter or heat map wants).
+        drag: container.axisPanZoomY ? 'zoom' : 'none',
+        wheel: container.axisPanZoomY,
+        onZoom: (factor, pivotPx) => {
+            // Read the scale at gesture time, not from the render that built this
+            // closure — a wheel notch mid-stream must compose onto what is drawn now.
+            if (onBoundsChange !== undefined) {
+                // **Controlled**: report the bounds the gesture reached and draw nothing
+                // ourselves — `min`/`max` coming back is what moves the axis.
+                //
+                // Computed by inverting through the scale in **pixel** space, not by
+                // affine arithmetic on its domain. That is what makes it correct on every
+                // scale kind: `log` and `symlog` are not affine in value space, so
+                // zooming their domain numerically drifts the grabbed pixel (visibly, on
+                // symlog, whose knee is re-derived from the domain each time) and can
+                // overflow to `[0, Infinity]` on a hard log zoom-out.
+                //
+                // Read from `baseYScales` — the axis's *resolved* scale, before the
+                // container's uniform `yTransform` and this axis's own transform. The
+                // consumer's `min`/`max` live in that space, so reporting a value read
+                // off the visible scale would have the transforms applied to it twice.
+                const base = row.baseYScales.get(id);
+                if (base === undefined)
+                    return;
+                const [r0, r1] = base.range();
+                const lo = Math.min(r0, r1);
+                const hi = Math.max(r0, r1);
+                // Clamp into the scale's own range, not the gutter box: a
+                // `labelPlacement="top"` row reserves a header, so a press up there would
+                // otherwise pivot about a value the axis never draws.
+                const pivot = Math.max(lo, Math.min(hi, pivotPx));
+                // `factor` scales the visible span, so the pixel window scales by its
+                // reciprocal about the pivot.
+                const at = (px) => +base.invert(pivot + (px - pivot) * factor);
+                const next = [at(r0), at(r1)];
+                // Orientation is preserved rather than required: `resolveYDomain` keeps
+                // an explicit `[max, min]` as a deliberate axis flip, and rejecting
+                // descending results would have made adding this callback silently
+                // disable the gesture on a flipped axis.
+                if (!Number.isFinite(next[0]) || !Number.isFinite(next[1]))
+                    return;
+                if (next[0] === next[1])
+                    return;
+                // `pad` is applied last and to explicit bounds too, so the resolved
+                // domain already includes it; handing that back would re-pad it and
+                // inflate the axis by `1 + 2·pad` per notch (see `unpadDomain`).
+                onBoundsChange(unpadDomain(next, pad, scale));
+                return;
+            }
+            // **Uncontrolled**: hold the zoom ourselves as this axis's own pixel
+            // transform. Read at gesture time for the same reason the scale is: two
+            // wheel notches inside one frame both see the render-scope value, so the
+            // second would compose onto the first's *input* and the notch be lost.
+            const own = row.axisTransforms.get(id) ?? IDENTITY_TRANSFORM;
+            // Same range clamp as the controlled path: keep the pivot on the scale.
+            const visible = row.yScales.get(id);
+            const vr = (visible?.range() ?? [0, 0]);
+            const pivot = Math.max(Math.min(vr[0], vr[1]), Math.min(Math.max(vr[0], vr[1]), pivotPx));
+            // `factor` scales the domain span, so its reciprocal is the pixel-space
+            // zoom — the relationship the plot's wheel handler uses.
+            const z = 1 / factor;
+            const nk = Math.min(MAX_AXIS_K, Math.max(MIN_AXIS_K, own.k * z));
+            // Re-derive the zoom the clamp actually allowed, so a gesture held at a
+            // limit stops moving the pivot too (rather than sliding the axis).
+            const zEff = own.k === 0 ? 1 : nk / own.k;
+            applyAxisTransform(id, {
+                k: nk,
+                // Zoom about the grabbed pixel: p' = pivot + (p − pivot)·z, expanded
+                // through the existing transform p = ty + k·base. No pan clamp here —
+                // the plot's exists to stop zoomed content sliding off the canvas, and
+                // this transform is applied by narrowing the domain, so there is no
+                // canvas to leave.
+                ty: pivot * (1 - zEff) + own.ty * zEff,
+            });
+        },
+        // Back to auto: `null` tells a controlled consumer to drop its override (the
+        // same thing their "manual → auto" toggle does), and an uncontrolled axis
+        // drops its own transform.
+        onReset: () => {
+            if (onBoundsChange !== undefined)
+                onBoundsChange(null);
+            else
+                applyAxisTransform(id, IDENTITY_TRANSFORM);
+        },
+    });
     // `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
@@ -133,6 +260,9 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
     // and the event is dropped. A categorical row labels by slot, matching its
     // ticks; every other row reads this axis's own tick format.
     const mouse = axisMouseProps(onMouseEvent, 'y', id, (event) => {
+        // See the x strip's: a zoom drag's trailing click is not a click on a value.
+        if (event.type === 'click' && gestures.consumeDrag())
+            return null;
         if (!yScale)
             return null;
         // Clamp on the **scale's** range, not the box: a row with a
@@ -151,7 +281,14 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
                 : fmt(value),
         };
     });
-    return (_jsx("div", { "data-axis": "y", "data-axis-id": id, ...mouse, style: {
+    return (_jsx("div", { "data-axis": "y", "data-axis-id": id, ref: gestures.ref, ...gestures.props, ...mouse, 
+        // See the x strip's: two `onDoubleClick`s meet here (the reset and the
+        // consumer's report) and a spread would silently drop one.
+        onDoubleClick: (e) => {
+            mouse.onDoubleClick?.(e);
+            gestures.props.onDoubleClick?.();
+        }, style: {
+            ...gestures.style,
             flex: `0 0 ${slotWidth}px`,
             display: 'flex',
             justifyContent: side === 'left' ? 'flex-end' : 'flex-start',

package/dist/annotations.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
 import { ContainerContext, RowContext, } from './context.js';
-import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
+import { flagChipStyle, flagChipX, axisPillX, axisPillStyle, axisPillConnector, } from './chip.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
  * User-authored **annotations** — marks you place *on* a chart, in a register
@@ -569,12 +569,19 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
                 }, children: text })), indicator &&
                 (() => {
                     const half = container.theme.font.size / 2 + 1;
-                    return (_jsx("div", { style: {
-                            ...axisPillStyle(container.theme, ann.color),
-                            top: `${Math.max(half, Math.min(row.height - half, y))}px`,
-                            transform: 'translateY(-50%)',
-                            ...axisPillX(row.axisSides.get(axisId) ?? 'left', w),
-                        }, children: fmt ? fmt(value) : String(value) }));
+                    const side = row.axisSides.get(axisId) ?? 'left';
+                    const offset = row.axisOffsets.get(axisId) ?? 0;
+                    const top = `${Math.max(half, Math.min(row.height - half, y))}px`;
+                    return (_jsxs(_Fragment, { children: [offset > 0 && (_jsx("div", { style: {
+                                    ...axisPillConnector(side, w, offset, ann.color),
+                                    top,
+                                    transform: 'translateY(-50%)',
+                                } })), _jsx("div", { style: {
+                                    ...axisPillStyle(container.theme, ann.color),
+                                    top,
+                                    transform: 'translateY(-50%)',
+                                    ...axisPillX(side, w, offset),
+                                }, children: fmt ? fmt(value) : String(value) })] }));
                 })()] }));
 }
 /**

package/dist/chip.d.ts

@@ -41,14 +41,57 @@ export declare function axisPillStyle(theme: ChartTheme, color: string): CSSProp
  */
 export declare function pointerStyle(side: 'left' | 'right', color: string): CSSProperties;
 /**
- * CSS placing a value pill **on the axis gutter** at `side`: anchor its inner
- * edge at the plot boundary (`plotWidth`) and let it overflow outward across the
- * reserved gutter (the plot div doesn't clip), lifted with `zIndex` above the
- * sibling axis column (rendered later in the row) so it covers the tick behind
- * it. Shared by {@link YAxisIndicator}'s `placement='axis'` and the crosshair
- * cursor's per-series value pills, so both sit identically on the axis.
+ * CSS placing a value pill **on an axis gutter** at `side`: anchor its inner
+ * edge at that axis's inner edge — the plot boundary (`plotWidth`) plus the
+ * axis's own `offset` out into the gutter — and let it overflow outward (the
+ * plot div doesn't clip), lifted with `zIndex` above the sibling axis columns
+ * (rendered later in the row) so it covers the tick behind it. The one placement
+ * every on-axis pill goes through — the crosshair cursor's value pill, a
+ * `<Baseline indicator>`, and {@link YAxisIndicator} — so they cannot drift
+ * apart.
+ *
+ * `offset` is `0` for the innermost axis on a side (the single-axis case, and the
+ * behaviour before it existed) and the reserved widths of the axes nearer the
+ * plot for one further out — {@link RowFrame.axisOffsets}. Passing it is what
+ * puts the pill on the axis whose scale produced the number, rather than on
+ * whichever axis happens to sit against the plot. **`YAxisIndicator` does not
+ * pass it** and so still lands innermost: it takes an explicit `side` beside its
+ * `axis`, and what an offset should mean when those two disagree is unsettled
+ * (see `[PND-XHAIRAXIS]` in the charts plan).
+ *
+ * A pill is deliberately unclipped, so a long formatted value can overflow past
+ * the gutter it sits in — further out for an outer-axis pill, which has only its
+ * own column left before the container's edge. Sized-to-content and unclipped
+ * beats truncating a number, but a very wide readout on a narrow outer axis will
+ * spill outside the chart box.
+ */
+export declare function axisPillX(side: 'left' | 'right', plotWidth: number, offset?: number): CSSProperties;
+/**
+ * The **connector** for a pill placed further out than the innermost axis: a 1px
+ * bridge from the plot's `side` edge across `offset` px of gutter to the pill's
+ * inner edge, so the in-plot line and its pill read as one object rather than as
+ * a value floating in a gutter two columns away. The y-side twin of the
+ * crosshair's x-axis time connector, which exists for exactly this reason.
+ *
+ * The caller positions it vertically (`top` + a `translateY(-50%)`), at the
+ * **pill's** centre rather than the raw value's — the two agree except where the
+ * pill is clamped inside the row, and a connector attached to the pill is what
+ * sells them as one object.
+ *
+ * In the pill's own colour and above the axis column (`zIndex`, as the pill is),
+ * but at **half opacity** — unlike the x-axis time connector, which is solid.
+ * The difference is what each one crosses: the time connector runs over an empty
+ * strip, while this one runs over *another axis's tick labels* (measured: a
+ * connector at a value whose neighbouring axis has a tick at the same height
+ * overlaps that label's glyphs). Half opacity keeps the labels legible and reads
+ * the bridge as subordinate chrome — the weight the flag cursor's staffs already
+ * use for "this line only connects two things I have drawn".
+ *
+ * Only drawn when `offset > 0`: at offset `0` the pill already touches the plot
+ * edge where the line ends, so a connector would be zero-length ink over a tick
+ * label for nothing.
  */
-export declare function axisPillX(side: 'left' | 'right', plotWidth: number): CSSProperties;
+export declare function axisPillConnector(side: 'left' | 'right', plotWidth: number, offset: number, color: string): CSSProperties;
 /**
  * Horizontal placement for a flag chip beside a vertical pole at plot-x `x`:
  * `FLAG_GAP` to the right, flipping to the left near the right edge so it stays

package/dist/chip.js

@@ -96,17 +96,74 @@ export function pointerStyle(side, color) {
     };
 }
 /**
- * CSS placing a value pill **on the axis gutter** at `side`: anchor its inner
- * edge at the plot boundary (`plotWidth`) and let it overflow outward across the
- * reserved gutter (the plot div doesn't clip), lifted with `zIndex` above the
- * sibling axis column (rendered later in the row) so it covers the tick behind
- * it. Shared by {@link YAxisIndicator}'s `placement='axis'` and the crosshair
- * cursor's per-series value pills, so both sit identically on the axis.
+ * CSS placing a value pill **on an axis gutter** at `side`: anchor its inner
+ * edge at that axis's inner edge — the plot boundary (`plotWidth`) plus the
+ * axis's own `offset` out into the gutter — and let it overflow outward (the
+ * plot div doesn't clip), lifted with `zIndex` above the sibling axis columns
+ * (rendered later in the row) so it covers the tick behind it. The one placement
+ * every on-axis pill goes through — the crosshair cursor's value pill, a
+ * `<Baseline indicator>`, and {@link YAxisIndicator} — so they cannot drift
+ * apart.
+ *
+ * `offset` is `0` for the innermost axis on a side (the single-axis case, and the
+ * behaviour before it existed) and the reserved widths of the axes nearer the
+ * plot for one further out — {@link RowFrame.axisOffsets}. Passing it is what
+ * puts the pill on the axis whose scale produced the number, rather than on
+ * whichever axis happens to sit against the plot. **`YAxisIndicator` does not
+ * pass it** and so still lands innermost: it takes an explicit `side` beside its
+ * `axis`, and what an offset should mean when those two disagree is unsettled
+ * (see `[PND-XHAIRAXIS]` in the charts plan).
+ *
+ * A pill is deliberately unclipped, so a long formatted value can overflow past
+ * the gutter it sits in — further out for an outer-axis pill, which has only its
+ * own column left before the container's edge. Sized-to-content and unclipped
+ * beats truncating a number, but a very wide readout on a narrow outer axis will
+ * spill outside the chart box.
  */
-export function axisPillX(side, plotWidth) {
+export function axisPillX(side, plotWidth, offset = 0) {
+    const inner = plotWidth + offset;
     return side === 'right'
-        ? { left: `${plotWidth}px`, zIndex: 3 }
-        : { right: `${plotWidth}px`, zIndex: 3 };
+        ? { left: `${inner}px`, zIndex: 3 }
+        : { right: `${inner}px`, zIndex: 3 };
+}
+/**
+ * The **connector** for a pill placed further out than the innermost axis: a 1px
+ * bridge from the plot's `side` edge across `offset` px of gutter to the pill's
+ * inner edge, so the in-plot line and its pill read as one object rather than as
+ * a value floating in a gutter two columns away. The y-side twin of the
+ * crosshair's x-axis time connector, which exists for exactly this reason.
+ *
+ * The caller positions it vertically (`top` + a `translateY(-50%)`), at the
+ * **pill's** centre rather than the raw value's — the two agree except where the
+ * pill is clamped inside the row, and a connector attached to the pill is what
+ * sells them as one object.
+ *
+ * In the pill's own colour and above the axis column (`zIndex`, as the pill is),
+ * but at **half opacity** — unlike the x-axis time connector, which is solid.
+ * The difference is what each one crosses: the time connector runs over an empty
+ * strip, while this one runs over *another axis's tick labels* (measured: a
+ * connector at a value whose neighbouring axis has a tick at the same height
+ * overlaps that label's glyphs). Half opacity keeps the labels legible and reads
+ * the bridge as subordinate chrome — the weight the flag cursor's staffs already
+ * use for "this line only connects two things I have drawn".
+ *
+ * Only drawn when `offset > 0`: at offset `0` the pill already touches the plot
+ * edge where the line ends, so a connector would be zero-length ink over a tick
+ * label for nothing.
+ */
+export function axisPillConnector(side, plotWidth, offset, color) {
+    return {
+        position: 'absolute',
+        ...(side === 'right'
+            ? { left: `${plotWidth}px` }
+            : { right: `${plotWidth}px` }),
+        width: `${offset}px`,
+        height: '1px',
+        background: color,
+        opacity: 0.5,
+        pointerEvents: 'none',
+        zIndex: 3,
+    };
 }
 /** Gap (px) between a flag chip and its pole — the cursor staff or an annotation's
  *  line — so the chip floats just beside the pole rather than sitting on it. */

package/dist/context.d.ts

@@ -40,7 +40,27 @@ export interface LabelPlacement {
 export type ChartXScale = ScaleTime<number, number> | ScaleLinear<number, number> | ScaleLogarithmic<number, number> | ScaleSymLog<number, number> | TradingTimeScale | ScaleBand | ElapsedScale;
 export interface ContainerFrame {
     readonly timeRange: readonly [number, number];
+    /**
+     * The **declared** view — the container's `range` prop, normalized — as
+     * against {@link timeRange}, which is where gestures have moved it. The
+     * x-axis strip's double-click reset returns here.
+     *
+     * On a **controlled** chart (one passing `onTimeRangeChange`) the two are the
+     * same object of truth by construction: the consumer owns the view, so `range`
+     * *is* the panned view and there is no declared home to go back to. The reset
+     * is then a no-op, and a consumer who wants one holds their own home range and
+     * wires it through `onMouseEvent` — which is exactly the shape of that job.
+     */
+    readonly seedRange: readonly [number, number];
     readonly width: number;
+    /**
+     * Whether the container is managing vertical layout ([PND-HEIGHT]) — it was
+     * given a `height` (number or `'auto'`), renders as a flex column, and flex
+     * rows have real space to divide. `false` is the classic mode: rows declare
+     * pixel heights and the container's height is their sum. A `<ChartRow
+     * flex>` reads this to warn when mounted somewhere it can never resolve.
+     */
+    readonly managesHeight: boolean;
     readonly theme: ChartTheme;
     /** Plot width in px after the gutters — shared by every row. */
     readonly plotWidth: number;
@@ -427,6 +447,16 @@ export interface ContainerFrame {
      * the **aspect ratio** fixed. The x half stays in domain space, where
      * `bounds`, `minDuration` and the trading-calendar zoom maths live.
      */
+    /**
+     * Whether the **axis strips** take gestures, from `<ChartContainer axisPanZoom>`
+     * — resolved per dimension, and independent of the plot's own
+     * {@link zoomX}/{@link zoomY}. `x` gives the `<XAxis>` strip the canvas
+     * gesture (drag pans, wheel zooms); `y` makes each `<YAxis>` gutter scale its
+     * own axis. Both default to `false`, so a chart that doesn't ask keeps inert
+     * axes however interactive its plot is.
+     */
+    readonly axisPanZoomX: boolean;
+    readonly axisPanZoomY: boolean;
     /** Which axes the gestures own; pan follows zoom's degrees of freedom. */
     readonly zoomX: boolean;
     readonly zoomY: boolean;
@@ -1356,15 +1386,24 @@ export type CursorSnapX = 'none' | 'sample' | 'sequence';
 /**
  * One resolved per-series measurement at the cursor — **finished numbers, not
  * raw materials** (interaction RFC A2.3): the sample's plot pixels, the axis it
- * scales against (id + side, so a pill can hug the right gutter), and its value
- * already formatted by that axis's formatter. A cursor slot draws these; it
- * never sees a scale, a format map, or an axis-side map.
+ * scales against (id + side + gutter offset + colour, so a pill can sit *on
+ * that* axis in *its* ink), and its value already formatted by that axis's
+ * formatter. A cursor slot draws these; it never sees a scale, a format map, or
+ * an axis-side map.
  */
 export interface ResolvedCursorSample {
     readonly px: number;
     readonly py: number;
     readonly axisId: string;
     readonly side: 'left' | 'right';
+    /** Distance in px from the plot's `side` edge to this axis's inner edge —
+     *  `0` for the innermost axis, the reserved widths of the axes between it and
+     *  the plot otherwise ({@link RowFrame.axisOffsets}). What lets an axis-edge
+     *  pill land on the axis that measured the value rather than the innermost. */
+    readonly axisOffset: number;
+    /** This axis's own `<YAxis color>`, or `undefined` for the theme's axis ink
+     *  ({@link RowFrame.axisColors}) — so an axis-edge pill matches its axis. */
+    readonly axisColor: string | undefined;
     readonly formatted: string;
     readonly color: string;
     readonly label: string;
@@ -1406,7 +1445,8 @@ export interface ResolvedCursorFrame {
     readonly flags: readonly ResolvedCursorFlag[];
     /**
      * The **raw pointer**'s y resolved against the row's default axis — position,
-     * formatted value, and axis side — or `null` when this row isn't hovered.
+     * formatted value, and that axis's placement (side + gutter offset + colour,
+     * as on {@link ResolvedCursorSample}) — or `null` when this row isn't hovered.
      * The free (non-snapping) crosshair reads this; it is resolved here because a
      * slot has no `yScale.invert` to do it itself.
      */
@@ -1414,6 +1454,8 @@ export interface ResolvedCursorFrame {
         readonly py: number;
         readonly formatted: string;
         readonly side: 'left' | 'right';
+        readonly axisOffset: number;
+        readonly axisColor: string | undefined;
     } | null;
     /** The range cursor's **band** under the pointer (bucket-snapped via the
      *  declared sequence, else the drag span), as clamped plot pixels; `null`
@@ -1661,6 +1703,11 @@ export interface AxisSpec {
      *  target; `undefined` derives the count from the row height (see
      *  {@link resolveYTickCount}). Ignored when {@link tickValues} is set. */
     readonly tickCount: number | undefined;
+    /** This axis's own ink (`<YAxis color>`), or `undefined` for the theme's.
+     *  Registered — not merely rendered — because the axis-edge chrome the row
+     *  and the cursor draw (the crosshair's value pill) has to match the axis it
+     *  sits on, and only the registry knows every axis. */
+    readonly color: string | undefined;
     /**
      * Declaration position among the row's children, injected by `ChartRow`. The
      * row sorts axes by this, so the **first declared** axis is the default
@@ -1689,6 +1736,52 @@ export interface RowFrame {
      */
     readonly topInset: number;
     readonly yScales: ReadonlyMap<string, YScale>;
+    /**
+     * Each axis's scale **before** any gesture transform — the domain it resolved
+     * to from `min`/`max`/`pad`/auto-fit, which is the space a controlled
+     * consumer's bounds live in.
+     *
+     * {@link yScales} carries the *visible* scales: the uniform
+     * {@link ContainerFrame.yTransform} and the axis's own
+     * {@link axisTransforms} entry have already narrowed them. A gutter gesture
+     * that reported values read off those and had them fed back as `min`/`max`
+     * would have the transforms applied a second time — the visible domain then
+     * diverges from every value the consumer was told.
+     */
+    readonly baseYScales: ReadonlyMap<string, YScale>;
+    /**
+     * **Per-axis** pixel zoom, keyed by axis id — what a drag on that axis's
+     * gutter produces, layered *under* the container's uniform
+     * {@link ContainerFrame.yTransform}. Identity (`{ k: 1, ty: 0 }`) for any axis
+     * nobody has grabbed, which is every axis until one is.
+     *
+     * The uniform transform exists precisely so a *plot* gesture never has to
+     * answer "which of this row's axes does a vertical drag own?" — see
+     * {@link ContainerFrame.yTransform}. Grabbing one gutter answers it by
+     * construction, and this is where that answer lives. Both are applied the same
+     * way (narrowing the domain to the window the transform makes visible), the
+     * uniform one first, so an axis carrying both reads as an ordinary axis over
+     * the doubly-narrowed window and nothing downstream knows either exists.
+     *
+     * Unlike the uniform transform this is **not** floored at `k ≥ 1`: that floor
+     * stops a plot gesture zooming every axis out past its natural fit into blank
+     * canvas, whereas squashing one axis you deliberately grabbed is the point of
+     * the gesture (and costs nothing — a `k < 1` widens the domain rather than
+     * exposing empty plot).
+     */
+    readonly axisTransforms: ReadonlyMap<string, {
+        readonly k: number;
+        readonly ty: number;
+    }>;
+    /**
+     * Set one axis's {@link axisTransforms} entry — the y counterpart of
+     * {@link ContainerFrame.applyRange}. Passing identity clears it (the
+     * double-click reset).
+     */
+    applyAxisTransform(id: string, next: {
+        k: number;
+        ty: number;
+    }): void;
     /** 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. */
@@ -1705,6 +1798,30 @@ export interface RowFrame {
     /** The side each axis sits on, keyed by id — so an axis-edge overlay (the
      *  crosshair value pills) hugs the correct gutter. */
     readonly axisSides: ReadonlyMap<string, 'left' | 'right'>;
+    /**
+     * How far out in its gutter each axis sits, keyed by id: the px distance from
+     * the plot's edge to that axis's **inner** edge — `0` for the innermost axis
+     * on a side, the sum of the reserved widths of the axes between it and the
+     * plot for the ones beyond it (the slots of {@link ContainerFrame.leftSlots} /
+     * `rightSlots` it sits behind).
+     *
+     * The companion to {@link axisSides}: side alone puts an axis-edge pill on the
+     * *innermost* axis of that side, which is the wrong axis whenever a side
+     * carries more than one — the pill then reads as a value on a scale that never
+     * measured it. Together they place it on the axis that did.
+     *
+     * Keyed by id, so a **mirrored** id (one scale registered on both sides, or a
+     * duplicate) resolves to the **last declared** instance — the same winner
+     * {@link axisSides} picks, deliberately, so that side and offset always
+     * describe one axis. Picking them by different rules would pair one
+     * instance's gutter with another's column, which is exactly the mis-placement
+     * this map exists to remove.
+     */
+    readonly axisOffsets: ReadonlyMap<string, number>;
+    /** Each axis's own ink (`<YAxis color>`), keyed by id; an axis that sets none
+     *  is absent. The other half of matching an axis-edge pill to its axis (see
+     *  {@link axisOffsets}) — the pill takes this colour, else the theme's. */
+    readonly axisColors: ReadonlyMap<string, string>;
     /** This row's cursor-mode override, or `undefined` to inherit the container's
      *  default ({@link ContainerFrame.cursor}). */
     readonly cursor: CursorMode | undefined;

package/dist/cursors.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useContext, useEffect, useMemo } from 'react';
 import { ContainerContext, RowContext, } from './context.js';
 import { renderBrushBand } from './brush.js';
-import { flagChipStyle, flagChipX, axisPillStyle, axisPillX } from './chip.js';
+import { flagChipStyle, flagChipX, axisPillStyle, axisPillX, axisPillConnector, } from './chip.js';
 import { useSlotKey } from './use-slot-key.js';
 import { isDev } from './dev.js';
 /**
@@ -188,6 +188,12 @@ function buildFlagCursor(o) {
  * sample nearest the pointer y in the hovered row — or the first sample when
  * nothing is hovered (a pinned tracker shows a reticle in every row); free
  * mode reads the container-resolved raw-pointer measurement.
+ *
+ * It carries the picked sample's **axis placement** (side + gutter offset +
+ * axis ink) as well as its value, because the reticle reads one series and its
+ * pill has to land on *that series' axis*: with two axes on a side, the value
+ * belongs to only one of the two scales, and a pill on the other one is a
+ * number pinned to a ruler that never measured it.
  */
 function crosshairPick(f, snap) {
     if (inBoundsX(f) === null)
@@ -204,7 +210,13 @@ function crosshairPick(f, snap) {
             ? f.samples[0]
             : null;
     return pick
-        ? { py: pick.py, formatted: pick.formatted, side: pick.side }
+        ? {
+            py: pick.py,
+            formatted: pick.formatted,
+            side: pick.side,
+            axisOffset: pick.axisOffset,
+            axisColor: pick.axisColor,
+        }
         : null;
 }
 /** `cursor="crosshair"` as a spec: the dashed reticle (renderPlot), the axis
@@ -223,17 +235,30 @@ function buildCrosshairCursor(o) {
                 const reticle = crosshairPick(f, o.snap);
                 return (_jsxs(_Fragment, { children: [_jsx("line", { x1: Math.round(x), y1: 0, x2: Math.round(x), y2: f.rowHeight, stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), reticle && (_jsxs(_Fragment, { children: [_jsx("line", { x1: 0, y1: Math.round(reticle.py), x2: f.plotWidth, y2: Math.round(reticle.py), stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), _jsx("circle", { cx: x, cy: reticle.py, r: 3, fill: ink, stroke: background, strokeWidth: background ? 1 : 0 })] }))] }));
             },
+            // The value pill goes **on the reticle's own axis**: its side, its offset
+            // out into that gutter (so a second axis on a side gets its own pill
+            // position rather than the innermost axis's), and its `<YAxis color>` when
+            // it has one — with several axes the pill's ink is what says which scale
+            // the number is on. An uncoloured axis keeps the cursor's own ink.
             renderYGutter: (f) => {
                 const reticle = crosshairPick(f, o.snap);
                 if (reticle === null)
                     return null;
                 const lh = chipLineHeight(f.theme);
-                return (_jsx("div", { style: {
-                        ...axisPillStyle(f.theme, cursorInk(f.theme)),
-                        top: `${Math.max(lh / 2, Math.min(f.rowHeight - lh / 2, reticle.py))}px`,
-                        transform: 'translateY(-50%)',
-                        ...axisPillX(reticle.side, f.plotWidth),
-                    }, children: reticle.formatted }));
+                const ink = reticle.axisColor ?? cursorInk(f.theme);
+                // Clamped inside the row like the y-tick labels; the connector shares it
+                // so the bridge always meets the pill it belongs to.
+                const top = Math.max(lh / 2, Math.min(f.rowHeight - lh / 2, reticle.py));
+                return (_jsxs(_Fragment, { children: [reticle.axisOffset > 0 && (_jsx("div", { style: {
+                                ...axisPillConnector(reticle.side, f.plotWidth, reticle.axisOffset, ink),
+                                top: `${top}px`,
+                                transform: 'translateY(-50%)',
+                            } })), _jsx("div", { style: {
+                                ...axisPillStyle(f.theme, ink),
+                                top: `${top}px`,
+                                transform: 'translateY(-50%)',
+                                ...axisPillX(reticle.side, f.plotWidth, reticle.axisOffset),
+                            }, children: reticle.formatted })] }));
             },
             ...(o.showTime
                 ? {