@pond-ts/charts 0.43.0 → 0.44.1

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 tag, so this file covers them all. Pre-1.0: minor bumps may include new features
 and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.43.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.44.1...HEAD
+[0.44.1]: https://github.com/pjm17971/pond-ts/compare/v0.44.0...v0.44.1
+[0.44.0]: https://github.com/pjm17971/pond-ts/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/pjm17971/pond-ts/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...v0.42.0
 [0.41.0]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...v0.41.0
@@ -41,6 +43,108 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.44.1] — 2026-07-13
+
+A `@pond-ts/charts` patch: fixes trading-time axis tick density. `pond-ts`,
+`@pond-ts/react`, `@pond-ts/fit`, and `@pond-ts/financial` carry no code
+changes — republished in lock-step; their `^0.44.0` peer ranges already
+admit this patch.
+
+### Fixed
+
+- **charts:** trading-time axis tick density now derives from plot width
+  instead of a fixed count of 5. The trading scale's tick `count` caps how many
+  calendar buckets `coarsenCalendar` may keep, so the fixed count coarsened any
+  ≳6-month daily view to quarter or year grain — a 1-year daily chart on a
+  ~900px plot showed 2 ticks; it now lands on month grain (~12). Continuous
+  (non-trading) time and value axes keep the fixed default, unchanged. The
+  count is shared through the container frame (`xTickCount`), so axis labels,
+  x gridlines, session dividers, and the cursor-time formatter all derive from
+  the same instants — previously the label formatter anchored at the scale's
+  internal default (10) while ticks used 5, which is why sparse year-grain
+  ticks were labelled with dates (`Jun 22`) instead of years. (Tidal friction
+  report, charts 0.44.)
+
+## [0.44.0] — 2026-07-11
+
+The **value-axis charts** release: cross-sectional data (a volatility smile keyed
+by strike) becomes a first-class charting surface. `ValueSeries.fromColumns` is
+the direct columnar door; `<ScatterChart>` and `<BoxPlot>` join `<LineChart>` on
+the value axis; `<BoxPlot>` gains range-only (bid→ask) marks, `offset` pairing,
+and `capWidth`; and the region cursor works on value axes and snaps to histogram
+bins.
+
+### Added
+
+- **`<BoxPlot>` finished for the value axis + range-only marks** (`@pond-ts/charts`).
+  Four coordinated changes, driven by the volatility smile's per-strike bid/ask IV
+  segments (`docs/notes/vol-smile-followups-2026-07.md` §1):
+  - **Accepts a `ValueSeries`** (`series.byValue('strike')` /
+    `ValueSeries.fromColumns`) — boxes on a value axis, the same instanceof branch
+    as `<LineChart>` / `<ScatterChart>`. The box **width** now comes from neighbour
+    spacing for a **point** key (a `ValueSeries`, or a point-keyed `TimeSeries`) —
+    like bars/candles — instead of collapsing to the 1px floor; an interval-keyed
+    `TimeSeries` still uses its `[begin, end)`.
+  - **Optional `q1`/`median`/`q3`** — omit `q1`+`q3` for a **range-only** box: a
+    whisker-only `lower→upper` segment, no body (a bid→ask IV mark honestly named,
+    not a candlestick abuse). Omitting exactly one of `q1`/`q3` throws.
+  - **`offset` prop** (`<BoxPlot>` and `<ScatterChart>`) — a **pixel** shift for
+    pairing same-key marks (call/put at one strike) side by side, zoom-stable. On
+    the scatter it moves the draw **and** the click hit-test together; on the box
+    the readout hit-tests in un-shifted data space (keep the offset small).
+  - **`capWidth` prop** (`<BoxPlot>`) — the whisker end-cap width in **pixels**
+    (else half the box width). A small fixed cap keeps two `offset`-paired marks'
+    T-bars from overlapping when the value-axis slot is wide; clamped to the box
+    width, `'whisker'` shape only.
+  - **Readout labels** carry the series' `as` identity (`iv upper`, `iv median`)
+    when set, instead of bare column names — the `as ?? column` convention
+    Line/Scatter already use.
+- **`<ScatterChart>` accepts a `ValueSeries`** (`@pond-ts/charts`) — scatter
+  marks on the value axis, the same instanceof-branched adapter as
+  `<LineChart>` (the container infers the x kind from the data). The
+  data-driven `radius` / `color` encodings work unchanged on a value axis;
+  the per-point `label` reads through a new columnar branch (a `ValueSeries`
+  has no per-row events) — IV marks keyed by strike with open-interest
+  radius is the driving composition (vol smile). New value-axis Storybook
+  fan-out (`ValueAxis` / `ValueAxisEncoded` / `ValueAxisSmile` /
+  `ValueAxisFlag`) + Linux visual baselines.
+
+- **`ValueSeries.fromColumns({ name, schema, columns, sort? })`** (`pond-ts`) —
+  the direct columnar door into value-land, for data that is _natively_
+  value-keyed (cross-sectional): an options chain keyed by strike, a spectrum
+  keyed by frequency. Exact `TimeSeries.fromColumns` contract with the axis in
+  place of time — same polymorphic `number[]` / `Float64Array` inputs, same
+  zero-copy adoption, same stable opt-in `sort`, same gap rule — the two doors
+  share one ingest engine. Previously cross-sectional callers had to launder
+  the axis through a fake `time` column (`TimeSeries.fromColumns` +
+  `byValue`); that detour is no longer needed.
+
+- **The region cursor snaps to a histogram's bins** (`@pond-ts/charts`). On a
+  `<BarChart>` histogram, `cursor="region"` now snaps **bar by bar** with no
+  `cursorSequence`: hovering highlights the bar under the pointer, a drag extends
+  across whole bars, and `onRegionSelect` reports the selected bin range
+  `[lo, hi]` at the bar edges. The bar layer publishes its `[begin, end)` spans
+  (a new internal `binIntervals` channel) as the region cursor's snap buckets —
+  the same machinery a `cursorSequence` drives on a time axis, so it also covers a
+  time-axis histogram. Only a **vertical** bar layer on a continuous (time /
+  value) x axis publishes bins; a horizontal chart (value on x) and a categorical
+  axis stay freeform / excluded. An explicit `cursorSequence` still takes
+  precedence. New `HistogramBins` region-cursor story.
+
+### Changed
+
+- **BREAKING (`@pond-ts/charts`): the region cursor works on a value x-axis, and
+  `onRegionSelect` reports a neutral `[lo, hi]` pair.** The drag-select callback
+  fired a `TimeRange`; it now fires `readonly [number, number]` in **axis units** —
+  epoch ms on a time axis, the axis value (strike, distance, …) on a value axis —
+  mirroring the container's polymorphic `range` input (which never takes the axis
+  _kind_ from its value). A time-axis consumer that wants a `TimeRange` builds one
+  from the pair (`new TimeRange({ start: lo, end: hi })`). The cursor itself is
+  ungated from time-only to any **continuous** x-axis (time **or** value; a
+  **category** axis stays excluded — an ordinal-slot select is a different gesture).
+  Bucket **snapping** stays time-only (a `cursorSequence` bucket is a time
+  interval), so a value axis is always **freeform** (hover line + raw-span drag).
+
 ## [0.43.0] — 2026-07-11
 
 The **categorical x-axis** release: a first-class ordinal band scale (ticker /

package/dist/BarChart.js

@@ -1,5 +1,5 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { ValueSeries } from 'pond-ts';
+import { Interval, ValueSeries } from 'pond-ts';
 import { barsFromTimeSeries, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
 import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { ContainerContext, LayersContext, } from './context.js';
@@ -155,6 +155,26 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 : series instanceof ValueSeries
                     ? 'value'
                     : 'time';
+    // The bars' `[begin, end)` spans as pond `Interval`s — the region cursor's snap
+    // buckets (a region drag snaps bar by bar; a hover highlights the bar under the
+    // pointer). Published only for a **vertical** bar layer on a **continuous**
+    // (time / value) x axis: a horizontal chart puts the value/count on x (snapping
+    // it is meaningless) and a categorical (ordinal-slot) axis is out of the region
+    // cursor's scope. Memoized off the shape alone, so a hover / selection change
+    // (which rebuilds the layer entry) doesn't re-allocate the intervals.
+    const binBuckets = useMemo(() => {
+        if (orientation !== 'vertical' || binAxisKind === 'category')
+            return null;
+        const { begin, end, length } = shape.kind === 'single' ? shape.bs : shape.ss;
+        if (length === 0)
+            return null;
+        const out = new Array(length);
+        for (let i = 0; i < length; i += 1) {
+            const b = begin[i];
+            out[i] = new Interval({ value: b, start: b, end: end[i] });
+        }
+        return out;
+    }, [shape, orientation, binAxisKind]);
     const { bar } = container.theme;
     // Single-series style: the `as` role → theme bar style (the single channel).
     const singleStyle = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
@@ -208,6 +228,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                     yExtent: () => barExtent(bs),
                     xKind: binAxisKind,
                     xExtent: () => bs.length === 0 ? null : [bs.begin[0], bs.end[bs.length - 1]],
+                    ...(binBuckets !== null ? { binIntervals: () => binBuckets } : {}),
                     sampleAt: (time) => {
                         if (bs.length === 0)
                             return [];
@@ -263,6 +284,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 xKind: vertical ? binAxisKind : 'value',
                 xExtent: vertical ? binExtent : valueExtent,
                 yExtent: vertical ? valueExtent : binExtent,
+                ...(binBuckets !== null ? { binIntervals: () => binBuckets } : {}),
                 // A categorical chart hands the container its ordered category names — the
                 // ordinal axis domain the shared band scale + label formatter build on.
                 ...(categoryLabels !== null
@@ -305,6 +327,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     }, [
         shape,
         binAxisKind,
+        binBuckets,
         categoryLabels,
         orientation,
         singleStyle,

package/dist/BoxPlot.d.ts

@@ -1,18 +1,35 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type BoxShape } from './box.js';
-export interface BoxPlotProps<S extends SeriesSchema> {
-    /** The source series. Its interval key column supplies the time axis (the box
-     *  x-span is the key's `[begin, end)`). */
-    series: TimeSeries<S>;
-    /** Name of the numeric column for the lower whisker end (e.g. `p5` / `min`). */
+export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` plots against the time axis; a `ValueSeries`
+     * (`series.byValue('strike')`, or `ValueSeries.fromColumns` for natively
+     * value-keyed data — a per-strike IV distribution) against its value axis — the
+     * container infers which from the data, no axis-type prop (mirrors `<LineChart>`
+     * / `<ScatterChart>`). The box x-span is the key's `[begin, end)` for an
+     * interval-keyed `TimeSeries`, else synthesized from neighbour spacing (a
+     * point-keyed `TimeSeries`, or a `ValueSeries`) so the box keeps real width.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
+    /** Name of the numeric column for the lower whisker end (e.g. `p5` / `min`).
+     *  **Required** — with `upper` it's the whisker reach. */
     lower: string;
-    /** Name of the numeric column for the box bottom — first quartile (e.g. `p25`). */
-    q1: string;
-    /** Name of the numeric column for the median line (e.g. `p50`). */
-    median: string;
-    /** Name of the numeric column for the box top — third quartile (e.g. `p75`). */
-    q3: string;
-    /** Name of the numeric column for the upper whisker end (e.g. `p95` / `max`). */
+    /**
+     * Name of the numeric column for the box bottom — first quartile (e.g. `p25`).
+     * **Optional:** omit `q1` **and** `q3` together for a **range-only** box — a
+     * whisker-only `lower→upper` segment, no body (a bid→ask IV mark). Giving just
+     * one of `q1`/`q3` throws.
+     */
+    q1?: string;
+    /** Name of the numeric column for the median line (e.g. `p50`). **Optional** —
+     *  omit for no centre line (independent of the box body). */
+    median?: string;
+    /** Name of the numeric column for the box top — third quartile (e.g. `p75`).
+     *  **Optional** — omit with `q1` for a range-only box (see `q1`). */
+    q3?: string;
+    /** Name of the numeric column for the upper whisker end (e.g. `p95` / `max`).
+     *  **Required** — with `lower` it's the whisker reach. */
     upper: string;
     /**
      * The box series' semantic identifier — what the spread _is_ (e.g. `latency`).
@@ -38,12 +55,39 @@ export interface BoxPlotProps<S extends SeriesSchema> {
      * How each box renders its spread — `'whisker'` (default; thin stems + caps),
      * `'solid'` (the candlestick look: a light outer bar over the full range with a
      * darker inner q1→q3 box, no stems), or `'none'` (the q1→q3 box only, no spread
-     * marks). See {@link BoxShape}.
+     * marks). See {@link BoxShape}. On a **range-only** box (no `q1`/`q3`),
+     * `'whisker'` is one full `lower→upper` stem and `'solid'` the outer bar; `'none'`
+     * would draw **nothing** (no body + no spread), so use `'whisker'`/`'solid'` there.
      */
     shape?: BoxShape;
-    /** Draw the median (centre) line across each box. Always optional; default
-     *  `true`. (The `median` prop above names the *column*; this toggles the line.) */
+    /** Draw the median (centre) line across each box. Default `true`, but a no-op
+     *  when the `median` column is omitted (nothing to draw). The `median` prop
+     *  names the *column*; this toggles the line. */
     showMedian?: boolean;
+    /**
+     * A **pixel** shift applied to every box's x — zoom-stable (unlike a data-space
+     * nudge). **Default `0`.** For pairing marks that share a key side by side: e.g.
+     * a call and a put box at the same strike, `offset={-4}` / `offset={+4}` (the
+     * react-timeseries-charts side-by-side-bars precedent). Pairs with
+     * `<ScatterChart offset>`.
+     *
+     * Only the **draw** is shifted. The box's **readouts** stay in un-shifted data
+     * space — the off-chart hover finds a box by span containment (`xScale.invert`),
+     * and the in-chart `flag` staff anchors at the box's data centre — so both can
+     * sit up to `offset` px from the pixel-shifted box. Keep the offset small (a
+     * pairing nudge, not a layout tool) and it's imperceptible. (`<ScatterChart
+     * offset>` has no such gap — its hit-test is pixel-space and shifts too.)
+     */
+    offset?: number;
+    /**
+     * Whisker end-cap **total width in pixels** (the top/bottom bars of the `T`).
+     * **Omitted ⇒ half the box width** (responsive — scales with the slot). Set a
+     * small fixed value (e.g. `6`) to keep the caps narrow so two `offset`-paired
+     * marks (call/put at one strike) don't overlap their T-bars — the caps no longer
+     * grow with the wide value-axis slot. Clamped to the box width. Only affects the
+     * `'whisker'` shape (`'solid'`/`'none'` have no caps).
+     */
+    capWidth?: number;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -52,26 +96,34 @@ export interface BoxPlotProps<S extends SeriesSchema> {
 }
 /**
  * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
- * band. Reads five **pre-computed quantile columns** of `series` (typically a
+ * band. Reads **pre-computed quantile columns** of `series` (typically a
  * `rolling`/`aggregate` percentile pass — the chart does **not** compute them)
- * into a {@link BoxSeries} and draws one box per key: the q1→q3 box, the median
- * line, and whiskers out to lower/upper, over the key's interval x-span. Gap-aware
- * (a key missing any quantile draws nothing) and registers itself into the
- * enclosing {@link Layers}. Renders nothing to the DOM — the row draws it.
+ * into a {@link BoxSeries} and draws one box per key: the q1→q3 body, the median
+ * line, and whiskers out to lower/upper. Registers itself into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it.
+ *
+ * - **Any axis.** A `TimeSeries` plots on time, a `ValueSeries`
+ *   (`series.byValue('strike')` or `ValueSeries.fromColumns`) on its value axis —
+ *   a vol smile's per-strike IV. The box width is the interval key's `[begin, end)`
+ *   or, for a point key (a `ValueSeries`, or a point-keyed `TimeSeries`),
+ *   neighbour spacing — so it never collapses to the 1px floor.
+ * - **Range-only.** `q1`/`q3` (the body) and `median` (the centre line) are
+ *   optional: omit `q1`+`q3` for a whisker-only `lower→upper` segment — a bid→ask
+ *   IV mark. Gap-aware: a key missing any **present** quantile draws nothing.
+ * - **`offset`** nudges the whole layer in pixel space, for pairing same-key marks
+ *   (call/put at one strike) side by side.
  *
  * There's no baseline — a box is a spread, not a bar to a floor; the y-domain
  * auto-fits the whisker reach (lower→upper).
  *
  * ```tsx
  * <Layers>
- *   <BoxPlot
- *     series={q}
- *     lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
- *     as="latency"
- *     gap={6}
- *   />
+ *   <BoxPlot series={q} lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
+ *     as="latency" gap={6} />
+ *   // range-only bid→ask on a value axis (a vol smile):
+ *   <BoxPlot series={smile} lower="bid" upper="ask" />
  * </Layers>
  * ```
  */
-export declare function BoxPlot<S extends SeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, index, }: BoxPlotProps<S>): null;
+export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, index, }: BoxPlotProps<S, VS>): null;
 //# sourceMappingURL=BoxPlot.d.ts.map

package/dist/BoxPlot.js

@@ -1,5 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { boxFromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { boxFromTimeSeries, boxFromValueSeries } from './data.js';
 import { boxExtent, boxIndexAtTime, drawBox, isFiniteBox, } from './box.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { useSlotKey } from './use-slot-key.js';
@@ -7,28 +8,36 @@ import { useSlotKey } from './use-slot-key.js';
 const MIN_BOX_WIDTH_PX = 1;
 /**
  * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
- * band. Reads five **pre-computed quantile columns** of `series` (typically a
+ * band. Reads **pre-computed quantile columns** of `series` (typically a
  * `rolling`/`aggregate` percentile pass — the chart does **not** compute them)
- * into a {@link BoxSeries} and draws one box per key: the q1→q3 box, the median
- * line, and whiskers out to lower/upper, over the key's interval x-span. Gap-aware
- * (a key missing any quantile draws nothing) and registers itself into the
- * enclosing {@link Layers}. Renders nothing to the DOM — the row draws it.
+ * into a {@link BoxSeries} and draws one box per key: the q1→q3 body, the median
+ * line, and whiskers out to lower/upper. Registers itself into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it.
+ *
+ * - **Any axis.** A `TimeSeries` plots on time, a `ValueSeries`
+ *   (`series.byValue('strike')` or `ValueSeries.fromColumns`) on its value axis —
+ *   a vol smile's per-strike IV. The box width is the interval key's `[begin, end)`
+ *   or, for a point key (a `ValueSeries`, or a point-keyed `TimeSeries`),
+ *   neighbour spacing — so it never collapses to the 1px floor.
+ * - **Range-only.** `q1`/`q3` (the body) and `median` (the centre line) are
+ *   optional: omit `q1`+`q3` for a whisker-only `lower→upper` segment — a bid→ask
+ *   IV mark. Gap-aware: a key missing any **present** quantile draws nothing.
+ * - **`offset`** nudges the whole layer in pixel space, for pairing same-key marks
+ *   (call/put at one strike) side by side.
  *
  * There's no baseline — a box is a spread, not a bar to a floor; the y-domain
  * auto-fits the whisker reach (lower→upper).
  *
  * ```tsx
  * <Layers>
- *   <BoxPlot
- *     series={q}
- *     lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
- *     as="latency"
- *     gap={6}
- *   />
+ *   <BoxPlot series={q} lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
+ *     as="latency" gap={6} />
+ *   // range-only bid→ask on a value axis (a vol smile):
+ *   <BoxPlot series={smile} lower="bid" upper="ask" />
  * </Layers>
  * ```
  */
-export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, axis, gap = 0, shape = 'whisker', showMedian = true, index = 0, }) {
+export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, axis, gap = 0, shape = 'whisker', showMedian = true, offset = 0, capWidth, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BoxPlot> must be rendered inside a <ChartContainer>');
@@ -37,78 +46,96 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
     if (layers === null) {
         throw new Error('<BoxPlot> must be rendered inside a <Layers>');
     }
-    const bx = useMemo(() => boxFromTimeSeries(series, { lower, q1, median, q3, upper }), [series, lower, q1, median, q3, upper]);
+    const isValue = series instanceof ValueSeries;
+    const bx = useMemo(() => series instanceof ValueSeries
+        ? boxFromValueSeries(series, { lower, q1, median, q3, upper })
+        : boxFromTimeSeries(series, { lower, q1, median, q3, upper }), [series, lower, q1, median, q3, upper]);
     // Styling: semantic identifier → theme box style. The single styling channel.
     const { box } = container.theme;
     const style = (semantic !== undefined ? box[semantic] : undefined) ?? box.default;
+    // Readout label per quantile: when a semantic `as` is set, label reads under the
+    // series name + role (`iv upper`, `iv median`) — the `as ?? column` convention
+    // Line/Scatter use, so a box no longer reads out as bare column names (e.g.
+    // `bidIv`); with no `as`, fall back to the column name (its role is self-evident).
+    const qLabel = useMemo(() => {
+        return (col, role) => semantic !== undefined ? `${semantic} ${role}` : (col ?? role);
+    }, [semantic]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => boxExtent(bx),
-            xKind: 'time',
+            // A ValueSeries plots on a value axis, a TimeSeries on time; the container
+            // infers the shared x kind from its layers.
+            xKind: isValue ? 'value' : 'time',
             xExtent: () => bx.length === 0 ? null : [bx.x[0], bx.xEnd[bx.length - 1]],
-            sampleAt: (time) => {
+            sampleAt: (x) => {
                 // The readout reads the box **under the cursor** (boxIndexAtTime — span
                 // containment, not nearest-by-begin which flips past a wide box's
                 // midpoint), anchored at the box **centre** `(x + xEnd) / 2`. Outside
                 // every box → no readout. Off-chart fan-in only; the in-chart flag is
-                // `cursorFlag`.
+                // `cursorFlag`. `push` skips a non-finite quantile, so an absent
+                // (range-only) q1/q3/median simply doesn't read out.
                 if (bx.length === 0)
                     return [];
-                const i = boxIndexAtTime(bx, time);
+                const i = boxIndexAtTime(bx, x);
                 if (i < 0)
                     return [];
                 const at = (bx.x[i] + bx.xEnd[i]) / 2;
                 const samples = [];
-                // The median is the primary readout (median colour); the four quantile
-                // edges ride the whisker colour, each labelled by its own column. A
-                // single non-finite quantile is omitted (a gap key yields nothing — all
-                // five missing — but a malformed partial set still reads what it has).
-                push(samples, at, bx.upper[i], style.whisker, upper);
-                push(samples, at, bx.q3[i], style.whisker, q3);
-                push(samples, at, bx.median[i], style.median, median);
-                push(samples, at, bx.q1[i], style.whisker, q1);
-                push(samples, at, bx.lower[i], style.whisker, lower);
+                push(samples, at, bx.upper[i], style.whisker, qLabel(upper, 'upper'));
+                push(samples, at, bx.q3[i], style.whisker, qLabel(q3, 'q3'));
+                push(samples, at, bx.median[i], style.median, qLabel(median, 'median'));
+                push(samples, at, bx.q1[i], style.whisker, qLabel(q1, 'q1'));
+                push(samples, at, bx.lower[i], style.whisker, qLabel(lower, 'lower'));
                 return samples;
             },
-            cursorFlag: (time) => {
-                // The in-chart `flag`: all five values on **one** flag at the box's
+            cursorFlag: (x) => {
+                // The in-chart `flag`: the box's values on **one** flag at its
                 // top-centre. The staff rises from `upper` (the mark's top); the values
                 // run high→low across one horizontal row (Layers renders them
-                // left→right), each coloured to its box piece. All-or-nothing — a gap
-                // box (any quantile non-finite, not drawn) shows no flag.
+                // left→right), each coloured to its box piece. A gap box (its present
+                // quantiles not all finite) shows no flag; an absent (range-only)
+                // quantile is simply skipped.
                 if (bx.length === 0)
                     return null;
-                const i = boxIndexAtTime(bx, time);
+                const i = boxIndexAtTime(bx, x);
                 if (i < 0 || !isFiniteBox(bx, i))
                     return null;
+                const lines = [];
+                const line = (value, color, label) => {
+                    if (Number.isFinite(value))
+                        lines.push({ value, color, label });
+                };
+                line(bx.upper[i], style.whisker, qLabel(upper, 'upper'));
+                line(bx.q3[i], style.whisker, qLabel(q3, 'q3'));
+                line(bx.median[i], style.median, qLabel(median, 'median'));
+                line(bx.q1[i], style.whisker, qLabel(q1, 'q1'));
+                line(bx.lower[i], style.whisker, qLabel(lower, 'lower'));
                 return {
                     x: (bx.x[i] + bx.xEnd[i]) / 2,
                     topValue: bx.upper[i],
-                    lines: [
-                        { value: bx.upper[i], color: style.whisker, label: upper },
-                        { value: bx.q3[i], color: style.whisker, label: q3 },
-                        { value: bx.median[i], color: style.median, label: median },
-                        { value: bx.q1[i], color: style.whisker, label: q1 },
-                        { value: bx.lower[i], color: style.whisker, label: lower },
-                    ],
+                    lines,
                 };
             },
-            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian),
+            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian, offset, capWidth),
         },
         axisId: axis,
         index,
     }), [
         bx,
+        isValue,
         series,
         lower,
         q1,
         median,
         q3,
         upper,
+        qLabel,
         style,
         gap,
         shape,
         showMedian,
+        offset,
+        capWidth,
         axis,
         index,
     ]);

package/dist/ChartContainer.d.ts

@@ -105,17 +105,25 @@ export interface ChartContainerProps {
     /**
      * Makes the `region` cursor **draggable**: drag across the plot and the band
      * extends **bucket by bucket** (snapping to `cursorSequence` points); on
-     * release this fires **once** with the selected `[start, end)` `TimeRange`, and
-     * the cursor reverts to the single-bucket highlight (it does not keep the
-     * range). Typical use — zoom the view to the returned range (the container
-     * doesn't zoom itself; that's the consumer's call).
+     * release this fires **once** with the selected `[lo, hi]` span, and the cursor
+     * reverts to the single-bucket highlight (it does not keep the range). Typical
+     * use — zoom the view to the returned span (the container doesn't zoom itself;
+     * that's the consumer's call), or map it onto a data subscription's range params.
+     *
+     * The span is a **neutral numeric pair in axis units** — epoch ms on a **time**
+     * axis, the axis value (strike, distance, …) on a **value** axis — mirroring the
+     * polymorphic `range` input. A time consumer that wants a `TimeRange` builds one
+     * from the pair.
      *
      * With **no `cursorSequence`** the region cursor is the degenerate case — it
-     * renders as a **line** on hover and the drag is **freeform** (raw `[start,
-     * end)`, no bucket snapping); the same callback fires on release. No-op unless
-     * `cursor="region"` (and a **time** x-axis).
+     * renders as a **line** on hover and the drag is **freeform** (raw `[lo, hi]`, no
+     * bucket snapping); the same callback fires on release. Bucket snapping needs a
+     * `cursorSequence`, which is **time-axis only** (a time interval over a value
+     * domain is meaningless), so a **value** axis is always freeform. No-op unless
+     * `cursor="region"` on a **time** or **value** x-axis (a **category** axis is
+     * excluded — an ordinal-slot select is a different gesture).
      */
-    onRegionSelect?: (range: TimeRange) => void;
+    onRegionSelect?: (range: readonly [number, number]) => void;
     /**
      * Which modifier a region-drag needs — set `'shift'` when you also enable
      * `panZoom` and want **plain drag to pan, shift-drag to select**. It's only