@pond-ts/charts 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...HEAD
+[0.41.0]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...v0.38.0
@@ -38,6 +39,33 @@ patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.41.0] — 2026-07-06
+
+### Added
+
+- **`@pond-ts/charts`: `<Candlestick>` — a first-class OHLC mark** (Phase 1 of
+  the financial-charts RFC, Tidal-driven). `open`/`high`/`low`/`close` props
+  default to the conventional names (`<Candlestick series={s} />` for a standard
+  OHLCV series); draws-only (body extents derived per-mark); **point- or
+  interval-keyed** so raw daily OHLCV feeds straight in (no `aggregate`), while a
+  weekly/monthly rollup is the identical call. `variant: 'candle' | 'bar' |
+'hollow'`, `colorBy: 'direction' | 'series'`, `gap`, and `showOHLC` (four-pill
+  O/H/L/C hover readout; default is a single `close` pill keyed on `as`).
+  Participates in the crosshair x-snap (unlike `BoxPlot`). Supersedes `BoxPlot
+shape='solid'` for OHLC data.
+- **`@pond-ts/charts`: `ohlcFromTimeSeries`** + the `OhlcSeries` / `OhlcColumns`
+  types — read four price columns into a chart-ready columnar view (exported
+  alongside the existing `*FromTimeSeries` builders).
+
+### Changed
+
+- **`@pond-ts/charts`: `ChartTheme` gains a required `candle` slot** (a
+  `CandleStyle`: `rising`/`falling`/`neutral` body+wick pairs, `bodyWidth`,
+  `wickWidth`). `defaultTheme` and `estelaTheme` ship neutral, **unbranded**
+  up/down pairs — market green/red is a `cssVarTheme` overlay, not a library
+  default. **Breaking (type-level):** a hand-built `ChartTheme` that doesn't
+  derive from a shipped theme must add a `candle` slot to compile.
+
 ## [0.40.0] — 2026-07-05
 
 A **core + charts** release from the estela `DataChart`-port friction wave.

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

package/dist/data.d.ts

@@ -53,6 +53,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
@@ -83,6 +109,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 +180,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.

package/dist/data.js

@@ -170,6 +170,41 @@ export function boxFromTimeSeries(series, columns) {
         length: series.length,
     };
 }
+/**
+ * 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 function ohlcFromTimeSeries(series, columns) {
+    const open = readNumericColumn(series, columns.open);
+    const high = readNumericColumn(series, columns.high);
+    const low = readNumericColumn(series, columns.low);
+    const close = readNumericColumn(series, columns.close);
+    const n = series.length;
+    if (series.keyColumn().kind !== 'time') {
+        // Interval / timeRange: the key's own endpoints are the candle slot.
+        const { begin, end } = keyBeginEnd(series);
+        return { x: begin, xEnd: end, open, high, low, close, length: n };
+    }
+    // Point key (begin === end): synthesize the slot from neighbour spacing so raw
+    // daily OHLCV renders as contiguous candles without a pre-key to intervals.
+    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
+    return { x: begin, xEnd: end, open, high, low, close, length: n };
+}
 /**
  * Per-row begin/end buffers for the key column, each aligned to the logical
  * length (zero-copy views). For an interval / timeRange key these are the key's
@@ -184,6 +219,30 @@ function keyBeginEnd(series) {
     // (point-in-time), which the caller's point-key fallback replaces.
     return { begin: key.begin.subarray(0, n), end: key.end.subarray(0, n) };
 }
+/**
+ * Synthesize per-point `[begin, end]` spans from a monotonic axis buffer by
+ * **neighbour spacing**: each point is centred on its own value and reaches
+ * halfway to each neighbour (a Voronoi cell on the axis). The first / last points
+ * mirror their single adjacent gap so the end cells match their interior width; a
+ * lone point (length 1) keeps zero width (the renderer's `minWidth` floor takes
+ * over). Shared by the point-keyed `TimeSeries` bars, the `ValueSeries` bars, and
+ * the point-keyed OHLC reader. `axis` is a zero-copy key buffer (must not be
+ * mutated) — fresh output buffers are allocated.
+ */
+function neighbourSpans(axis, n) {
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const x = axis[i];
+        // Half-gap to the previous neighbour (mirror the next gap at the left edge).
+        const prevGap = i > 0 ? x - axis[i - 1] : i + 1 < n ? axis[i + 1] - x : 0;
+        // Half-gap to the next neighbour (mirror the previous gap at the right edge).
+        const nextGap = i + 1 < n ? axis[i + 1] - x : i > 0 ? x - axis[i - 1] : 0;
+        begin[i] = x - prevGap / 2;
+        end[i] = x + nextGap / 2;
+    }
+    return { begin, end };
+}
 /**
  * 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.
@@ -215,20 +274,8 @@ export function barsFromTimeSeries(series, column) {
         return { begin, end, y, length: n };
     }
     // Point key (begin === end): synthesize a span from neighbour spacing so the
-    // bars have width. Copy into fresh buffers — the key's begin buffer is shared
-    // (zero-copy) and must not be mutated.
-    const src = series.keyColumn().begin;
-    const begin = new Float64Array(n);
-    const end = new Float64Array(n);
-    for (let i = 0; i < n; i += 1) {
-        const t = src[i];
-        // Half-gap to the previous point (mirror the next gap at the left edge).
-        const prevGap = i > 0 ? t - src[i - 1] : i + 1 < n ? src[i + 1] - t : 0;
-        // Half-gap to the next point (mirror the previous gap at the right edge).
-        const nextGap = i + 1 < n ? src[i + 1] - t : i > 0 ? t - src[i - 1] : 0;
-        begin[i] = t - prevGap / 2;
-        end[i] = t + nextGap / 2;
-    }
+    // bars have width (see neighbourSpans).
+    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
     return { begin, end, y, length: n };
 }
 /**
@@ -253,20 +300,9 @@ export function barsFromTimeSeries(series, column) {
 export function barsFromValueSeries(series, column) {
     const y = readValueColumn(series, column);
     const n = series.length;
-    // axisValues() is the monotonic key buffer (zero-copy) — must not be mutated,
-    // so synthesise the spans into fresh buffers.
-    const ax = series.axisValues();
-    const begin = new Float64Array(n);
-    const end = new Float64Array(n);
-    for (let i = 0; i < n; i += 1) {
-        const x = ax[i];
-        // Half-gap to the previous neighbour (mirror the next gap at the left edge).
-        const prevGap = i > 0 ? x - ax[i - 1] : i + 1 < n ? ax[i + 1] - x : 0;
-        // Half-gap to the next neighbour (mirror the previous gap at the right edge).
-        const nextGap = i + 1 < n ? ax[i + 1] - x : i > 0 ? x - ax[i - 1] : 0;
-        begin[i] = x - prevGap / 2;
-        end[i] = x + nextGap / 2;
-    }
+    // axisValues() is the monotonic key buffer (zero-copy); neighbourSpans reads it
+    // and allocates fresh span buffers (never mutates the source).
+    const { begin, end } = neighbourSpans(series.axisValues(), n);
     return { begin, end, y, length: n };
 }
 //# sourceMappingURL=data.js.map

package/dist/index.d.ts

@@ -42,18 +42,21 @@ export { BoxPlot } from './BoxPlot.js';
 export type { BoxPlotProps } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
 export type { BarChartProps } from './BarChart.js';
+export { Candlestick } from './Candlestick.js';
+export type { CandlestickProps } from './Candlestick.js';
+export type { CandleVariant, ColorBy } from './ohlc.js';
 export { Region, Baseline, Marker } from './annotations.js';
 export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, } from './data.js';
+export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, } from './data.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';
 export type { Curve } from './curve.js';
 export type { GapMode } from './gaps.js';
 export { defaultTheme, estelaTheme } from './theme.js';
-export type { ChartTheme, LineStyle, BandStyle, AreaStyle, ScatterStyle, BoxStyle, BarStyle, } from './theme.js';
+export type { ChartTheme, LineStyle, BandStyle, AreaStyle, ScatterStyle, BoxStyle, CandleStyle, BarStyle, } from './theme.js';
 export { cssVarTheme } from './css-theme.js';
 export type { ChartThemeOverrides, VarReader } from './css-theme.js';
 export { useChartTheme } from './useChartTheme.js';

package/dist/index.js

@@ -29,13 +29,14 @@ export { AreaChart } from './AreaChart.js';
 export { ScatterChart } from './ScatterChart.js';
 export { BoxPlot } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
+export { Candlestick } from './Candlestick.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the
 // data): a shaded span, a horizontal value line, a vertical x line.
 export { Region, Baseline, Marker } from './annotations.js';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, ohlcFromTimeSeries, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 // CSS-custom-property → ChartTheme bridge: build a theme from a design system's
 // tokens (`cssVarTheme`), and a hook that re-resolves it on a `data-theme`

package/dist/ohlc.d.ts

@@ -0,0 +1,81 @@
+import type { OhlcSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { CandleStyle } from './theme.js';
+/**
+ * How an OHLC mark renders (pjm17971's fork 2 — bundled as one component, like
+ * {@link BoxShape}, not split into a separate `<OHLCBar>`):
+ *
+ * - **`candle`** (default) — a filled `open→close` body with a `high–low` wick.
+ * - **`bar`** — an OHLC tick bar: a `high–low` stem with a left tick at `open`
+ *   and a right tick at `close`, no body.
+ * - **`hollow`** — like `candle`, but a **rising** candle (close > open) draws a
+ *   *hollow* (outlined) body and a **falling / doji** one a filled body.
+ */
+export type CandleVariant = 'candle' | 'bar' | 'hollow';
+/**
+ * What drives a candle's colour:
+ *
+ * - **`direction`** (default, market convention) — `rising` when close > open,
+ *   `falling` when close < open, `neutral` when equal (a doji).
+ * - **`series`** — one colour off the `as` role (the style's `rising` pair),
+ *   *no* green/red. Keeps "colour = series" when a candle sits beside coloured
+ *   lines and the up/down split would read as a second, conflicting encoding.
+ */
+export type ColorBy = 'direction' | 'series';
+/**
+ * The `[min, max]` vertical extent of the **drawn** candles — the lowest `low`
+ * and highest `high` over keys where **all four** prices are finite — or `null`
+ * if none are. Gap keys (any price `NaN`) are excluded, matching what
+ * {@link drawCandles} draws, so they don't drag the y-domain.
+ *
+ * Only `low`/`high` bound the extent: they are the outermost reach of a candle,
+ * so `open`/`close` lie within `[low, high]` for any well-formed OHLC row and
+ * never widen it. (A malformed row where, say, `close > high` would clip — an
+ * upstream data error, not the chart's to paper over.)
+ */
+export declare function ohlcExtent(ohlc: OhlcSeries): [number, number] | null;
+/**
+ * The index of the candle whose slot `[x, xEnd]` contains `time` — the candle
+ * **under the cursor** — or `-1` if `time` is in no slot. Containment (the box
+ * analog {@link boxIndexAtTime}), not nearest-by-`begin` (which flips to the next
+ * candle past a wide one's midpoint). Candles are sorted by `x`; at a shared edge
+ * the left candle wins. A gap candle (some price non-finite) still owns its span
+ * here; the caller drops it on the finiteness check. O(N) over the candles
+ * (view-scale).
+ */
+export declare function ohlcIndexAtTime(ohlc: OhlcSeries, time: number): number;
+/** All four prices finite at `i` — i.e. this candle is drawn. */
+export declare function isFiniteOhlc(ohlc: OhlcSeries, i: number): boolean;
+/**
+ * Resolve the `{ body, wick }` colours for one candle from its `open`/`close`
+ * and the {@link ColorBy} mode. `direction` picks `rising` (close > open) /
+ * `falling` (close < open) / `neutral` (equal — a doji, falling back to `rising`
+ * when the style omits it); `series` always returns `rising` (one colour, no
+ * up/down split). The single source of the colour decision, shared by
+ * {@link drawCandles} and `<Candlestick>`'s tracker readouts so the pill colour
+ * matches the mark.
+ */
+export declare function resolveCandleStyle(style: CandleStyle, open: number, close: number, colorBy: ColorBy): {
+    body: string;
+    wick: string;
+};
+/**
+ * Draw one candle per key of `ohlc`, mapping data→pixels through
+ * `xScale`/`yScale`. The OHLC sibling of {@link drawBox}: each key gets its own
+ * mark over its slot x-span (`barSpanPx`, inset by `gapPx` so adjacent candles
+ * breathe), in the chosen {@link CandleVariant}, coloured per {@link ColorBy}.
+ *
+ * The body extents are derived here (`min`/`max` of open/close) — the consumer
+ * never precomputes them. A doji (open === close) draws a {@link MIN_BODY_HEIGHT_PX}
+ * body so it stays visible. The body is a fraction (`style.bodyWidth`, default
+ * {@link DEFAULT_BODY_WIDTH}) of the slot, centred; the wick / OHLC-bar stem sits
+ * at the slot centre.
+ *
+ * **Gap-aware**: a key with any price non-finite is skipped entirely (no partial
+ * candle) — the same contract as a box / band gap.
+ *
+ * O(N) over the keys, a fixed number of path ops each — no per-key allocation
+ * beyond the `barSpanPx` tuple.
+ */
+export declare function drawCandles(ctx: CanvasRenderingContext2D, ohlc: OhlcSeries, xScale: Scale, yScale: Scale, style: CandleStyle, variant?: CandleVariant, colorBy?: ColorBy, gapPx?: number, minWidthPx?: number): void;
+//# sourceMappingURL=ohlc.d.ts.map

package/dist/ohlc.js

@@ -0,0 +1,153 @@
+import { barSpanPx } from './range.js';
+/** Default body width as a fraction of the candle slot when the style omits one. */
+const DEFAULT_BODY_WIDTH = 0.8;
+/** Minimum body height in px so a doji (open === close) still shows a mark. */
+const MIN_BODY_HEIGHT_PX = 1;
+/**
+ * The `[min, max]` vertical extent of the **drawn** candles — the lowest `low`
+ * and highest `high` over keys where **all four** prices are finite — or `null`
+ * if none are. Gap keys (any price `NaN`) are excluded, matching what
+ * {@link drawCandles} draws, so they don't drag the y-domain.
+ *
+ * Only `low`/`high` bound the extent: they are the outermost reach of a candle,
+ * so `open`/`close` lie within `[low, high]` for any well-formed OHLC row and
+ * never widen it. (A malformed row where, say, `close > high` would clip — an
+ * upstream data error, not the chart's to paper over.)
+ */
+export function ohlcExtent(ohlc) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (!isFiniteOhlc(ohlc, i))
+            continue;
+        const lo = ohlc.low[i];
+        const hi = ohlc.high[i];
+        if (lo < min)
+            min = lo;
+        if (hi > max)
+            max = hi;
+    }
+    return min === Infinity ? null : [min, max];
+}
+/**
+ * The index of the candle whose slot `[x, xEnd]` contains `time` — the candle
+ * **under the cursor** — or `-1` if `time` is in no slot. Containment (the box
+ * analog {@link boxIndexAtTime}), not nearest-by-`begin` (which flips to the next
+ * candle past a wide one's midpoint). Candles are sorted by `x`; at a shared edge
+ * the left candle wins. A gap candle (some price non-finite) still owns its span
+ * here; the caller drops it on the finiteness check. O(N) over the candles
+ * (view-scale).
+ */
+export function ohlcIndexAtTime(ohlc, time) {
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (time >= ohlc.x[i] && time <= ohlc.xEnd[i])
+            return i;
+    }
+    return -1;
+}
+/** All four prices finite at `i` — i.e. this candle is drawn. */
+export function isFiniteOhlc(ohlc, i) {
+    return (Number.isFinite(ohlc.open[i]) &&
+        Number.isFinite(ohlc.high[i]) &&
+        Number.isFinite(ohlc.low[i]) &&
+        Number.isFinite(ohlc.close[i]));
+}
+/**
+ * Resolve the `{ body, wick }` colours for one candle from its `open`/`close`
+ * and the {@link ColorBy} mode. `direction` picks `rising` (close > open) /
+ * `falling` (close < open) / `neutral` (equal — a doji, falling back to `rising`
+ * when the style omits it); `series` always returns `rising` (one colour, no
+ * up/down split). The single source of the colour decision, shared by
+ * {@link drawCandles} and `<Candlestick>`'s tracker readouts so the pill colour
+ * matches the mark.
+ */
+export function resolveCandleStyle(style, open, close, colorBy) {
+    if (colorBy === 'series')
+        return style.rising;
+    if (close > open)
+        return style.rising;
+    if (close < open)
+        return style.falling;
+    return style.neutral ?? style.rising;
+}
+/**
+ * Draw one candle per key of `ohlc`, mapping data→pixels through
+ * `xScale`/`yScale`. The OHLC sibling of {@link drawBox}: each key gets its own
+ * mark over its slot x-span (`barSpanPx`, inset by `gapPx` so adjacent candles
+ * breathe), in the chosen {@link CandleVariant}, coloured per {@link ColorBy}.
+ *
+ * The body extents are derived here (`min`/`max` of open/close) — the consumer
+ * never precomputes them. A doji (open === close) draws a {@link MIN_BODY_HEIGHT_PX}
+ * body so it stays visible. The body is a fraction (`style.bodyWidth`, default
+ * {@link DEFAULT_BODY_WIDTH}) of the slot, centred; the wick / OHLC-bar stem sits
+ * at the slot centre.
+ *
+ * **Gap-aware**: a key with any price non-finite is skipped entirely (no partial
+ * candle) — the same contract as a box / band gap.
+ *
+ * O(N) over the keys, a fixed number of path ops each — no per-key allocation
+ * beyond the `barSpanPx` tuple.
+ */
+export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1) {
+    const bodyFraction = style.bodyWidth ?? DEFAULT_BODY_WIDTH;
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (!isFiniteOhlc(ohlc, i))
+            continue;
+        const open = ohlc.open[i];
+        const close = ohlc.close[i];
+        const [x0, x1] = barSpanPx(ohlc.x[i], ohlc.xEnd[i], xScale, gapPx, minWidthPx);
+        const mid = (x0 + x1) / 2;
+        const bodyHalf = ((x1 - x0) * bodyFraction) / 2;
+        const bx0 = mid - bodyHalf;
+        const bodyW = bodyHalf * 2;
+        const yOpen = yScale(open);
+        const yHigh = yScale(ohlc.high[i]);
+        const yLow = yScale(ohlc.low[i]);
+        const yClose = yScale(close);
+        const { body, wick } = resolveCandleStyle(style, open, close, colorBy);
+        if (variant === 'bar') {
+            // OHLC bar: a high–low stem, a left tick at open, a right tick at close —
+            // all one colour (the `body` role), no filled body.
+            ctx.strokeStyle = body;
+            ctx.lineWidth = style.wickWidth;
+            ctx.beginPath();
+            ctx.moveTo(mid, yHigh); // stem
+            ctx.lineTo(mid, yLow);
+            ctx.moveTo(bx0, yOpen); // open tick (points left)
+            ctx.lineTo(mid, yOpen);
+            ctx.moveTo(mid, yClose); // close tick (points right)
+            ctx.lineTo(mid + bodyHalf, yClose);
+            ctx.stroke();
+            continue;
+        }
+        // candle / hollow: the high–low wick first (so the body overlaps it), then
+        // the open→close body.
+        ctx.strokeStyle = wick;
+        ctx.lineWidth = style.wickWidth;
+        ctx.beginPath();
+        ctx.moveTo(mid, yHigh);
+        ctx.lineTo(mid, yLow);
+        ctx.stroke();
+        // Body extents, with a doji floor so open === close still shows a mark.
+        let top = Math.min(yOpen, yClose);
+        let h = Math.abs(yClose - yOpen);
+        if (h < MIN_BODY_HEIGHT_PX) {
+            top -= (MIN_BODY_HEIGHT_PX - h) / 2;
+            h = MIN_BODY_HEIGHT_PX;
+        }
+        // `hollow`: a rising candle is outlined (hollow), a falling / doji one filled
+        // — the same strict-`>` boundary resolveCandleStyle uses (equality → neutral),
+        // so a doji's fill and its colour agree.
+        const hollow = variant === 'hollow' && close > open;
+        if (hollow) {
+            ctx.strokeStyle = body;
+            ctx.lineWidth = style.wickWidth;
+            ctx.strokeRect(bx0, top, bodyW, h);
+        }
+        else {
+            ctx.fillStyle = body;
+            ctx.fillRect(bx0, top, bodyW, h);
+        }
+    }
+}
+//# sourceMappingURL=ohlc.js.map

package/dist/theme.d.ts

@@ -73,6 +73,22 @@ export interface ChartTheme {
         readonly default: BoxStyle;
         readonly [semantic: string]: BoxStyle;
     };
+    /**
+     * Map from a candle's semantic identifier to its style — a first-class OHLC
+     * mark ({@link Candlestick}), the financial sibling of the box. Unlike the
+     * other slots a {@link CandleStyle} carries a *pair* (`rising`/`falling`, plus
+     * an optional `neutral` doji): direction colouring is intrinsic to the mark, so
+     * one colour can't express it. `default` is the fallback; a chart tags each
+     * series with a role (`<Candlestick as="AAPL" />`) resolving `candle[semantic]
+     * ?? candle.default`. The default pair is **neutral / unbranded** (a
+     * distinguishable up/down, *not* market green/red) — a consumer supplies its
+     * own palette via `cssVarTheme`; the library owns the type + a renderable
+     * default, never a brand.
+     */
+    readonly candle: {
+        readonly default: CandleStyle;
+        readonly [semantic: string]: CandleStyle;
+    };
     /**
      * Map from a bar's semantic identifier to its style — the fill, the
      * selected-bar highlight, and the slot gap / minimum width ({@link BarChart}).
@@ -204,6 +220,42 @@ export interface BoxStyle {
     readonly whisker: string;
     readonly whiskerWidth: number;
 }
+/**
+ * A resolved candlestick style ({@link Candlestick}). A candle is unreadable in
+ * one colour — rising vs falling *must* differ to mean anything — so the style
+ * is a **pair**: `rising` (close > open) and `falling` (close < open), each a
+ * `body` (the open→close rectangle / the OHLC bar) and a `wick` (the high–low
+ * line / the bar's stem). `neutral` styles a **doji** (open === close); it falls
+ * back to `rising` when unset. `bodyWidth` is the body's fraction of the candle
+ * slot (0–1; the wick always sits at the slot centre) — omitted ⇒ `0.8`.
+ * `wickWidth` is the wick / bar stroke width in px.
+ *
+ * With `colorBy='series'` the direction split is bypassed and every candle draws
+ * in the `rising` colours (one colour = one series, for a candle sitting beside
+ * coloured lines).
+ */
+export interface CandleStyle {
+    /** Rising candle (close > open) — body + wick colours. Also the single colour
+     *  under `colorBy='series'`. */
+    readonly rising: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Falling candle (close < open) — body + wick colours. */
+    readonly falling: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Doji (open === close) — body + wick colours; falls back to `rising` if unset. */
+    readonly neutral?: {
+        readonly body: string;
+        readonly wick: string;
+    };
+    /** Body width as a fraction of the candle slot (0–1). Omitted ⇒ `0.8`. */
+    readonly bodyWidth?: number;
+    /** Wick / OHLC-bar stroke width in px. */
+    readonly wickWidth: number;
+}
 /**
  * A resolved area style: an outline stroke plus a graded fill. `color`/`width`
  * stroke the value line on top; `fill` is the gradient base colour, opaque

package/dist/theme.js

@@ -75,6 +75,18 @@ export const defaultTheme = {
             whiskerWidth: 1,
         },
     },
+    candle: {
+        // Neutral / unbranded up-down pair — *not* market green/red (a consumer
+        // supplies that via cssVarTheme). Rising reuses the brand blue; falling the
+        // warm secondary accent — distinguishable at a glance on the light ground.
+        default: {
+            rising: { body: '#2563eb', wick: '#1e3a8a' },
+            falling: { body: '#e8836b', wick: '#b4442a' },
+            neutral: { body: '#94a3b8', wick: '#64748b' },
+            bodyWidth: 0.7,
+            wickWidth: 1,
+        },
+    },
     bar: {
         // Flat blue fill; the selected bar brightens + outlines. `secondary` reuses
         // the line's warm accent for a second series.
@@ -202,6 +214,18 @@ export const estelaTheme = {
             whiskerWidth: 1.5,
         },
     },
+    candle: {
+        // On the dark ground: brand teal rising, warm filament falling — the estela
+        // palette's own up/down, still *not* literal green/red (a financial consumer
+        // like Tidal overlays its market palette via cssVarTheme).
+        default: {
+            rising: { body: '#15B3A6', wick: '#0E7D74' }, // --es-estela
+            falling: { body: '#E0B36A', wick: '#B4863F' }, // --es-filament
+            neutral: { body: '#4E6B6B', wick: '#DBEAE8' }, // --es-slate / --es-mist
+            bodyWidth: 0.7,
+            wickWidth: 1.5,
+        },
+    },
     bar: {
         // Brand-teal fill on the dark ground; the selected bar lifts to the bright
         // reef + an outline. `secondary` is the warm filament accent.

package/package.json

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