@pond-ts/charts 0.42.0 → 0.44.0

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.42.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.44.0...HEAD
+[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
 [0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
@@ -40,6 +42,157 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [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 /
+account / expiry on x — the transpose view of a time series), plus the charts
+**interaction** wave that landed after v0.42.0 was cut — the region cursor and
+its drag-to-select gesture, per-bin band colour, and annotation edges that snap
+to session boundaries.
+
+### Added
+
+- **`@pond-ts/charts`: a first-class categorical x-axis.** `<BarChart
+categories={[{ label, value }]}>` draws one bar per category on an ordinal
+  **band scale** (the transpose view's "columns on x" — ticker / account / zone
+  on x). The container infers `xKind:'category'` and builds a `scaleBand` over the
+  labels; `<CategoryAxis>` ticks once per category. Colour per category via
+  `binColors`; selection reports the category name. **Negative** category values
+  draw below the baseline (the P&L / delta case) — a single-series category bar
+  honours its sign. New exports `scaleBand` / `ScaleBand`, `CategoryAxis`,
+  `categoryStack` / `CategoryDatum`. Additive — a new x-kind alongside time /
+  value; existing charts are unchanged. First slice of the categorical-axis RFC
+  (`docs/rfcs/categorical-axis.md`, Phase 1).
+- **`@pond-ts/charts`: `transposeRow`** — read one **row** of a wide `TimeSeries`
+  **across** into `{ label, value }[]` for `<BarChart categories>`: the schema's
+  numeric columns (a `pivotByGroup` output's per-group columns, a term
+  structure's per-expiry columns) become the categories at one instant. Pick the
+  row with `at` (`'last'` — the head/live row — by default; `'first'`, an index,
+  or `{ time }`); bound / order the set with `columns`.
+- **`@pond-ts/charts`: stable per-column selection identity.** `SelectInfo` gains
+  an optional **`mark`** — a stable per-mark identity within a layer. A categorical
+  bar reports its **column name** as `mark`, and a controlled `selected` echo /
+  the highlight match key on `(id, mark)`, so a pinned selection survives a column
+  reorder (the slot index doesn't; the name does). Additive — `mark` is
+  `undefined` for a time / value bar (whose sample `key` is already its identity).
+  Plus a category-axis **label policy**: a dense axis thins (keeps every k-th) and
+  ellipsis-truncates its labels so they stay legible while every bar draws.
+- **`@pond-ts/charts`: region cursor (`cursor="region"`).** A shaded **band**
+  highlights the bucket under the pointer, bucketed by a new **`cursorSequence`**
+  prop — a `Sequence` (`Sequence.every('15m')`, `Sequence.calendar('week')`)
+  realized over the view, or a `BoundedSequence` (a `TradingCalendar`'s
+  `sessionSequence()` / `barSequence()`) used as-is. The band maps through the x
+  scale, so on a trading-time axis the closed part of a bucket collapses (crops
+  to live sessions). Time-axis only (a no-op on a value axis). (#409, #413)
+- **`@pond-ts/charts`: draggable region cursor → one-shot select.** Opt-in
+  **`onRegionSelect?: (range: TimeRange) => void`** makes the region cursor
+  draggable: the band extends bucket by bucket and fires **once** on release
+  with the selected `[start, end)` `TimeRange` (the cursor doesn't keep it —
+  typical use is to zoom the view). With **no `cursorSequence`** it degenerates
+  to a hover **line** + **freeform** drag. **`regionSelectModifier="shift"`**
+  resolves the gesture conflict with `panZoom` (plain drag pans, shift-drag
+  selects); omitted, a region-drag preempts pan. (#416)
+- **`@pond-ts/charts`: `binColors` — per-bin colour for single-series bars.**
+  `<BarChart binColors={[...]}>` colours each bar/band segment individually (one
+  colour per bin, in order), the single-series analog of the stacked `colors`
+  prop — used by the category axis (colour per category) and any single-series
+  band chart. (#408)
+- **`@pond-ts/charts`: annotation edges snap to session boundaries.** When a
+  `<ChartContainer>` carries a trading calendar (disjoint x axis), dragging a
+  `<Region>` edge (or creating one) snaps to the nearest **session boundary**
+  rather than raw wall-clock, so a drawn span aligns with real market sessions.
+  (#410)
+
+### Fixed
+
+- **`@pond-ts/charts`: region body-move no longer distorts across a session
+  boundary.** On a trading-time (discontinuous) axis, dragging a `<Region>`
+  annotation by its body now translates it rigidly in pixel space, so the box
+  keeps its width as it crosses a collapsed gap (it previously applied one
+  value-delta to both edges, which stretched the box in the different
+  rate-contexts either side of a session boundary). No-op on a continuous axis.
+  (#405)
+
 ## [0.42.0] — 2026-07-10
 
 The **trading-calendar** release: a new `@pond-ts/financial` package (its first
@@ -82,6 +235,16 @@ collapses closed-market time (weekends, holidays, overnight, lunch breaks).
     (`theme.axis.sessionDivider`), aligned with the labels.
   - `Charts/TradingTimeAxis` stories (weekend/holiday/half-day/intraday,
     continuous-vs-trading, daily-months, proportional-vs-uniform).
+- **`@pond-ts/charts`: first-class histograms.** `<BarChart>` gains **stacking**
+  — a group-by dimension → stacked segments, from a wide series (`columns`), a
+  `Map<group, TimeSeries>` (the `partitionBy().aggregate().toMap()` shape), or a
+  `byColumn` `bins` array; per-group colour via `colors` or theme roles — and an
+  **`orientation`** prop (`'vertical'` default | `'horizontal'`, bars grow right
+  with the bins on a y band axis). New readers `stacksFromGroups` /
+  `stacksFromColumns` / `stacksFromBins` plus `StackedBarSeries` / `BinRecord` /
+  `Orientation` types. All data generation composes from existing operators
+  (`aggregate` / `byColumn` / `partitionBy`); no core changes. Guide: How-to
+  guides → Histograms. (#401)
 - **`@pond-ts/charts`:** selection now has a stable series identity. `SelectInfo`
   carries an `id`, and `BarChart` / `ScatterChart` take an optional `id` prop —
   the series identity used for selection + hover. An `id` **gates interactivity**:

package/dist/BarChart.d.ts

@@ -1,6 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
-import { type BinRecord } from './data.js';
+import { type BinRecord, type CategoryDatum } from './data.js';
 import { type Orientation } from './bars.js';
 export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
@@ -29,6 +29,17 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * draw. Pair with `ordinal` for a category (band) axis.
      */
     bins?: readonly BinRecord[];
+    /**
+     * **Categorical** data — an ordered `{ label, value }[]`, one bar per category
+     * on a first-class **ordinal category x-axis** (the container infers
+     * `xKind:'category'` and builds a band scale over the labels). The transpose
+     * view's "columns on x": each `label` is a category (ticker / account / zone),
+     * `value` its bar height. Provide **exactly one** of `series` / `bins` /
+     * `categories`; `categories` takes no `column`/`columns` and is **vertical only**
+     * (categories on x). Colour per category via `binColors`. (Categorical-axis RFC,
+     * Phase 1.)
+     */
+    categories?: readonly CategoryDatum[];
     /** Name of the numeric value column for the bar height (single series). Provide
      *  `column` **or** `columns`, not both. */
     column?: string;
@@ -55,6 +66,17 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * this is the stack's one colour input.
      */
     colors?: Readonly<Record<string, string>>;
+    /**
+     * **Per-bin** colours for a single-series band chart — `binColors[i]` fills
+     * bar `i` (aligned to the bins / bands in order), overriding the `as`/theme
+     * fill. This is the way to colour heart-rate / power **zones** or value bands
+     * each their own colour (the `colors` map above is per-**group**, for stacks).
+     * An `undefined`/short entry falls back to the theme fill. Meant for a
+     * single-series chart (`column` + `bins`, or a horizontal single series); on a
+     * multi-group stack it would tint every segment of a bin alike, so it's not
+     * the tool there.
+     */
+    binColors?: readonly (string | undefined)[];
     /**
      * Bar growth direction (the histogram orientation). **Default `'vertical'`.**
      *
@@ -147,5 +169,5 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, column, columns, as: semantic, colors, orientation, ordinal, id, axis, gap, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, index, }: BarChartProps<S, VS>): null;
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { ValueSeries } from 'pond-ts';
-import { barsFromTimeSeries, barsFromValueSeries, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
+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';
 import { useSlotKey } from './use-slot-key.js';
@@ -47,7 +47,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, column, columns, as: semantic, colors, orientation = 'vertical', ordinal = false, id, axis, gap, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -58,8 +58,19 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
     }
     // Validate the data-source / value-column combination up front (throws are
     // stable across renders, so no need to memoize them).
-    if ((series === undefined) === (bins === undefined)) {
-        throw new Error('<BarChart> needs exactly one of `series` or `bins`');
+    const nSources = (series !== undefined ? 1 : 0) +
+        (bins !== undefined ? 1 : 0) +
+        (categories !== undefined ? 1 : 0);
+    if (nSources !== 1) {
+        throw new Error('<BarChart> needs exactly one of `series`, `bins`, or `categories`');
+    }
+    if (categories !== undefined) {
+        if (column !== undefined || columns !== undefined) {
+            throw new Error('<BarChart categories> takes no `column`/`columns` (each datum carries its own value)');
+        }
+        if (orientation === 'horizontal') {
+            throw new Error('<BarChart categories> is vertical only (categories on x); horizontal category axes are not yet supported');
+        }
     }
     const isMap = series instanceof Map;
     if (isMap && columns !== undefined) {
@@ -76,6 +87,12 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
     // stack, any horizontal — builds a StackedBarSeries (G === 1 for a single
     // horizontal bar) so one oriented draw path covers it.
     const shape = useMemo(() => {
+        if (categories !== undefined) {
+            // Categorical row-read: one unit-slot bar per category (G === 1), drawn on
+            // the container's band scale. The reused stacked geometry — only the axis
+            // (band scale + labels) is new.
+            return { kind: 'stacked', ss: categoryStack(categories) };
+        }
         if (bins !== undefined) {
             const cols = columns ?? (column !== undefined ? [column] : undefined);
             if (cols === undefined) {
@@ -111,18 +128,53 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
                 ? barsFromValueSeries(s, column)
                 : barsFromTimeSeries(s, column),
         };
-    }, [series, bins, column, columns, ordinal, orientation, isMap, label]);
-    // The bin axis kind (time vs value) — a `TimeSeries`/`Map` bins on time, a
-    // `ValueSeries`/`bins`-array on a value axis. For a vertical histogram this is
-    // the shared x-kind; a horizontal one puts the *value* on x (always 'value')
-    // and the bin axis on a linear y.
-    const binAxisKind = bins !== undefined
-        ? 'value'
-        : isMap
-            ? 'time'
-            : series instanceof ValueSeries
-                ? 'value'
-                : 'time';
+    }, [
+        series,
+        bins,
+        categories,
+        column,
+        columns,
+        ordinal,
+        orientation,
+        isMap,
+        label,
+    ]);
+    // The category labels — the ordinal axis's ordered column set (`xCategories`),
+    // and the per-bar readout label. `null` unless this is a categorical chart.
+    const categoryLabels = useMemo(() => categories?.map((c) => c.label) ?? null, [categories]);
+    // The bin axis kind — `'category'` for a categorical chart, else `'time'`/`'value'`
+    // (a `TimeSeries`/`Map` bins on time, a `ValueSeries`/`bins`-array on a value
+    // axis). For a vertical chart this is the shared x-kind; a horizontal one puts
+    // the *value* on x (always 'value') and the bin axis on a linear y.
+    const binAxisKind = categories !== undefined
+        ? 'category'
+        : bins !== undefined
+            ? 'value'
+            : isMap
+                ? 'time'
+                : 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;
@@ -137,8 +189,13 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
     const stackStyle = useMemo(() => {
         const base = bar.default;
         const fills = (groups ?? []).map((g) => colors?.[g] ?? (bar[g] ?? base).fill);
-        return { fills, opacity: base.opacity, outlineWidth: base.outlineWidth };
-    }, [bar, groups, colors]);
+        return {
+            fills,
+            opacity: base.opacity,
+            outlineWidth: base.outlineWidth,
+            ...(binColors !== undefined ? { binFills: binColors } : {}),
+        };
+    }, [bar, groups, colors, binColors]);
     // The current selection / hover, narrowed to the identity the highlight match
     // needs. For a stack that's (id, key, label = group); the single path uses just
     // (id, key). Read here so a change re-registers the layer → the canvas repaints.
@@ -146,13 +203,21 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
     const hoveredMark = container.hovered;
     const selection = useMemo(() => selected === null
         ? null
-        : { id: selected.id, key: selected.key, label: selected.label }, [selected]);
+        : {
+            id: selected.id,
+            key: selected.key,
+            label: selected.label,
+            ...(selected.mark !== undefined ? { mark: selected.mark } : {}),
+        }, [selected]);
     const hover = useMemo(() => hoveredMark === null
         ? null
         : {
             id: hoveredMark.id,
             key: hoveredMark.key,
             label: hoveredMark.label,
+            ...(hoveredMark.mark !== undefined
+                ? { mark: hoveredMark.mark }
+                : {}),
         }, [hoveredMark]);
     const entry = useMemo(() => {
         // ── Single-series, vertical: the original bar path, pixels unchanged. ──
@@ -163,6 +228,7 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
                     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 [];
@@ -218,6 +284,12 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
                 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
+                    ? { xCategories: () => categoryLabels }
+                    : {}),
                 // No x-scrub flag for a stack / horizontal chart — hover + click read it
                 // out instead (the flag is single-series-vertical only).
                 sampleAt: () => [],
@@ -228,13 +300,22 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
                             const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth);
                             if (hit === null)
                                 return null;
-                            const [, g, begin, name, value] = hit;
+                            const [bi, g, begin, name, value] = hit;
+                            // A categorical bar carries a stable per-bar `mark` (its column
+                            // name); the selection keys on `(id, mark)` so it survives a
+                            // reorder. `bi` is the exact bin index from the hit.
+                            const stableMark = ss.marks?.[bi];
                             return {
                                 id,
                                 key: begin,
                                 value,
-                                color: stackStyle.fills[g],
-                                label: name,
+                                // A per-bin colour override wins over the group fill, so the
+                                // readout pill reads the bar's own colour.
+                                color: stackStyle.binFills?.[bi] ?? stackStyle.fills[g],
+                                // A categorical bar reports its category name; a stack reports
+                                // the group.
+                                label: stableMark ?? name,
+                                ...(stableMark !== undefined ? { mark: stableMark } : {}),
                             };
                         },
                     }),
@@ -246,6 +327,8 @@ export function BarChart({ series, bins, column, columns, as: semantic, colors,
     }, [
         shape,
         binAxisKind,
+        binBuckets,
+        categoryLabels,
         orientation,
         singleStyle,
         stackStyle,

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