@pond-ts/charts 0.41.0 → 0.42.0

package/dist/BarChart.js

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

package/dist/ChartContainer.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingTimeScale.js';
 import type { TimeRange } from 'pond-ts';
 import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
 import { type AxisFormat } from './format.js';
@@ -12,6 +13,45 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * A **trading-calendar** discontinuity provider — closed-market time
+     * (weekends, holidays, overnight, lunch breaks) collapsed. Supply it to turn
+     * the shared x axis into a **trading-time** axis: gaps disappear and time
+     * stays proportional within each session. A `@pond-ts/financial`
+     * `TradingCalendar.discontinuities()` satisfies this structurally (charts
+     * never imports that package). The **low-level** primitive: pass
+     * `calendar.discontinuities()` (or a `{ spacing, period }` variant) directly.
+     * Only affects a **time** axis (ignored on a value axis). Takes precedence
+     * over {@link calendar} if both are given.
+     *
+     * **Pass a stable reference.** The scale (and container frame) rebuild when
+     * this prop's identity changes, so memoize it — `const disc = useMemo(() =>
+     * calendar.discontinuities(), [calendar])` — rather than calling
+     * `.discontinuities()` inline in JSX, which would rebuild every render.
+     */
+    discontinuities?: DiscontinuityProvider;
+    /**
+     * The **high-level** sugar for {@link discontinuities}: a trading calendar the
+     * container derives the provider from itself (`calendar.discontinuities({
+     * spacing })`), so you don't wire the low-level prop. A `@pond-ts/financial`
+     * `TradingCalendar` satisfies the structural {@link TradingCalendarLike} shape
+     * (charts never imports that package). Combine with {@link spacing}. For the
+     * full option matrix (a bar `period`, a scoped `range`) use the low-level
+     * `discontinuities` prop instead. Only affects a **time** axis.
+     *
+     * The provider is memoized on `(calendar, spacing)`, so pass a **stable**
+     * calendar reference (build it once, not inline in JSX).
+     */
+    calendar?: TradingCalendarLike;
+    /**
+     * The trading axis **metric**, when a {@link calendar} is supplied
+     * (trading-calendar RFC Q7). `'proportional'` (default) keeps time
+     * proportional within and across sessions — a half-day is half as wide.
+     * `'uniform'` gives every session equal width (the TradingView ordinal look).
+     * Ignored without `calendar` (a low-level `discontinuities` provider already
+     * carries its own metric).
+     */
+    spacing?: 'proportional' | 'uniform';
     /** Total width in CSS pixels (plot + axis gutters). */
     width: number;
     /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
@@ -46,15 +86,21 @@ export interface ChartContainerProps {
     /**
      * Controlled selection — the selected mark (echo the `onSelect` arg back), or
      * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
-     * internally; pass `null` to force nothing selected). Selectable layers
-     * (`BarChart`, `BoxPlot`, `ScatterChart`) highlight the mark matching both its
-     * key and series — so two series sharing a timestamp don't both light up.
+     * internally; pass `null` to force nothing selected). A layer is **selectable
+     * only when it carries an `id`** (the stable series identity) — `BarChart` /
+     * `ScatterChart` highlight the mark matching the selection's `id` (the series)
+     * and its `key` (the sample), so two series sharing a timestamp don't both
+     * light up, and the selection survives a data update (it keys on the stable
+     * `id`, not the sample `key`). A layer with no `id` renders + reads out but
+     * can't be selected.
      */
     selected?: SelectInfo | null;
     /**
      * Fires when a selectable layer's mark is clicked, with the hit mark, or `null`
-     * when a click misses every mark (clears the selection). Notification only —
-     * works in both controlled and uncontrolled mode.
+     * when a click misses every mark (or hits a layer with no `id` — display-only,
+     * so it reads as empty space). Notification only — works in both controlled and
+     * uncontrolled mode. If this or `selected` is set but no layer has an `id`, a
+     * dev-warning notes that nothing is selectable.
      */
     onSelect?: (hit: SelectInfo | null) => void;
     /**
@@ -180,5 +226,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, discontinuities, calendar, spacing, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map