@pond-ts/charts 0.41.0 → 0.43.0

package/dist/bars.js

@@ -82,7 +82,8 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
  * (inset by `gapPx`) from the resolved `baseline` to the value.
  *
  * A gap (non-finite value) is skipped — no bar, no zero-height sliver. A bar
- * matching the current `selection` (same `begin` **and** the layer's own `label`)
+ * matching the current `selection` (same sample `key` **and** the layer's own
+ * series `id` — `seriesId`; a no-id layer passes `undefined` and never matches)
  * draws in the style's `highlight` colour **and outlined**, so a click reads back
  * on the canvas; a bar matching `hovered` draws in `highlight` **without** the
  * outline (a lighter "this bar is live" on pointer-over); all others use the flat
@@ -92,7 +93,7 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
  * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
  * allocation beyond the rect tuple.
  */
-export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, label, selection, hovered) {
+export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
     for (let i = 0; i < cs.length; i += 1) {
@@ -100,16 +101,18 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, label,
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;
-        // Match by key (begin) **and** label, so two series sharing a timestamp don't
-        // both light up. Both the committed selection and the transient hover use the
-        // `highlight` fill; only the selection adds the outline, so hover reads as a
-        // lighter "this bar is live" and select as the committed pick.
+        // Match by the series `id` **and** the sample `key` (begin), so two series
+        // sharing a timestamp don't both light up (a no-id, non-selectable layer
+        // passes `seriesId === undefined` and never matches). Both the committed
+        // selection and the transient hover use the `highlight` fill; only the
+        // selection adds the outline, so hover reads as a lighter "this bar is live"
+        // and select as the committed pick.
         const selected = selection !== null &&
-            selection.key === cs.begin[i] &&
-            selection.label === label;
+            selection.id === seriesId &&
+            selection.key === cs.begin[i];
         const isHovered = hovered !== null &&
-            hovered.key === cs.begin[i] &&
-            hovered.label === label;
+            hovered.id === seriesId &&
+            hovered.key === cs.begin[i];
         ctx.fillStyle = selected || isHovered ? style.highlight : style.fill;
         ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
         if (selected) {
@@ -168,4 +171,180 @@ export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
     }
     return null;
 }
+/**
+ * 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.
+ */
+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))
+                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;
+    }
+    // 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
+ * last bin's `end` (the slots are ascending). `null` for an empty series. Feeds
+ * the x auto-fit for a vertical histogram, the y auto-fit for a horizontal one.
+ */
+export function stackBinExtent(ss) {
+    if (ss.length === 0)
+        return null;
+    return [ss.begin[0], ss.end[ss.length - 1]];
+}
+/**
+ * The pixel rect `[x0, x1, yTop, yBottom]` (ascending on both axes) of bin `b`'s
+ * segment `g`, stacked so it sits atop `cumBefore` (the summed value of the
+ * segments below it, in value units). `null` for a gap (see below). Transposes on
+ * `orientation`:
+ *
+ * - **vertical** — the bin span is horizontal (`barSpanPx` on `xScale`); the
+ *   segment runs vertically from `yScale(cumBefore)` to `yScale(cumBefore + v)`.
+ * - **horizontal** — the bin span is vertical (`barSpanPx` on `yScale`); the
+ *   segment runs horizontally from `xScale(cumBefore)` to `xScale(cumBefore + v)`.
+ *
+ * `null` for a **gap** — a non-finite, negative, **or zero** value: none of them
+ * draw (a zero segment has no extent), and each contributes nothing to the running
+ * total. `minSpanPx` floors the **bin** span (bar thickness); the value direction
+ * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
+ * and the hit rect are identical.
+ */
+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 (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);
+        const yA = yScale(cumBefore);
+        const yB = yScale(cumBefore + v);
+        return [x0, x1, Math.min(yA, yB), Math.max(yA, yB)];
+    }
+    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx);
+    const xA = xScale(cumBefore);
+    const xB = xScale(cumBefore + v);
+    return [Math.min(xA, xB), Math.max(xA, xB), y0, y1];
+}
+/**
+ * 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, 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
+ * shared opacity and is restored.
+ *
+ * O(N·G) over bins × groups, one fill (+ optional stroke) per drawn segment.
+ */
+export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, minSpanPx, seriesId, selection, hover) {
+    const G = ss.groups.length;
+    ctx.save();
+    ctx.globalAlpha = style.opacity;
+    for (let b = 0; b < ss.length; b += 1) {
+        let cum = 0;
+        for (let g = 0; g < G; g += 1) {
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, cum, gapPx, minSpanPx);
+            const v = ss.values[b * G + g];
+            if (Number.isFinite(v) && v > 0)
+                cum += v;
+            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 &&
+                (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;
+            // 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 = fill;
+                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            }
+        }
+    }
+    ctx.restore();
+}
+/**
+ * Hit-test plot-pixel `(px, py)` against `ss`'s stacked segments — the **first**
+ * segment whose rect contains the point, or `null`. The geometry is
+ * {@link segmentRect}, so the hit rect is exactly the drawn rect. The returned
+ * tuple is `[bin, group, begin, groupName, value]` for the chart to assemble a
+ * `SelectInfo` (it owns the colour). Orientation-agnostic — it reads `(px, py)`,
+ * so a horizontal histogram hit-tests the same way a vertical one does.
+ *
+ * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
+ * small; click / hover are cheap events).
+ */
+export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx) {
+    const G = ss.groups.length;
+    for (let b = 0; b < ss.length; b += 1) {
+        let cum = 0;
+        for (let g = 0; g < G; g += 1) {
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, cum, gapPx, minSpanPx);
+            const v = ss.values[b * G + g];
+            if (Number.isFinite(v) && v > 0)
+                cum += v;
+            if (rect === null)
+                continue;
+            const [x0, x1, yTop, yBottom] = rect;
+            if (px >= x0 && px <= x1 && py >= yTop && py <= yBottom) {
+                return [b, g, ss.begin[b], ss.groups[g], v];
+            }
+        }
+    }
+    return null;
+}
 //# sourceMappingURL=bars.js.map

package/dist/context.d.ts

@@ -1,6 +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*
@@ -63,13 +66,45 @@ 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 **both** the key (epoch ms) and the series
-     * (`label`) — so two series sharing a timestamp don't both light up. A
+     * highlights the mark matching the selection's series **`id`** and the clicked
+     * sample `key` (epoch ms) — the `id` picks the series (so two series sharing a
+     * timestamp don't both light up), the `key` picks the mark within it. A
      * controlled `selected` prop pins it; otherwise a click on a selectable layer
-     * sets it. The full {@link SelectInfo} (not just the key) is the identity so
-     * multi-series Bar/Scatter can target the exact clicked mark.
+     * (one with an `id`) sets it.
      */
     readonly selected: SelectInfo | null;
     /**
@@ -86,12 +121,13 @@ export interface ContainerFrame {
      * from the committed `selected`. A row's pointer-move surface hit-tests its
      * selectable layers and sets it; a layer that supports hover-highlight (Bar)
      * draws the matching mark lit (a lighter treatment than `selected`'s outline).
-     * Set-on-change (deduped by key+label) so the data canvas repaints only on a
-     * mark transition, not every pointer move.
+     * Set-on-change (deduped by the series `id` + sample `key`) so the data canvas
+     * repaints only on a mark transition, not every pointer move.
      */
     readonly hovered: SelectInfo | null;
     /** Set the hovered mark (or `null` to clear) from a pointer-move hit-test;
-     *  deduped, so an unchanged mark is a no-op (no repaint). */
+     *  deduped by series `id` + sample `key`, so an unchanged mark is a no-op
+     *  (no repaint). */
     setHovered(hit: SelectInfo | null): void;
     /** The default in-chart cursor presentation for all rows ({@link CursorMode});
      *  a row may override it via its own `cursor`. */
@@ -116,6 +152,14 @@ export interface ContainerFrame {
      */
     registerTrackerSource(key: symbol, source: TrackerSource): void;
     unregisterTrackerSource(key: symbol): void;
+    /**
+     * Register this layer as **selectable** — a layer calls this (keyed by its
+     * per-instance slot) only when it was given an `id`, so the container knows at
+     * least one series can be selected. Powers the dev-warn when `selected` /
+     * `onSelect` are wired but no layer carries an `id`. Unregister on unmount.
+     */
+    registerSelectable(key: symbol): void;
+    unregisterSelectable(key: symbol): void;
     /**
      * Shared x→pixel scale, range `[0, plotWidth]`. A d3 `scaleTime` (default) so
      * ticks land on wall-clock boundaries, or a `scaleLinear` when the data is
@@ -124,16 +168,28 @@ export interface ContainerFrame {
      * scales are callable
      * (`value → px`) and expose `invert`/`ticks`/`tickFormat`; consumers use only
      * that shared surface (the cursor coerces `invert` via `+`, `<TimeAxis>` keys
-     * ticks via `+d`), so either kind drops in.
+     * ticks via `+d`), so either kind drops in. A **`scaleTradingTime`** (when the
+     * container is given `discontinuities`) is the third kind — same callable /
+     * `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>;
+    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand;
     /**
-     * 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 discontinuity provider backing a **trading-time** x axis, if one was
+     * supplied to the container — closed-market time (weekends, holidays,
+     * overnight, lunch breaks) collapsed. `undefined` for a normal continuous
+     * time / value axis. Pan and zoom read it to move the view in *trading* time
+     * rather than raw wall-clock ms.
      */
-    readonly xKind: 'time' | 'value';
+    readonly discontinuities?: DiscontinuityProvider | undefined;
+    /**
+     * 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' | '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. */
@@ -293,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
@@ -324,9 +389,12 @@ export interface RowLayer {
     /**
      * Hit-test plot-pixel `(px, py)` against this layer's marks for click
      * selection — the select-analog of {@link sampleAt}. Returns the hit mark or
-     * `null`. **Optional:** layers without discrete selectable marks (line, band,
-     * area) omit it; bar / box / scatter implement it. `xScale`/`yScale` map
-     * data→pixels (the row resolves the layer's axis scale, as for `draw`).
+     * `null`. **Optional, and gated on the layer's `id`:** a layer only wires
+     * `hitTest` when it was given an `id` (the series identity). Layers without an
+     * `id` — or without discrete selectable marks (line, band, area) — omit it,
+     * so they render + read out but never select/hover (a click on them resolves
+     * to empty space ⇒ deselect). `xScale`/`yScale` map data→pixels (the row
+     * resolves the layer's axis scale, as for `draw`).
      */
     hitTest?(px: number, py: number, xScale: (value: number) => number, yScale: (value: number) => number): SelectInfo | null;
     /** Draw into the plot canvas. `xScale`/`yScale` map data→pixels. */
@@ -370,24 +438,47 @@ 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 selected mark — what {@link RowLayer.hitTest} returns and `onSelect`
- * reports. Mirrors {@link TrackerSample}: the mark's key (its stable identity,
- * for controlled selection + highlight matching), value, colour, and series
- * label.
+ * One selection — what {@link RowLayer.hitTest} returns and `onSelect` reports.
+ * Selection identity is the **series `id`**, not the sample: `key`/`value` are
+ * click **provenance** (the nearest sample under the pointer, informational);
+ * equality, dedup, and the controlled echo all key on `id`. Because `id` is a
+ * stable series identity — distinct from the `as` theme role, which can repeat —
+ * a selection survives a streaming data update where a sample `key` would go
+ * stale. Only layers that carry an `id` are selectable (see {@link RowLayer.hitTest}).
  */
 export interface SelectInfo {
-    /** The mark's key as epoch ms (its event's `begin`) — its stable identity. */
+    /**
+     * The **series identity** — the layer's `id` prop. The selection / dedup /
+     * controlled-echo key; stable across data updates (unlike {@link key}).
+     */
+    readonly id: string;
+    /**
+     * The clicked sample's key as epoch ms (its event's `begin`) — click
+     * **provenance**, informational. NOT the selection identity (that is {@link id}).
+     */
     readonly key: number;
-    /** The mark's value (the plotted column). */
+    /** The clicked sample's value (the plotted column) — provenance. */
     readonly value: number;
     /** The mark's resolved style colour. */
     readonly color: string;
-    /** Series identity (`as` ?? column) — labels the selection in a readout. */
+    /** 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. */
@@ -411,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

@@ -1,4 +1,5 @@
-import type { SeriesSchema, TimeSeries, ValueSeries, ValueSeriesSchema } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 /**
  * A chart-ready columnar view of a series: parallel typed arrays for the time
  * (x) and value (y) axes, plus the logical row count.
@@ -96,6 +97,40 @@ export interface BarSeries {
     readonly y: Float64Array;
     readonly length: number;
 }
+/**
+ * A chart-ready view of a **stacked / histogram** bar series — the multi-segment
+ * generalization of {@link BarSeries}. Each of the `length` bins spans
+ * `[begin[i], end[i]]` on the **bin axis** (time ms, a value, or a band edge) and
+ * carries one value per `group` (a stack segment). `groups` lists the segment
+ * identities **bottom → top**; `values` is a flat `length × groups.length` grid
+ * in **row-major** order, so bin `b`'s segment `g` is `values[b * groups.length + g]`.
+ *
+ * A single-series bar (the {@link BarSeries} case) is just `groups.length === 1`.
+ * Missing / non-finite segment values are `NaN` — the gap signal a stack skips
+ * (no segment, and it contributes nothing to the running total), the same
+ * `Number.isFinite` contract as {@link BarSeries}. Segment values are assumed
+ * **non-negative** (counts / durations); a negative value is treated as a gap
+ * (diverging stacks are out of scope — see the histogram guide).
+ *
+ * The bin axis is x for a **vertical** histogram (bars grow up) and y for a
+ * **horizontal** one (bars grow right); the same grid drives both — the draw
+ * layer transposes by orientation, the data does not change.
+ */
+export interface StackedBarSeries {
+    readonly begin: Float64Array;
+    readonly end: Float64Array;
+    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 {
     /** Lower whisker end (e.g. `p5` / `min`). */
@@ -242,4 +277,142 @@ export declare function barsFromTimeSeries<S extends SeriesSchema>(series: TimeS
  * @throws TypeError if `column` is not a numeric column.
  */
 export declare function barsFromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, column: string): BarSeries;
+/**
+ * Build a {@link StackedBarSeries} from a **`Map` of grouped series** — one series
+ * per stack group. This is the natural reader for pond's grouped-aggregate output:
+ * `series.partitionBy('host', { groups }).aggregate(Sequence.every('5m'), { n: 'count' }).toMap()`
+ * yields a `Map<host, TimeSeries>`, one interval-keyed series per host. The stack
+ * order (`groups`, bottom → top) is the map's **insertion order** (stable when you
+ * pass `partitionBy`'s `{ groups }` option).
+ *
+ * **Aligned by bucket key, not by index.** Each partition's `aggregate` spans only
+ * *its own* events' range, so the groups generally have **different** grids (host A
+ * might have buckets 0–8, host B buckets 3–9). This reader takes the **union** of
+ * every group's `[begin, end)` slots (ascending) and places each group's `column`
+ * value at the matching `begin`; a bucket a group is missing reads as a gap
+ * (`NaN`, contributing nothing to that stack). So the segments always line up on
+ * the real bucket, never on a positional accident. (Pass `aggregate`'s
+ * `{ range }` option if you want every group padded to one dense grid — the union
+ * is then that grid.) When two groups carry the **same `begin`**, the first
+ * group's `end` sets that slot's width — correct for the uniform-width buckets
+ * `aggregate` / `pivotByGroup` produce (all groups share the grid width), which is
+ * the intended input.
+ *
+ * @throws Error if `groups` is empty.
+ * @throws RangeError / TypeError (via {@link readNumericColumn}) if `column` is
+ *   missing or non-numeric in any member.
+ */
+export declare function stacksFromGroups<S extends SeriesSchema>(groups: ReadonlyMap<string, TimeSeries<S>>, column: string): StackedBarSeries;
+/**
+ * Build a {@link StackedBarSeries} from a **wide** series — one numeric column
+ * per stack group. This is the reader for pond's `pivotByGroup` output (long →
+ * wide reshape: each group value becomes its own column), or any series that is
+ * already wide (e.g. `in` / `out` traffic). `columns` names the segment columns
+ * **bottom → top**; a `ValueSeries` bins on its value axis (neighbour-spaced
+ * slots), a `TimeSeries` on its key (interval spans or neighbour-spaced points).
+ *
+ * @throws RangeError / TypeError if any column is missing or non-numeric.
+ */
+export declare function stacksFromColumns<S extends SeriesSchema, VS extends ValueSeriesSchema>(series: TimeSeries<S> | ValueSeries<VS>, columns: readonly string[]): StackedBarSeries;
+/**
+ * A single bin record from `byColumn` — its `[start, end)` range plus the mapped
+ * aggregate columns (read by name via {@link stacksFromBins}). Deliberately just
+ * the `start`/`end` shape (no index signature) so pond's
+ * `byColumn(...): Array<{ start, end } & ReduceResult>` assigns to it structurally
+ * — the aggregate fields ride along and are read out by the reader.
+ */
+export type BinRecord = {
+    readonly start: number;
+    readonly end: number;
+};
+/** Options for {@link stacksFromBins}. */
+export interface StacksFromBinsOptions {
+    /**
+     * Use uniform **unit slots** (`[i, i+1]`) for the bins instead of their numeric
+     * `[start, end]` edges — an **ordinal** band axis (heart-rate zones, Coggan
+     * power zones) where every band reads the same width regardless of its numeric
+     * span. The caller labels the slots via `<YAxis ticks>` at `i + 0.5`. Omitted /
+     * `false` ⇒ real numeric edges (a true value axis — power W, risk %).
+     */
+    readonly ordinal?: boolean;
+}
+/**
+ * Build a {@link StackedBarSeries} from **`byColumn` bin records** — the array of
+ * `{ start, end, …aggregates }` a value-band aggregation returns
+ * (`series.byColumn('power', { width: 20 }, { seconds: { from: 'dt', using: 'sum' } })`).
+ * `columns` names the aggregate field(s) to draw as segments (`['seconds']` for a
+ * plain distribution; several for a stacked value-band histogram).
+ *
+ * By default each bin keeps its real numeric `[start, end]` edges — a true value
+ * axis (power W, risk %). Pass `{ ordinal: true }` for uniform unit slots
+ * (`[i, i+1]`) when the bins are **categories** whose numeric width shouldn't
+ * distort the layout (heart-rate zones); label them with `<YAxis ticks>`.
+ *
+ * A missing / non-finite aggregate reads as a gap (`NaN`).
+ */
+export 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