@pond-ts/charts 0.41.0 → 0.43.0

package/dist/data.js

@@ -1,3 +1,4 @@
+import { ValueSeries } from 'pond-ts';
 /**
  * Read a numeric column into a `Float64Array`, missing cells as `NaN`.
  *
@@ -305,4 +306,217 @@ export function barsFromValueSeries(series, column) {
     const { begin, end } = neighbourSpans(series.axisValues(), n);
     return { begin, end, y, length: n };
 }
+/**
+ * The per-bin `[begin, end]` slots for a `TimeSeries`, key-shape aware — the same
+ * rule {@link barsFromTimeSeries} applies: an interval / timeRange key uses its
+ * own endpoints; a point (`time`) key synthesizes a span from neighbour spacing
+ * (see {@link neighbourSpans}). Shared by the stacked readers so a stack draws
+ * true bucket spans over an `aggregate` rollup and contiguous bars over a raw
+ * point series.
+ */
+function seriesSlots(series) {
+    const n = series.length;
+    if (series.keyColumn().kind !== 'time') {
+        return keyBeginEnd(series);
+    }
+    return neighbourSpans(series.keyColumn().begin, n);
+}
+/**
+ * Build a {@link StackedBarSeries} from a **`Map` of grouped series** — one series
+ * per stack group. This is the natural reader for pond's grouped-aggregate output:
+ * `series.partitionBy('host', { groups }).aggregate(Sequence.every('5m'), { n: 'count' }).toMap()`
+ * yields a `Map<host, TimeSeries>`, one interval-keyed series per host. The stack
+ * order (`groups`, bottom → top) is the map's **insertion order** (stable when you
+ * pass `partitionBy`'s `{ groups }` option).
+ *
+ * **Aligned by bucket key, not by index.** Each partition's `aggregate` spans only
+ * *its own* events' range, so the groups generally have **different** grids (host A
+ * might have buckets 0–8, host B buckets 3–9). This reader takes the **union** of
+ * every group's `[begin, end)` slots (ascending) and places each group's `column`
+ * value at the matching `begin`; a bucket a group is missing reads as a gap
+ * (`NaN`, contributing nothing to that stack). So the segments always line up on
+ * the real bucket, never on a positional accident. (Pass `aggregate`'s
+ * `{ range }` option if you want every group padded to one dense grid — the union
+ * is then that grid.) When two groups carry the **same `begin`**, the first
+ * group's `end` sets that slot's width — correct for the uniform-width buckets
+ * `aggregate` / `pivotByGroup` produce (all groups share the grid width), which is
+ * the intended input.
+ *
+ * @throws Error if `groups` is empty.
+ * @throws RangeError / TypeError (via {@link readNumericColumn}) if `column` is
+ *   missing or non-numeric in any member.
+ */
+export function stacksFromGroups(groups, column) {
+    const names = [...groups.keys()];
+    if (names.length === 0) {
+        throw new Error('stacksFromGroups: `groups` map is empty');
+    }
+    const series = [...groups.values()];
+    const G = names.length;
+    // Union of all groups' slots, keyed by begin (each begin → its end).
+    const ends = new Map();
+    const perGroupSlots = series.map((s) => seriesSlots(s));
+    for (let g = 0; g < G; g += 1) {
+        const { begin, end } = perGroupSlots[g];
+        for (let i = 0; i < series[g].length; i += 1) {
+            if (!ends.has(begin[i]))
+                ends.set(begin[i], end[i]);
+        }
+    }
+    const begins = [...ends.keys()].sort((a, b) => a - b);
+    const n = begins.length;
+    const beginArr = new Float64Array(n);
+    const endArr = new Float64Array(n);
+    const slotOf = new Map();
+    for (let i = 0; i < n; i += 1) {
+        beginArr[i] = begins[i];
+        endArr[i] = ends.get(begins[i]);
+        slotOf.set(begins[i], i);
+    }
+    const values = new Float64Array(n * G);
+    values.fill(NaN);
+    for (let g = 0; g < G; g += 1) {
+        const { begin } = perGroupSlots[g];
+        const col = readNumericColumn(series[g], column);
+        for (let i = 0; i < series[g].length; i += 1) {
+            const slot = slotOf.get(begin[i]);
+            if (slot !== undefined)
+                values[slot * G + g] = col[i];
+        }
+    }
+    return { begin: beginArr, end: endArr, groups: names, values, length: n };
+}
+/**
+ * Build a {@link StackedBarSeries} from a **wide** series — one numeric column
+ * per stack group. This is the reader for pond's `pivotByGroup` output (long →
+ * wide reshape: each group value becomes its own column), or any series that is
+ * already wide (e.g. `in` / `out` traffic). `columns` names the segment columns
+ * **bottom → top**; a `ValueSeries` bins on its value axis (neighbour-spaced
+ * slots), a `TimeSeries` on its key (interval spans or neighbour-spaced points).
+ *
+ * @throws RangeError / TypeError if any column is missing or non-numeric.
+ */
+export function stacksFromColumns(series, columns) {
+    const n = series.length;
+    const G = columns.length;
+    const isValue = series instanceof ValueSeries;
+    const { begin, end } = isValue
+        ? neighbourSpans(series.axisValues(), n)
+        : seriesSlots(series);
+    const values = new Float64Array(n * G);
+    for (let g = 0; g < G; g += 1) {
+        const col = isValue
+            ? readValueColumn(series, columns[g])
+            : readNumericColumn(series, columns[g]);
+        for (let i = 0; i < n; i += 1) {
+            values[i * G + g] = col[i];
+        }
+    }
+    return { begin, end, groups: columns, values, length: n };
+}
+/**
+ * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
+ * `{ start, end, …aggregates }` a value-band aggregation returns
+ * (`series.byColumn('power', { width: 20 }, { seconds: { from: 'dt', using: 'sum' } })`).
+ * `columns` names the aggregate field(s) to draw as segments (`['seconds']` for a
+ * plain distribution; several for a stacked value-band histogram).
+ *
+ * By default each bin keeps its real numeric `[start, end]` edges — a true value
+ * axis (power W, risk %). Pass `{ ordinal: true }` for uniform unit slots
+ * (`[i, i+1]`) when the bins are **categories** whose numeric width shouldn't
+ * distort the layout (heart-rate zones); label them with `<YAxis ticks>`.
+ *
+ * A missing / non-finite aggregate reads as a gap (`NaN`).
+ */
+export function stacksFromBins(bins, columns, options = {}) {
+    const n = bins.length;
+    const G = columns.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const values = new Float64Array(n * G);
+    for (let i = 0; i < n; i += 1) {
+        const bin = bins[i];
+        if (options.ordinal) {
+            begin[i] = i;
+            end[i] = i + 1;
+        }
+        else {
+            begin[i] = bin.start;
+            end[i] = bin.end;
+        }
+        const fields = bin;
+        for (let g = 0; g < G; g += 1) {
+            const v = fields[columns[g]];
+            values[i * G + g] = typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+        }
+    }
+    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/grid.d.ts

@@ -8,4 +8,18 @@
  * data layers that draw next.
  */
 export declare function drawGrid(ctx: CanvasRenderingContext2D, xTicks: readonly number[], yTicks: readonly number[], width: number, height: number, color: string, dash: readonly number[]): void;
+/**
+ * Greedily thin an **ascending** list of pixel positions so no two kept lines
+ * are closer than `minGap` px — keeps the axis from crowding when collapse
+ * points are dense (e.g. a divider at every daily candle). Keeps the first of
+ * each cluster.
+ */
+export declare function thinPixels(xs: readonly number[], minGap: number): number[];
+/**
+ * Stroke **session dividers** — solid vertical lines at each `xs` pixel, spanning
+ * the plot height. Drawn a touch stronger than the dashed gridlines (solid, so a
+ * session/day boundary reads as structural, not just another tick) at the
+ * discontinuity provider's collapse points (see `DiscontinuityProvider.boundaries`).
+ */
+export declare function drawDividers(ctx: CanvasRenderingContext2D, xs: readonly number[], height: number, color: string): void;
 //# sourceMappingURL=grid.d.ts.map

package/dist/grid.js

@@ -26,4 +26,40 @@ export function drawGrid(ctx, xTicks, yTicks, width, height, color, dash) {
     ctx.stroke();
     ctx.restore();
 }
+/**
+ * Greedily thin an **ascending** list of pixel positions so no two kept lines
+ * are closer than `minGap` px — keeps the axis from crowding when collapse
+ * points are dense (e.g. a divider at every daily candle). Keeps the first of
+ * each cluster.
+ */
+export function thinPixels(xs, minGap) {
+    const out = [];
+    for (const x of xs) {
+        if (out.length === 0 || x - out[out.length - 1] >= minGap)
+            out.push(x);
+    }
+    return out;
+}
+/**
+ * Stroke **session dividers** — solid vertical lines at each `xs` pixel, spanning
+ * the plot height. Drawn a touch stronger than the dashed gridlines (solid, so a
+ * session/day boundary reads as structural, not just another tick) at the
+ * discontinuity provider's collapse points (see `DiscontinuityProvider.boundaries`).
+ */
+export function drawDividers(ctx, xs, height, color) {
+    if (xs.length === 0)
+        return;
+    ctx.save();
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 1;
+    ctx.setLineDash([]);
+    ctx.beginPath();
+    for (const x of xs) {
+        const px = Math.round(x) + 0.5;
+        ctx.moveTo(px, 0);
+        ctx.lineTo(px, height);
+    }
+    ctx.stroke();
+    ctx.restore();
+}
 //# sourceMappingURL=grid.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';
@@ -45,13 +46,18 @@ export type { BarChartProps } from './BarChart.js';
 export { Candlestick } from './Candlestick.js';
 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, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, } 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';
 export type { GapMode } from './gaps.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';
@@ -30,13 +31,23 @@ export { ScatterChart } from './ScatterChart.js';
 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';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, } from './data.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, 
+// 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

@@ -44,13 +44,15 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
  * @param labelAt optional per-point text label; `undefined` ⇒ no labels drawn.
  * @param font    `theme.font` (family + size) for label text.
  * @param selected the container's current selection (or `null`).
- * @param seriesLabel this layer's series identity (`as` ?? column) — the
- *                `label` half of the selection match.
+ * @param seriesId this layer's stable series identity (its `id` prop, or
+ *                `undefined` when the layer isn't selectable) — the series half
+ *                of the selection match. A point lights only when the selection's
+ *                `id` matches, keyed to the sample by its `key`.
  */
 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, seriesLabel: string): void;
+}, selected: SelectInfo | null, seriesId: string | undefined): void;
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the
@@ -59,12 +61,12 @@ export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeri
  *
  * A point's hit radius is its drawn radius (data-driven or base) — clicking the
  * visible disc selects it. Distance is compared squared (no `sqrt` in the loop).
- * Returns the point's {@link SelectInfo} with `key = keyAt(i)` (its event
- * `begin`), the encoded fill colour (so the readout swatch matches the mark),
- * and the series `label`.
+ * Returns the point's {@link SelectInfo} with the series `id` (the selection
+ * identity), `key = keyAt(i)` (its event `begin` — click provenance), the encoded
+ * fill colour (so the readout swatch matches the mark), and the display `label`.
  *
  * 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, 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): SelectInfo | null;
 //# sourceMappingURL=scatter.d.ts.map

package/dist/scatter.js

@@ -109,13 +109,16 @@ export function scatterExtent(cs) {
  * @param labelAt optional per-point text label; `undefined` ⇒ no labels drawn.
  * @param font    `theme.font` (family + size) for label text.
  * @param selected the container's current selection (or `null`).
- * @param seriesLabel this layer's series identity (`as` ?? column) — the
- *                `label` half of the selection match.
+ * @param seriesId this layer's stable series identity (its `id` prop, or
+ *                `undefined` when the layer isn't selectable) — the series half
+ *                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, seriesLabel) {
+export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId) {
     ctx.save();
     // The selection only lights up a point of *this* series; resolve the key once.
-    const selectedKey = selected !== null && selected.label === seriesLabel ? selected.key : null;
+    // A no-id (non-selectable) layer passes `undefined` and never matches.
+    const selectedKey = selected !== null && selected.id === seriesId ? selected.key : null;
     let selPx = 0;
     let selPy = 0;
     let selR = 0;
@@ -183,14 +186,14 @@ const LABEL_GAP = 4;
  *
  * A point's hit radius is its drawn radius (data-driven or base) — clicking the
  * visible disc selects it. Distance is compared squared (no `sqrt` in the loop).
- * Returns the point's {@link SelectInfo} with `key = keyAt(i)` (its event
- * `begin`), the encoded fill colour (so the readout swatch matches the mark),
- * and the series `label`.
+ * Returns the point's {@link SelectInfo} with the series `id` (the selection
+ * identity), `key = keyAt(i)` (its event `begin` — click provenance), the encoded
+ * fill colour (so the readout swatch matches the mark), and the display `label`.
  *
  * 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, seriesLabel) {
+export function hitTestScatter(cs, qx, qy, xScale, yScale, encoding, keyAt, id, seriesLabel) {
     for (let i = cs.length - 1; i >= 0; i -= 1) {
         if (!isPoint(cs, i))
             continue;
@@ -201,6 +204,7 @@ export function hitTestScatter(cs, qx, qy, xScale, yScale, encoding, keyAt, seri
         const dy = qy - py;
         if (dx * dx + dy * dy <= r * r) {
             return {
+                id,
                 key: keyAt(i),
                 value: cs.y[i],
                 color: encoding.colorAt(i),

package/dist/theme.d.ts

@@ -104,6 +104,13 @@ export interface ChartTheme {
         readonly grid: string;
         /** Gridline dash pattern (px on/off pairs); `[]` for solid. */
         readonly gridDash: readonly number[];
+        /**
+         * Stroke for **session dividers** — the solid verticals a trading-time axis
+         * draws at each collapsed gap (session/day open). Optional; falls back to
+         * {@link grid}. Set it a touch stronger than the gridlines so a session
+         * boundary reads as structural.
+         */
+        readonly sessionDivider?: string;
         /**
          * Typography for the axis **title** — the rotated y-axis unit strip and the
          * x-axis label (distinct from the per-tick `label` colour above). Omit a

package/dist/theme.js

@@ -111,6 +111,7 @@ export const defaultTheme = {
         label: '#64748b',
         grid: '#e2e8f0',
         gridDash: [2, 2],
+        sessionDivider: '#cbd5e1', // slate-300 — a step stronger than the gridlines
     },
     font: {
         family: 'system-ui, -apple-system, sans-serif',

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

package/dist/tracker.js

@@ -4,6 +4,72 @@
  * themselves render as an SVG overlay in `Layers` (no cursor canvas); these
  * helpers stay pure, so they're unit-tested directly.
  */
+/**
+ * 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 function bucketAt(buckets, t) {
+    let lo = 0;
+    let hi = buckets.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const b = buckets[mid];
+        if (t < b.begin())
+            hi = mid - 1;
+        else if (t >= b.end())
+            lo = mid + 1;
+        else
+            return b;
+    }
+    return 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 function regionSpan(buckets, t1, t2) {
+    const a = bucketAt(buckets, t1);
+    if (a === undefined) {
+        // Freeform: no bucket under t1. A drag spans the raw [t1, t2]; a bare hover
+        // has nothing to shade (Layers draws a line for the degenerate region cursor).
+        return t2 === undefined
+            ? null
+            : { start: Math.min(t1, t2), end: Math.max(t1, t2) };
+    }
+    if (t2 === undefined)
+        return { start: a.begin(), end: a.end() };
+    const b = bucketAt(buckets, t2);
+    if (b === undefined)
+        return { start: a.begin(), end: a.end() };
+    return {
+        start: Math.min(a.begin(), b.begin()),
+        end: Math.max(a.end(), b.end()),
+    };
+}
+/**
+ * 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 function bandRect(buckets, t1, xScale, plotWidth, t2) {
+    const span = regionSpan(buckets, t1, t2);
+    if (span === null)
+        return null;
+    const x0 = Math.max(0, xScale(span.start));
+    const x1 = Math.min(plotWidth, xScale(span.end));
+    return x1 > x0 ? { x0, x1 } : null;
+}
 /** Default cursor mode — the synced vertical line (cursor enabled on the
  *  container by default; pair with an off-chart readout via `onTrackerChanged`). */
 export const DEFAULT_CURSOR_MODE = 'line';
@@ -15,22 +81,27 @@ export const DEFAULT_CURSOR_MODE = 'line';
  * value flag stacked near the top of the row (drawn in `Layers`).
  */
 export function cursorParts(mode) {
+    const base = { line: false, dots: false, chip: 'none', band: false };
     switch (mode) {
         case 'line':
-            return { line: true, dots: false, chip: 'none' };
+            return { ...base, line: true };
         case 'point':
-            return { line: false, dots: true, chip: 'none' };
+            return { ...base, dots: true };
         case 'inline':
-            return { line: false, dots: true, chip: 'inline' };
+            return { ...base, dots: true, chip: 'inline' };
         case 'flag':
-            return { line: false, dots: true, chip: 'flag' };
+            return { ...base, dots: true, chip: 'flag' };
         case 'crosshair':
             // A single reticle (not per-series): `Layers` draws the dashed vertical +
             // full-width horizontal lines, the centre dot, and one value pill itself
             // (so no generic line/dots here); the x-time pill is on `<XAxis>`.
-            return { line: false, dots: false, chip: 'axis' };
+            return { ...base, chip: 'axis' };
+        case 'region':
+            // A shaded band over the bucket under the pointer — `Layers` resolves the
+            // bucket from `cursorBuckets` and draws the rect (cropped through xScale).
+            return { ...base, band: true };
         case 'none':
-            return { line: false, dots: false, chip: 'none' };
+            return { ...base };
     }
 }
 /**