@pond-ts/charts 0.42.0 → 0.43.0

package/CHANGELOG.md

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

package/dist/BarChart.d.ts

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

package/dist/BarChart.js

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

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,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.
@@ -226,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, 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,42 @@ 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"` buckets: realize the `cursorSequence` over the current view
+    // (a `Sequence` → `.bounded`; a `BoundedSequence` used as-is), so the band can
+    // find the interval under the pointer. Memoized on the sequence + view range;
+    // a coarse sequence (days / sessions) is a handful of intervals.
+    // A `Sequence` bucket is a **time** interval, so gate it to a time axis — on a
+    // value axis (a horizontal histogram, a value-keyed chart) the value domain is
+    // not epoch-ms, so realizing time buckets over it is meaningless (it would
+    // shade the whole plot). Region cursor is time-axis only.
+    const cursorBuckets = useMemo(() => {
+        if (cursorSequence === undefined || resolvedKind !== 'time')
+            return undefined;
+        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();
+    }, [cursorSequence, d0, d1, resolvedKind]);
     // 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 +434,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 +487,11 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         hoverPoint,
         setHoverY,
         crosshairSnap,
+        cursorBuckets,
+        regionAnchor,
+        setRegionAnchor,
+        onRegionSelect,
+        regionSelectModifier,
         draggingKey,
         setDragging,
         selectedValue,