@pond-ts/charts 0.42.0 → 0.43.0

package/dist/bars.js

@@ -172,9 +172,12 @@ export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
     return null;
 }
 /**
- * The `[min, max]` extent of the **value (stacked) axis** — always `[0, maxTotal]`,
- * where `maxTotal` is the tallest bin's summed finite non-negative segments. `0` is
- * pulled in so the stack rests on a visible baseline (the bar analog of
+ * The `[min, max]` extent of the **value (stacked) axis**. For a true multi-group
+ * stack it is `[0, maxTotal]`, where `maxTotal` is the tallest bin's summed finite
+ * non-negative segments. For a **single-group** series (`G === 1` — the plain /
+ * categorical bar case) it spans the values' own `[min, max]`, so a **negative**
+ * bar's floor is in the domain (segments below the baseline stay visible). `0` is
+ * always pulled in so the bars rest on a visible baseline (the bar analog of
  * {@link barExtent}). An empty / all-gap series returns `[0, 1]` so the axis still
  * has a usable domain. Feeds the y auto-fit for a vertical histogram, the x
  * auto-fit for a horizontal one.
@@ -182,17 +185,32 @@ export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
 export function stackValueExtent(ss) {
     const G = ss.groups.length;
     let max = 0;
+    let min = 0;
     for (let b = 0; b < ss.length; b += 1) {
         let cum = 0;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            if (Number.isFinite(v) && v > 0)
-                cum += v;
+            if (!Number.isFinite(v))
+                continue;
+            if (G === 1) {
+                // Single-group: a bar honours its sign, so track both ends.
+                if (v > max)
+                    max = v;
+                if (v < min)
+                    min = v;
+            }
+            else if (v > 0) {
+                cum += v; // True stack: sum the positive segments.
+            }
         }
         if (cum > max)
             max = cum;
     }
-    return [0, max > 0 ? max : 1];
+    // Empty / all-gap / all-zero → a usable unit domain; otherwise the real extent
+    // (with 0 pulled in via the `min`/`max` seeds above).
+    if (min === 0 && max === 0)
+        return [0, 1];
+    return [min, max];
 }
 /**
  * The `[min, max]` extent of the **bin axis** — the first bin's `begin` to the
@@ -224,9 +242,14 @@ export function stackBinExtent(ss) {
 export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx) {
     const G = ss.groups.length;
     const v = ss.values[b * G + g];
-    // Skip non-finite / negative / zero: a zero segment would otherwise draw a
-    // wasted zero-extent rect (and can't be hit-tested).
-    if (!Number.isFinite(v) || v <= 0)
+    // Skip non-finite (a gap) or zero (a zero-extent rect that can't draw or be
+    // hit-tested). A **negative** value is a gap only in a true multi-group stack
+    // (`G > 1`) — stacking a negative segment is undefined. A **single-group**
+    // series (`G === 1`) is a plain bar: it honours its sign and draws from the
+    // baseline *down* to a negative value (the categorical row-read's P&L / delta
+    // case), so negatives are kept and the `Math.min/Math.max` below normalizes the
+    // below-baseline rect.
+    if (!Number.isFinite(v) || v === 0 || (v < 0 && G > 1))
         return null;
     if (orientation === 'vertical') {
         const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
@@ -242,8 +265,10 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
 /**
  * Fill every segment of every bin in `ss`, stacking each bin's groups from the
  * value baseline outward (bottom → top vertical, left → right horizontal). A gap
- * (non-finite / negative) segment is skipped and adds nothing to the running
- * total, so the segments above it close the space. A segment matching the current
+ * (non-finite, or a negative segment of a true multi-group stack) is skipped and
+ * adds nothing to the running total, so the segments above it close the space; a
+ * single-group series draws its negative bars below the baseline (see
+ * {@link segmentRect}). A segment matching the current
  * `selection` (same series `id`, bin `key` **and** group `label`) draws in its
  * group's `highlight` **and** outlined; one matching `hover` draws in `highlight`
  * without the outline; all others use the flat `fill`. `globalAlpha` carries the
@@ -265,20 +290,27 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
             if (rect === null)
                 continue;
             const [x0, x1, yTop, yBottom] = rect;
+            // With `marks` (the categorical axis), match on the stable per-bin name so a
+            // pinned selection survives a column reorder; otherwise on the sample `key`
+            // (begin) + group `label`, as a time / value stack does.
+            const stableMark = ss.marks?.[b];
             const matches = (m) => m !== null &&
                 m.id === seriesId &&
-                m.key === ss.begin[b] &&
-                m.label === ss.groups[g];
+                (stableMark !== undefined
+                    ? m.mark === stableMark
+                    : m.key === ss.begin[b] && m.label === ss.groups[g]);
             const selected = matches(selection);
             const isHovered = matches(hover);
             // A hovered / selected segment pops to full opacity in its own colour; a
             // resting one draws at the shared alpha.
             ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
-            ctx.fillStyle = style.fills[g];
+            // A per-bin colour (the single-series band case) overrides the group fill.
+            const fill = style.binFills?.[b] ?? style.fills[g];
+            ctx.fillStyle = fill;
             ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
             if (selected) {
                 ctx.lineWidth = style.outlineWidth;
-                ctx.strokeStyle = style.fills[g];
+                ctx.strokeStyle = fill;
                 ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
             }
         }

package/dist/context.d.ts

@@ -1,7 +1,9 @@
 import type { ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
+import type { Interval, TimeRange } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
+import type { ScaleBand } from './bandScale.js';
 /**
  * The frame a {@link ChartContainer} provides to its rows and the time axis.
  * The container owns the **shared x geometry**: each side is split into *slots*
@@ -64,6 +66,38 @@ export interface ContainerFrame {
      * (`yScale.invert`). The x always snaps to the data grid either way.
      */
     readonly crosshairSnap: boolean;
+    /**
+     * `cursor="region"` buckets — the intervals (from `cursorSequence`) realized
+     * over the current view, sorted + non-overlapping. `Layers` finds the one under
+     * the pointer and shades it (mapped through `xScale`, so on a trading-time axis
+     * the closed part of the bucket collapses). `undefined` when no `cursorSequence`
+     * is set.
+     */
+    readonly cursorBuckets: readonly Interval[] | undefined;
+    /**
+     * The `region`-cursor **drag anchor** (epoch ms), or `null` when not dragging.
+     * A drag on a region cursor (only when {@link onRegionSelect} is set) records
+     * the press time here; the band then spans from the anchor's bucket to the
+     * pointer's bucket (extending bucket by bucket). Cleared on release.
+     */
+    readonly regionAnchor: number | null;
+    /** Set / clear the region-drag anchor (see {@link regionAnchor}). */
+    setRegionAnchor(time: number | null): void;
+    /**
+     * One-shot callback fired when a `region`-cursor **drag** is released, with the
+     * selected `[start, end)` `TimeRange` (snapped to the `cursorSequence` buckets).
+     * Providing it is what makes the region cursor **draggable**; the cursor does
+     * not keep the range (it reverts to the single-bucket highlight). Typical use:
+     * zoom the view to the returned range.
+     */
+    readonly onRegionSelect: ((range: TimeRange) => void) | undefined;
+    /**
+     * Require a modifier key held to start a region-drag — set to `'shift'` to make
+     * plain drag **pan** and **shift**-drag select, when `panZoom` is on. Only
+     * enforced while pan is enabled (with no pan there's no gesture to share, so the
+     * modifier is optional). `undefined` ⇒ a region-drag preempts pan.
+     */
+    readonly regionSelectModifier: 'shift' | undefined;
     /**
      * The selected mark, or `null`. Shared across rows (single selection). A layer
      * highlights the mark matching the selection's series **`id`** and the clicked
@@ -139,7 +173,7 @@ export interface ContainerFrame {
      * `invert` / `ticks` / `tickFormat` surface, but the mapping runs through
      * trading time so closed-market gaps collapse (see {@link discontinuities}).
      */
-    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale;
+    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand;
     /**
      * The discontinuity provider backing a **trading-time** x axis, if one was
      * supplied to the container — closed-market time (weekends, holidays,
@@ -149,12 +183,13 @@ export interface ContainerFrame {
      */
     readonly discontinuities?: DiscontinuityProvider | undefined;
     /**
-     * The resolved kind of the shared x scale — `'time'` (a `scaleTime`) or
-     * `'value'` (a `scaleLinear`), inferred from the layers' data. `<XAxis>` reads
-     * it to pick its default tick formatter (a time format vs a number format),
-     * and the cursor readout to format the x position.
+     * The resolved kind of the shared x scale — `'time'` (a `scaleTime`),
+     * `'value'` (a `scaleLinear`), or `'category'` (a {@link ScaleBand}: an ordinal
+     * column-domain axis, one slot per category). Inferred from the layers' data.
+     * `<XAxis>` reads it to pick its default tick formatter (time / number / the
+     * category label), and the cursor readout to format the x position.
      */
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     /** Pan/zoom enabled — the plot drag-pans and wheel-zooms the shared time range. */
     readonly panZoom: boolean;
     /** Minimum visible duration (ms) — the zoom-in floor. */
@@ -314,17 +349,26 @@ export interface RowLayer {
     yExtent(): [number, number] | null;
     /**
      * The **kind of x axis** this layer's data lives on — `'time'` for a
-     * `TimeSeries`, `'value'` for a `ValueSeries`. The container infers the one
-     * shared x scale from its layers (all must agree — a mix is an error), so the
-     * axis kind never needs declaring. See {@link ContainerFrame.xScale}.
+     * `TimeSeries`, `'value'` for a `ValueSeries`, `'category'` for a categorical
+     * (ordinal column-domain) layer. The container infers the one shared x scale
+     * from its layers (all must agree — a mix is an error), so the axis kind never
+     * needs declaring. See {@link ContainerFrame.xScale}.
      */
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     /**
      * This layer's `[min, max]` along the **x** axis (the key / value-axis extent),
      * or `null` if empty. The container unions these to auto-fit the shared x
-     * domain when no explicit `range` is given.
+     * domain when no explicit `range` is given. For a `'category'` layer this is
+     * the slot extent `[0, n]` (n = category count).
      */
     xExtent(): readonly [number, number] | null;
+    /**
+     * A `'category'` layer's ordered category names (the ordinal axis domain the
+     * container builds a {@link ScaleBand} + label formatter from). `undefined` /
+     * absent for a `'time'` or `'value'` layer. Category layers in one container
+     * must agree on this list (a mix is an error), the same way {@link xKind} must.
+     */
+    xCategories?(): readonly string[] | null;
     /**
      * The layer's value(s) at `time` — the nearest sample — for the scrub tracker:
      * one for a line, two (lower/upper) for a band, empty at a gap. Each carries
@@ -394,8 +438,10 @@ export interface CursorFlag {
  */
 export interface TrackerSource {
     sampleAt(time: number): readonly TrackerSample[];
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     xExtent(): readonly [number, number] | null;
+    /** A `'category'` source's ordered category names (see {@link RowLayer.xCategories}). */
+    xCategories?(): readonly string[] | null;
 }
 /**
  * One selection — what {@link RowLayer.hitTest} returns and `onSelect` reports.
@@ -423,6 +469,16 @@ export interface SelectInfo {
     readonly color: string;
     /** Display label (`as` ?? column ?? id) — labels the selection in a readout. */
     readonly label: string;
+    /**
+     * An optional **stable per-mark identity within the layer** — a *category's
+     * column name* on the categorical axis, where every bar shares the layer's
+     * `id` but each column needs its own stable handle. When present, the
+     * highlight match + controlled `selected` echo key on `(id, mark)` instead of
+     * the sample `key`, so a pinned selection survives a column reorder / data
+     * update (the slot index is not stable; the column name is). `undefined` for
+     * marks whose sample `key` is already their identity (a time / value bar).
+     */
+    readonly mark?: string;
 }
 /** The hover snapshot handed to `onTrackerChanged` — the cursor time + every
  *  series' value there, so a consumer can render the readout outside the chart. */
@@ -446,7 +502,7 @@ export interface TrackerInfo {
  *   time pinned to the x-axis. The ChartIQ / trading-terminal readout. Values
  *   snap to the series (the axis pills read like ticks), not the raw mouse Y.
  */
-export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair';
+export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair' | 'region';
 /** A registered layer plus the axis id it draws against. */
 export interface LayerEntry {
     readonly layer: RowLayer;

package/dist/data.d.ts

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

package/dist/data.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/tracker.d.ts

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

package/dist/tracker.js

@@ -4,6 +4,72 @@
  * themselves render as an SVG overlay in `Layers` (no cursor canvas); these
  * helpers stay pure, so they're unit-tested directly.
  */
+/**
+ * The interval in the sorted, non-overlapping `buckets` that contains `t`
+ * (`begin ≤ t < end`), or `undefined` if `t` falls in no bucket. Binary search —
+ * the `region` cursor uses it to find the bucket under the pointer.
+ */
+export function bucketAt(buckets, t) {
+    let lo = 0;
+    let hi = buckets.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const b = buckets[mid];
+        if (t < b.begin())
+            hi = mid - 1;
+        else if (t >= b.end())
+            lo = mid + 1;
+        else
+            return b;
+    }
+    return undefined;
+}
+/**
+ * The `[start, end)` **span** a region cursor covers, in axis units (not pixels —
+ * the drag-release callback reports this):
+ *
+ * - **Snapping** (`buckets` non-empty, `t1` in a bucket): the bucket at `t1`, or —
+ *   with a drag anchor `t2` — the union of the `t1` and `t2` buckets, so a drag
+ *   extends **bucket by bucket** either direction. A `t2` in no bucket is ignored.
+ * - **Freeform** (`t1` in no bucket — e.g. no `cursorSequence` at all): a drag
+ *   spans the raw `[t1, t2]`; without a drag (`t2` omitted) there's nothing to
+ *   shade (the cursor renders as a plain line), so it returns `null`.
+ */
+export function regionSpan(buckets, t1, t2) {
+    const a = bucketAt(buckets, t1);
+    if (a === undefined) {
+        // Freeform: no bucket under t1. A drag spans the raw [t1, t2]; a bare hover
+        // has nothing to shade (Layers draws a line for the degenerate region cursor).
+        return t2 === undefined
+            ? null
+            : { start: Math.min(t1, t2), end: Math.max(t1, t2) };
+    }
+    if (t2 === undefined)
+        return { start: a.begin(), end: a.end() };
+    const b = bucketAt(buckets, t2);
+    if (b === undefined)
+        return { start: a.begin(), end: a.end() };
+    return {
+        start: Math.min(a.begin(), b.begin()),
+        end: Math.max(a.end(), b.end()),
+    };
+}
+/**
+ * The pixel band for the `region` cursor: the {@link regionSpan} for `t1` (and an
+ * optional drag anchor `t2`), its `[start, end)` mapped through `xScale` and
+ * clamped to `[0, plotWidth]`. Returns `null` when there's no span, or when the
+ * band has no width — including a span entirely in a **collapsed gap** on a
+ * trading-time scale (both edges map to the same pixel), so it draws nothing
+ * there rather than a zero-width sliver.
+ */
+export function bandRect(buckets, t1, xScale, plotWidth, t2) {
+    const span = regionSpan(buckets, t1, t2);
+    if (span === null)
+        return null;
+    const x0 = Math.max(0, xScale(span.start));
+    const x1 = Math.min(plotWidth, xScale(span.end));
+    return x1 > x0 ? { x0, x1 } : null;
+}
 /** Default cursor mode — the synced vertical line (cursor enabled on the
  *  container by default; pair with an off-chart readout via `onTrackerChanged`). */
 export const DEFAULT_CURSOR_MODE = 'line';
@@ -15,22 +81,27 @@ export const DEFAULT_CURSOR_MODE = 'line';
  * value flag stacked near the top of the row (drawn in `Layers`).
  */
 export function cursorParts(mode) {
+    const base = { line: false, dots: false, chip: 'none', band: false };
     switch (mode) {
         case 'line':
-            return { line: true, dots: false, chip: 'none' };
+            return { ...base, line: true };
         case 'point':
-            return { line: false, dots: true, chip: 'none' };
+            return { ...base, dots: true };
         case 'inline':
-            return { line: false, dots: true, chip: 'inline' };
+            return { ...base, dots: true, chip: 'inline' };
         case 'flag':
-            return { line: false, dots: true, chip: 'flag' };
+            return { ...base, dots: true, chip: 'flag' };
         case 'crosshair':
             // A single reticle (not per-series): `Layers` draws the dashed vertical +
             // full-width horizontal lines, the centre dot, and one value pill itself
             // (so no generic line/dots here); the x-time pill is on `<XAxis>`.
-            return { line: false, dots: false, chip: 'axis' };
+            return { ...base, chip: 'axis' };
+        case 'region':
+            // A shaded band over the bucket under the pointer — `Layers` resolves the
+            // bucket from `cursorBuckets` and draws the rect (cropped through xScale).
+            return { ...base, band: true };
         case 'none':
-            return { line: false, dots: false, chip: 'none' };
+            return { ...base };
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.42.0",
-    "pond-ts": "^0.42.0",
+    "@pond-ts/react": "^0.43.0",
+    "pond-ts": "^0.43.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {