@pond-ts/charts 0.59.0 → 0.61.0

package/dist/Layers.js

@@ -9,7 +9,8 @@ import { resolveSelection } from './select.js';
 import { isDev } from './dev.js';
 import { useIndexedChildren } from './child-index.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
-import { yTickValues } from './yticks.js';
+// Aliased: `tickValues` is already a local map of per-axis explicit ticks.
+import { tickValues as axisTickValues } from './yticks.js';
 import { ContainerContext, CursorContext, LayersContext, RowContext, } from './context.js';
 /** Fallback **y**-gridline tick count, used only before the row publishes its
  *  resolved `tickCounts` (pre-registration). Normally the gridlines read the
@@ -240,7 +241,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 ?? yTickValues(gridY, yCount)).map((t) => gridY(t))
+                ? (explicitY ?? axisTickValues(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
@@ -1078,7 +1079,13 @@ export function Layers({ children }) {
             else {
                 const span = drag.startRange[1] - drag.startRange[0];
                 const dt = c.plotWidth > 0 ? -dx * (span / c.plotWidth) : 0;
-                c.applyRange(panRange(drag.startRange, dt));
+                // A log x pans by ratio, not by offset — see `ViewportOptions`.
+                // `snap` follows: whole-millisecond snapping is a time-axis rule and
+                // wrong for any value axis, log or not.
+                c.applyRange(panRange(drag.startRange, dt, {
+                    log: c.xIsLog,
+                    snap: c.xKind === 'time',
+                }));
             }
             return; // tracker suppressed during a pan
         }
@@ -1467,7 +1474,10 @@ export function Layers({ children }) {
                     // the minimum visible *trading* time (ms of open-market time)
                     // rather than wall-clock ms — the sensible meaning for this axis.
                     zoomRangeTrading(c.timeRange, pivot, f, c.discontinuities, c.minDuration)
-                : zoomRange(c.timeRange, pivot, f, c.minDuration);
+                : zoomRange(c.timeRange, pivot, f, c.minDuration, {
+                    log: c.xIsLog,
+                    snap: c.xKind === 'time',
+                });
             // ── The aspect lock has to be NEGOTIATED, not asserted ────────────────
             // Both axes zooming by "the same factor" only holds the ratio while both
             // can actually take that factor. Each has its own limit — y cannot zoom

package/dist/XAxis.d.ts

@@ -1,5 +1,30 @@
 import { type AxisTransform } from './derivedTicks.js';
 import { type AxisFormat } from './format.js';
+import { type AxisMouseHandler } from './axis-events.js';
+/** One placed tick — its plot-pixel x, the text to draw, and (stacked band
+ *  style) whether it sits on a band turn and renders emphasized. */
+interface PlacedTick {
+    readonly x: number;
+    readonly label: string;
+    /** This tick opens a coarser calendar period (a day/month/year turn), so it
+     *  renders emphasized (bold): a band turn in stacked, an inline promotion in
+     *  flat — the same boundaries in both styles. */
+    readonly bold?: boolean;
+}
+/**
+ * Thin + truncate a **category** axis's labels so a dense axis stays legible
+ * — triggered by **measured geometry**, not category count ([PND-CATFIT]):
+ * keep every `stride`-th label, and middle-ellipsize a kept one that still
+ * overruns its room. `stride` is the fewest slots the widest label needs once
+ * it may ellipsize to {@link TRUNC_KEEP} of itself, so short label sets keep
+ * every full label and long ones trade thinning against truncation instead of
+ * overprinting. `slot` is the **real band pitch** (`bandwidth()`), which a
+ * `maxBandWidth`-packed axis makes narrower than `plotWidth / n`. Rotation is
+ * a later option.
+ *
+ * Exported for tests only — not re-exported from the package index.
+ */
+export declare function thinCategoryLabels(ticks: readonly PlacedTick[], slot: number, plotWidth: number, fontSize: number, fontFamily: string): PlacedTick[];
 export interface XAxisProps {
     /**
      * Tick / cursor value formatting — a d3 format/time specifier string or a
@@ -59,8 +84,10 @@ export interface XAxisProps {
      * - `'auto'` — centred, but the first label left-anchors and the last
      *   right-anchors so the edge labels stay inside the plot (the old default).
      * - `'right'` — the label sits to the **right** of an extended tick that
-     *   drops from the axis line (label beside the tick, not under it) — useful
-     *   for dense or wide labels that would collide when centred.
+     *   drops from the axis line (label beside the tick, not under it) — a
+     *   *style* choice (the TradingView look). It re-anchors without measuring,
+     *   so it is **not** a remedy for colliding labels; on a category axis the
+     *   measured fit (thin + middle-ellipsize) is what prevents collisions.
      */
     align?: 'auto' | 'center' | 'right';
     /**
@@ -80,6 +107,22 @@ export interface XAxisProps {
      *   on each turn is emphasized and joins its divider as one boundary line.
      */
     dateStyle?: 'flat' | 'stacked';
+    /**
+     * Mouse events on the axis strip, with the **axis value under the pointer**
+     * ({@link AxisMouseHandler}, whose `AxisMouseEvent` payload carries it) — a click on a time axis reports the instant it
+     * landed on, a click on a category axis reports the category. The lever for
+     * axis-driven UI: pick a date by clicking its tick, open a menu on the strip
+     * (`event.type === 'contextmenu'`), drill into a category.
+     *
+     * **One handler takes every mouse event** — click, double-click, context
+     * 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.
+     *
+     * The x strip has no `id` (only a `<YAxis>` does); to distinguish stacked
+     * axes, close over it: `onMouseEvent={(e) => onAxis('delta', e)}`.
+     */
+    onMouseEvent?: AxisMouseHandler;
 }
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
@@ -91,5 +134,6 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, onMouseEvent, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export {};
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -3,9 +3,11 @@ import { Fragment, useContext } from 'react';
 import { scaleLinear } from 'd3-scale';
 import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext, CursorContext, } from './context.js';
+import { tickValues } from './yticks.js';
 import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
+import { axisMouseProps, axisPointerPx, } from './axis-events.js';
 /** Tick strip height (mark + value label) in CSS px. */
 const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
@@ -17,32 +19,132 @@ const BAND_STRIP = 20;
  *  ladder's per-tick budget (a hair tighter: derived labels are short). */
 const TRANSFORM_TICK_PX = 48;
 /**
- * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
- * every `stride`-th label (so a kept label has room), and ellipsize one that still
- * overruns its space. `stride` grows with the longest label vs the per-category
- * slot width, so a few short categories keep every full label and many long ones
- * decimate. A rough `fontSize`-based width estimate (no DOM measure) — good enough
- * for placement; the exact metric is the browser's. Rotation is a later option.
+ * Measure a category label's rendered width in the axis font. A shared
+ * offscreen canvas gives the browser's own metric — the thing the old
+ * per-character estimate could only approximate, and approximated low on
+ * exactly the labels category axes carry (all-caps keys with digits and
+ * hyphens), which let "fits by the estimate" labels overprint on screen
+ * ([PND-CATFIT]). Falls back to the estimate where no canvas backend exists
+ * (SSR, test DOMs). Results are cached per font+text; a webfont that loads
+ * after first measure keeps its fallback-font metric until the cache turns
+ * over, which the fit's inter-label gap absorbs.
  */
-function thinCategoryLabels(ticks, plotWidth, fontSize) {
+const measureCache = new Map();
+// Module state: the first render's canvas context is kept for the process
+// lifetime. In tests this captures whatever canvas stub is installed at first
+// measure — harmless while stubs measure 0 (the estimate fallback takes over
+// per call), but a future *nonzero* canvas mock would need a reset hook here.
+let measureCtx;
+function labelWidth(text, font, fontSize) {
+    const key = `${font}|${text}`;
+    const hit = measureCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    if (measureCtx === undefined) {
+        try {
+            measureCtx =
+                typeof document === 'undefined'
+                    ? null
+                    : (document.createElement('canvas').getContext('2d') ?? null);
+        }
+        catch {
+            measureCtx = null; // a DOM shim whose getContext throws → estimate path
+        }
+    }
+    let w = 0;
+    if (measureCtx !== null) {
+        measureCtx.font = font;
+        w = measureCtx.measureText(text).width;
+    }
+    // No backend, or a mock that measures everything at 0 → per-glyph estimate.
+    if (!(w > 0))
+        w = text.length * fontSize * 0.62;
+    if (measureCache.size > 4096)
+        measureCache.clear();
+    measureCache.set(key, w);
+    return w;
+}
+/** Minimum clear space between two neighbouring drawn labels, px. */
+const LABEL_GAP = 4;
+/**
+ * A kept label may ellipsize down to this fraction of its full width before
+ * the fit prefers dropping labels (growing `stride`) instead — below it, the
+ * text no longer identifies its category.
+ */
+const TRUNC_KEEP = 0.6;
+/**
+ * Ellipsize `text` from the **middle** to fit `room` px: category keys often
+ * share a prefix and differ in the tail (or the reverse), so keeping both ends
+ * preserves whichever part distinguishes — end-truncation makes shared-prefix
+ * keys visually identical. Head-heavy split (60/40). Binary search on the kept
+ * **code-point** count (a UTF-16 `slice` could split a surrogate pair and
+ * emit mojibake); the result is only accepted when it *measures* within
+ * `room`, so the returned label can never overrun its space.
+ */
+function ellipsizeMiddle(text, room, font, fontSize) {
+    const cp = Array.from(text); // code points, not UTF-16 units
+    let lo = 1;
+    let hi = cp.length - 1;
+    let best = '…';
+    while (lo <= hi) {
+        const k = (lo + hi) >> 1;
+        const head = Math.ceil(k * 0.6);
+        const tail = k - head;
+        const s = cp.slice(0, head).join('') +
+            '…' +
+            (tail > 0 ? cp.slice(cp.length - tail).join('') : '');
+        if (labelWidth(s, font, fontSize) <= room) {
+            best = s;
+            lo = k + 1;
+        }
+        else {
+            hi = k - 1;
+        }
+    }
+    return best;
+}
+/**
+ * Thin + truncate a **category** axis's labels so a dense axis stays legible
+ * — triggered by **measured geometry**, not category count ([PND-CATFIT]):
+ * keep every `stride`-th label, and middle-ellipsize a kept one that still
+ * overruns its room. `stride` is the fewest slots the widest label needs once
+ * it may ellipsize to {@link TRUNC_KEEP} of itself, so short label sets keep
+ * every full label and long ones trade thinning against truncation instead of
+ * overprinting. `slot` is the **real band pitch** (`bandwidth()`), which a
+ * `maxBandWidth`-packed axis makes narrower than `plotWidth / n`. Rotation is
+ * a later option.
+ *
+ * Exported for tests only — not re-exported from the package index.
+ */
+export function thinCategoryLabels(ticks, slot, plotWidth, fontSize, fontFamily) {
     const n = ticks.length;
-    const slot = plotWidth / n; // per-category width in px
-    // Before first layout `plotWidth` is 0 → `slot` is 0 and the stride/room math
-    // below goes to Infinity/NaN. Nothing is visible at zero width anyway, so pass
-    // the ticks through untouched until a real width arrives.
-    if (!(slot > 0))
-        return [...ticks];
-    const charW = fontSize * 0.62; // ~average glyph advance
-    const longest = Math.min(12, ticks.reduce((m, t) => Math.max(m, t.label.length), 1));
-    const stride = Math.max(1, Math.ceil((longest * charW) / slot));
-    const room = Math.max(1, Math.floor((slot * stride) / charW));
+    // Degenerate / pre-layout width: nothing can be legible, so draw NO labels.
+    // The old passthrough here was the collapsed-panel smear: these are
+    // absolutely-positioned `nowrap` divs, so at width ≈ 0 every label rendered
+    // full-length at x ≈ 0, overflowing the strip and overprinting.
+    if (!(slot > 0) || !(plotWidth > 0))
+        return [];
+    const font = `${fontSize}px ${fontFamily}`;
+    const widths = ticks.map((t) => labelWidth(t.label, font, fontSize));
+    const maxW = widths.reduce((m, w) => Math.max(m, w), 0);
+    // The width a kept label must be allowed: its full measure when that's
+    // modest, else the legibility floor — TRUNC_KEEP of it, but never less than
+    // ~two glyphs of text.
+    const required = Math.min(maxW, Math.max(maxW * TRUNC_KEEP, fontSize * 2));
+    const stride = Math.max(1, Math.ceil((required + LABEL_GAP) / slot));
+    const room = Math.min(slot * stride - LABEL_GAP, plotWidth - LABEL_GAP);
+    // Not even ~two glyphs fit (a collapsed strip) — an empty axis over a smear.
+    if (!(room >= fontSize * 2))
+        return [];
     const out = [];
     for (let i = 0; i < n; i += stride) {
-        const s = ticks[i].label;
-        out.push({
-            x: ticks[i].x,
-            label: s.length <= room ? s : `${s.slice(0, Math.max(1, room - 1))}…`,
-        });
+        const t = ticks[i];
+        const label = widths[i] <= room
+            ? t.label
+            : ellipsizeMiddle(t.label, room, font, fontSize);
+        // A bare ellipsis identifies nothing — leave that tick unlabeled.
+        if (label !== '…')
+            out.push({ x: t.x, label });
     }
     return out;
 }
@@ -56,7 +158,7 @@ function thinCategoryLabels(ticks, plotWidth, fontSize) {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', onMouseEvent, } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -261,24 +363,33 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
         : derived !== null
             ? honestDerived()
-            : xScale.ticks(xTickCount).map((d) => ({
-                x: xScale(d),
-                label: tickFmt(+d),
-                // A **period turn** renders emphasized (bold), consistently across
-                // styles: in stacked, a tick on a band divider (matched by pixel);
-                // in flat, a tick whose label was *promoted* to a coarser period
-                // (its flat label differs from the terse base) — the same boundaries,
-                // so `Feb` / `2026` read as strong in flat just as the band turns do.
-                bold: stacked
-                    ? dividerXs.has(Math.round(xScale(d)))
-                    : flatFmt !== undefined &&
-                        baseFmt !== undefined &&
-                        flatFmt(+d) !== baseFmt(+d),
-            }));
+            : // `tickValues`, not `xScale.ticks` — d3's raw `scaleLog.ticks()` is
+                // nearly a step function (see `yticks.ts`), so a log x needs the same
+                // decade ladder the y axis already builds. For a time or linear scale
+                // it defers to `scale.ticks(count)`, so this is a no-op there.
+                tickValues(xScale, xTickCount).map((d) => ({
+                    x: xScale(d),
+                    label: tickFmt(+d),
+                    // A **period turn** renders emphasized (bold), consistently across
+                    // styles: in stacked, a tick on a band divider (matched by pixel);
+                    // in flat, a tick whose label was *promoted* to a coarser period
+                    // (its flat label differs from the terse base) — the same boundaries,
+                    // so `Feb` / `2026` read as strong in flat just as the band turns do.
+                    bold: stacked
+                        ? dividerXs.has(Math.round(xScale(d)))
+                        : flatFmt !== undefined &&
+                            baseFmt !== undefined &&
+                            flatFmt(+d) !== baseFmt(+d),
+                }));
     // A category axis ticks once per category; thin + truncate its labels when they
-    // crowd (an explicit `customTicks` axis keeps its labels verbatim).
-    const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1
-        ? thinCategoryLabels(rawTicks, plotWidth, theme.font.size)
+    // crowd (an explicit `customTicks` axis keeps its labels verbatim). The slot is
+    // the scale's own band pitch — under `maxBandWidth` packing it is narrower than
+    // `plotWidth / n`, and the fit must measure against the pitch labels actually
+    // sit on.
+    const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 0
+        ? thinCategoryLabels(rawTicks, 'bandwidth' in xScale
+            ? xScale.bandwidth()
+            : plotWidth / rawTicks.length, plotWidth, theme.font.size, theme.font.family)
         : rawTicks;
     const onTop = side === 'top';
     // Axis pills (marker / crosshair) sit at the same offset as the tick labels so
@@ -300,7 +411,20 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
         (hasBands ? BAND_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
-    return (_jsxs("div", { style: {
+    // The axis coordinate under the pointer, for `onMouseEvent`. The strip is
+    // laid out flush with the plot (the left gutter is its margin, its width is
+    // `plotWidth`), so a strip-local pixel inverts straight through the shared x
+    // 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.
+    const mouse = axisMouseProps(onMouseEvent, 'x', undefined, (event) => {
+        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: {
             position: 'relative',
             marginLeft: `${leftGutter}px`,
             width: `${plotWidth}px`,

package/dist/YAxis.d.ts

@@ -1,4 +1,5 @@
 import { type AxisFormat } from './format.js';
+import { type AxisMouseHandler } from './axis-events.js';
 export interface YAxisProps {
     /** Identifier a chart links to via its `axis` prop (and the first declared is
      *  the row's default). */
@@ -197,6 +198,19 @@ export interface YAxisProps {
      * colours. Presentation-only: it never re-registers the axis.
      */
     color?: string;
+    /**
+     * Mouse events on this axis's gutter, with the **axis value under the
+     * pointer** ({@link AxisMouseHandler}, whose `AxisMouseEvent` payload carries it) — a click reports the value it landed
+     * on, and this axis's `id`, so one handler can serve several axes. The lever
+     * for axis-driven UI: set a threshold by clicking the gutter, open a scale
+     * menu (`event.type === 'contextmenu'`), drill into a categorical row.
+     *
+     * **One handler takes every mouse event** — click, double-click, context
+     * 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.
+     */
+    onMouseEvent?: AxisMouseHandler;
     /**
      * @internal Declaration position among the row's children, injected by
      * `ChartRow` so the first-declared axis stays the default. Do not set.
@@ -211,5 +225,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, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, 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, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -3,7 +3,8 @@ 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';
+import { tickValues } from './yticks.js';
+import { axisMouseProps, axisPointerPx, } from './axis-events.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
@@ -17,7 +18,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, 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, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -114,7 +115,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
         ? ticks.map((t) => ({ value: t.at, label: t.label }))
         : layerCategories !== null
             ? layerCategories.map((label, i) => ({ value: i + 0.5, label }))
-            : (yScale ? yTickValues(yScale, count) : []).map((t) => ({
+            : (yScale ? tickValues(yScale, count) : []).map((t) => ({
                 value: t,
                 label: fmt(t),
             }));
@@ -124,7 +125,33 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
     // axes line up column-by-column. Keyed by this instance's slot key (not `id`,
     // which may repeat across a mirror). Falls back to own width until reserved.
     const slotWidth = row.axisSlots.get(slot) ?? width;
-    return (_jsx("div", { style: {
+    // The axis value under the pointer, for `onMouseEvent` — read on the **slot**
+    // box (below), so the whole reserved gutter answers, not just this axis's own
+    // narrower content. The box is exactly the row's height and shares its top
+    // edge with the plot, so a box-local pixel inverts straight through this
+    // axis's scale. Before the row has published one there is no value to report
+    // 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) => {
+        if (!yScale)
+            return null;
+        // Clamp on the **scale's** range, not the box: a row with a
+        // `labelPlacement="top"` axis reserves a header, so the range is
+        // `[height, topHeader]` while the box still starts at 0 (`ChartRow`).
+        const [r0, r1] = yScale.range();
+        const value = yScale.invert(axisPointerPx(event, 'y', [r0, r1]));
+        return {
+            value,
+            label: layerCategories !== null
+                ? // A slot index, clamped to a real category: the domain's top edge
+                    // inverts to exactly `n` (and rounding can nudge the bottom below
+                    // 0), which no category occupies — the nearest one is the honest
+                    // answer, matching the band scale's own `invert`.
+                    (layerCategories[Math.min(layerCategories.length - 1, Math.max(0, Math.floor(value)))] ?? '')
+                : fmt(value),
+        };
+    });
+    return (_jsx("div", { "data-axis": "y", "data-axis-id": id, ...mouse, style: {
             flex: `0 0 ${slotWidth}px`,
             display: 'flex',
             justifyContent: side === 'left' ? 'flex-end' : 'flex-start',

package/dist/area.d.ts

@@ -1,6 +1,7 @@
 import { type CurveFactory } from 'd3-shape';
 import type { ChartSeries } from './data.js';
 import { type Scale, type TraceState } from './line.js';
+import type { BandLadder } from './bars.js';
 import type { AreaStyle } from './theme.js';
 import type { LayerDrawStats } from './context.js';
 import { type GapMode } from './gaps.js';
@@ -69,7 +70,48 @@ export declare function areaExtent(cs: ChartSeries, baseline: number | undefined
  * bracketed by `save`/`restore` so they don't leak into later layers. Gap edges
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
-export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, decimate?: DecimateOption): LayerDrawStats;
+export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, decimate?: DecimateOption, banding?: BandLadder): LayerDrawStats;
+/**
+ * The banded fill + stroke for `<AreaChart thresholds>` ([PND-BANDAREA]): one
+ * vertical **hard-stop gradient in pixel space**, a colour switch at every
+ * threshold crossing — `colors[0]` between `-t0` and `+t0`, `colors[k]` over
+ * magnitudes `[t(k-1), tk)` on both sides of zero. `thresholds`/`colors` arrive
+ * as a resolved {@link BandLadder} (ascending, positive, `n + 1` colours), the
+ * same currency `drawBars` takes.
+ *
+ * A gradient rather than one clipped redraw per band, and that is the
+ * load-bearing choice: K + 1 clipped passes walk the path K + 1 times and meet
+ * themselves at every boundary with an antialiased seam, where a gradient
+ * draws the identical single path once and costs O(K) colour stops. It also
+ * bands the **outline for free** — `strokeStyle` takes the same gradient, so
+ * the value line switches hue exactly at a crossing, which no per-band clip
+ * can do without shearing the stroke.
+ *
+ * The ladder is walked on the **magnitude** and mirrored below zero, exactly
+ * as `bandSpan` does for a bar: the boundary at `±tk` separates band `k` (the
+ * zero side) from band `k + 1` (the away side). Whether "away from zero" is up
+ * or down the canvas is probed from the scale itself (`t0` vs `t0 + 1`, both
+ * positive and finite by construction), so a flipped axis bands correctly. A
+ * boundary with **no position** on the scale contributes no crossing — on a
+ * log axis the negative mirrors (and zero) simply don't exist, which is the
+ * right reading. A crossing **off the plot** clamps to the gradient's ends
+ * (a real canvas throws on stops outside `[0, 1]`), which is also what makes a
+ * zoomed-in view honest: with every visible pixel inside one band, the clamp
+ * degenerates the other stops and the whole plot paints that band's colour.
+ *
+ * Falls back to the top band's flat colour when there is nothing to anchor on
+ * (no plot height, or no boundary with a position at all) — reachable only
+ * with a degenerate scale stub, since every real axis positions a positive
+ * finite value; any flat colour is equally (in)correct there, and the top
+ * band's is at least stable.
+ *
+ * Like the bar ladder, breakpoints are **absolute data values**, so the
+ * baseline plays no part here: an area resting on a non-zero floor still bands
+ * at the same heights as its neighbours — measuring from the resolved baseline
+ * instead would silently shift every breakpoint by the floor, the quiet
+ * wrongness [PND-BANDBAR2] exists to remove.
+ */
+export declare function buildBandGradient(ctx: CanvasRenderingContext2D, yScale: Scale, plotHeight: number, banding: BandLadder): CanvasGradient | string;
 /**
  * **Is the pointer inside this area?** The filled-region counterpart of
  * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as