@pond-ts/charts 0.40.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/Candlestick.d.ts

@@ -0,0 +1,93 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type CandleVariant, type ColorBy } from './ohlc.js';
+export interface CandlestickProps<S extends SeriesSchema> {
+    /**
+     * The source series. **Point-keyed** (`time`) raw OHLCV feeds straight in —
+     * each candle's slot is derived from neighbour spacing (see
+     * {@link ohlcFromTimeSeries}), no `aggregate` pass needed. An **interval /
+     * timeRange**-keyed series (an `aggregate` rollup — weekly / monthly bars) uses
+     * the key's own `[begin, end)` as the slot. The chart infers the x-kind from
+     * the data; there's no axis-type prop.
+     */
+    series: TimeSeries<S>;
+    /** Opening-price column. **Omitted ⇒ `'open'`.** */
+    open?: string;
+    /** Session-high column. **Omitted ⇒ `'high'`.** */
+    high?: string;
+    /** Session-low column. **Omitted ⇒ `'low'`.** */
+    low?: string;
+    /** Closing-price column. **Omitted ⇒ `'close'`.** */
+    close?: string;
+    /**
+     * The series' semantic identifier — what the data _is_ (e.g. a ticker). The
+     * theme maps it to a {@link CandleStyle} (`theme.candle[as] ??
+     * theme.candle.default`). **Omitted ⇒ the `default` candle style.** It's also
+     * the tracker/readout label for the series (the primary `close` pill keys on
+     * `as`, not the raw column name).
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this candle scales against — the *scale*, where
+     * `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * How each mark renders — `'candle'` (default; filled body + wick), `'bar'`
+     * (OHLC tick bar), or `'hollow'` (rising hollow / falling filled). See
+     * {@link CandleVariant}.
+     */
+    variant?: CandleVariant;
+    /**
+     * What drives the colour — `'direction'` (default; rising / falling / doji off
+     * open vs close, the market convention) or `'series'` (one colour off the `as`
+     * role, no green/red). See {@link ColorBy}.
+     */
+    colorBy?: ColorBy;
+    /**
+     * Total horizontal inset between adjacent candles in px (half each side), so
+     * they breathe — see `barSpanPx`. **Omitted ⇒ `0`** (the body already insets to
+     * `style.bodyWidth` of the slot). A candle narrower than 1px after the inset
+     * collapses to a 1px mark, so a thin slot stays visible.
+     */
+    gap?: number;
+    /**
+     * Fan the **full O/H/L/C** to the tracker readout (four value pills) instead of
+     * the default single `close` pill. **Omitted ⇒ `false`** — close is "the price"
+     * for a compact legend; the full quote is opt-in for a dense hover readout.
+     */
+    showOHLC?: boolean;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A first-class OHLC **candlestick** draw layer — the financial sibling of
+ * {@link BoxPlot}. Reads four price columns (`open`/`high`/`low`/`close`) of
+ * `series` into an {@link OhlcSeries} and draws one candle per key: the
+ * `open→close` body (direction-coloured) and the `high–low` wick, over the key's
+ * slot x-span. Derives the body extents itself (`min`/`max` of open/close) — the
+ * consumer never runs a `withColumn` precompute. Registers into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it. Gap-aware (a key
+ * missing any price draws nothing).
+ *
+ * **Draws only** — windowing stays upstream: raw daily OHLCV is a point-keyed
+ * `TimeSeries` fed straight in, and a weekly / monthly bar is the identical call
+ * on an `aggregate(Sequence.calendar('week'), …)` rollup (interval-keyed). This
+ * supersedes `BoxPlot shape='solid'` for OHLC (which needed a quantile remap, a
+ * body precompute, two overlaid layers for green/red, and a column-name tracker).
+ *
+ * **Cursor.** Unlike `BoxPlot`, a candle **participates in the crosshair x-snap**
+ * (it exposes plain `sampleAt`, not a consolidated `cursorFlag`), so the reticle
+ * lands on candles. The readout keys on `as` and shows `close` by default; pass
+ * `showOHLC` for the full four-pill quote.
+ *
+ * ```tsx
+ * <Layers>
+ *   <Candlestick series={daily} as="AAPL" />
+ * </Layers>
+ * ```
+ */
+export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, index, }: CandlestickProps<S>): null;
+//# sourceMappingURL=Candlestick.d.ts.map

package/dist/Candlestick.js

@@ -0,0 +1,102 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { ohlcFromTimeSeries } from './data.js';
+import { drawCandles, isFiniteOhlc, ohlcExtent, ohlcIndexAtTime, resolveCandleStyle, } from './ohlc.js';
+import { ContainerContext, LayersContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A first-class OHLC **candlestick** draw layer — the financial sibling of
+ * {@link BoxPlot}. Reads four price columns (`open`/`high`/`low`/`close`) of
+ * `series` into an {@link OhlcSeries} and draws one candle per key: the
+ * `open→close` body (direction-coloured) and the `high–low` wick, over the key's
+ * slot x-span. Derives the body extents itself (`min`/`max` of open/close) — the
+ * consumer never runs a `withColumn` precompute. Registers into the enclosing
+ * {@link Layers}; renders nothing to the DOM — the row draws it. Gap-aware (a key
+ * missing any price draws nothing).
+ *
+ * **Draws only** — windowing stays upstream: raw daily OHLCV is a point-keyed
+ * `TimeSeries` fed straight in, and a weekly / monthly bar is the identical call
+ * on an `aggregate(Sequence.calendar('week'), …)` rollup (interval-keyed). This
+ * supersedes `BoxPlot shape='solid'` for OHLC (which needed a quantile remap, a
+ * body precompute, two overlaid layers for green/red, and a column-name tracker).
+ *
+ * **Cursor.** Unlike `BoxPlot`, a candle **participates in the crosshair x-snap**
+ * (it exposes plain `sampleAt`, not a consolidated `cursorFlag`), so the reticle
+ * lands on candles. The readout keys on `as` and shows `close` by default; pass
+ * `showOHLC` for the full four-pill quote.
+ *
+ * ```tsx
+ * <Layers>
+ *   <Candlestick series={daily} as="AAPL" />
+ * </Layers>
+ * ```
+ */
+export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<Candlestick> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<Candlestick> must be rendered inside a <Layers>');
+    }
+    const ohlc = useMemo(() => ohlcFromTimeSeries(series, { open, high, low, close }), [series, open, high, low, close]);
+    // Styling: semantic identifier → theme candle style. The single styling channel.
+    const { candle } = container.theme;
+    const style = (semantic !== undefined ? candle[semantic] : undefined) ?? candle.default;
+    // Series identity for the readout (the `as` role, else the close column name) —
+    // the primary `close` pill keys on this, like every other layer.
+    const label = semantic ?? close;
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => ohlcExtent(ohlc),
+            xKind: 'time',
+            xExtent: () => ohlc.length === 0 ? null : [ohlc.x[0], ohlc.xEnd[ohlc.length - 1]],
+            sampleAt: (time) => {
+                // The readout reads the candle **under the cursor** (containment span,
+                // not nearest-by-begin), anchored at the slot centre. Outside every
+                // candle → no readout. No `cursorFlag`: the samples flow through the
+                // normal per-series tracker path, which is also what keeps the candle
+                // in the crosshair x-snap (BoxPlot's cursorFlag opts out of both).
+                if (ohlc.length === 0)
+                    return [];
+                const i = ohlcIndexAtTime(ohlc, time);
+                if (i < 0 || !isFiniteOhlc(ohlc, i))
+                    return [];
+                const at = (ohlc.x[i] + ohlc.xEnd[i]) / 2;
+                const { body, wick } = resolveCandleStyle(style, ohlc.open[i], ohlc.close[i], colorBy);
+                if (!showOHLC) {
+                    // Default: `close` is "the price", keyed on the series id.
+                    return [{ x: at, value: ohlc.close[i], color: body, label }];
+                }
+                // Opt-in full quote: four value pills (body colour for open/close, wick
+                // colour for the high/low extremes). Each is a value-only axis pill.
+                const samples = [
+                    { x: at, value: ohlc.high[i], color: wick, label: 'high' },
+                    { x: at, value: ohlc.open[i], color: body, label: 'open' },
+                    { x: at, value: ohlc.close[i], color: body, label: 'close' },
+                    { x: at, value: ohlc.low[i], color: wick, label: 'low' },
+                ];
+                return samples;
+            },
+            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap),
+        },
+        axisId: axis,
+        index,
+    }), [ohlc, style, label, variant, colorBy, gap, showOHLC, axis, index]);
+    // Stable per-instance slot (see useSlotKey): keeps this candle layer's
+    // z-position + identity across prop updates; the injected index drives the sort.
+    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' OHLC at the cursor
+    // for the (outside-the-chart) readout.
+    const { registerTrackerSource, unregisterTrackerSource } = container;
+    useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
+    useEffect(() => {
+        registerTrackerSource(slot, entry.layer);
+    }, [registerTrackerSource, slot, entry.layer]);
+    return null;
+}
+//# sourceMappingURL=Candlestick.js.map