@pond-ts/charts 0.42.0 → 0.44.0

package/dist/BoxPlot.js

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

package/dist/CategoryAxis.d.ts

@@ -0,0 +1,16 @@
+import { type XAxisProps } from './XAxis.js';
+/**
+ * The category-flavoured preset of {@link XAxis} — `<CategoryAxis />` is
+ * `<XAxis />`. The axis kind follows the data: on a **category** container (a
+ * layer that plots on the ordinal column-domain axis) it ticks once per category,
+ * labelling each band centre with the category name (the container's shared
+ * formatter). Kept as the familiar name for categorical charts, mirroring
+ * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
+ *
+ * A high-cardinality axis (many categories) thins + truncates its labels to stay
+ * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
+ * `categories` list), so a d3 `format` prop does not apply here (it can't name a
+ * category); customize a label by changing the `categories` datum's `label`.
+ */
+export declare function CategoryAxis(props?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=CategoryAxis.d.ts.map

package/dist/CategoryAxis.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { XAxis } from './XAxis.js';
+/**
+ * The category-flavoured preset of {@link XAxis} — `<CategoryAxis />` is
+ * `<XAxis />`. The axis kind follows the data: on a **category** container (a
+ * layer that plots on the ordinal column-domain axis) it ticks once per category,
+ * labelling each band centre with the category name (the container's shared
+ * formatter). Kept as the familiar name for categorical charts, mirroring
+ * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
+ *
+ * A high-cardinality axis (many categories) thins + truncates its labels to stay
+ * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
+ * `categories` list), so a d3 `format` prop does not apply here (it can't name a
+ * category); customize a label by changing the `categories` datum's `label`.
+ */
+export function CategoryAxis(props = {}) {
+    return _jsx(XAxis, { ...props });
+}
+//# sourceMappingURL=CategoryAxis.js.map

package/dist/ChartContainer.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingTimeScale.js';
+import { Sequence, BoundedSequence } from 'pond-ts';
 import type { TimeRange } from 'pond-ts';
 import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
 import { type AxisFormat } from './format.js';
@@ -75,9 +76,63 @@ export interface ChartContainerProps {
      * via `<ChartRow cursor>`). **Default `'line'`** — the synced vertical line,
      * with values surfaced *outside* the chart via {@link onTrackerChanged}.
      * `'point'` / `'inline'` / `'flag'` add per-series marks; `'none'` hides it.
+     * `'region'` shades the bucket under the pointer (needs {@link cursorSequence}).
      * See {@link CursorMode}.
      */
     cursor?: CursorMode;
+    /**
+     * The bucketing for `cursor="region"` — the interval highlighted under the
+     * pointer. A pond {@link Sequence} (duration or calendar-aware —
+     * `Sequence.every('1d')`, `Sequence.calendar('month')`) is realized over the
+     * current view; a {@link BoundedSequence} (e.g. a `TradingCalendar`'s
+     * `sessionSequence()` / `barSequence()`) is used as-is, so the band can track
+     * whole **sessions**. Either way the band maps through `xScale`, so on a
+     * trading-time axis the closed part of the bucket collapses. Ignored unless
+     * `cursor="region"`.
+     *
+     * **Time axis only.** A bucket is a *time* interval, so the region cursor is
+     * gated to a **time** x-axis — on a **value** axis (a horizontal histogram, a
+     * value-keyed chart) it's a no-op (highlighting a value *band* on a horizontal
+     * histogram would be a different, y-oriented cursor).
+     *
+     * **Pass a stable reference.** The buckets are memoized on this value + the
+     * view range; a `Sequence`/`BoundedSequence` rebuilt inline every render
+     * re-realizes the buckets on each pointer move (harmless for a coarse
+     * day/session sequence, wasteful for a fine one over a wide view) — hoist it or
+     * `useMemo` it.
+     */
+    cursorSequence?: Sequence | BoundedSequence;
+    /**
+     * Makes the `region` cursor **draggable**: drag across the plot and the band
+     * extends **bucket by bucket** (snapping to `cursorSequence` points); on
+     * release this fires **once** with the selected `[lo, hi]` span, and the cursor
+     * reverts to the single-bucket highlight (it does not keep the range). Typical
+     * use — zoom the view to the returned span (the container doesn't zoom itself;
+     * that's the consumer's call), or map it onto a data subscription's range params.
+     *
+     * The span is a **neutral numeric pair in axis units** — epoch ms on a **time**
+     * axis, the axis value (strike, distance, …) on a **value** axis — mirroring the
+     * polymorphic `range` input. A time consumer that wants a `TimeRange` builds one
+     * from the pair.
+     *
+     * With **no `cursorSequence`** the region cursor is the degenerate case — it
+     * renders as a **line** on hover and the drag is **freeform** (raw `[lo, hi]`, no
+     * bucket snapping); the same callback fires on release. Bucket snapping needs a
+     * `cursorSequence`, which is **time-axis only** (a time interval over a value
+     * domain is meaningless), so a **value** axis is always freeform. No-op unless
+     * `cursor="region"` on a **time** or **value** x-axis (a **category** axis is
+     * excluded — an ordinal-slot select is a different gesture).
+     */
+    onRegionSelect?: (range: readonly [number, number]) => void;
+    /**
+     * Which modifier a region-drag needs — set `'shift'` when you also enable
+     * `panZoom` and want **plain drag to pan, shift-drag to select**. It's only
+     * enforced while `panZoom` is on (with pan off there's no gesture conflict, so
+     * shift is optional — either drag selects). **Omitted** ⇒ a region-drag
+     * **preempts** pan (drag always selects; document that precedence for users).
+     * Wheel-zoom is unaffected in every case.
+     */
+    regionSelectModifier?: 'shift';
     /**
      * Fires on pointer move with the hovered time + every series' value there (so
      * you can render a readout outside the chart), and `null` on leave.
@@ -226,5 +281,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, discontinuities, calendar, spacing, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, discontinuities, calendar, spacing, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -2,6 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { scaleLinear, scaleTime } from 'd3-scale';
 import { scaleTradingTime, } from './tradingTimeScale.js';
+import { scaleBand } from './bandScale.js';
+import { Sequence } from 'pond-ts';
 import { ContainerContext, } from './context.js';
 import { maxSlotWidths, sum } from './slots.js';
 import { computeLabelLanes } from './annotations.js';
@@ -32,7 +34,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, discontinuities, calendar, spacing, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, discontinuities, calendar, spacing, children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -78,6 +80,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // still cursor stays put while a live window slides under it; a controlled
     // `trackerPosition` resolves to a pixel below.
     const [hoverX, setHoverX] = useState(null);
+    // The region-cursor drag anchor (epoch ms) — set on press, cleared on release.
+    const [regionAnchor, setRegionAnchor] = useState(null);
     // The free-form crosshair also needs the pointer's y + which row (row-specific,
     // unlike the shared x). One state object so a move updates both atomically.
     const [hoverPoint, setHoverPoint] = useState(null);
@@ -151,11 +155,31 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             else if (kind !== s.xKind) {
                 throw new Error(`ChartContainer: rows mix x-axis kinds ('${kind}' and '${s.xKind}'). ` +
                     `A container has one shared x axis — every row must plot the same ` +
-                    `kind (all time-keyed, or all value-keyed).`);
+                    `kind (all time-keyed, all value-keyed, or all category).`);
             }
         }
         return kind ?? 'time';
     }, [sources]);
+    // A `'category'` container's ordered category names — the ordinal axis domain.
+    // Every category layer must agree on the same list (a mix is an error, like the
+    // kind), so the shared band scale has one authoritative slot order. `null` when
+    // no category layer has registered (or the kind isn't category).
+    const categories = useMemo(() => {
+        let cats = null;
+        for (const s of sources.values()) {
+            const c = s.xCategories?.() ?? null;
+            if (c === null)
+                continue;
+            if (cats === null)
+                cats = c;
+            else if (cats.length !== c.length || cats.some((v, i) => v !== c[i])) {
+                throw new Error(`ChartContainer: category rows disagree on the axis categories. ` +
+                    `Every category layer in one container must share the same ordered ` +
+                    `column set (got [${cats.join(', ')}] and [${c.join(', ')}]).`);
+            }
+        }
+        return cats;
+    }, [sources]);
     // Auto-fit extent — the union of the layers' x extents — used as the domain
     // when no explicit `range` is given. (Same source registry as the kind; the
     // two-pass register→resolve applies.)
@@ -300,6 +324,17 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         : undefined, [resolvedKind, discontinuities, calendar, spacing]);
     const xDiscontinuities = resolvedKind === 'time' ? (discontinuities ?? calendarProvider) : undefined;
     const { xScale, formatTime } = useMemo(() => {
+        if (resolvedKind === 'category') {
+            // Ordinal column-domain axis: a band scale over the category slots. The
+            // domain is **always** `[0, n]` (one unit slot per category) — NOT the
+            // resolved `[d0, d1]`: a category axis ignores an explicit `range` (its
+            // slots are absolute `0..n`, matching `categoryStack`), so an out-of-`[0,n]`
+            // range can't silently offset the labels from the bars. The pixel mapping
+            // stays linear; the formatter is the category-name lookup.
+            const cats = categories ?? [];
+            const s = scaleBand(cats).domain([0, cats.length]).range([0, plotWidth]);
+            return { xScale: s, formatTime: (v) => s.label(v) };
+        }
         if (resolvedKind === 'value') {
             const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
             return {
@@ -323,12 +358,65 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             xScale: s,
             formatTime: resolveTimeFormat(s, TIME_TICK_COUNT, timeFormat),
         };
-    }, [resolvedKind, d0, d1, plotWidth, timeFormat, xDiscontinuities]);
+    }, [
+        resolvedKind,
+        categories,
+        d0,
+        d1,
+        plotWidth,
+        timeFormat,
+        xDiscontinuities,
+    ]);
     // The crosshair pixel (see resolveCursorX). A stored hoverX is a *plot* pixel;
     // if plotWidth changes mid-hover (a gutter reserving, or a width change) it's
     // briefly stale until the next pointer move — rare, and the bounds check below
     // hides an out-of-plot crosshair meanwhile.
     const cursorX = resolveCursorX(trackerPosition, hoverX, xScale);
+    // `cursor="region"` snap buckets — the intervals the band snaps to (and a drag
+    // extends bucket by bucket over). Two sources, in precedence order:
+    //
+    // 1. **An explicit `cursorSequence`** (time axis only): realized over the view
+    //    (a `Sequence` → `.bounded`; a `BoundedSequence` used as-is). A `Sequence`
+    //    bucket is a *time* interval, so it's gated to a time axis — realizing time
+    //    buckets over a value domain is meaningless (it would shade the whole plot).
+    // 2. **A bar/histogram layer's bins** (`binIntervals`, time **or** value axis):
+    //    when no `cursorSequence` is set, the region cursor snaps to the bars —
+    //    a histogram gets bin-aligned selection for free (the first bar layer that
+    //    publishes bins wins; a plain histogram has exactly one).
+    //
+    // With neither, `undefined` ⇒ the freeform region cursor (raw-span drag).
+    const cursorBuckets = useMemo(() => {
+        if (cursorSequence !== undefined && resolvedKind === 'time') {
+            if (!(cursorSequence instanceof Sequence))
+                return cursorSequence.intervals();
+            // `bounded` (sample 'begin') drops a partial *leading* bucket — the one that
+            // contains the view start begins before it. Widen the realized range back by
+            // one bucket width so that covering bucket is included (a coarse calendar
+            // unit is bounded at ~a year; a fixed step uses its own width).
+            const back = cursorSequence.kind() === 'fixed'
+                ? cursorSequence.stepMs()
+                : 366 * 86_400_000;
+            return cursorSequence.bounded({ start: d0 - back, end: d1 }).intervals();
+        }
+        // No sequence → snap to a bar/histogram layer's bins, if any (a value axis,
+        // or a time-axis histogram with no explicit sequence). `binIntervals` is only
+        // published by a vertical bar layer on a continuous axis, so this is a no-op
+        // for line/area/scatter rows and for a category axis.
+        //
+        // **First bar layer wins** — deliberately non-fatal, unlike `xCategories`
+        // (which *throws* when category rows disagree, because a mismatched slot order
+        // corrupts the shared band scale). Two overlaid histograms with different bins
+        // is a degenerate layout the region cursor just snaps to whichever registered
+        // first; a wrong snap grid is harmless where a wrong axis is not.
+        if (resolvedKind === 'time' || resolvedKind === 'value') {
+            for (const s of sources.values()) {
+                const bins = s.binIntervals?.() ?? null;
+                if (bins && bins.length > 0)
+                    return bins;
+            }
+        }
+        return undefined;
+    }, [cursorSequence, d0, d1, resolvedKind, sources]);
     // Emit { time, values } for an outside readout — recomputed as the cursor moves
     // *or* the window slides under it (xScale change → new time at the same pixel).
     // Out of the plot (null, or a controlled trackerPosition d3 extrapolated past
@@ -369,6 +457,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         cursorRowKey: hoverPoint?.rowKey ?? null,
         setHoverY,
         crosshairSnap,
+        cursorBuckets,
+        regionAnchor,
+        setRegionAnchor,
+        onRegionSelect,
+        regionSelectModifier,
         draggingKey,
         setDragging,
         selected: selectedValue,
@@ -417,6 +510,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         hoverPoint,
         setHoverY,
         crosshairSnap,
+        cursorBuckets,
+        regionAnchor,
+        setRegionAnchor,
+        onRegionSelect,
+        regionSelectModifier,
         draggingKey,
         setDragging,
         selectedValue,

package/dist/Layers.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
 import { drawGrid, drawDividers, thinPixels } from './grid.js';
-import { cursorParts } from './tracker.js';
+import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
@@ -69,7 +69,9 @@ export function Layers({ children }) {
         // Explicit `<YAxis ticks>` drive the gridlines too, so they align with the
         // axis labels; otherwise d3 auto-picks (the default).
         const explicitY = tickValues.get(defaultAxisId);
-        const xTickVals = xScale.ticks(GRID_TICKS);
+        // A category axis draws no vertical gridlines — a line through each bar
+        // centre reads as noise; the bars are the structure.
+        const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(GRID_TICKS);
         const xTicks = xTickVals.map((d) => xScale(+d));
         const yTicks = gridY
             ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
@@ -257,7 +259,33 @@ export function Layers({ children }) {
             }
             return;
         }
-        if (!c.panZoom)
+        // Region-cursor drag-select (opt-in via `onRegionSelect`): anchor the
+        // selection at the press; the band then extends as the pointer moves (bucket
+        // by bucket with a sequence, freeform without), and release commits the span.
+        // Works on a continuous x axis — time **or** value (a category axis is
+        // excluded; its ordinal-slot select is a different gesture). A
+        // `regionSelectModifier` (only while `panZoom` is on) gates it behind the key
+        // so plain drag can still pan; otherwise it preempts pan (returns before the
+        // pan is armed below).
+        if (c.cursor === 'region' &&
+            c.onRegionSelect &&
+            (c.xKind === 'time' || c.xKind === 'value')) {
+            const needsShift = c.regionSelectModifier === 'shift' && c.panZoom;
+            if (!needsShift || e.shiftKey) {
+                const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+                c.setRegionAnchor(+c.xScale.invert(px));
+                c.setHoverX(px);
+                try {
+                    e.currentTarget.setPointerCapture(e.pointerId);
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            // Modifier required but not held → fall through to pan.
+        }
+        if (!c.panZoom || c.xKind === 'category')
             return;
         const r = c.timeRange;
         // Arm a potential pan: record the anchor, but DON'T capture the pointer or
@@ -287,6 +315,13 @@ export function Layers({ children }) {
             c.setHoverX(px); // share the preview x so other rows draw a guide there
             return;
         }
+        // Region drag in progress: just track the pointer x (the band spans from the
+        // anchor bucket to here); no pan, no hover hit-test.
+        if (c.regionAnchor !== null) {
+            const rect = e.currentTarget.getBoundingClientRect();
+            c.setHoverX(Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left)));
+            return;
+        }
         // A pan is only live while a button is held. A move with no buttons means
         // the press already ended without us seeing the pointerup — which the
         // deferred-capture path allows: an uncommitted (sub-slop) potential-pan
@@ -372,6 +407,22 @@ export function Layers({ children }) {
     }, []);
     const handlePointerUp = useCallback((e) => {
         const c = containerRef.current;
+        // End a region drag: commit the anchor→pointer span as a one-shot range,
+        // then clear the anchor (the cursor reverts to the single-bucket highlight).
+        if (c.regionAnchor !== null) {
+            const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+            const span = regionSpan(c.cursorBuckets ?? [], c.regionAnchor, +c.xScale.invert(px));
+            c.setRegionAnchor(null);
+            try {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+            if (span)
+                c.onRegionSelect?.([span.start, span.end]);
+            return;
+        }
         if (c.creating !== null) {
             const rect = e.currentTarget.getBoundingClientRect();
             const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
@@ -439,6 +490,10 @@ export function Layers({ children }) {
             c.setHoverY(null, null);
             return;
         }
+        // Cancel a region-drag on leave (no commit) — a safety net for the rare case
+        // where the pointer capture didn't take, so the anchor can't get stuck.
+        if (c.regionAnchor !== null)
+            c.setRegionAnchor(null);
         c.setHoverX(null);
         c.setHoverY(null, null);
         c.setHovered(null);
@@ -478,7 +533,7 @@ export function Layers({ children }) {
             return;
         const onWheel = (e) => {
             const c = containerRef.current;
-            if (!c.panZoom)
+            if (!c.panZoom || c.xKind === 'category')
                 return;
             e.preventDefault();
             const rect = el.getBoundingClientRect();
@@ -571,6 +626,23 @@ export function Layers({ children }) {
             side: axisSides.get(defaultAxisId) ?? 'left',
         };
     })();
+    // `region` cursor (continuous x axis — time or value): shade the span under the
+    // pointer. With a `cursorSequence` (time axis only) the band snaps to the bucket
+    // (and extends bucket by bucket under a drag); with none — always the case on a
+    // value axis — it's the **freeform** case: a bare hover draws a plain line
+    // (`regionLine`), a drag shades the raw `[anchor, pointer]`. Edges map through
+    // `xScale`, so on a trading-time axis the band crops to live time.
+    const regionActive = parts.band && (container.xKind === 'time' || container.xKind === 'value');
+    const band = regionActive && cursorTime !== null
+        ? bandRect(container.cursorBuckets ?? [], cursorTime, (v) => xScale(v), plotWidth, container.regionAnchor ?? undefined)
+        : null;
+    // Degenerate region cursor (no sequence, not mid-drag): a plain vertical line.
+    const regionLine = regionActive &&
+        container.cursorBuckets === undefined &&
+        container.regionAnchor === null &&
+        cursorX !== null &&
+        cursorX >= 0 &&
+        cursorX <= plotWidth;
     // Cross-row guide lines: the x-positions of annotations on the OTHER rows
     // (markers + region edges), so a mark on one row reads against this row's data +
     // the shared x axis. A mark's own row skips itself; baselines cast no vertical
@@ -638,7 +710,7 @@ export function Layers({ children }) {
                         top: 0,
                         left: 0,
                         pointerEvents: 'none',
-                    }, children: [parts.line &&
+                    }, children: [band !== null && (_jsx("rect", { x: band.x0, y: 0, width: band.x1 - band.x0, height: row.height, fill: cursorColor, opacity: 0.12 })), regionLine && cursorX !== null && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.line &&
                             cursorX !== null &&
                             cursorX >= 0 &&
                             cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&