@pond-ts/charts 0.40.0 → 0.42.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,148 @@ 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
+ * {@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;
+    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 (cum > max)
+            max = cum;
+    }
+    return [0, max > 0 ? max : 1];
+}
+/**
+ * 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 / 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)
+        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 / negative) segment is skipped and adds nothing to the running
+ * total, so the segments above it close the space. 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;
+            const matches = (m) => m !== null &&
+                m.id === seriesId &&
+                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];
+            ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+            if (selected) {
+                ctx.lineWidth = style.outlineWidth;
+                ctx.strokeStyle = style.fills[g];
+                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,7 @@
 import type { ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
+import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.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*
@@ -65,11 +66,11 @@ export interface ContainerFrame {
     readonly crosshairSnap: boolean;
     /**
      * 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 +87,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 +118,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,9 +134,20 @@ 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;
+    /**
+     * 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 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
@@ -324,9 +345,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. */
@@ -374,19 +398,30 @@ export interface TrackerSource {
     xExtent(): readonly [number, number] | 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;
 }
 /** The hover snapshot handed to `onTrackerChanged` — the cursor time + every

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.
@@ -53,6 +54,32 @@ export interface BoxSeries {
     readonly upper: Float64Array;
     readonly length: number;
 }
+/**
+ * A chart-ready view of an OHLC series ({@link Candlestick}): the candle's
+ * horizontal slot (`x` = left edge, `xEnd` = right edge) plus the four price
+ * channels per mark — `open`/`high`/`low`/`close`. The chart derives the body
+ * extents (`min`/`max` of open/close) itself at draw time; only the four raw
+ * columns are read here.
+ *
+ * A mark is drawn only where **all four** prices are finite; any one `NaN` is a
+ * gap (the candle draws nothing — same gap contract as {@link BoxSeries}).
+ *
+ * Unlike {@link BoxSeries} (interval-keyed only), the OHLC view supports **both**
+ * key shapes, like {@link BarSeries}: an **interval**-keyed series (an
+ * `aggregate` rollup — weekly/monthly bars) uses the key's own `[begin, end)` as
+ * the slot; a **point**-keyed series (raw daily OHLCV) derives the slot from
+ * neighbour spacing (see {@link ohlcFromTimeSeries}), so it feeds straight in
+ * with no `aggregate` pass.
+ */
+export interface OhlcSeries {
+    readonly x: Float64Array;
+    readonly xEnd: Float64Array;
+    readonly open: Float64Array;
+    readonly high: Float64Array;
+    readonly low: Float64Array;
+    readonly close: Float64Array;
+    readonly length: number;
+}
 /**
  * A chart-ready view of an interval-keyed series for bars: each mark spans
  * `[begin[i], end[i]]` (the key's range) with height `y[i]`. Unlike
@@ -70,6 +97,32 @@ 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;
+}
 /** The five quantile column names a {@link boxFromTimeSeries} reads, in order. */
 export interface BoxColumns {
     /** Lower whisker end (e.g. `p5` / `min`). */
@@ -83,6 +136,17 @@ export interface BoxColumns {
     /** Upper whisker end (e.g. `p95` / `max`). */
     readonly upper: string;
 }
+/** The four OHLC column names {@link ohlcFromTimeSeries} reads. */
+export interface OhlcColumns {
+    /** Opening price column. */
+    readonly open: string;
+    /** Session high column. */
+    readonly high: string;
+    /** Session low column. */
+    readonly low: string;
+    /** Closing price column. */
+    readonly close: string;
+}
 /**
  * Build a {@link ChartSeries} from a pond `TimeSeries` by reading its columnar
  * buffers directly — no per-event materialization. `column` names a numeric
@@ -143,6 +207,26 @@ export declare function bandFromValueSeries<VS extends ValueSeriesSchema>(series
  * @throws TypeError if any quantile column is not a numeric column.
  */
 export declare function boxFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: BoxColumns): BoxSeries;
+/**
+ * Build an {@link OhlcSeries} from a pond `TimeSeries` — four numeric price
+ * columns (`open`/`high`/`low`/`close`) plus the candle's horizontal slot.
+ *
+ * **Key-shape aware, like {@link barsFromTimeSeries}.** An **interval /
+ * timeRange**-keyed series (an `aggregate` rollup — weekly / monthly bars) uses
+ * the key's own `[begin, end)` as the slot. A **point**-keyed (`time`) series —
+ * raw daily OHLCV — has `begin === end` (zero width), so the slot is derived from
+ * neighbour spacing (each candle centred on its timestamp, reaching halfway to
+ * each neighbour; see {@link neighbourSpans}). This is the ergonomic win over the
+ * interval-only {@link boxFromTimeSeries}: raw OHLC feeds straight in with no
+ * `aggregate` pass.
+ *
+ * A key with any of the four prices missing reads as a gap (the candle draws
+ * nothing). Detected by `keyColumn().kind === 'time'`.
+ *
+ * @throws RangeError if any price column does not exist.
+ * @throws TypeError if any price column is not a numeric column.
+ */
+export declare function ohlcFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, columns: OhlcColumns): OhlcSeries;
 /**
  * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
  * key's `[begin, end]` as the x-span and `column` as the height.
@@ -185,4 +269,78 @@ 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;
 //# sourceMappingURL=data.d.ts.map