@pond-ts/charts 0.42.0 → 0.44.0

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
@@ -122,18 +137,32 @@ export interface StackedBarSeries {
     readonly groups: readonly string[];
     readonly values: Float64Array;
     readonly length: number;
+    /**
+     * Optional **stable per-bin identity** — `marks[b]` names bin `b` (a category's
+     * column name on the categorical axis). When present, the draw / hit-test /
+     * selection key on this name instead of the bin's `begin` slot index, so a
+     * pinned selection survives a column reorder (the slot index is not stable).
+     * `undefined` for a time / value series whose `begin` is already stable.
+     */
+    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. */
@@ -197,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.
@@ -343,4 +394,68 @@ export interface StacksFromBinsOptions {
  * A missing / non-finite aggregate reads as a gap (`NaN`).
  */
 export declare function stacksFromBins(bins: readonly BinRecord[], columns: readonly string[], options?: StacksFromBinsOptions): StackedBarSeries;
+/**
+ * One category's `{ label, value }` for a categorical bar chart — the row-read /
+ * transpose view's `(columnName, cell)` pair (categorical-axis RFC, Phase 1). An
+ * ordered list of these is the explicit categorical data source; Phase 2's
+ * transpose reader produces the same list from a wide series' row.
+ *
+ * **Labels are the stable identity** — the axis maps each `label` to a slot and
+ * selection/highlight key on it (so a pick survives a reorder). They must be
+ * **unique** within the list: two categories sharing a label collapse to one axis
+ * tick and both highlight together on a pick. The transpose reader satisfies this
+ * for free (a series' column names are unique); only a hand-built list can break
+ * it. `value` may be **negative** — a single-series category bar draws it below
+ * the baseline (the P&L / delta case).
+ */
+export interface CategoryDatum {
+    readonly label: string;
+    readonly value: number;
+}
+/**
+ * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
+ * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in
+ * order. This is the categorical row-read's geometry: the slots are ordinal
+ * indices (the bar's pixel span comes from the container's {@link ScaleBand}), and
+ * the `label`s become the axis's ordered category names (`xCategories`). A
+ * non-finite value reads as a gap (`NaN`). Reuses the shipped stacked geometry —
+ * no new draw path.
+ */
+export declare function categoryStack(records: readonly CategoryDatum[]): StackedBarSeries;
+/** Which row {@link transposeRow} reads across. */
+export type RowAt = 'first' | 'last' | number | {
+    readonly time: number;
+};
+/** Options for {@link transposeRow}. */
+export interface TransposeRowOptions {
+    /**
+     * Which row to read across. **Default `'last'`** — the head / latest row (the
+     * live snapshot). `'first'`, an **index** (negative from the end), or
+     * `{ time }` for the row nearest a key.
+     */
+    readonly at?: RowAt;
+    /**
+     * The columns to lay on the axis, **in order** — a declared / bounded set (a
+     * watchlist, or a top-N computed upstream; the RFC §7 "bound in the data layer"
+     * stance). Omit to use **every numeric value column** of the series, in schema
+     * order. A named column that's missing / non-numeric in the row reads as a gap.
+     */
+    readonly columns?: readonly string[];
+}
+/**
+ * **The transpose reader** (categorical-axis RFC, Phase 1 PR2): read **one row**
+ * of a wide `TimeSeries` **across** — its columns become the categories, that
+ * row's cells the values — for `<BarChart categories={…}>`. This is "columns on
+ * x": the schema's numeric columns (a `pivotByGroup` output's per-group columns,
+ * a vol term structure's per-expiry columns, …) laid out at one instant.
+ *
+ * The row is picked the ordinary way (`options.at`, default the **head row**):
+ * `series.last()` / `.first()` / `.at(index)` / `.nearest(time)`. So "which row"
+ * is just row selection — the live snapshot is the head row; a static report
+ * pins a row by index or time. (Binding the row to a scrubbing time cursor is a
+ * later phase.) Pass `options.columns` to bound / order the category set; omit it
+ * to take every numeric value column. An empty series (or a row past the ends)
+ * yields `[]`; a missing / non-numeric cell reads as a gap (`NaN`).
+ */
+export declare function transposeRow<S extends SeriesSchema>(series: TimeSeries<S>, options?: TransposeRowOptions): CategoryDatum[];
 //# sourceMappingURL=data.d.ts.map

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,
     };
 }
 /**
@@ -452,4 +510,71 @@ export function stacksFromBins(bins, columns, options = {}) {
     }
     return { begin, end, groups: columns, values, length: n };
 }
+/**
+ * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
+ * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in
+ * order. This is the categorical row-read's geometry: the slots are ordinal
+ * indices (the bar's pixel span comes from the container's {@link ScaleBand}), and
+ * the `label`s become the axis's ordered category names (`xCategories`). A
+ * non-finite value reads as a gap (`NaN`). Reuses the shipped stacked geometry —
+ * no new draw path.
+ */
+export function categoryStack(records) {
+    const n = records.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const values = new Float64Array(n);
+    const marks = new Array(n);
+    for (let i = 0; i < n; i += 1) {
+        begin[i] = i;
+        end[i] = i + 1;
+        const v = records[i].value;
+        values[i] = Number.isFinite(v) ? v : NaN;
+        marks[i] = records[i].label;
+    }
+    // `marks` carry the category names — the stable per-bar identity the categorical
+    // axis selects on (the slot index `begin` renumbers on reorder; the name doesn't).
+    return { begin, end, groups: ['value'], values, length: n, marks };
+}
+/** A series' numeric value column names in schema order (the key column excluded). */
+function numericValueColumns(series) {
+    const schema = series.schema;
+    return schema
+        .slice(1)
+        .filter((c) => c.kind === 'number')
+        .map((c) => c.name);
+}
+/**
+ * **The transpose reader** (categorical-axis RFC, Phase 1 PR2): read **one row**
+ * of a wide `TimeSeries` **across** — its columns become the categories, that
+ * row's cells the values — for `<BarChart categories={…}>`. This is "columns on
+ * x": the schema's numeric columns (a `pivotByGroup` output's per-group columns,
+ * a vol term structure's per-expiry columns, …) laid out at one instant.
+ *
+ * The row is picked the ordinary way (`options.at`, default the **head row**):
+ * `series.last()` / `.first()` / `.at(index)` / `.nearest(time)`. So "which row"
+ * is just row selection — the live snapshot is the head row; a static report
+ * pins a row by index or time. (Binding the row to a scrubbing time cursor is a
+ * later phase.) Pass `options.columns` to bound / order the category set; omit it
+ * to take every numeric value column. An empty series (or a row past the ends)
+ * yields `[]`; a missing / non-numeric cell reads as a gap (`NaN`).
+ */
+export function transposeRow(series, options = {}) {
+    const at = options.at ?? 'last';
+    const event = at === 'last'
+        ? series.last()
+        : at === 'first'
+            ? series.first()
+            : typeof at === 'number'
+                ? series.at(at)
+                : series.nearest(at.time);
+    if (event === undefined)
+        return [];
+    const cols = options.columns ?? numericValueColumns(series);
+    const get = event.get.bind(event);
+    return cols.map((name) => {
+        const v = get(name);
+        return { label: name, value: typeof v === 'number' ? v : NaN };
+    });
+}
 //# sourceMappingURL=data.js.map

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export type { YAxisProps } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export type { XAxisProps } from './XAxis.js';
 export { TimeAxis } from './TimeAxis.js';
+export { CategoryAxis } from './CategoryAxis.js';
 export type { AxisFormat } from './format.js';
 export { LineChart } from './LineChart.js';
 export type { LineChartProps } from './LineChart.js';
@@ -47,13 +48,15 @@ export type { CandlestickProps } from './Candlestick.js';
 export type { CandleVariant, ColorBy } from './ohlc.js';
 export { scaleTradingTime } from './tradingTimeScale.js';
 export type { TradingTimeScale, DiscontinuityProvider, } from './tradingTimeScale.js';
+export { scaleBand } from './bandScale.js';
+export type { ScaleBand } from './bandScale.js';
 export { Region, Baseline, Marker } from './annotations.js';
 export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow, } from './data.js';
+export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, RowAt, TransposeRowOptions, } from './data.js';
 export type { Orientation } from './bars.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';
 export type { Curve } from './curve.js';

package/dist/index.js

@@ -23,6 +23,7 @@ export { Layers } from './Layers.js';
 export { YAxis } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export { TimeAxis } from './TimeAxis.js';
+export { CategoryAxis } from './CategoryAxis.js';
 export { LineChart } from './LineChart.js';
 export { BandChart } from './BandChart.js';
 export { AreaChart } from './AreaChart.js';
@@ -31,6 +32,8 @@ export { BoxPlot } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
 export { Candlestick } from './Candlestick.js';
 export { scaleTradingTime } from './tradingTimeScale.js';
+// The ordinal category (band) scale — the transpose view's "columns on x" axis.
+export { scaleBand } from './bandScale.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the
 // data): a shaded span, a horizontal value line, a vertical x line.
 export { Region, Baseline, Marker } from './annotations.js';
@@ -40,7 +43,11 @@ export { YAxisIndicator, createLiveValue } from './indicators.js';
 export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, 
 // Stacked / histogram readers — assemble a StackedBarSeries from pond's own
 // aggregation output: a Map of grouped series, a wide series, or byColumn bins.
-stacksFromGroups, stacksFromColumns, stacksFromBins, } from './data.js';
+stacksFromGroups, stacksFromColumns, stacksFromBins, 
+// Categorical row-read: one bar per `{ label, value }` on the category axis.
+categoryStack, 
+// The transpose reader — one row of a wide series read across into categories.
+transposeRow, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 // CSS-custom-property → ChartTheme bridge: build a theme from a design system's
 // tokens (`cssVarTheme`), and a hook that re-resolves it on a `data-theme`

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;

package/dist/tracker.d.ts

@@ -4,7 +4,41 @@
  * themselves render as an SVG overlay in `Layers` (no cursor canvas); these
  * helpers stay pure, so they're unit-tested directly.
  */
+import type { Interval } from 'pond-ts';
 import type { CursorMode } from './context.js';
+/**
+ * The interval in the sorted, non-overlapping `buckets` that contains `t`
+ * (`begin ≤ t < end`), or `undefined` if `t` falls in no bucket. Binary search —
+ * the `region` cursor uses it to find the bucket under the pointer.
+ */
+export declare function bucketAt(buckets: readonly Interval[], t: number): Interval | undefined;
+/**
+ * The `[start, end)` **span** a region cursor covers, in axis units (not pixels —
+ * the drag-release callback reports this):
+ *
+ * - **Snapping** (`buckets` non-empty, `t1` in a bucket): the bucket at `t1`, or —
+ *   with a drag anchor `t2` — the union of the `t1` and `t2` buckets, so a drag
+ *   extends **bucket by bucket** either direction. A `t2` in no bucket is ignored.
+ * - **Freeform** (`t1` in no bucket — e.g. no `cursorSequence` at all): a drag
+ *   spans the raw `[t1, t2]`; without a drag (`t2` omitted) there's nothing to
+ *   shade (the cursor renders as a plain line), so it returns `null`.
+ */
+export declare function regionSpan(buckets: readonly Interval[], t1: number, t2?: number): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * The pixel band for the `region` cursor: the {@link regionSpan} for `t1` (and an
+ * optional drag anchor `t2`), its `[start, end)` mapped through `xScale` and
+ * clamped to `[0, plotWidth]`. Returns `null` when there's no span, or when the
+ * band has no width — including a span entirely in a **collapsed gap** on a
+ * trading-time scale (both edges map to the same pixel), so it draws nothing
+ * there rather than a zero-width sliver.
+ */
+export declare function bandRect(buckets: readonly Interval[], t1: number, xScale: (value: number) => number, plotWidth: number, t2?: number): {
+    x0: number;
+    x1: number;
+} | null;
 /** Default cursor mode — the synced vertical line (cursor enabled on the
  *  container by default; pair with an off-chart readout via `onTrackerChanged`). */
 export declare const DEFAULT_CURSOR_MODE: CursorMode;
@@ -19,6 +53,9 @@ export declare function cursorParts(mode: CursorMode): {
     readonly line: boolean;
     readonly dots: boolean;
     readonly chip: 'none' | 'inline' | 'flag' | 'axis';
+    /** `region` mode: a shaded **band** over the bucket under the pointer (from
+     *  `cursorSequence`), drawn by `Layers`; no line/dots/chip of its own. */
+    readonly band: boolean;
 };
 /**
  * The crosshair's plot-pixel x from the tracker inputs. A controlled