@pond-ts/charts 0.43.0 → 0.44.1

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
@@ -145,6 +151,17 @@ export interface ContainerFrame {
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
      *  shared by `<TimeAxis>` and the cursor-time readout. */
     readonly formatTime: (epochMs: number) => string;
+    /**
+     * The shared **x-side tick count** — the `count` every x-side `ticks()` /
+     * `tickFormat()` call passes (`<XAxis>` labels, the canvas x gridlines and
+     * session dividers, {@link formatTime}), so labels, grid, and dividers all
+     * derive from the same instants. A fixed default on a continuous axis;
+     * **width-derived on a trading-time axis**, where the count caps how many
+     * calendar buckets `coarsenCalendar` may keep — a fixed small count would
+     * coarsen any long daily view to year grain (2 ticks) no matter how wide
+     * the plot is.
+     */
+    readonly xTickCount: number;
     /**
      * Register a draw layer as a tracker source so the container can fan in every
      * series' value at the cursor for `onTrackerChanged`. Keyed by the layer's
@@ -369,6 +386,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 +470,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.

package/dist/data.d.ts

@@ -30,19 +30,30 @@ export interface BandSeries {
     readonly length: number;
 }
 /**
- * A chart-ready view of a box-and-whisker series ({@link BoxPlot}): the
- * interval-keyed time axis (`x` = key `begin`, `xEnd` = key `end`, the box's
- * horizontal span) plus the five quantile edges per key —
- * `lower`/`q1`/`median`/`q3`/`upper`. The quantiles are pre-computed columns
- * (a `rolling`/`aggregate` percentile pass upstream); the chart only reads them.
- *
- * A key is drawn only where **all five** quantiles are finite; any one `NaN` is
- * a gap (the box draws nothing — same gap contract as {@link BandSeries}).
- *
- * `x` and `xEnd` are zero-copy views of the key column's `begin`/`end` buffers
- * (immutable by contract — do not mutate). For a point-in-time key the column's
- * `end` coincides with `begin`, so `xEnd === x` and the box collapses to a
- * minimum-width mark via `barSpanPx`; an interval key gives the box real width.
+ * A chart-ready view of a box-and-whisker series ({@link BoxPlot}): a horizontal
+ * span (`x`/`xEnd`) per key plus its quantile edges — the required
+ * `lower`/`upper` (whisker reach) and the optional `q1`/`median`/`q3` (box body +
+ * centre line). The quantiles are pre-computed columns (a `rolling`/`aggregate`
+ * percentile pass upstream); the chart only reads them.
+ *
+ * A key is drawn only where the quantiles it **carries** are all finite (a full
+ * box needs all five; a range-only box just `lower`/`upper`); any present one
+ * `NaN` is a gap (the box draws nothing — same gap contract as {@link BandSeries}).
+ *
+ * `x` and `xEnd` are the box's horizontal span. An **interval**-keyed
+ * `TimeSeries` uses the key's own `[begin, end)`; a **point**-keyed `TimeSeries`
+ * (or a `ValueSeries`, always point-keyed on its value axis) synthesizes the span
+ * from **neighbour spacing** (each box centred on its key, reaching halfway to
+ * each neighbour — the same rule as bars / candles), so a point series still gets
+ * real box width instead of collapsing to the 1px floor.
+ *
+ * **Range-only boxes.** `q1`/`median`/`q3` are optional at the source (a bid→ask
+ * IV segment is a degenerate box — whiskers only, no body). `hasBox` is `false`
+ * when `q1`/`q3` were omitted (no box body; the whisker runs the full
+ * `lower→upper`), and `hasMedian` is `false` when `median` was omitted (no centre
+ * line). Absent quantile buffers are all-`NaN`; the flags — not the buffers —
+ * decide what draws, so an absent quantile isn't confused with a per-row gap.
+ * Both default to `true` (a full five-number box) when unset.
  */
 export interface BoxSeries {
     readonly x: Float64Array;
@@ -53,6 +64,10 @@ export interface BoxSeries {
     readonly q3: Float64Array;
     readonly upper: Float64Array;
     readonly length: number;
+    /** `false` ⇒ `q1`/`q3` absent (range-only box, no body). Default `true`. */
+    readonly hasBox?: boolean;
+    /** `false` ⇒ `median` absent (no centre line). Default `true`. */
+    readonly hasMedian?: boolean;
 }
 /**
  * A chart-ready view of an OHLC series ({@link Candlestick}): the candle's
@@ -131,17 +146,23 @@ export interface StackedBarSeries {
      */
     readonly marks?: readonly string[];
 }
-/** The five quantile column names a {@link boxFromTimeSeries} reads, in order. */
+/**
+ * The quantile column names a {@link boxFromTimeSeries} / {@link boxFromValueSeries}
+ * reads. `lower`/`upper` (the whisker reach) are required; `q1`/`q3` (the box
+ * body) and `median` (the centre line) are **optional** — omit them for a
+ * range-only box (a bid→ask IV segment: whiskers only, no body). Omitting exactly
+ * one of `q1`/`q3` is a data error (a box needs both edges or neither).
+ */
 export interface BoxColumns {
-    /** Lower whisker end (e.g. `p5` / `min`). */
+    /** Lower whisker end (e.g. `p5` / `min`). Required. */
     readonly lower: string;
-    /** Box bottom — first quartile (e.g. `p25`). */
-    readonly q1: string;
-    /** Median line inside the box (e.g. `p50`). */
-    readonly median: string;
-    /** Box top — third quartile (e.g. `p75`). */
-    readonly q3: string;
-    /** Upper whisker end (e.g. `p95` / `max`). */
+    /** Box bottom — first quartile (e.g. `p25`). Omit with `q3` for a range-only box. */
+    readonly q1?: string | undefined;
+    /** Median line inside the box (e.g. `p50`). Omit for no centre line. */
+    readonly median?: string | undefined;
+    /** Box top — third quartile (e.g. `p75`). Omit with `q1` for a range-only box. */
+    readonly q3?: string | undefined;
+    /** Upper whisker end (e.g. `p95` / `max`). Required. */
     readonly upper: string;
 }
 /** The four OHLC column names {@link ohlcFromTimeSeries} reads. */
@@ -205,16 +226,38 @@ export declare function bandFromTimeSeries<S extends SeriesSchema>(series: TimeS
  */
 export declare function bandFromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, lower: string, upper: string): BandSeries;
 /**
- * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
- * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
- * axis (`begin`/`end`, the box's horizontal span). The quantile columns are
- * typically `rolling`/`aggregate` percentiles (e.g. p5/p25/p50/p75/p95); a key
- * with any quantile missing reads as a gap (the box draws nothing).
- *
- * @throws RangeError if any quantile column does not exist.
- * @throws TypeError if any quantile column is not a numeric column.
+ * Build a {@link BoxSeries} from a pond `TimeSeries`. `lower`/`upper` (the whisker
+ * reach) are required; `q1`/`q3` (the box body) and `median` (the centre line)
+ * are optional — omit them for a **range-only** box (a bid→ask segment). The
+ * quantile columns are typically `rolling`/`aggregate` percentiles; a key with
+ * any **present** quantile missing reads as a gap (the box draws nothing).
+ *
+ * **Key-shape aware, like {@link ohlcFromTimeSeries}.** An **interval /
+ * timeRange**-keyed series uses the key's own `[begin, end)` as the box span; a
+ * **point**-keyed (`time`) series synthesizes the span from neighbour spacing
+ * (each box centred on its timestamp, halfway to each neighbour), so a raw
+ * percentile-per-timestamp feed renders as contiguous boxes instead of collapsing
+ * to the 1px floor.
+ *
+ * @throws RangeError if any named quantile column does not exist, or if exactly
+ *   one of `q1`/`q3` is given.
+ * @throws TypeError if any named quantile column is not a numeric column.
  */
 export declare function boxFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: BoxColumns): BoxSeries;
+/**
+ * Build a {@link BoxSeries} from a pond `ValueSeries` — the value-axis sibling of
+ * {@link boxFromTimeSeries} (a volatility smile's per-strike bid/ask IV segments,
+ * a per-strike intraday IV distribution). A `ValueSeries` is **point-keyed** on
+ * its value axis, so the box span comes from **neighbour spacing** on
+ * `axisValues()` (each box centred on its axis value, halfway to each neighbour —
+ * the same rule as {@link barsFromValueSeries}), instead of collapsing to a point.
+ * Same optional-quantile / range-only contract as the time reader.
+ *
+ * @throws RangeError if any named quantile column does not exist, or if exactly
+ *   one of `q1`/`q3` is given.
+ * @throws TypeError if any named quantile column is not a numeric column.
+ */
+export declare function boxFromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, columns: BoxColumns): BoxSeries;
 /**
  * Build an {@link OhlcSeries} from a pond `TimeSeries` — four numeric price
  * columns (`open`/`high`/`low`/`close`) plus the candle's horizontal slot.

package/dist/data.js

@@ -65,14 +65,6 @@ function timeAxis(series) {
     // it lines up with the value arrays.
     return series.keyColumn().begin.subarray(0, series.length);
 }
-/**
- * The key column's `end` buffer aligned to the logical length (zero-copy). For a
- * point-in-time key the column sets `end === begin`, so this returns the same
- * timestamps as {@link timeAxis} — an interval key gives a distinct span.
- */
-function timeEndAxis(series) {
-    return series.keyColumn().end.subarray(0, series.length);
-}
 /**
  * Build a {@link ChartSeries} from a pond `TimeSeries` by reading its columnar
  * buffers directly — no per-event materialization. `column` names a numeric
@@ -150,25 +142,91 @@ export function bandFromValueSeries(series, lower, upper) {
     };
 }
 /**
- * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
- * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
- * axis (`begin`/`end`, the box's horizontal span). The quantile columns are
- * typically `rolling`/`aggregate` percentiles (e.g. p5/p25/p50/p75/p95); a key
- * with any quantile missing reads as a gap (the box draws nothing).
+ * Reject a half-specified box body — `q1`/`q3` are both-or-neither (a box needs
+ * two edges or none). Called by both box readers before they build.
+ */
+function validateBoxColumns(columns) {
+    if ((columns.q1 === undefined) !== (columns.q3 === undefined)) {
+        throw new RangeError(`BoxPlot: 'q1' and 'q3' are both-or-neither — a box body needs both edges ` +
+            `(got q1=${columns.q1 ?? 'undefined'}, q3=${columns.q3 ?? 'undefined'}). ` +
+            `Omit both for a range-only box (whiskers lower→upper).`);
+    }
+}
+/** An all-`NaN` buffer of length `n` — the value channel of an absent quantile. */
+function nanBuffer(n) {
+    return new Float64Array(n).fill(NaN);
+}
+/**
+ * Build a {@link BoxSeries} from a pond `TimeSeries`. `lower`/`upper` (the whisker
+ * reach) are required; `q1`/`q3` (the box body) and `median` (the centre line)
+ * are optional — omit them for a **range-only** box (a bid→ask segment). The
+ * quantile columns are typically `rolling`/`aggregate` percentiles; a key with
+ * any **present** quantile missing reads as a gap (the box draws nothing).
  *
- * @throws RangeError if any quantile column does not exist.
- * @throws TypeError if any quantile column is not a numeric column.
+ * **Key-shape aware, like {@link ohlcFromTimeSeries}.** An **interval /
+ * timeRange**-keyed series uses the key's own `[begin, end)` as the box span; a
+ * **point**-keyed (`time`) series synthesizes the span from neighbour spacing
+ * (each box centred on its timestamp, halfway to each neighbour), so a raw
+ * percentile-per-timestamp feed renders as contiguous boxes instead of collapsing
+ * to the 1px floor.
+ *
+ * @throws RangeError if any named quantile column does not exist, or if exactly
+ *   one of `q1`/`q3` is given.
+ * @throws TypeError if any named quantile column is not a numeric column.
  */
 export function boxFromTimeSeries(series, columns) {
+    validateBoxColumns(columns);
+    const n = series.length;
+    const hasBox = columns.q1 !== undefined;
+    const hasMedian = columns.median !== undefined;
+    const { begin, end } = series.keyColumn().kind !== 'time'
+        ? keyBeginEnd(series) // interval / timeRange: the key's own span
+        : neighbourSpans(series.keyColumn().begin, n); // point: neighbour spacing
     return {
-        x: timeAxis(series),
-        xEnd: timeEndAxis(series),
+        x: begin,
+        xEnd: end,
         lower: readNumericColumn(series, columns.lower),
-        q1: readNumericColumn(series, columns.q1),
-        median: readNumericColumn(series, columns.median),
-        q3: readNumericColumn(series, columns.q3),
+        q1: hasBox ? readNumericColumn(series, columns.q1) : nanBuffer(n),
+        median: hasMedian
+            ? readNumericColumn(series, columns.median)
+            : nanBuffer(n),
+        q3: hasBox ? readNumericColumn(series, columns.q3) : nanBuffer(n),
         upper: readNumericColumn(series, columns.upper),
-        length: series.length,
+        length: n,
+        hasBox,
+        hasMedian,
+    };
+}
+/**
+ * Build a {@link BoxSeries} from a pond `ValueSeries` — the value-axis sibling of
+ * {@link boxFromTimeSeries} (a volatility smile's per-strike bid/ask IV segments,
+ * a per-strike intraday IV distribution). A `ValueSeries` is **point-keyed** on
+ * its value axis, so the box span comes from **neighbour spacing** on
+ * `axisValues()` (each box centred on its axis value, halfway to each neighbour —
+ * the same rule as {@link barsFromValueSeries}), instead of collapsing to a point.
+ * Same optional-quantile / range-only contract as the time reader.
+ *
+ * @throws RangeError if any named quantile column does not exist, or if exactly
+ *   one of `q1`/`q3` is given.
+ * @throws TypeError if any named quantile column is not a numeric column.
+ */
+export function boxFromValueSeries(series, columns) {
+    validateBoxColumns(columns);
+    const n = series.length;
+    const hasBox = columns.q1 !== undefined;
+    const hasMedian = columns.median !== undefined;
+    const { begin, end } = neighbourSpans(series.axisValues(), n);
+    return {
+        x: begin,
+        xEnd: end,
+        lower: readValueColumn(series, columns.lower),
+        q1: hasBox ? readValueColumn(series, columns.q1) : nanBuffer(n),
+        median: hasMedian ? readValueColumn(series, columns.median) : nanBuffer(n),
+        q3: hasBox ? readValueColumn(series, columns.q3) : nanBuffer(n),
+        upper: readValueColumn(series, columns.upper),
+        length: n,
+        hasBox,
+        hasMedian,
     };
 }
 /**

package/dist/format.d.ts

@@ -42,8 +42,10 @@ interface TimeTickable {
  * - a **function** → used as-is (called with epoch ms);
  * - a **specifier string** → `scale.tickFormat(count, specifier)` (one format for
  *   every value), wrapped to take epoch ms;
- * - **`undefined`** → `scale.tickFormat()` — d3's **multi-scale** time format (the
- *   time axis's default; no `count` so it matches `<TimeAxis>` exactly).
+ * - **`undefined`** → `scale.tickFormat(count)` — the scale's default. On a d3
+ *   `scaleTime` that is the **multi-scale** time format (which ignores `count`);
+ *   a trading-time scale picks its **anchor grain** from `count`, so passing the
+ *   axis's count here is what keeps the labels on the same grain as the ticks.
  *
  * The cursor time is epoch ms, so the resolved formatter wraps the d3 `Date`
  * formatter in `new Date(ms)`.

package/dist/format.js

@@ -32,8 +32,10 @@ export function resolveAxisFormat(scale, count, format) {
  * - a **function** → used as-is (called with epoch ms);
  * - a **specifier string** → `scale.tickFormat(count, specifier)` (one format for
  *   every value), wrapped to take epoch ms;
- * - **`undefined`** → `scale.tickFormat()` — d3's **multi-scale** time format (the
- *   time axis's default; no `count` so it matches `<TimeAxis>` exactly).
+ * - **`undefined`** → `scale.tickFormat(count)` — the scale's default. On a d3
+ *   `scaleTime` that is the **multi-scale** time format (which ignores `count`);
+ *   a trading-time scale picks its **anchor grain** from `count`, so passing the
+ *   axis's count here is what keeps the labels on the same grain as the ticks.
  *
  * The cursor time is epoch ms, so the resolved formatter wraps the d3 `Date`
  * formatter in `new Date(ms)`.
@@ -41,7 +43,9 @@ export function resolveAxisFormat(scale, count, format) {
 export function resolveTimeFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
-    const tf = format !== undefined ? scale.tickFormat(count, format) : scale.tickFormat();
+    const tf = format !== undefined
+        ? scale.tickFormat(count, format)
+        : scale.tickFormat(count);
     return (ms) => tf(new Date(ms));
 }
 //# sourceMappingURL=format.js.map

package/dist/scatter.d.ts

@@ -52,7 +52,7 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
 export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: ScatterStyle, encoding: ResolvedEncoding, keyAt: (i: number) => number, labelAt: ((i: number) => string | undefined) | undefined, font: {
     readonly family: string;
     readonly size: number;
-}, selected: SelectInfo | null, seriesId: string | undefined): void;
+}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number): void;
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the
@@ -68,5 +68,5 @@ export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeri
  * Pure: takes the same `xScale`/`yScale` the row hands to `draw`, so it
  * unit-tests without a DOM (mirrors the `sampleAt` / `resolveSelection` split).
  */
-export declare function hitTestScatter(cs: ChartSeries, qx: number, qy: number, xScale: Scale, yScale: Scale, encoding: ResolvedEncoding, keyAt: (i: number) => number, id: string, seriesLabel: string): SelectInfo | null;
+export declare function hitTestScatter(cs: ChartSeries, qx: number, qy: number, xScale: Scale, yScale: Scale, encoding: ResolvedEncoding, keyAt: (i: number) => number, id: string, seriesLabel: string, offsetPx?: number): SelectInfo | null;
 //# sourceMappingURL=scatter.d.ts.map

package/dist/scatter.js

@@ -114,7 +114,7 @@ export function scatterExtent(cs) {
  *                of the selection match. A point lights only when the selection's
  *                `id` matches, keyed to the sample by its `key`.
  */
-export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId) {
+export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0) {
     ctx.save();
     // The selection only lights up a point of *this* series; resolve the key once.
     // A no-id (non-selectable) layer passes `undefined` and never matches.
@@ -126,7 +126,9 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
     for (let i = 0; i < cs.length; i += 1) {
         if (!isPoint(cs, i))
             continue;
-        const px = xScale(cs.x[i]);
+        // `offsetPx` nudges the whole scatter in pixel space (zoom-stable) — for
+        // pairing same-key marks (call/put at one strike) beside each other.
+        const px = xScale(cs.x[i]) + offsetPx;
         const py = yScale(cs.y[i]);
         const r = encoding.radiusAt(i);
         ctx.beginPath();
@@ -166,7 +168,7 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
             const text = labelAt(i);
             if (text === undefined || text === '')
                 continue;
-            const px = xScale(cs.x[i]);
+            const px = xScale(cs.x[i]) + offsetPx;
             const py = yScale(cs.y[i]);
             const r = encoding.radiusAt(i);
             // Sit the label just right of the point (past its radius), vertically
@@ -193,11 +195,12 @@ const LABEL_GAP = 4;
  * Pure: takes the same `xScale`/`yScale` the row hands to `draw`, so it
  * unit-tests without a DOM (mirrors the `sampleAt` / `resolveSelection` split).
  */
-export function hitTestScatter(cs, qx, qy, xScale, yScale, encoding, keyAt, id, seriesLabel) {
+export function hitTestScatter(cs, qx, qy, xScale, yScale, encoding, keyAt, id, seriesLabel, offsetPx = 0) {
     for (let i = cs.length - 1; i >= 0; i -= 1) {
         if (!isPoint(cs, i))
             continue;
-        const px = xScale(cs.x[i]);
+        // Match the drawn position (offset in px space) so the click target aligns.
+        const px = xScale(cs.x[i]) + offsetPx;
         const py = yScale(cs.y[i]);
         const r = encoding.radiusAt(i);
         const dx = qx - px;