@pond-ts/charts 0.56.2 → 0.58.0

package/dist/XAxis.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useContext } from 'react';
 import { scaleLinear } from 'd3-scale';
 import { derivedTicks } from './derivedTicks.js';
-import { ContainerContext, CursorContext } from './context.js';
+import { ContainerContext, CursorContext, } from './context.js';
+import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 /** Tick strip height (mark + value label) in CSS px. */
@@ -65,16 +66,19 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // gridlines and `formatTime` use, so labels and grid stay on the same instants
     // (width-derived on a trading-time axis).
     const { xScale, plotWidth, leftGutter, theme, formatTime, xKind, xTickCount, } = container;
-    // The crosshair's x-time pill: when the container cursor is `'crosshair'` and a
-    // cursor is live in-bounds, pin the hovered time to this axis (covering the
-    // tick behind it), matching the on-axis y value pills the rows draw. Gated on
-    // the container default, so a per-row `cursor` override doesn't reach here.
+    // The cursor's x-axis slot: did the mounted cursor in effect register one
+    // (`renderXAxis` — the crosshair's time pill)? While hovering, that is the
+    // **hovered row's** effective cursor — so a per-row override reaches this
+    // axis, which the old `container.cursor === 'crosshair'` string gate never
+    // let it do (a row-level crosshair had no time pill); with no live pointer
+    // (a controlled `trackerPosition`), any scope's effective cursor keeps its
+    // pill. The slot renders below when the cursor is live in-bounds.
     const cursorX = cursor.cursorX;
-    const showCursorTag = container.cursor === 'crosshair' &&
+    const xSlotEntries = xAxisCursorEntries(container.cursors, cursor.cursorRowKey).filter((e) => e.spec.renderXAxis !== undefined);
+    const showCursorTag = xSlotEntries.length > 0 &&
         cursorX !== null &&
         cursorX >= 0 &&
         cursorX <= plotWidth;
-    const cursorColor = theme.cursor ?? theme.axis.label;
     const annotationColor = theme.annotation?.color ?? '#0d9488';
     // Derived-unit (`transform`) layout: nice ticks in the derived unit at
     // mixed step sizes, admitted where they keep pixel room (see derivedTicks).
@@ -417,20 +421,34 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: `${laneY}px`,
                                 zIndex: 2,
                             }, children: t.text })] }, t.id));
-            }), showCursorTag && (_jsxs(Fragment, { children: [_jsx("div", { style: {
-                            position: 'absolute',
-                            left: `${cursorX}px`,
-                            [onTop ? 'bottom' : 'top']: 0,
-                            width: '1px',
-                            height: `${pillOffset}px`,
-                            background: cursorColor,
-                            zIndex: 3,
-                        } }), _jsx("div", { style: {
-                            ...axisPillStyle(theme, cursorColor),
-                            left: `${cursorX}px`,
-                            transform: 'translateX(-50%)',
-                            [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
-                            zIndex: 3,
-                        }, children: readoutFmt(+xScale.invert(cursorX)) })] }))] }));
+            }), showCursorTag &&
+                (() => {
+                    // The x-axis {@link ResolvedCursorFrame}: no row, no samples — the
+                    // slot draws a pill from the resolved cursor x + the axis's own
+                    // readout-formatted time (this axis's precedence chain, `readoutFmt`),
+                    // placed per the strip's side + tick-label offset.
+                    const f = {
+                        cursorX,
+                        cursorY: null,
+                        rowKey: null,
+                        hoveredRowKey: cursor.cursorRowKey,
+                        samples: [],
+                        flags: [],
+                        pointer: null,
+                        band: null,
+                        bandY: null, // …nor a transposed one: same reason as `rect`
+                        bandLine: false,
+                        bandDragging: false, // no band in the axis strip to edge
+                        rect: null, // …and no 2-D brush: the strip has no y
+                        restingCross: false,
+                        formattedTime: readoutFmt(+xScale.invert(cursorX)),
+                        plotWidth,
+                        rowHeight: 0,
+                        isFirstRow: false,
+                        theme,
+                        xAxis: { onTop, pillOffset },
+                    };
+                    return xSlotEntries.map((e, i) => (_jsx(Fragment, { children: e.spec.renderXAxis(f) }, `cursor-${i}`)));
+                })()] }));
 }
 //# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -106,6 +106,33 @@ export interface YAxisProps {
     boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
+    /**
+     * **Keep the scale, draw no gutter.** The axis still registers its domain
+     * (`min`/`max`/`scale`/`pad`) and layers still bind to it by `id`, but it
+     * renders nothing and reserves **no width** — the plot gets the space.
+     *
+     * A `<YAxis>` does two jobs: it *holds the scale* and it *renders a gutter*.
+     * Without this there was no way to ask for the first without the second, so a
+     * chart with a **fixed** domain whose scale is already explained by its
+     * chrome (threshold band lines, a legend, a panel header) had two reachable
+     * options and needed a third:
+     *
+     * | | auto domain | explicit domain |
+     * |---|---|---|
+     * | **gutter** | `<YAxis />` | `<YAxis min max />` |
+     * | **no gutter** | omit the axis | ← this prop |
+     *
+     * Omitting the axis is not the same thing: the row then supplies an implicit
+     * auto-domain axis, and the fixed domain is exactly what must not be given
+     * up. `width={0}` is not it either — the labels still draw, now over the
+     * plot.
+     *
+     * **Gridlines are unaffected.** They belong to the plot, not the gutter, and
+     * `<ChartContainer grid>` already controls them — so a hidden axis can still rule
+     * its own gridlines, which is usually what a "the shape matters, the numbers
+     * don't" chart wants. Turn them off there if you want neither.
+     */
+    hide?: boolean;
     /**
      * This axis instance's colour — tick labels and the axis title take it,
      * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
@@ -128,5 +155,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -17,7 +17,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -29,7 +29,11 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
     const spec = useMemo(() => ({
         id,
         side,
-        width,
+        // A hidden axis reserves no gutter — the row's slot placement reads this
+        // width, so zeroing it here is what gives the space back to the plot.
+        // Everything else about the spec is unchanged: the domain still resolves
+        // and layers still bind to it, which is the whole point of the prop.
+        width: hide ? 0 : width,
         scale,
         min,
         max,
@@ -43,6 +47,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         id,
         side,
         width,
+        hide,
         scale,
         min,
         max,
@@ -65,6 +70,23 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
     useEffect(() => {
         registerAxis(slot, spec);
     }, [registerAxis, slot, spec]);
+    // `hide`: everything above still runs — the axis is registered, so its scale
+    // exists and layers bind to it — and everything below (the gutter chrome)
+    // does not. Placed after the last hook so the early return can't change hook
+    // order when `hide` is toggled at runtime.
+    //
+    // It renders an **empty box at the reserved slot width**, not nothing. The
+    // container reserves each axis *column* at the widest across rows
+    // (`maxSlotWidths`), so a hidden axis sharing a column with a visible one in
+    // another row is still allotted that column's width — and drawing nothing
+    // there slides this row's plot left, out of line with its siblings and with
+    // the shared x-axis. When this axis is alone in its column the reservation is
+    // its own `width: 0`, the box is zero-wide, and the plot reclaims the space,
+    // which is the point of the prop. Both cases fall out of the same expression.
+    if (hide) {
+        const hiddenSlot = row.axisSlots.get(slot) ?? 0;
+        return hiddenSlot > 0 ? (_jsx("div", { "aria-hidden": "true", style: { flex: `0 0 ${hiddenSlot}px`, height: `${row.height}px` } })) : null;
+    }
     const { theme } = container;
     const yScale = row.yScales.get(id);
     // The auto-tick count — the row resolves it (explicit `tickCount` else

package/dist/annotations.d.ts

@@ -161,6 +161,80 @@ export interface BaselineProps {
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
 export declare function Baseline({ value, axis, label, labelSide, labelPosition, id, selected, selectable, hovered, editing, onChange, indicator, role, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
+export interface ZoneProps {
+    /** Lower bound in the linked y-axis's units. */
+    from: number;
+    /** Upper bound in the linked y-axis's units. `from`/`to` may arrive either way
+     *  round (they're ordered here), and either may be **infinite** for an
+     *  open-ended band (`to={Infinity}` — the AQI "Hazardous" tail, a
+     *  `ZoneTime.openEnded` zone): the rect clamps to the plot. */
+    to: number;
+    /** Which `<YAxis>` (by id) to measure against; omit for the row's default axis. */
+    axis?: string;
+    /** Chip label, anchored at the band's vertical centre. **Omit for no label** —
+     *  unlike `<Region>` a zone does *not* auto-label its bounds, because they're
+     *  already legible on the y axis it spans (a region's x span isn't). The label
+     *  worth showing is a **name** — `"Good"`, `"Z4 threshold"` — which only the
+     *  caller has. */
+    label?: string;
+    /** Which side of the chart the label chip sits. **Default `left`.** */
+    labelSide?: 'left' | 'right';
+    /** Stable consumer id — a click reports it via `onSelectAnnotation`. Only
+     *  meaningful with `selectable`. */
+    id?: string;
+    /** Controlled selection — brightens to the front (level 1). Ignored unless
+     *  `selectable`. */
+    selected?: boolean;
+    /**
+     * Whether the band responds to hover + selection. **Default `false`** — the
+     * opposite of the rest of the family, and deliberately so: a zone spans the
+     * **full plot width**, and a zone *set* tiles the whole y range, so the pointer
+     * is always inside one. Interactive by default, they'd light up on every
+     * mousemove and their hit rects would swallow the plot's own clicks. A zone is
+     * background context first (level 3, pointer-transparent); opt in per band when
+     * a band is genuinely a thing to point at.
+     */
+    selectable?: boolean;
+    /** Theme **role** — colours this band from `theme.annotation.roles[role]` (its
+     *  `color`, optionally `fillOpacity`), keeping the shared depth ramp. This is
+     *  how a zone set gets its **semantic palette** (`good` green, `moderate`
+     *  yellow, …): the scale lives in the theme, not at the call site. Omitted /
+     *  unknown ⇒ the base annotation colour. */
+    role?: string;
+    /** Controlled hover (OR'd with pointer hover) — lets a legend row light the
+     *  band remotely. Ignored unless `selectable`. */
+    hovered?: boolean;
+    /** Draw the horizontal **boundary lines** at `from`/`to`. **Default `false`** —
+     *  again the opposite of `<Region>`, because zone sets are usually
+     *  **contiguous**: every interior boundary is shared by two bands, so edges-on
+     *  draws each one twice at double opacity. `true` outlines an isolated band (a
+     *  target range). */
+    edges?: boolean;
+}
+/**
+ * A shaded band between two **y values**, spanning the full plot width — the
+ * y-axis counterpart of `<Region>`. The mark for a **classification of the value
+ * axis**: US EPA AQI categories, heart-rate / power zones, a control chart's
+ * spec limits, an SLO band.
+ *
+ * Being a `<Layers>` child it lives in its row and is scaled by that row's y
+ * axis — pass `axis` to pick one on a dual-axis row. Like every annotation it
+ * paints in the SVG overlay **above** the data canvas, so keep the fill light
+ * (the register's `fillOpacity`, ~0.1–0.2) and the trace reads cleanly through
+ * it. A zone set is a wash of colour behind the story, not a layer competing
+ * with it.
+ *
+ * Zones are **background context by default** (`selectable={false}`,
+ * `edges={false}`, no label) because that is what a tiled zone set is; see
+ * {@link ZoneProps.selectable} for why the family's usual defaults invert here.
+ * Colour comes from the theme's {@link ZoneProps.role | role} map, so a palette
+ * is a theme, not six call-site colours.
+ *
+ * Unlike the other marks a zone has **no `onChange`** — dragging zone edges
+ * (a zone editor) is a real feature but has no consumer yet; the band is
+ * declarative until one arrives.
+ */
+export declare function Zone({ from, to, axis, label, labelSide, id, selected, selectable, hovered, role, edges, }: ZoneProps): import("react/jsx-runtime").JSX.Element | null;
 export interface RegionProps {
     /** Start x in axis units (time or value). */
     from: number;

package/dist/annotations.js

@@ -6,7 +6,8 @@ import { useSlotKey } from './use-slot-key.js';
 /**
  * User-authored **annotations** — marks you place *on* a chart, in a register
  * deliberately distinct from the data: `<Region>` (a shaded x-span), `<Baseline>`
- * (a horizontal value line), and `<Marker>` (a vertical x line). All three render
+ * (a horizontal value line), `<Marker>` (a vertical x line), and `<Zone>` (a
+ * shaded y-span — `<Region>`'s counterpart on the value axis). All four render
  * in the theme's turquoise {@link ChartTheme.annotation} register so a placed mark
  * never reads as data ("the data stays foam; the marks you place are turquoise").
  *
@@ -101,7 +102,7 @@ const overlayStyle = {
  * Read the container + row frames an annotation needs (throw if misplaced), and
  * resolve the mark's annotation style for its optional `role`. A `role` recolors
  * *this* mark from the theme's `annotation.roles[role]` map (`color`, and
- * optionally `fillOpacity`) while keeping the shared depth ramp — so a smile can
+ * optionally `fillOpacity` / `dash`) while keeping the shared depth ramp — so a smile can
  * place a green ATM baseline, a neutral vertical, and a distinct marker at once
  * without splitting the whole register. An unknown / unset role falls back to
  * the base `annotation` register (`roles[role] ?? annotation`).
@@ -117,17 +118,23 @@ function useAnnotationFrame(name, role) {
     }
     const base = container.theme.annotation ?? DEFAULT_ANNOTATION;
     const roleStyle = role !== undefined ? base.roles?.[role] : undefined;
-    // The role overrides only colour (+ optional fill); depth stays the shared
-    // ramp, so selection / hover / edit levels read identically per role.
+    // The role overrides only colour (+ optional fill / dash); depth stays the
+    // shared ramp, so selection / hover / edit levels read identically per role.
     const ann = roleStyle
         ? {
             ...base,
             color: roleStyle.color,
             fillOpacity: roleStyle.fillOpacity ?? base.fillOpacity,
+            dash: roleStyle.dash ?? base.dash,
         }
         : base;
     return { container, row, ann };
 }
+/** The register's dash as an SVG `stroke-dasharray`, or `undefined` for solid
+ *  (an empty pattern means solid, matching `LineStyle.dash`). */
+function dashArray(dash) {
+    return dash === undefined || dash.length === 0 ? undefined : dash.join(' ');
+}
 /** Register this annotation with the container (so it can draw the mark's guide on
  *  other rows, order regions, and serve snap targets), keyed by the caller's stable
  *  per-instance slot key; unregister on unmount. `xs` should be memoised by the
@@ -504,7 +511,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     // The staff (vertical line) hangs from the top of its flag — so a flag stacked
     // into a lower lane doesn't leave line poking above it. No label ⇒ full height.
     const staffTop = text ? FLAG_TOP + lane * LANE_H : 0;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
                             +container.xScale.invert(px)) }))] }), chipLabel && x >= 0 && x <= container.plotWidth && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
                     ...flagChipX(x, container.plotWidth),
@@ -552,7 +559,7 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
     const text = label === false ? '' : (label ?? (fmt ? fmt(value) : String(value)));
     // Handle pill near the right end (clears the left-anchored label).
     const handleX = w - 14;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${y}px`,
                     [labelSide === 'right' ? 'right' : 'left']: '2px',
                     // `center` rides on the line; `above` sits its bottom edge on the line.
@@ -570,6 +577,89 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
                         }, children: fmt ? fmt(value) : String(value) }));
                 })()] }));
 }
+/**
+ * A shaded band between two **y values**, spanning the full plot width — the
+ * y-axis counterpart of `<Region>`. The mark for a **classification of the value
+ * axis**: US EPA AQI categories, heart-rate / power zones, a control chart's
+ * spec limits, an SLO band.
+ *
+ * Being a `<Layers>` child it lives in its row and is scaled by that row's y
+ * axis — pass `axis` to pick one on a dual-axis row. Like every annotation it
+ * paints in the SVG overlay **above** the data canvas, so keep the fill light
+ * (the register's `fillOpacity`, ~0.1–0.2) and the trace reads cleanly through
+ * it. A zone set is a wash of colour behind the story, not a layer competing
+ * with it.
+ *
+ * Zones are **background context by default** (`selectable={false}`,
+ * `edges={false}`, no label) because that is what a tiled zone set is; see
+ * {@link ZoneProps.selectable} for why the family's usual defaults invert here.
+ * Colour comes from the theme's {@link ZoneProps.role | role} map, so a palette
+ * is a theme, not six call-site colours.
+ *
+ * Unlike the other marks a zone has **no `onChange`** — dragging zone edges
+ * (a zone editor) is a real feature but has no consumer yet; the band is
+ * declarative until one arrives.
+ */
+export function Zone({ from, to, axis, label, labelSide = 'left', id, selected = false, selectable = false, hovered, role, edges = false, }) {
+    const { container, row, ann } = useAnnotationFrame('Zone', role);
+    const selfKey = useSlotKey();
+    const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
+    // A horizontal band casts no vertical guide (like a baseline) — register with
+    // no xs, so it's tracked for ordering but offers no snap target.
+    const xs = useMemo(() => [], []);
+    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'zone', xs, selected, selectable, false, // zones aren't editable — no single-annotation edit state
+    label ?? '', false);
+    // No select while a create tool is armed — the chart is in draw mode then.
+    const select = id !== undefined && container.creating === null
+        ? () => container.onSelectAnnotation?.(id)
+        : undefined;
+    const axisId = axis ?? row.defaultAxisId;
+    const yScale = row.yScales.get(axisId);
+    // The axis may not have resolved yet (a layer mounts before its <YAxis>); skip
+    // until its scale exists rather than guessing a domain.
+    if (yScale === undefined)
+        return null;
+    const h = row.height;
+    const w = container.plotWidth;
+    // A NaN bound has no position to draw at — cull rather than let it fall
+    // through the finite check below and silently become the domain's low end.
+    if (Number.isNaN(from) || Number.isNaN(to))
+        return null;
+    // Open-ended bounds resolve against the axis **domain** before scaling, not
+    // after: d3's interpolator is `a·(1−t) + b·t`, so an infinite `t` yields
+    // `0 · Infinity` = NaN rather than an off-plot pixel. Substituting the domain
+    // end is also exactly the intent — an open band reaches the plot edge.
+    const [d0, d1] = yScale.domain();
+    const dLo = Math.min(d0 ?? 0, d1 ?? 0);
+    const dHi = Math.max(d0 ?? 0, d1 ?? 0);
+    const bound = (v) => (Number.isFinite(v) ? v : v > 0 ? dHi : dLo);
+    // Order + clamp to the plot: a band may run past the axis domain (the AQI
+    // 151–200 band on an axis topping out at 120). Clamping keeps the rect inside
+    // its row; a band entirely outside culls.
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    const loY = yScale(bound(lo));
+    const hiY = yScale(bound(hi));
+    const top = Math.max(Math.min(loY, hiY), 0);
+    const bottom = Math.min(Math.max(loY, hiY), h);
+    if (bottom <= top)
+        return null;
+    const bandH = bottom - top;
+    // Edit is never on (no onChange) — the levels reduce to selected / hover /
+    // resting, and to a flat level 3 when the band is inert background.
+    const edgeOpacity = rampAt(ann.depth, lineLevel(selectable, false, hovering, selected));
+    const fillOpacity = ann.fillOpacity *
+        rampAt(FILL_MULT, bodyLevel(selectable, false, hovering, selected));
+    /** A boundary line — drawn only where the band has a *real*, in-plot edge. An
+     *  open-ended bound has no boundary at all, and a bound the clamp cut off would
+     *  otherwise draw its line on the plot border, reading as chrome. */
+    const boundary = (v, aty) => edges && Number.isFinite(v) && aty >= 0 && aty <= h ? (_jsx("line", { x1: 0, y1: aty, x2: w, y2: aty, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" })) : null;
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: h, style: overlayStyle, children: [_jsx("rect", { x: 0, y: top, width: w, height: bandH, fill: ann.color, opacity: fillOpacity }), boundary(lo, loY), boundary(hi, hiY), selectable && (_jsx(DragArea, { x: 0, y: top, w: w, h: bandH, cursor: "inherit", editable: false, onHover: reportHover, onSelect: select, onDrag: () => { } }))] }), label !== undefined && label !== '' && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                    top: `${top + bandH / 2}px`,
+                    [labelSide === 'right' ? 'right' : 'left']: '2px',
+                    transform: 'translateY(-50%)',
+                }, children: label }))] }));
+}
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
 export function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, edges = true, role, }) {
@@ -616,7 +706,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     // even after the dragged edge crosses it — {@link orderRegion} then re-opens the
     // region the other way instead of dead-ending at zero width.
     const edgeRef = useRef(null);
-    const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, shapeRendering: "crispEdges" }));
+    const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, strokeDasharray: dashArray(ann.dash), shapeRendering: "crispEdges" }));
     return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edges && edge(xa), edges && edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: (px) => {
                                     dragRef.current = { from, to, startPx: px };
                                 }, onDrag: (px) => {

package/dist/area.d.ts

@@ -1,6 +1,6 @@
 import { type CurveFactory } from 'd3-shape';
 import type { ChartSeries } from './data.js';
-import { type Scale } from './line.js';
+import { type Scale, type TraceState } from './line.js';
 import type { AreaStyle } from './theme.js';
 import type { LayerDrawStats } from './context.js';
 import { type GapMode } from './gaps.js';
@@ -70,4 +70,37 @@ export declare function areaExtent(cs: ChartSeries, baseline: number | undefined
  * 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;
+/**
+ * **Is the pointer inside this area?** The filled-region counterpart of
+ * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as
+ * click provenance, or `null` when the pointer is outside the fill.
+ *
+ * An area is not a stroke, so the test is not distance-to-path: the pointer is
+ * on the area when it lies **between the trace and the baseline** at that x.
+ * That is the honest reading of "you clicked the area", and it makes the whole
+ * filled shape the target rather than a 1.5px edge — which is the same reason
+ * the list family made the row the target rather than the bar.
+ *
+ * The x cut bisects `xScale(cs.x[i])` for `traceHitIndex`'s reasons (a layer's
+ * `hitTest` gets the forward scale only, and a trading-time scale has no honest
+ * inverse), and the trace's y is **interpolated** between the bracketing
+ * samples so the boundary follows the drawn edge rather than a step. A tolerance
+ * is still added, so the top edge is grabbable from just outside.
+ *
+ * A gap is a hole, not a bridge: either bracketing sample non-finite ⇒ no hit,
+ * matching what `drawArea` actually fills.
+ */
+export declare function areaHitIndex(cs: ChartSeries, baseline: number | undefined, px: number, py: number, xScale: Scale, yScale: Scale, tolerance?: number): number | null;
+/**
+ * The style an area fills with in a given interaction state
+ * ([PND-TRACESEL]) — the {@link AreaStyle} counterpart of `traceStateStyle`.
+ *
+ * The channels differ from a line's because what carries the mark differs: an
+ * area's mark is its **fill**, so state is the fill's strength plus the edge's
+ * weight. A line has only a stroke, so there weight is all there is.
+ *
+ * Alpha comes back separately, as it does for a line, so a muted area keeps its
+ * hue rather than having the fade baked into a colour.
+ */
+export declare function areaStateStyle(style: AreaStyle, state: TraceState): readonly [AreaStyle, number];
 //# sourceMappingURL=area.d.ts.map

package/dist/area.js

@@ -1,5 +1,5 @@
 import { area as d3area, curveLinear } from 'd3-shape';
-import { strokeAffinePolyline } from './line.js';
+import { baselinePxFromScale, strokeAffinePolyline, TRACE_HIT_PX, } from './line.js';
 import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, gapUnscalable, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { cullChartSeries } from './culling.js';
 import { decimateM4Cached } from './decimate.js';
@@ -345,4 +345,91 @@ function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
     }
     return grad;
 }
+/**
+ * **Is the pointer inside this area?** The filled-region counterpart of
+ * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as
+ * click provenance, or `null` when the pointer is outside the fill.
+ *
+ * An area is not a stroke, so the test is not distance-to-path: the pointer is
+ * on the area when it lies **between the trace and the baseline** at that x.
+ * That is the honest reading of "you clicked the area", and it makes the whole
+ * filled shape the target rather than a 1.5px edge — which is the same reason
+ * the list family made the row the target rather than the bar.
+ *
+ * The x cut bisects `xScale(cs.x[i])` for `traceHitIndex`'s reasons (a layer's
+ * `hitTest` gets the forward scale only, and a trading-time scale has no honest
+ * inverse), and the trace's y is **interpolated** between the bracketing
+ * samples so the boundary follows the drawn edge rather than a step. A tolerance
+ * is still added, so the top edge is grabbable from just outside.
+ *
+ * A gap is a hole, not a bridge: either bracketing sample non-finite ⇒ no hit,
+ * matching what `drawArea` actually fills.
+ */
+export function areaHitIndex(cs, baseline, px, py, xScale, yScale, tolerance = TRACE_HIT_PX) {
+    const n = cs.length;
+    if (n === 0)
+        return null;
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (xScale(cs.x[mid]) < px)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    // The bracketing pair around the pointer. At either end of the series the
+    // pair degenerates to one sample, which is correct — the fill stops there.
+    const i = Math.max(0, Math.min(n - 1, lo));
+    const j = Math.max(0, Math.min(n - 1, lo === 0 ? 0 : lo - 1));
+    const yi = cs.y[i];
+    const yj = cs.y[j];
+    if (!Number.isFinite(yi) || !Number.isFinite(yj))
+        return null;
+    const xi = xScale(cs.x[i]);
+    const xj = xScale(cs.x[j]);
+    // Interpolate the edge at the pointer's x, so the boundary is the drawn
+    // slope and not a staircase. Guard the degenerate same-pixel pair.
+    const t = xi === xj ? 0 : (px - xj) / (xi - xj);
+    const edgePx = yScale(yj + (yi - yj) * Math.max(0, Math.min(1, t)));
+    const basePx = baseline === undefined ? baselinePxFromScale(yScale) : yScale(baseline);
+    const top = Math.min(edgePx, basePx) - tolerance;
+    const bottom = Math.max(edgePx, basePx) + tolerance;
+    if (py < top || py > bottom)
+        return null;
+    // Outside the series' own x span there is no fill to be inside of.
+    if (px < xScale(cs.x[0]) - tolerance)
+        return null;
+    if (px > xScale(cs.x[n - 1]) + tolerance)
+        return null;
+    return Math.abs(px - xi) <= Math.abs(px - xj) ? i : j;
+}
+/**
+ * The style an area fills with in a given interaction state
+ * ([PND-TRACESEL]) — the {@link AreaStyle} counterpart of `traceStateStyle`.
+ *
+ * The channels differ from a line's because what carries the mark differs: an
+ * area's mark is its **fill**, so state is the fill's strength plus the edge's
+ * weight. A line has only a stroke, so there weight is all there is.
+ *
+ * Alpha comes back separately, as it does for a line, so a muted area keeps its
+ * hue rather than having the fade baked into a colour.
+ */
+export function areaStateStyle(style, state) {
+    const emphasised = {
+        ...style,
+        width: style.selectedWidth ?? style.width * 2,
+        fillOpacity: style.selectedFillOpacity ?? Math.min(style.fillOpacity * 2, 1),
+    };
+    switch (state) {
+        case 'selected':
+            return [emphasised, 1];
+        case 'hover':
+            return [emphasised, 1];
+        case 'dimmed':
+            return [style, style.dimmedOpacity ?? 0.32];
+        case 'rest':
+            return [style, 1];
+    }
+}
 //# sourceMappingURL=area.js.map