@pond-ts/charts 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -3,12 +3,14 @@
 All notable changes to this project are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
-`@pond-ts/fit` — release together under a single `v*` tag, so this file covers
-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
+The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
+`@pond-ts/fit`, and `@pond-ts/financial` — release together under a single `v*`
+tag, so this file covers 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.42.0...HEAD
+[0.42.0]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...v0.42.0
+[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 +40,101 @@ patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.42.0] — 2026-07-10
+
+The **trading-calendar** release: a new `@pond-ts/financial` package (its first
+publish) and a discontinuous **trading-time x axis** in `@pond-ts/charts` that
+collapses closed-market time (weekends, holidays, overnight, lunch breaks).
+
+### Added
+
+- **`@pond-ts/financial` — new package (first release).** A calendar/analytics
+  layer on `pond-ts` (peer dep; ESM, no React; `@js-temporal/polyfill` for
+  DST-correct session generation):
+  - **`TradingCalendar`** — `fromSessions` (explicit schedule) and `fromRules`
+    (weekmask / holidays / early-closes / breaks, DST-correct via Temporal);
+    query surface (`sessionOn`, `sessionContaining`, `isOpen`, `sessionsInRange`,
+    `nextSession`, `previousSession`).
+  - **Bucketing seam** — `sessionSequence()` / `barSequence(period)` return a
+    `BoundedSequence` that flows straight through `aggregate` / `materialize`,
+    so every bucket is a real trading session/bar (no weekend/holiday buckets,
+    no bucket spanning a closure). Zero core edits.
+  - **`tagSessions(series, { column?, stamped? })`** — appends a session-id
+    column (`number | undefined`) for `partitionBy` so stateful ops don't bridge
+    a session boundary. `stamped: 'close'` bins a bar stamped at its close into
+    the closing session (`(open, close]`) for OHLC feeds.
+  - **`DiscontinuityProvider`** — the d3fc-style 5-method provider
+    (`clampUp`/`clampDown`/`distance`/`offset`/`copy` + optional `boundaries`);
+    `identityDiscontinuity`, `weekendSkip` (bundled reference), and
+    `segmentDiscontinuity(segments, { spacing })`.
+  - **`TradingCalendar.discontinuities({ range?, spacing?, period? })`** — the
+    chart-ready provider; `spacing: 'proportional'` (default, true-time) or
+    `'uniform'` (equal-width per session/bar, the TradingView ordinal look).
+- **`@pond-ts/charts`: trading-time x axis.** Pass a `@pond-ts/financial`
+  provider (structurally — charts never imports that package) to collapse
+  closed-market gaps:
+  - **`ChartContainer` `discontinuities` prop** (low-level) and **`calendar` +
+    `spacing` props** (high-level sugar; `calendar` is a structural
+    `TradingCalendarLike`, `spacing` defaults to proportional).
+  - **`scaleTradingTime`** — a d3-scale-shaped discontinuous time scale; ticks
+    coarsen to a **calendar grain** (week/month/quarter/year starts) with
+    date/year labels, and **session dividers** draw at the collapse points
+    (`theme.axis.sessionDivider`), aligned with the labels.
+  - `Charts/TradingTimeAxis` stories (weekend/holiday/half-day/intraday,
+    continuous-vs-trading, daily-months, proportional-vs-uniform).
+- **`@pond-ts/charts`:** selection now has a stable series identity. `SelectInfo`
+  carries an `id`, and `BarChart` / `ScatterChart` take an optional `id` prop —
+  the series identity used for selection + hover. An `id` **gates interactivity**:
+  a layer is selectable/hoverable only when given one (a layer with no `id`
+  renders and reads out but can't be selected). A dev-warning fires when
+  `selected`/`onSelect` is wired but no layer carries an `id`. First slice of the
+  selection RFC (`docs/rfcs/selection.md`, Amendments 2–3).
+- **`pond-ts`: `bin(W, 'minMaxFirstLast')`** — the four-channel M4 downsampling
+  reducer (per-bin min/max/first/last, validity-aware, chunked-delegating); the
+  foundation for the charts decimator wave.
+- **`pond-ts`: `binBy`** — key-domain bucketed reduction (the M4 gappy-data
+  decimation path).
+
+### Changed
+
+- **BREAKING (`@pond-ts/charts`):** `SelectInfo` gained a required `id` field
+  (`{ id, key, value, color, label }`) — `id` is the selection identity, `key` /
+  `value` are now click provenance. Code that constructs a `SelectInfo` by hand
+  must add `id`, and selection equality/dedup now keys on `id`, not the sample
+  `begin`.
+- **BREAKING (`@pond-ts/charts`):** `BarChart` / `ScatterChart` selection now
+  requires an explicit `id` prop — the previous implicit `as ?? column` selection
+  identity is gone. A selectable bar/scatter layer must add `id` (e.g.
+  `<BarChart series={s} column="v" id="v" />`); without it the layer is
+  display-only.
+
+## [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/BarChart.d.ts

@@ -1,42 +1,101 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import { type BinRecord } from './data.js';
+import { type Orientation } from './bars.js';
 export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
-     * The source series. **Interval / timeRange-keyed** `TimeSeries` is the primary
-     * form — each event's key `[begin, end]` is a bar's x-span. A **point-keyed**
-     * (`time`) series is supported too: each bar's width is derived from neighbour
-     * spacing (see {@link barsFromTimeSeries}). A **`ValueSeries`**
-     * (`series.byValue('dist')`) bars against its value axis — also point-keyed, so
-     * the same neighbour-spacing span applies (see {@link barsFromValueSeries}); the
-     * container infers the x-kind from the data, no axis-type prop (mirrors the
-     * other layers).
+     * The source series. Provide **exactly one** of `series` or `bins`.
      *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
-     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
-     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
+     * - A **`TimeSeries`** (interval / timeRange-keyed is the primary form — each
+     *   event's key `[begin, end]` is a bar's x-span; a point-keyed series derives
+     *   its width from neighbour spacing) → single-series bars via `column`, or
+     *   stacked bars from a **wide** series via `columns`.
+     * - A **`ValueSeries`** (`series.byValue('dist')`) bars against its value axis.
+     * - A **`ReadonlyMap<group, TimeSeries>`** — one series per stack group, all on
+     *   the same bin grid, the shape
+     *   `series.partitionBy('host', { groups }).aggregate(seq, m).toMap()` returns.
+     *   Stacked bars, `column` names the shared value column, groups = map order.
+     *
+     * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
+     * call, so an inline `series={…}` re-registers this layer every render — on a
+     * frequently re-rendering chart, memoize the projection (`useMemo`).
+     */
+    series?: TimeSeries<S> | ValueSeries<VS> | ReadonlyMap<string, TimeSeries<S>>;
+    /**
+     * `byColumn` **bin records** — `Array<{ start, end, …aggregates }>` from a
+     * value-band aggregation
+     * (`series.byColumn('power', { width: 20 }, { seconds: … })`). The value-axis
+     * alternative to `series`: `column` / `columns` name the aggregate field(s) to
+     * draw. Pair with `ordinal` for a category (band) axis.
+     */
+    bins?: readonly BinRecord[];
+    /** Name of the numeric value column for the bar height (single series). Provide
+     *  `column` **or** `columns`, not both. */
+    column?: string;
+    /**
+     * Stacked-segment columns, **bottom → top** — one segment per name. Use with a
+     * **wide** `series` (e.g. `pivotByGroup` output) or with `bins`. Mutually
+     * exclusive with `column`, and invalid with a `Map` series (there the segments
+     * are the map's groups; use `column`).
      */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric value column for the bar height. */
-    column: string;
+    columns?: readonly string[];
     /**
-     * The series' semantic identifier — what the data _is_ / how it should read.
-     * The theme maps it to a {@link BarStyle} (`theme.bar[as] ?? theme.bar.default`).
-     * **Omitted ⇒ the `default` style** — `column` is the data, `as` is the
-     * identity, and there's no per-component colour override (the single styling
-     * channel; restyle via the theme).
+     * The single series' semantic identifier — what the data _is_. The theme maps
+     * it to a {@link BarStyle} (`theme.bar[as] ?? theme.bar.default`). **Single
+     * series only** — **ignored** (not an error) on a stacked chart, which colours
+     * its segments per group instead (see `colors`).
      */
     as?: string;
     /**
-     * Which `<YAxis>` (by its `id`) this bar scales against — picks the *scale*,
-     * where `as` picks the *style* (separate concerns). **Omitted ⇒ the row's
-     * default axis.**
+     * Per-group colour override for a **stacked** chart — `{ group: cssColor }`.
+     * A segment resolves `colors[group] ?? theme.bar[group]?.fill ??
+     * theme.bar.default.fill`, so named roles (e.g. a `crit` band styled in the
+     * theme) come from the theme while ad-hoc groups (five hosts) take a colour
+     * here without minting a theme role. The single styling channel still holds:
+     * this is the stack's one colour input.
+     */
+    colors?: Readonly<Record<string, string>>;
+    /**
+     * Bar growth direction (the histogram orientation). **Default `'vertical'`.**
+     *
+     * - `'vertical'` — bars grow **up** from a value baseline, bins on the **x**
+     *   axis (time buckets, value bands). The column / time-histogram look.
+     * - `'horizontal'` — bars grow **right**, bins on the **y** axis (a band axis
+     *   like heart-rate zones). Label the bands with `<YAxis ticks={[{ at, label }]}>`.
+     *
+     * A `'horizontal'` chart puts the **value** on the shared x axis, so its
+     * container's x-kind is `'value'` — it cannot share a `<ChartContainer>` with
+     * time-series rows (each horizontal histogram stands alone). Vertical charts
+     * have no such constraint. The in-chart `flag` / `crosshair` value cursor is
+     * drawn for the **single-series vertical** case only; stacked and horizontal
+     * charts read out via hover / click (`onHover` / `onSelect`).
+     */
+    orientation?: Orientation;
+    /**
+     * For `bins`: lay the bands out as uniform **unit slots** (`[i, i+1]`) instead
+     * of their numeric `[start, end]` edges — an ordinal band axis where every band
+     * reads the same width (heart-rate zones). Ignored for `series`.
+     */
+    ordinal?: boolean;
+    /**
+     * The **stable series identity** for selection + hover — and it **gates
+     * interactivity** (a bar layer is selectable/hoverable only when given an
+     * `id`). For a stack, a clicked / hovered **segment** is identified by
+     * `(id, key = bin begin, label = group)`, so two segments in one bin don't both
+     * light up.
+     */
+    id?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this layer scales against — the *scale* (`as`
+     * picks the *style*). **Omitted ⇒ the row's default axis.** For a horizontal
+     * histogram this is the **bin (band) axis**; for a vertical one the **value**
+     * axis.
      */
     axis?: string;
     /**
-     * Pixel gap between adjacent bars — each bar's key span is inset by this total
-     * (half each side), so neighbours breathe. **Omitted ⇒ the theme's
-     * `bar[as].gap`.** A span the gap would invert collapses to the style's
-     * `minWidth`, so a too-thin bucket stays visible.
+     * Pixel gap between adjacent bars / bins — the bar's key span is inset by this
+     * total (half each side). **Omitted ⇒ the theme's `bar` `gap`.** A span the gap
+     * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
     /**
@@ -46,43 +105,47 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
     index?: number;
 }
 /**
- * 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 declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, gap, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, column, columns, as: semantic, colors, orientation, ordinal, id, axis, gap, index, }: BarChartProps<S, VS>): null;
 //# sourceMappingURL=BarChart.d.ts.map