@pond-ts/charts 0.43.0 → 0.44.0

package/dist/Layers.js

@@ -2,7 +2,6 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
 import { drawGrid, drawDividers, thinPixels } from './grid.js';
-import { TimeRange } from 'pond-ts';
 import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
@@ -260,13 +259,17 @@ export function Layers({ children }) {
             }
             return;
         }
-        // Region-cursor drag-select (opt-in via `onRegionSelect`, time axis only):
-        // anchor the selection at the press; the band then extends as the pointer
-        // moves (bucket by bucket with a sequence, freeform without), and release
-        // commits the range. A `regionSelectModifier` (only while `panZoom` is on)
-        // gates it behind the key so plain drag can still pan; otherwise it preempts
-        // pan (returns before the pan is armed below).
-        if (c.cursor === 'region' && c.onRegionSelect && c.xKind === 'time') {
+        // Region-cursor drag-select (opt-in via `onRegionSelect`): anchor the
+        // selection at the press; the band then extends as the pointer moves (bucket
+        // by bucket with a sequence, freeform without), and release commits the span.
+        // Works on a continuous x axis — time **or** value (a category axis is
+        // excluded; its ordinal-slot select is a different gesture). A
+        // `regionSelectModifier` (only while `panZoom` is on) gates it behind the key
+        // so plain drag can still pan; otherwise it preempts pan (returns before the
+        // pan is armed below).
+        if (c.cursor === 'region' &&
+            c.onRegionSelect &&
+            (c.xKind === 'time' || c.xKind === 'value')) {
             const needsShift = c.regionSelectModifier === 'shift' && c.panZoom;
             if (!needsShift || e.shiftKey) {
                 const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
@@ -417,7 +420,7 @@ export function Layers({ children }) {
                 /* ignore */
             }
             if (span)
-                c.onRegionSelect?.(new TimeRange({ start: span.start, end: span.end }));
+                c.onRegionSelect?.([span.start, span.end]);
             return;
         }
         if (c.creating !== null) {
@@ -623,12 +626,13 @@ export function Layers({ children }) {
             side: axisSides.get(defaultAxisId) ?? 'left',
         };
     })();
-    // `region` cursor (time axis only): shade the span under the pointer. With a
-    // `cursorSequence` the band snaps to the bucket (and extends bucket by bucket
-    // under a drag); with none it's the **freeform** case — a bare hover draws a
-    // plain line (`regionLine`), a drag shades the raw `[anchor, pointer]`. Edges
-    // map through `xScale`, so on a trading-time axis the band crops to live time.
-    const regionActive = parts.band && container.xKind === 'time';
+    // `region` cursor (continuous x axis — time or value): shade the span under the
+    // pointer. With a `cursorSequence` (time axis only) the band snaps to the bucket
+    // (and extends bucket by bucket under a drag); with none — always the case on a
+    // value axis — it's the **freeform** case: a bare hover draws a plain line
+    // (`regionLine`), a drag shades the raw `[anchor, pointer]`. Edges map through
+    // `xScale`, so on a trading-time axis the band crops to live time.
+    const regionActive = parts.band && (container.xKind === 'time' || container.xKind === 'value');
     const band = regionActive && cursorTime !== null
         ? bandRect(container.cursorBuckets ?? [], cursorTime, (v) => xScale(v), plotWidth, container.regionAnchor ?? undefined)
         : null;

package/dist/ScatterChart.d.ts

@@ -1,8 +1,21 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type ColorEncoding, type RadiusEncoding } from './encoding.js';
-export interface ScatterChartProps<S extends SeriesSchema> {
-    /** The source series. Its key column supplies the time axis (each point's x). */
-    series: TimeSeries<S>;
+export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` scatters against the time axis; a
+     * `ValueSeries` (`series.byValue('cumDist')`, or `ValueSeries.fromColumns`
+     * for natively value-keyed data — IV marks keyed by strike) against its
+     * value axis — the container infers which from the data, no axis-type prop
+     * (mirrors `<LineChart>`). Either way the key / axis column supplies each
+     * point's x and `column` supplies y.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call,
+     * so passing `series={s.byValue('dist')}` inline re-registers this layer
+     * every render — memoize the projection (`useMemo`) on a frequently
+     * re-rendering chart.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column — each point's y. */
     column: string;
     /**
@@ -24,6 +37,11 @@ export interface ScatterChartProps<S extends SeriesSchema> {
      * the key the controlled `selected` echo, dedup, and (later) multi-select all
      * match on — so a selection survives a data update where a sample `key` goes
      * stale.
+     *
+     * A point's identity within the series is its **x** (key / axis value). The
+     * key contract allows duplicate x's (equal timestamps; a value-axis plateau
+     * from `byValue('cumDist')`) — points sharing an x share identity, so
+     * selecting one highlights the last drawn point at that x.
      */
     id?: string;
     /**
@@ -59,6 +77,14 @@ export interface ScatterChartProps<S extends SeriesSchema> {
      * dense scatter is noise; this is for a handful of called-out marks.
      */
     label?: string | boolean;
+    /**
+     * A **pixel** shift applied to every point's x — zoom-stable. **Default `0`.**
+     * For pairing marks that share a key side by side (a call and a put mark at one
+     * strike: `offset={-4}` / `offset={+4}`). Pairs with `<BoxPlot offset>`; on the
+     * scatter the shift is exact — both the draw and the click hit-test move
+     * together, so a nudged point still selects.
+     */
+    offset?: number;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -66,7 +92,8 @@ export interface ScatterChartProps<S extends SeriesSchema> {
     index?: number;
 }
 /**
- * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * A scatter draw layer: one mark per finite point at `(x, column-value)`
+ * — x from the series' key / axis column (time or value axis) —
  * with **data-driven radius + colour** (the signed-off exception — encode from
  * columns via scales, not a per-event style callback). Reads `column` into a
  * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
@@ -92,5 +119,5 @@ export interface ScatterChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function ScatterChart<S extends SeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, index, }: ScatterChartProps<S>): null;
+export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, index, }: ScatterChartProps<S, VS>): null;
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/ScatterChart.js

@@ -1,11 +1,13 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { fromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { fromTimeSeries, fromValueSeries } from './data.js';
 import { drawScatter, hitTestScatter, nearestIndex, scatterExtent, } from './scatter.js';
 import { resolveEncoding, } from './encoding.js';
 import { ContainerContext, LayersContext } from './context.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
- * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * A scatter draw layer: one mark per finite point at `(x, column-value)`
+ * — x from the series' key / axis column (time or value axis) —
  * with **data-driven radius + colour** (the signed-off exception — encode from
  * columns via scales, not a per-event style callback). Reads `column` into a
  * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
@@ -31,7 +33,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, index = 0, }) {
+export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
@@ -40,7 +42,9 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     if (layers === null) {
         throw new Error('<ScatterChart> must be rendered inside a <Layers>');
     }
-    const cs = useMemo(() => fromTimeSeries(series, column), [series, column]);
+    const cs = useMemo(() => series instanceof ValueSeries
+        ? fromValueSeries(series, column)
+        : fromTimeSeries(series, column), [series, column]);
     // Styling: semantic identifier → theme scatter style. The single styling
     // channel for the base mark.
     const { scatter } = container.theme;
@@ -53,13 +57,26 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     // pulls a named numeric column to a Float64Array (gaps NaN) — the same path
     // fromTimeSeries uses; an unknown / non-numeric column throws there (eager,
     // so a typo surfaces at render, not silently as base-styled points).
-    const encoding = useMemo(() => resolveEncoding(cs, style.radius, style.color, radius, color, (col) => fromTimeSeries(series, col).y), [cs, style.radius, style.color, radius, color, series]);
+    const encoding = useMemo(() => resolveEncoding(cs, style.radius, style.color, radius, color, (col) => series instanceof ValueSeries
+        ? fromValueSeries(series, col).y
+        : fromTimeSeries(series, col).y), [cs, style.radius, style.color, radius, color, series]);
     // Per-point label accessor: a column name reads that field, `true` reads the
     // plotted column, anything else (false / omitted) ⇒ no labels.
     const labelAt = useMemo(() => {
         if (label === undefined || label === false)
             return undefined;
         const field = label === true ? column : label;
+        if (series instanceof ValueSeries) {
+            // Columnar read — a ValueSeries has no per-row events. The field is a
+            // runtime string, cast onto the schema-literal column name (the same
+            // pattern as data.ts' readValueColumn). A gap or an unknown column reads
+            // undefined => no label at that point.
+            const col = series.column(field);
+            return (i) => {
+                const v = col?.read(i);
+                return v === undefined || v === null ? undefined : String(v);
+            };
+        }
         return (i) => {
             // series.at(i) is O(1) per row (columnar eventAt cache), so a label per
             // point stays cheap. The field is a runtime string → cast off the literal-
@@ -71,26 +88,28 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
             return v === undefined || v === null ? undefined : String(v);
         };
     }, [label, column, series]);
-    // The point's stable key is its event begin (epoch ms) — the same as cs.x[i],
-    // which is the key column's begin buffer. Used for selection identity.
+    // The point's stable key is its x — the event begin (epoch ms) on a time
+    // axis, the axis value on a value axis; either way it's cs.x[i], the key
+    // column's begin buffer. Used for selection identity.
     const keyAt = useMemo(() => (i) => cs.x[i], [cs]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => scatterExtent(cs),
-            xKind: 'time',
+            // The container infers the shared x scale's kind + auto-fit domain from
+            // its layers: a ValueSeries scatters on a value axis, a TimeSeries on time.
+            xKind: series instanceof ValueSeries ? 'value' : 'time',
             xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
-            sampleAt: (time) => {
+            sampleAt: (x) => {
                 // No readout past the data (tracker policy — the dot snaps to a drawn
-                // mark, never extrapolates past the span); bounds from the time axis.
-                if (cs.length === 0 ||
-                    time < cs.x[0] ||
-                    time > cs.x[cs.length - 1]) {
+                // mark, never extrapolates past the span); bounds from the columnar x
+                // axis (epoch ms or axis value — the bisect doesn't care).
+                if (cs.length === 0 || x < cs.x[0] || x > cs.x[cs.length - 1]) {
                     return [];
                 }
                 // Nearest *drawn* point by index (skips gaps) — O(log N). Reading by
                 // index gives the value, the snap-to x, and the encoded colour in one
                 // shot, so the readout swatch matches the mark the user sees.
-                const i = nearestIndex(cs, time);
+                const i = nearestIndex(cs, x);
                 if (i < 0)
                     return [];
                 return [
@@ -108,9 +127,9 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
             ...(id === undefined
                 ? {}
                 : {
-                    hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel),
+                    hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel, offset),
                 }),
-            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id, offset),
         },
         axisId: axis,
         index,
@@ -126,6 +145,7 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
         labelAt,
         font,
         container.selected,
+        offset,
         axis,
         index,
     ]);

package/dist/box.d.ts

@@ -3,9 +3,10 @@ import type { Scale } from './line.js';
 import type { BoxStyle } from './theme.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
- * whisker and highest `upper` whisker over keys where **all five** quantiles are
- * finite — or `null` if none are. Gap keys (any quantile `NaN`) are excluded,
- * matching what {@link drawBox} draws, so they don't drag the y-domain.
+ * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
+ * (a full box needs all five quantiles; a range-only box just `lower`/`upper`) —
+ * or `null` if none are. Gap keys are excluded, matching what {@link drawBox}
+ * draws, so they don't drag the y-domain.
  *
  * Only `lower`/`upper` bound the extent: they are the outermost reach of a key
  * (the whisker ends), so `q1`/`median`/`q3` lie within `[lower, upper]` for any
@@ -44,16 +45,32 @@ export type BoxShape = 'whisker' | 'solid' | 'none';
  *   reads darker on a light ground, brighter on a dark one), no stems/outline.
  * - **`none`** — the `q1→q3` box fill + outline only, no spread marks.
  *
- * Then, if `showMedian`, the median line across the box on top. Fills are
- * bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * **Range-only** (`box.hasBox === false` — no `q1`/`q3`): there's no body, so
+ * `whisker` draws **one** full `lower→upper` stem with caps, `solid` draws just
+ * the outer bar, and `none` draws **nothing** (no body + no spread ⇒ empty — pick
+ * `whisker`/`solid` for a range-only box). `showMedian` is a no-op when the box
+ * carries no `median` (`hasMedian === false`).
  *
- * **Gap-aware**: a key with any quantile non-finite is skipped entirely (no
- * partial box) — the same contract as a band gap.
+ * Then, if `showMedian` (and a median is present), the median line on top. Fills
+ * are bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * `offsetPx` shifts every mark in pixel space (for pairing same-key marks);
+ * `capWidthPx` sets a fixed whisker-cap width (else half the box width — a small
+ * fixed cap keeps paired offset marks' T-bars from overlapping), clamped to the
+ * box width.
+ *
+ * **Gap-aware**: a key whose present quantiles aren't all finite is skipped
+ * entirely (no partial box) — the same contract as a band gap.
  *
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean): void;
-/** All five quantiles finite at `i` — i.e. this key is drawn. */
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number): void;
+/**
+ * This key is drawable — the quantiles it actually carries are all finite at `i`.
+ * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the
+ * box has a body (`hasBox !== false`), `median` only when it has a centre line
+ * (`hasMedian !== false`). So a **range-only** box (bid→ask, no body/median) draws
+ * wherever `lower`/`upper` are finite, and a full box still needs all five.
+ */
 export declare function isFiniteBox(box: BoxSeries, i: number): boolean;
 //# sourceMappingURL=box.d.ts.map

package/dist/box.js

@@ -3,9 +3,10 @@ import { barSpanPx } from './range.js';
 const WHISKER_CAP_FRACTION = 0.5;
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
- * whisker and highest `upper` whisker over keys where **all five** quantiles are
- * finite — or `null` if none are. Gap keys (any quantile `NaN`) are excluded,
- * matching what {@link drawBox} draws, so they don't drag the y-domain.
+ * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
+ * (a full box needs all five quantiles; a range-only box just `lower`/`upper`) —
+ * or `null` if none are. Gap keys are excluded, matching what {@link drawBox}
+ * draws, so they don't drag the y-domain.
  *
  * Only `lower`/`upper` bound the extent: they are the outermost reach of a key
  * (the whisker ends), so `q1`/`median`/`q3` lie within `[lower, upper]` for any
@@ -56,70 +57,101 @@ export function boxIndexAtTime(box, time) {
  *   reads darker on a light ground, brighter on a dark one), no stems/outline.
  * - **`none`** — the `q1→q3` box fill + outline only, no spread marks.
  *
- * Then, if `showMedian`, the median line across the box on top. Fills are
- * bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * **Range-only** (`box.hasBox === false` — no `q1`/`q3`): there's no body, so
+ * `whisker` draws **one** full `lower→upper` stem with caps, `solid` draws just
+ * the outer bar, and `none` draws **nothing** (no body + no spread ⇒ empty — pick
+ * `whisker`/`solid` for a range-only box). `showMedian` is a no-op when the box
+ * carries no `median` (`hasMedian === false`).
  *
- * **Gap-aware**: a key with any quantile non-finite is skipped entirely (no
- * partial box) — the same contract as a band gap.
+ * Then, if `showMedian` (and a median is present), the median line on top. Fills
+ * are bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * `offsetPx` shifts every mark in pixel space (for pairing same-key marks);
+ * `capWidthPx` sets a fixed whisker-cap width (else half the box width — a small
+ * fixed cap keeps paired offset marks' T-bars from overlapping), clamped to the
+ * box width.
+ *
+ * **Gap-aware**: a key whose present quantiles aren't all finite is skipped
+ * entirely (no partial box) — the same contract as a band gap.
  *
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true) {
+export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true, offsetPx = 0, capWidthPx) {
+    // A range-only box (bid→ask segment) has no body / median; the whisker (or the
+    // solid bar) runs the full lower→upper. Flags default true (a full box).
+    const hasBox = box.hasBox !== false;
+    const drawMedian = showMedian && box.hasMedian !== false;
     for (let i = 0; i < box.length; i += 1) {
         if (!isFiniteBox(box, i))
             continue;
-        const [x0, x1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
+        const [span0, span1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
+        // `offsetPx` nudges the whole mark in pixel space (zoom-stable) — for pairing
+        // same-key marks (call/put at one strike) side by side without overlap.
+        const x0 = span0 + offsetPx;
+        const x1 = span1 + offsetPx;
         const mid = (x0 + x1) / 2;
         const yLower = yScale(box.lower[i]);
-        const yQ1 = yScale(box.q1[i]);
-        const yMedian = yScale(box.median[i]);
-        const yQ3 = yScale(box.q3[i]);
         const yUpper = yScale(box.upper[i]);
+        // q1/q3 are NaN on a range-only box — read them only when there's a body.
+        const yQ1 = hasBox ? yScale(box.q1[i]) : 0;
+        const yQ3 = hasBox ? yScale(box.q3[i]) : 0;
         if (shape === 'solid') {
-            // Candlestick: a light outer bar over the full lower→upper spread, then a
-            // more-prominent inner q1→q3 box on top (same fill at rising opacity, so the
-            // inner reads darker on a light ground / brighter on a dark one). No stems,
-            // no outline.
+            // Candlestick: a light outer bar over the full lower→upper spread, then —
+            // when there's a body — a more-prominent inner q1→q3 box on top (same fill
+            // at rising opacity). No stems, no outline.
             ctx.save();
             ctx.fillStyle = style.fill;
             ctx.globalAlpha = style.fillOpacity;
             ctx.fillRect(x0, yUpper, x1 - x0, yLower - yUpper);
-            ctx.globalAlpha = Math.min(1, style.fillOpacity * 2);
-            ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            if (hasBox) {
+                ctx.globalAlpha = Math.min(1, style.fillOpacity * 2);
+                ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            }
             ctx.restore();
         }
         else {
-            // `whisker` / `none`: the graded q1→q3 box fill + outline.
-            ctx.save();
-            ctx.fillStyle = style.fill;
-            ctx.globalAlpha = style.fillOpacity;
-            ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
-            ctx.restore();
-            ctx.strokeStyle = style.stroke;
-            ctx.lineWidth = style.strokeWidth;
-            ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            // `whisker` / `none`: the graded q1→q3 box fill + outline (body only).
+            if (hasBox) {
+                ctx.save();
+                ctx.fillStyle = style.fill;
+                ctx.globalAlpha = style.fillOpacity;
+                ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+                ctx.restore();
+                ctx.strokeStyle = style.stroke;
+                ctx.lineWidth = style.strokeWidth;
+                ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            }
             if (shape === 'whisker') {
-                // Whiskers: a stem from each box edge to the whisker end, with a cap.
-                const capHalf = ((x1 - x0) * WHISKER_CAP_FRACTION) / 2;
+                // Whiskers with end-caps. With a body: two stems (q3→upper, q1→lower).
+                // Range-only (no body): one stem spanning the full lower→upper.
+                // Cap half-width: an explicit `capWidthPx` (a fixed pixel cap — for
+                // pairing offset marks without their T-bars overlapping) else a fraction
+                // of the box width (responsive default). Never wider than the box.
+                const capHalf = capWidthPx !== undefined
+                    ? Math.min(capWidthPx, x1 - x0) / 2
+                    : ((x1 - x0) * WHISKER_CAP_FRACTION) / 2;
                 ctx.strokeStyle = style.whisker;
                 ctx.lineWidth = style.whiskerWidth;
                 ctx.beginPath();
-                // Upper: stem q3 → upper, cap at upper.
-                ctx.moveTo(mid, yQ3);
+                // Upper stem: from the box top (q3) or, range-only, from lower.
+                ctx.moveTo(mid, hasBox ? yQ3 : yLower);
                 ctx.lineTo(mid, yUpper);
                 ctx.moveTo(mid - capHalf, yUpper);
                 ctx.lineTo(mid + capHalf, yUpper);
-                // Lower: stem q1 → lower, cap at lower.
-                ctx.moveTo(mid, yQ1);
-                ctx.lineTo(mid, yLower);
+                // Lower cap (and, with a body, the lower stem q1→lower).
+                if (hasBox) {
+                    ctx.moveTo(mid, yQ1);
+                    ctx.lineTo(mid, yLower);
+                }
                 ctx.moveTo(mid - capHalf, yLower);
                 ctx.lineTo(mid + capHalf, yLower);
                 ctx.stroke();
             }
         }
-        // The median line across the box, on top — always optional.
-        if (showMedian) {
+        // The median line across the box, on top — drawn only when the box carries a
+        // median column and `showMedian` is on.
+        if (drawMedian) {
+            const yMedian = yScale(box.median[i]);
             ctx.strokeStyle = style.median;
             ctx.lineWidth = style.medianWidth;
             ctx.beginPath();
@@ -129,12 +161,24 @@ export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx =
         }
     }
 }
-/** All five quantiles finite at `i` — i.e. this key is drawn. */
+/**
+ * This key is drawable — the quantiles it actually carries are all finite at `i`.
+ * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the
+ * box has a body (`hasBox !== false`), `median` only when it has a centre line
+ * (`hasMedian !== false`). So a **range-only** box (bid→ask, no body/median) draws
+ * wherever `lower`/`upper` are finite, and a full box still needs all five.
+ */
 export function isFiniteBox(box, i) {
-    return (Number.isFinite(box.lower[i]) &&
-        Number.isFinite(box.q1[i]) &&
-        Number.isFinite(box.median[i]) &&
-        Number.isFinite(box.q3[i]) &&
-        Number.isFinite(box.upper[i]));
+    if (!Number.isFinite(box.lower[i]) || !Number.isFinite(box.upper[i])) {
+        return false;
+    }
+    if (box.hasBox !== false &&
+        (!Number.isFinite(box.q1[i]) || !Number.isFinite(box.q3[i]))) {
+        return false;
+    }
+    if (box.hasMedian !== false && !Number.isFinite(box.median[i])) {
+        return false;
+    }
+    return true;
 }
 //# sourceMappingURL=box.js.map

package/dist/context.d.ts

@@ -1,7 +1,7 @@
 import type { ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
-import type { Interval, TimeRange } from 'pond-ts';
+import type { Interval } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
 import type { ScaleBand } from './bandScale.js';
 /**
@@ -75,22 +75,28 @@ export interface ContainerFrame {
      */
     readonly cursorBuckets: readonly Interval[] | undefined;
     /**
-     * The `region`-cursor **drag anchor** (epoch ms), or `null` when not dragging.
-     * A drag on a region cursor (only when {@link onRegionSelect} is set) records
-     * the press time here; the band then spans from the anchor's bucket to the
-     * pointer's bucket (extending bucket by bucket). Cleared on release.
+     * The `region`-cursor **drag anchor** in axis units (epoch ms on a time axis,
+     * the axis value on a value axis), or `null` when not dragging. A drag on a
+     * region cursor (only when {@link onRegionSelect} is set) records the press
+     * position here; the band then spans from the anchor's bucket to the pointer's
+     * bucket (extending bucket by bucket), or freeform when there are no buckets.
+     * Cleared on release.
      */
     readonly regionAnchor: number | null;
     /** Set / clear the region-drag anchor (see {@link regionAnchor}). */
-    setRegionAnchor(time: number | null): void;
+    setRegionAnchor(value: number | null): void;
     /**
      * One-shot callback fired when a `region`-cursor **drag** is released, with the
-     * selected `[start, end)` `TimeRange` (snapped to the `cursorSequence` buckets).
+     * selected `[lo, hi]` span in **axis units** — epoch ms on a time axis, the axis
+     * value on a value axis (snapped to the `cursorSequence` buckets when present,
+     * else the raw drag span). The neutral numeric pair mirrors the container's
+     * polymorphic `range` input (which never takes the axis *kind* from its value);
+     * a time-axis consumer who wants a `TimeRange` constructs one from the pair.
      * Providing it is what makes the region cursor **draggable**; the cursor does
      * not keep the range (it reverts to the single-bucket highlight). Typical use:
-     * zoom the view to the returned range.
+     * zoom the view, or map the span onto a subscription's range params.
      */
-    readonly onRegionSelect: ((range: TimeRange) => void) | undefined;
+    readonly onRegionSelect: ((range: readonly [number, number]) => void) | undefined;
     /**
      * Require a modifier key held to start a region-drag — set to `'shift'` to make
      * plain drag **pan** and **shift**-drag select, when `panZoom` is on. Only
@@ -369,6 +375,17 @@ export interface RowLayer {
      * must agree on this list (a mix is an error), the same way {@link xKind} must.
      */
     xCategories?(): readonly string[] | null;
+    /**
+     * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
+     * **region cursor's snap buckets**. When present (and no `cursorSequence` is
+     * set), a region drag snaps bar by bar and a hover highlights the bar under the
+     * pointer, so a histogram gets bin-aligned selection for free. Only a
+     * **vertical** bar layer on a **continuous** (time / value) x axis publishes
+     * them — a horizontal chart puts the value on x (snapping counts is meaningless)
+     * and a **category** (ordinal-slot) axis is excluded from the region cursor.
+     * `null` / absent otherwise.
+     */
+    binIntervals?(): readonly Interval[] | null;
     /**
      * The layer's value(s) at `time` — the nearest sample — for the scrub tracker:
      * one for a line, two (lower/upper) for a band, empty at a gap. Each carries
@@ -442,6 +459,8 @@ export interface TrackerSource {
     xExtent(): readonly [number, number] | null;
     /** A `'category'` source's ordered category names (see {@link RowLayer.xCategories}). */
     xCategories?(): readonly string[] | null;
+    /** A bar/histogram source's bar `[begin, end)` spans (see {@link RowLayer.binIntervals}). */
+    binIntervals?(): readonly Interval[] | null;
 }
 /**
  * One selection — what {@link RowLayer.hitTest} returns and `onSelect` reports.