@pond-ts/charts 0.41.0 → 0.43.0

package/dist/BarChart.js

@@ -1,49 +1,53 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
-import { barsFromTimeSeries, barsFromValueSeries } from './data.js';
-import { barAt, barExtent, barIndexAtTime, drawBars, resolveBarBaseline, } from './bars.js';
+import { barsFromTimeSeries, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
+import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
- * A bar draw layer: one rectangle per event, spanning the key's `[begin, end]`
- * (inset by `gap`) from the axis baseline to a numeric `column`'s value. Reads
- * the key endpoints + column into a {@link BarSeries}, registers into the
- * enclosing {@link Layers} (scaling against its `axis`), and renders nothing to
- * the DOM — the row draws it. A gap (missing value) is skipped (no bar).
+ * A bar / histogram draw layer. In its simplest form, one rectangle per event
+ * spanning the key's `[begin, end]` from the axis baseline to a numeric
+ * `column`'s value (see below). It also draws **stacked** bars (a group-by
+ * dimension → segments, `columns` / a `Map` series / `bins`) and **horizontal**
+ * bars (`orientation='horizontal'`, bins on the y axis) — first-class histogram
+ * support. Registers into the enclosing {@link Layers} and renders nothing to the
+ * DOM; the row draws it.
  *
- * **Baseline.** Bars rest on the zero line when the axis domain spans zero (the
- * common all-positive auto-fit case — {@link barExtent} pulls `0` into the
- * domain), or on the axis floor when an explicit `<YAxis min={…}>` sits above
- * zero (see {@link resolveBarBaseline}).
+ * **Data sources.** A time / value `TimeSeries` or `ValueSeries` (`column`), a
+ * wide series or `bins` array (`columns`), or a `Map<group, TimeSeries>`
+ * (`column`) — the last three stack. Every shape composes from pond's own
+ * aggregation (`aggregate` / `byColumn` / `partitionBy`); the histogram guide
+ * has the recipes.
  *
- * **Interaction.** Hover joins the tracker (`sampleAt` → the value of the bar
- * **under the cursor**) and lights that bar (hover-highlight). Click selects the
- * hit bar (`hitTest`); the matching bar — same key **and** this series' `label`,
- * so two series sharing a timestamp don't both light up — draws highlighted
- * (outlined for the committed select, fill-only for the transient hover). Both
- * resolve by **containment**: the tracker by the bar's `[begin, end]` time span
- * (`barIndexAtTime`), the click by the bar's pixel rect (`barAt`) — so the
- * readout reads the same bar you click, even across a wide bucket (they differ
- * only by the `gap` inset, where the pixel rect is narrower than the span).
+ * **Baseline (single, vertical).** Bars rest on the zero line when the axis
+ * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
+ * above zero (see {@link resolveBarBaseline}).
  *
- * Both channels are also **controllable from outside** the chart via the
- * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
- * — pass either to pin the lit/selected bar from a legend or list row, and read
- * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
- * keyed by the same {@link SelectInfo} identity.
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
+ * sum upward from the zero line, so its value axis **must include 0**. The
+ * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
+ * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
+ * would hide the bottom of the cumulative column; only the portion above the floor
+ * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
+ * Segment values are assumed **non-negative** (a negative or zero segment is
+ * skipped — diverging stacks are out of scope).
  *
- * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
- * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
- * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is
- * neighbour-derived like a point `TimeSeries` (see {@link barsFromValueSeries}).
+ * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
+ * cursor (hit-tested by pixel rect, so it works in both orientations); click
+ * selects it (outlined). A stacked segment's identity is `(id, key = bin begin,
+ * label = group)`. Both channels are controllable from outside via the container
+ * (`selected`/`onSelect`, `hovered`/`onHover`). The in-chart `flag`/`crosshair`
+ * value cursor is single-series-vertical only.
  *
  * ```tsx
  * <Layers>
  *   <BarChart series={hourlyVolume} column="count" />
+ *   <BarChart series={byHost} column="n" colors={{ web1: '#…' }} />
+ *   <BarChart bins={powerDist} column="seconds" orientation="horizontal" ordinal />
  * </Layers>
  * ```
  */
-export function BarChart({ series, column, as: semantic, axis, gap, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -52,98 +56,291 @@ export function BarChart({ series, column, as: semantic, axis, gap, index = 0, }
     if (layers === null) {
         throw new Error('<BarChart> must be rendered inside a <Layers>');
     }
-    const bs = useMemo(() => series instanceof ValueSeries
-        ? barsFromValueSeries(series, column)
-        : barsFromTimeSeries(series, column), [series, column]);
-    // Styling: semantic identifier → theme bar style. The single styling channel.
+    // Validate the data-source / value-column combination up front (throws are
+    // stable across renders, so no need to memoize them).
+    const nSources = (series !== undefined ? 1 : 0) +
+        (bins !== undefined ? 1 : 0) +
+        (categories !== undefined ? 1 : 0);
+    if (nSources !== 1) {
+        throw new Error('<BarChart> needs exactly one of `series`, `bins`, or `categories`');
+    }
+    if (categories !== undefined) {
+        if (column !== undefined || columns !== undefined) {
+            throw new Error('<BarChart categories> takes no `column`/`columns` (each datum carries its own value)');
+        }
+        if (orientation === 'horizontal') {
+            throw new Error('<BarChart categories> is vertical only (categories on x); horizontal category axes are not yet supported');
+        }
+    }
+    const isMap = series instanceof Map;
+    if (isMap && columns !== undefined) {
+        throw new Error('<BarChart> with a `Map` series stacks its groups — use `column` (the shared value column), not `columns`');
+    }
+    if (column !== undefined && columns !== undefined) {
+        throw new Error('<BarChart> takes `column` or `columns`, not both');
+    }
+    // The single series' semantic label (its identity for the readout + selection):
+    // the `as` role, else the value column. Used only on the single path.
+    const label = semantic ?? column ?? id ?? 'value';
+    // Build the chart-ready data view. Single-series *vertical* stays on the
+    // original BarSeries path (its pixels are unchanged); everything else — any
+    // stack, any horizontal — builds a StackedBarSeries (G === 1 for a single
+    // horizontal bar) so one oriented draw path covers it.
+    const shape = useMemo(() => {
+        if (categories !== undefined) {
+            // Categorical row-read: one unit-slot bar per category (G === 1), drawn on
+            // the container's band scale. The reused stacked geometry — only the axis
+            // (band scale + labels) is new.
+            return { kind: 'stacked', ss: categoryStack(categories) };
+        }
+        if (bins !== undefined) {
+            const cols = columns ?? (column !== undefined ? [column] : undefined);
+            if (cols === undefined) {
+                throw new Error('<BarChart bins> needs `column` or `columns`');
+            }
+            return { kind: 'stacked', ss: stacksFromBins(bins, cols, { ordinal }) };
+        }
+        if (isMap) {
+            if (column === undefined) {
+                throw new Error('<BarChart> with a `Map` series needs `column`');
+            }
+            return {
+                kind: 'stacked',
+                ss: stacksFromGroups(series, column),
+            };
+        }
+        const s = series;
+        if (columns !== undefined) {
+            return { kind: 'stacked', ss: stacksFromColumns(s, columns) };
+        }
+        if (column === undefined) {
+            throw new Error('<BarChart> needs `column` or `columns`');
+        }
+        if (orientation === 'horizontal') {
+            // Single horizontal bar: route through the stacked path (G === 1), naming
+            // the one group with the series' label so selection matches on it.
+            const ss = stacksFromColumns(s, [column]);
+            return { kind: 'stacked', ss: { ...ss, groups: [label] } };
+        }
+        return {
+            kind: 'single',
+            bs: s instanceof ValueSeries
+                ? barsFromValueSeries(s, column)
+                : barsFromTimeSeries(s, column),
+        };
+    }, [
+        series,
+        bins,
+        categories,
+        column,
+        columns,
+        ordinal,
+        orientation,
+        isMap,
+        label,
+    ]);
+    // The category labels — the ordinal axis's ordered column set (`xCategories`),
+    // and the per-bar readout label. `null` unless this is a categorical chart.
+    const categoryLabels = useMemo(() => categories?.map((c) => c.label) ?? null, [categories]);
+    // The bin axis kind — `'category'` for a categorical chart, else `'time'`/`'value'`
+    // (a `TimeSeries`/`Map` bins on time, a `ValueSeries`/`bins`-array on a value
+    // axis). For a vertical chart this is the shared x-kind; a horizontal one puts
+    // the *value* on x (always 'value') and the bin axis on a linear y.
+    const binAxisKind = categories !== undefined
+        ? 'category'
+        : bins !== undefined
+            ? 'value'
+            : isMap
+                ? 'time'
+                : series instanceof ValueSeries
+                    ? 'value'
+                    : 'time';
     const { bar } = container.theme;
-    const style = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
-    // Series identity for the readout + selection match (the `as` role, else the
-    // column name).
-    const label = semantic ?? column;
-    // The gap prop overrides the theme default; otherwise the style carries it.
-    const gapPx = gap ?? style.gap;
-    // The current selection, narrowed to what the highlight match needs (key +
-    // label). Read here so a selection change re-registers the layer (in the deps)
-    // → the data canvas repaints with the highlight. Infrequent (a click).
+    // Single-series style: the `as` role → theme bar style (the single channel).
+    const singleStyle = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
+    const gapPx = gap ?? bar.default.gap;
+    // The stacked path's bar-thickness floor comes from `bar.default` (not the `as`
+    // role — `as` is single-series only), matching how `gapPx` sources its default.
+    const stackMinWidth = bar.default.minWidth;
+    // Stacked style: per-group fills (colors override → theme role → default),
+    // plus the shared opacity / outline from the default bar style. Memoized on the
+    // groups + colours so a selection change doesn't rebuild it.
+    const groups = shape.kind === 'stacked' ? shape.ss.groups : undefined;
+    const stackStyle = useMemo(() => {
+        const base = bar.default;
+        const fills = (groups ?? []).map((g) => colors?.[g] ?? (bar[g] ?? base).fill);
+        return {
+            fills,
+            opacity: base.opacity,
+            outlineWidth: base.outlineWidth,
+            ...(binColors !== undefined ? { binFills: binColors } : {}),
+        };
+    }, [bar, groups, colors, binColors]);
+    // The current selection / hover, narrowed to the identity the highlight match
+    // needs. For a stack that's (id, key, label = group); the single path uses just
+    // (id, key). Read here so a change re-registers the layer → the canvas repaints.
     const selected = container.selected;
-    const selection = useMemo(() => selected === null ? null : { key: selected.key, label: selected.label }, [selected]);
-    // The transient hover-highlight, narrowed to the match key (key + label) like
-    // the selection. Read here so a hover change re-registers the layer → the data
-    // canvas repaints with the lit bar. Deduped in the container, so this only
-    // fires on a bar transition (not every pointer move).
     const hoveredMark = container.hovered;
+    const selection = useMemo(() => selected === null
+        ? null
+        : {
+            id: selected.id,
+            key: selected.key,
+            label: selected.label,
+            ...(selected.mark !== undefined ? { mark: selected.mark } : {}),
+        }, [selected]);
     const hover = useMemo(() => hoveredMark === null
         ? null
-        : { key: hoveredMark.key, label: hoveredMark.label }, [hoveredMark]);
-    const entry = useMemo(() => ({
-        layer: {
-            yExtent: () => barExtent(bs),
-            // The container infers the shared x scale's kind from its layers — a
-            // ValueSeries bars on a value axis, a TimeSeries on time.
-            xKind: series instanceof ValueSeries ? 'value' : 'time',
-            xExtent: () => bs.length === 0 ? null : [bs.begin[0], bs.end[bs.length - 1]],
-            sampleAt: (time) => {
-                // The flag belongs to the bar **under the cursor** — the bar whose
-                // span `[begin, end]` contains `time` (barIndexAtTime), NOT
-                // nearest-by-begin (which flips to the next bar past a wide bar's
-                // midpoint, landing the flag on the wrong bar). For a point key the
-                // span is the neighbour-derived Voronoi cell (`barsFromTimeSeries`
-                // widens `begin === end` into one), so the cells tile the axis and a
-                // moving cursor always lands in one. Before the first / after the last
-                // bar → no readout, matching the line/area tracker.
-                if (bs.length === 0)
-                    return [];
-                const i = barIndexAtTime(bs, time);
-                if (i < 0)
-                    return [];
-                const v = bs.y[i];
-                if (!Number.isFinite(v))
-                    return []; // a gap bar (missing value) reads nothing
-                // Anchor at the bar's **top-centre** (RFC): the span's centre time
-                // `(begin + end) / 2` (the bucket mid for an interval key; the Voronoi
-                // cell centre — ~on the point — for a point key), at `yScale(value)` =
-                // the bar top. A tall bar (top above the flag stack) drops the staff for
-                // free (the shared `s.py > stackBottom` rule).
-                return [
-                    {
-                        x: (bs.begin[i] + bs.end[i]) / 2,
-                        value: v,
-                        color: style.fill,
-                        label,
+        : {
+            id: hoveredMark.id,
+            key: hoveredMark.key,
+            label: hoveredMark.label,
+            ...(hoveredMark.mark !== undefined
+                ? { mark: hoveredMark.mark }
+                : {}),
+        }, [hoveredMark]);
+    const entry = useMemo(() => {
+        // ── Single-series, vertical: the original bar path, pixels unchanged. ──
+        if (shape.kind === 'single') {
+            const bs = shape.bs;
+            return {
+                layer: {
+                    yExtent: () => barExtent(bs),
+                    xKind: binAxisKind,
+                    xExtent: () => bs.length === 0 ? null : [bs.begin[0], bs.end[bs.length - 1]],
+                    sampleAt: (time) => {
+                        if (bs.length === 0)
+                            return [];
+                        const i = barIndexAtTime(bs, time);
+                        if (i < 0)
+                            return [];
+                        const v = bs.y[i];
+                        if (!Number.isFinite(v))
+                            return [];
+                        return [
+                            {
+                                x: (bs.begin[i] + bs.end[i]) / 2,
+                                value: v,
+                                color: singleStyle.fill,
+                                label,
+                            },
+                        ];
                     },
-                ];
-            },
-            hitTest: (px, py, xScale, yScale) => {
-                const baseline = resolveBarBaseline(yScale);
-                const hit = barAt(bs, px, py, xScale, yScale, baseline, gapPx, style.minWidth);
-                if (hit === null)
-                    return null;
-                const [, begin, value] = hit;
-                // key = the bar's begin (its stable identity); colour = the resolved
-                // fill; label = this series' identity (so the highlight targets the
-                // exact clicked series, not another sharing the timestamp).
-                return { key: begin, value, color: style.fill, label };
+                    ...(id === undefined
+                        ? {}
+                        : {
+                            hitTest: (px, py, xScale, yScale) => {
+                                const baseline = resolveBarBaseline(yScale);
+                                const hit = barAt(bs, px, py, xScale, yScale, baseline, gapPx, singleStyle.minWidth);
+                                if (hit === null)
+                                    return null;
+                                const [, begin, value] = hit;
+                                return {
+                                    id,
+                                    key: begin,
+                                    value,
+                                    color: singleStyle.fill,
+                                    label,
+                                };
+                            },
+                        }),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover),
+                },
+                axisId: axis,
+                index,
+            };
+        }
+        // ── Stacked (or single horizontal): the oriented, transposed draw path. ──
+        const ss = shape.ss;
+        const binExtent = () => stackBinExtent(ss);
+        const valueExtent = () => stackValueExtent(ss);
+        const vertical = orientation === 'vertical';
+        return {
+            layer: {
+                // Horizontal puts the value on the shared x (always 'value'); vertical
+                // keeps the bin axis on x. The bin axis on the *other* side is a linear
+                // numeric scale either way (time ms label via <YAxis ticks>).
+                xKind: vertical ? binAxisKind : 'value',
+                xExtent: vertical ? binExtent : valueExtent,
+                yExtent: vertical ? valueExtent : binExtent,
+                // A categorical chart hands the container its ordered category names — the
+                // ordinal axis domain the shared band scale + label formatter build on.
+                ...(categoryLabels !== null
+                    ? { xCategories: () => categoryLabels }
+                    : {}),
+                // No x-scrub flag for a stack / horizontal chart — hover + click read it
+                // out instead (the flag is single-series-vertical only).
+                sampleAt: () => [],
+                ...(id === undefined
+                    ? {}
+                    : {
+                        hitTest: (px, py, xScale, yScale) => {
+                            const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth);
+                            if (hit === null)
+                                return null;
+                            const [bi, g, begin, name, value] = hit;
+                            // A categorical bar carries a stable per-bar `mark` (its column
+                            // name); the selection keys on `(id, mark)` so it survives a
+                            // reorder. `bi` is the exact bin index from the hit.
+                            const stableMark = ss.marks?.[bi];
+                            return {
+                                id,
+                                key: begin,
+                                value,
+                                // A per-bin colour override wins over the group fill, so the
+                                // readout pill reads the bar's own colour.
+                                color: stackStyle.binFills?.[bi] ?? stackStyle.fills[g],
+                                // A categorical bar reports its category name; a stack reports
+                                // the group.
+                                label: stableMark ?? name,
+                                ...(stableMark !== undefined ? { mark: stableMark } : {}),
+                            };
+                        },
+                    }),
+                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover),
             },
-            draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, style, resolveBarBaseline(yScale), gapPx, label, selection, hover),
-        },
-        axisId: axis,
+            axisId: axis,
+            index,
+        };
+    }, [
+        shape,
+        binAxisKind,
+        categoryLabels,
+        orientation,
+        singleStyle,
+        stackStyle,
+        label,
+        id,
+        gapPx,
+        stackMinWidth,
+        selection,
+        hover,
+        axis,
         index,
-    }), [bs, series, column, style, label, gapPx, selection, hover, axis, index]);
-    // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
-    // fixed across series/style/selection updates (no jump to the front).
+    ]);
+    // A stable per-instance slot keeps this layer's z-position fixed across data /
+    // style / selection updates (see useSlotKey).
     const slot = useSlotKey();
     useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
     useEffect(() => {
         layers.registerLayer(slot, entry);
     }, [layers, slot, entry]);
-    // Also a tracker source: the container fans in this series' value at the
-    // cursor for the (outside-the-chart) readout.
+    // Also a tracker source: the container fans in this layer's value at the cursor
+    // for the (outside-the-chart) readout. A stacked / horizontal layer's sampleAt
+    // returns nothing, so it contributes no flag but still registers cleanly.
     const { registerTrackerSource, unregisterTrackerSource } = container;
     useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // Advertise selectability (only when an `id` was given).
+    const { registerSelectable, unregisterSelectable } = container;
+    useEffect(() => {
+        if (id === undefined)
+            return;
+        registerSelectable(slot);
+        return () => unregisterSelectable(slot);
+    }, [registerSelectable, unregisterSelectable, slot, id]);
     return null;
 }
 //# sourceMappingURL=BarChart.js.map

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,4 +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';
@@ -12,6 +14,45 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * A **trading-calendar** discontinuity provider — closed-market time
+     * (weekends, holidays, overnight, lunch breaks) collapsed. Supply it to turn
+     * the shared x axis into a **trading-time** axis: gaps disappear and time
+     * stays proportional within each session. A `@pond-ts/financial`
+     * `TradingCalendar.discontinuities()` satisfies this structurally (charts
+     * never imports that package). The **low-level** primitive: pass
+     * `calendar.discontinuities()` (or a `{ spacing, period }` variant) directly.
+     * Only affects a **time** axis (ignored on a value axis). Takes precedence
+     * over {@link calendar} if both are given.
+     *
+     * **Pass a stable reference.** The scale (and container frame) rebuild when
+     * this prop's identity changes, so memoize it — `const disc = useMemo(() =>
+     * calendar.discontinuities(), [calendar])` — rather than calling
+     * `.discontinuities()` inline in JSX, which would rebuild every render.
+     */
+    discontinuities?: DiscontinuityProvider;
+    /**
+     * The **high-level** sugar for {@link discontinuities}: a trading calendar the
+     * container derives the provider from itself (`calendar.discontinuities({
+     * spacing })`), so you don't wire the low-level prop. A `@pond-ts/financial`
+     * `TradingCalendar` satisfies the structural {@link TradingCalendarLike} shape
+     * (charts never imports that package). Combine with {@link spacing}. For the
+     * full option matrix (a bar `period`, a scoped `range`) use the low-level
+     * `discontinuities` prop instead. Only affects a **time** axis.
+     *
+     * The provider is memoized on `(calendar, spacing)`, so pass a **stable**
+     * calendar reference (build it once, not inline in JSX).
+     */
+    calendar?: TradingCalendarLike;
+    /**
+     * The trading axis **metric**, when a {@link calendar} is supplied
+     * (trading-calendar RFC Q7). `'proportional'` (default) keeps time
+     * proportional within and across sessions — a half-day is half as wide.
+     * `'uniform'` gives every session equal width (the TradingView ordinal look).
+     * Ignored without `calendar` (a low-level `discontinuities` provider already
+     * carries its own metric).
+     */
+    spacing?: 'proportional' | 'uniform';
     /** Total width in CSS pixels (plot + axis gutters). */
     width: number;
     /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
@@ -35,9 +76,55 @@ 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 `[start, end)` `TimeRange`, and
+     * the cursor reverts to the single-bucket highlight (it does not keep the
+     * range). Typical use — zoom the view to the returned range (the container
+     * doesn't zoom itself; that's the consumer's call).
+     *
+     * With **no `cursorSequence`** the region cursor is the degenerate case — it
+     * renders as a **line** on hover and the drag is **freeform** (raw `[start,
+     * end)`, no bucket snapping); the same callback fires on release. No-op unless
+     * `cursor="region"` (and a **time** x-axis).
+     */
+    onRegionSelect?: (range: TimeRange) => 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.
@@ -46,15 +133,21 @@ export interface ChartContainerProps {
     /**
      * Controlled selection — the selected mark (echo the `onSelect` arg back), or
      * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
-     * internally; pass `null` to force nothing selected). Selectable layers
-     * (`BarChart`, `BoxPlot`, `ScatterChart`) highlight the mark matching both its
-     * key and series — so two series sharing a timestamp don't both light up.
+     * internally; pass `null` to force nothing selected). A layer is **selectable
+     * only when it carries an `id`** (the stable series identity) — `BarChart` /
+     * `ScatterChart` highlight the mark matching the selection's `id` (the series)
+     * and its `key` (the sample), so two series sharing a timestamp don't both
+     * light up, and the selection survives a data update (it keys on the stable
+     * `id`, not the sample `key`). A layer with no `id` renders + reads out but
+     * can't be selected.
      */
     selected?: SelectInfo | null;
     /**
      * Fires when a selectable layer's mark is clicked, with the hit mark, or `null`
-     * when a click misses every mark (clears the selection). Notification only —
-     * works in both controlled and uncontrolled mode.
+     * when a click misses every mark (or hits a layer with no `id` — display-only,
+     * so it reads as empty space). Notification only — works in both controlled and
+     * uncontrolled mode. If this or `selected` is set but no layer has an `id`, a
+     * dev-warning notes that nothing is selectable.
      */
     onSelect?: (hit: SelectInfo | null) => void;
     /**
@@ -180,5 +273,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, 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