@pond-ts/charts 0.48.1 → 0.50.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 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/pond-ts/pond/compare/v0.48.1...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.50.0...HEAD
+[0.50.0]: https://github.com/pond-ts/pond/compare/v0.49.0...v0.50.0
+[0.49.0]: https://github.com/pond-ts/pond/compare/v0.48.1...v0.49.0
 [0.48.1]: https://github.com/pond-ts/pond/compare/v0.48.0...v0.48.1
 [0.48.0]: https://github.com/pond-ts/pond/compare/v0.47.0...v0.48.0
 [0.47.0]: https://github.com/pond-ts/pond/compare/v0.46.0...v0.47.0
@@ -48,6 +50,228 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.50.0] — 2026-07-21
+
+### Added
+
+- **charts:** M4 decimation extended to **`<Candlestick>`** (same auto-on
+  `decimate` prop). Dense candles are drawn as per-pixel-column **aggregate
+  candles** — `open=first`, `high=max`, `low=min`, `close=last` over the column —
+  i.e. re-bucketed to the pixel-column timeframe, the way a trading chart shows
+  fewer, wider candles as you zoom out (decimator §2.4). It is a faithful OHLC of
+  each column's span, never a distortion; the hover readout still reads the
+  **source** candle at the cursor (§2.3). Decimation gates on the **visible**
+  candle count, so a deep zoom into a large series still draws full-width
+  candles. Pass `decimate={false}` (and pre-aggregate upstream) for
+  fixed-timeframe candles.
+- **charts:** M4 decimation extended to **`<BoxPlot>`** (same auto-on `decimate`
+  prop) — the interval-mark sibling of the candle. Dense boxes are drawn as
+  per-pixel-column **aggregate boxes**: the whiskers widen to the column's reach
+  (`min(lower)`/`max(upper)`), the body to its IQR envelope
+  (`min(q1)`/`max(q3)`), the centre line to the first box's median. Gates on the
+  **visible** box count (a deep zoom still draws full-width boxes); the
+  `hasBox`/`hasMedian` flags carry through, so a range-only box stays range-only.
+  Interaction is unaffected — hit-testing reads the source boxes (§2.3). Pass
+  `decimate={false}` to draw every box at its own slot.
+
+## [0.49.0] — 2026-07-21
+
+### Added
+
+- **charts:** **Annotation theme roles** (#508 item 3, Tidal vol-surface
+  friction). `theme.annotation` gains an optional **`roles`** map (role name →
+  `{ color, fillOpacity? }`), and `<Baseline>` / `<Marker>` / `<Region>` gain a
+  **`role`** prop that recolours that mark from `roles[role]` while keeping the
+  shared depth ramp — so a smile can place a green ATM baseline, a distinct
+  reference marker, and an amber zone at once without the whole register
+  shifting together. Resolves `roles[role] ?? annotation` (an unknown/unset
+  role is the base register). **Colour stays a theme concern** — there is no
+  per-mark colour prop (the one-styling-channel discipline; consistent with the
+  per-box red/green reject). `cssVarTheme` carries the `roles` map through
+  unchanged (deep-merged). `theme.annotation.roles` is optional, so existing
+  themes are unaffected.
+- **charts:** **`<BoxPlot id>` — box selection** (#508 item 5, Tidal
+  vol-surface friction). A `BoxPlot` with an `id` is now clickable on the same
+  id-gated contract `<BarChart>` / `<ScatterChart>` carry
+  (`selected`/`onSelect`, `hovered`/`onHover`): a click anywhere on a box —
+  body or whisker, a range-only bid→ask segment included — selects it via
+  rect-containment (`boxAt`, the interval-mark analog of `barAt`, **not** the
+  continuous nearest-point threshold), and the selected box outlines (hovered
+  fainter, reusing `theme.box.stroke`, no new token). `key` is the box's `x`
+  (its span begin). Without an `id` the box stays display-only. Independent of
+  the box's `cursorFlag` cursor opt-out — selection rides the separate
+  `hitTest` path.
+- **charts:** **`<YAxis tickCount>` + height-derived tick density** (#508
+  item 4, Tidal vol-surface friction). The y axis's auto-tick count now
+  follows the **row height** by default — a short strip (e.g. a 72px
+  histogram lane) gets fewer ticks than a tall row instead of crushing the
+  same ~5 labels into the space (mirrors the width-derived trading-time x
+  axis). A new **`tickCount`** prop pins an explicit target; explicit
+  `ticks` still overrides both. The count is resolved once per axis on the
+  row (`resolveYTickCount`) and shared by the axis labels, the cursor-readout
+  formatter, and the row gridlines, so a label / its gridline / its readout
+  stay on the same `ticks(count)` (replaces three hardcoded `5`s that agreed
+  by convention).
+
+- **charts:** **`<Legend>` — the series key** (#508 item 2, Tidal vol-surface
+  friction; design per the sender's sketch on the issue). Every draw layer now
+  registers its readout identity (`as ?? column`) plus its **resolved** style
+  as a `SwatchSpec` (line stroke+dash, area fill+line, band envelope, scatter
+  dot, box whisker, bar fill, candle up/down pair), and `<Legend />` renders
+  the registry as a small card anchored to a corner of the rows block
+  (`placement`, default `top-right`) — so the key can never drift from the
+  plot. Rows follow chart-row → declaration order; identities collapse
+  (`id ?? label`, as the tracker readout merges keys); a **stacked bar
+  registers one row per group** with its resolved fill. Per-layer control via
+  a new `legend` prop on all seven marks: `false` opts out, a string renames.
+  Interactions are **id-gated** (the shipped selection contract): rows whose
+  layer has an `id` echo hover into the container and toggle selection on
+  click; `onRowHover` / `onRowClick` take over when provided; series
+  show/hide deliberately stays consumer-side. **Scope follows placement:** at
+  the container level the card lists every row; placed inside a `<Layers>` it
+  scopes to that `<ChartRow>` and anchors to that row's plot (a per-row legend
+  needs no prop). `<Legend items={…}>` renders explicit rows — inside a
+  container or standalone (a dashboard-side key).
+  New optional `theme.legend` slot (background/border/text; derives from
+  `chip`/`axis` tokens when absent, so hand-built themes keep compiling).
+  **Headless variant:** `useChartLegend()` serves the entries as data —
+  `rows` (**items grouped by chart row**; each item is
+  `label` + resolved swatch + `id` + live `selected`/`hovered`; a flat list
+  is `rows.flatMap((r) => r.items)`) plus chart-synced `hover`/`select`
+  verbs, the container's axis `gutters` (for aligning a custom layout to the
+  plot), and **`cursorTime`** (the cursor's axis instant, `null` when idle) —
+  the seams for a legend that is a design of its own: horizontal chip rows,
+  ticker-compare with the secondary dimmed, and **current-or-cursor values**
+  per item (`series.nearest(cursorTime)`, else the latest sample; item
+  labels also match the tracker's sample labels, so an `onTrackerChanged`
+  merge is a label-keyed join); `<Legend>` itself renders through the same
+  core, so the two can't disagree. **Scope follows placement** for both the
+  card and the hook: inside a `<Layers>` they scope to that `<ChartRow>` and
+  the card anchors to that row's plot; container-level stays all-rows. Card
+  polish per the first design pass: plot-area-inset placement, selection
+  reads by contrast (the selected item bold, others dulled — the
+  ticker-compare treatment), a dashed line's swatch hand-renders as a
+  canonical three-dash glyph, and a bar's swatch is a centred rounded square.
+  New exports: `Legend`, `LegendProps`, `LegendPlacement`, `SwatchSpec`,
+  `LegendItemInput`, `useChartLegend`, `ChartLegend`, `LegendRow`,
+  `LegendItem`.
+- **charts:** **`cursorFormat` reaches value axes** (#508 item 1, Tidal
+  vol-surface friction) — the container's readout channel now applies on a
+  value x axis exactly as on a time axis: a **string** is a d3 _number_
+  specifier there, a **function** receives
+  `(value, { grain: undefined, defaultText })` (no time grain to hand over;
+  `defaultText` is the axis-default text). The readout also gains its
+  documented precedence on the axis strip on **every** axis kind:
+  `cursorFormat → axis format → container`, so an explicit `<XAxis format>`
+  keeps ticks terse while `cursorFormat` makes the cursor pill / marker
+  indicators / annotation auto-labels precise (`+2.0σ` ticks, `+1.83σ` pill).
+  A `transform`ed axis is exempt (its pill speaks the derived unit); a
+  category axis reads names and ignores `cursorFormat`. Type change:
+  `CursorFormat`'s function form widens `ctx.grain` from `TimeGrain` to
+  `TimeGrain | undefined`; the frame gains an optional `formatReadout`
+  channel (see Fixed below for the `formatTime` clarification).
+- **charts:** **M4 line decimation** (charts decimator wave, Phase 3) — the
+  `<LineChart>` now draws from the per-device-pixel-column min/max/first/last
+  (pond's `binBy(…, 'minMaxFirstLast')`) once the visible data exceeds ~2 samples
+  per pixel, so a **fully-visible** dense series (which viewport culling can't
+  help) draws from O(plot width) points instead of every sample: a 1M-point line
+  drops from ~34 ms/frame to ~3.4 ms, under the 60 fps budget. It is **visually
+  lossless** (an e2e pixel-diff bounds the decimated-vs-full difference to a thin
+  sub-pixel AA seam) and **preserves single-sample anomalies** (the min/max
+  channel keeps the spike M4 is chosen over LTTB to keep). Bucket edges are the
+  scale's pixel range inverted back to key space, so each bucket is one pixel
+  column on **any** scale, including a non-affine `TradingTimeScale`. Auto-on with
+  an opt-out / tuning prop
+  `decimate={false | { threshold }}` (new `DecimateOption` export). **All gap
+  modes** decimate: a §2.2 **gap-edge union** folds each ≥1-pixel interior gap's
+  boundaries into the bucket edges, so the gap reduces to its own empty (`NaN`)
+  bucket with exact pre/post-gap values — `'empty'` breaks precisely, `'none'`
+  bridges, and the `dashed`/`step`/`fade` connectors still draw across the gap.
+  **`sessionBreaks` decimate too** — the same union folds each trading-axis
+  session-break instant into the bucket edges so no bucket merges two sessions'
+  extremes across the discontinuity, and `sessionRuns` then splits the decimated
+  series into clean per-session subpaths (a dense intraday line on a trading-time
+  axis decimates _and_ breaks at each session open). Still gated off only a
+  non-linear `curve` (documented backlog). Interaction reads the source series
+  (§2.3), so readouts/selection are unaffected.
+- **charts:** M4 decimation extended to **`<AreaChart>` and `<BandChart>`** (same
+  auto-on `decimate={false | { threshold }}` prop). An **area** reuses the line M4
+  on its outline (gap-edge union included) with the fill following under the
+  full-series gradient — so a dense filled area shrinks its fill + outline work to
+  O(plot width). A **band** decimates to the per-pixel-column **min(`lower`) /
+  max(`upper`)** — the widest envelope the samples span, so it can never invert
+  (§2.5) and covers the same pixels; the win is the canvas fill (≈W vertices vs
+  every sample). Both gated off a non-linear `curve`; interaction unaffected.
+- **charts:** **Viewport culling** (charts decimator wave, Phase 2). Line, area,
+  and band layers now clip to the **visible slice** of their key column — plus
+  one entry/exit point each side so the segment crossing each plot edge still
+  draws — before any path work, so a pan/zoom repaint costs O(visible) instead
+  of O(N). On a large series zoomed in, the per-frame `drawLine` path-generation
+  cost drops from ~29 ms at 1M points (over the 16.67 ms/60 fps budget — the
+  cause of the #256 pan-FPS collapse) to ~0.06 ms; a fully-visible series is
+  unchanged (culling no-ops, keeping that draw byte-identical — the baseline the
+  Phase 3 M4 decimator addresses). Interaction is unaffected: `sampleAt` /
+  `hitTest` read the full source series, so a hover readout or selection never
+  shifts when the window resizes (the decimator RFC §2.3 invariant). Culling is
+  automatic and internal — no API change.
+- **charts:** Viewport culling extended to the **per-mark** layers — scatter,
+  bars, candles, and boxes. These loop over independent marks with index-keyed
+  accessors (a scatter's `colorAt(i)`, a bar's `begin[i]` selection match), so
+  rather than a subarray view they cull by **restricting the draw loop to the
+  visible index range** (the original `i` is preserved, so every accessor and
+  selection/hover match stays correct). Point marks (scatter) use the same
+  entry/exit window as lines; interval marks (bars / candles / boxes) use a
+  span-overlap window that keeps a wide mark crossing a plot edge. Same
+  automatic, internal, interaction-safe behaviour — a 500k-bar chart zoomed in
+  drops from ~23 ms/frame to ~0.16 ms.
+- **charts:** Scatter culling is now **radius-aware**. The per-mark index margin
+  above measures neighbours in sample count, but a scatter mark's disc has a
+  pixel radius independent of sample spacing — so a dense scatter of fat marks
+  could drop an edge bubble whose _centre_ sits several samples off-screen while
+  its _disc_ still overlaps the plot edge (a subtle flicker under pan). The
+  scatter draw now widens the visible window by its max drawn radius (converted
+  px→data through the scale, plus any `offsetPx` nudge) before culling, so every
+  mark that can paint into the plot is kept. Small-radius scatters are unaffected
+  (they re-expand by a few pixels — usually the same window). Interval marks
+  (bars / candles / boxes) don't need this — their width _is_ their x-span.
+
+### Changed
+
+- **charts:** **Tracker labels key on `as` across the multi-value marks**
+  (F-charts-8 §3, the `<Legend>` label-source prerequisite). With a semantic
+  `as`, a `<BandChart>`'s edge samples now read `"<as> lower"` / `"<as>
+upper"` and a `<Candlestick showOHLC>`'s quote pills read `"<as> high"` /
+  `"<as> open"` / … — the series-name + role convention `<BoxPlot>` already
+  shipped (`iv upper`) — so readout/legend merge keys are the series
+  identity, not raw column names or bare role words. Without an `as`,
+  labels are unchanged (column names / role words). Consumers keying
+  `onTrackerChanged` readouts on the old labels while setting `as` should
+  key on the new `"<as> <role>"` form.
+
+### Fixed
+
+- **charts:** **`cursorFormat` no longer leaks into tick labels** — setting
+  `timeFormat` _and_ `cursorFormat` together on a time axis rendered the
+  **tick labels** with `cursorFormat` (the ladder was disqualified by
+  `timeFormat`, and the tick fallback read the merged readout formatter).
+  The frame now carries two channels: `formatTime` is the label channel
+  (`timeFormat`-shaped, never `cursorFormat` — restoring its documented
+  meaning), and the new optional `formatReadout` carries `cursorFormat` to
+  the readout consumers (crosshair pill + in-plot cursor time, marker
+  indicators, annotation auto-labels). Frame consumers that read
+  `ContainerFrame.formatTime` for a readout should use
+  `formatReadout ?? formatTime`.
+- **charts:** **Region drag-select no longer races the pointer stream**
+  (#508 item 7) — the drag anchor was container **state** read back through
+  the rendered frame at `pointerup`, so a batched/untrusted pointer stream
+  (automation, jsdom — plausibly a very fast flick under load) could deliver
+  `down→up` before the anchor committed: the select was **silently dropped**
+  and the late-committing anchor **leaked**, leaving the band stuck.
+  Human-paced trusted input hid this (React flushes trusted discrete events
+  synchronously). Gesture logic now reads a ref (the same ref+state
+  discipline the annotation-create drag already used); the state stays
+  paint-only. Deterministic regression tests cover both pacings.
+
 ## [0.48.1] — 2026-07-19
 
 ### Fixed

package/dist/AreaChart.d.ts

@@ -1,5 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
 export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
@@ -65,6 +66,22 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `'dashed'` / `'step'` connector faintness is the theme's `gap.connectorOpacity`.)
      */
     gaps?: GapMode;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible data is denser than ~2 samples per device pixel, the fill +
+     * outline are drawn from the per-pixel-column M4 buckets (a visually-lossless
+     * polyline of O(plot width) points) instead of every sample. Applies with a
+     * linear `curve`; pass `false` to always draw every point, or `{ threshold }`
+     * to tune the samples-per-pixel factor. Shares {@link LineChart}'s
+     * `DecimateOption`.
+     */
+    decimate?: DecimateOption;
+    /**
+     * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
+     * row's display name. **Omitted ⇒ a row named by the layer's readout
+     * identity** (`as` ?? `column`). The swatch is the resolved area style.
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -91,5 +108,5 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -5,6 +5,7 @@ import { areaExtent, drawArea } from './area.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext } from './context.js';
+import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
  *  `(value) => pixel` function the row hands to `draw`. The runtime object is a
@@ -35,7 +36,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, index = 0, }) {
+export function AreaChart({ series, column, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -96,7 +97,7 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
             // Omitted baseline rests on the axis floor (resolved late from the
             // scale, so it tracks the auto-fit domain); a fixed baseline is used
             // verbatim.
-            baseline ?? domainFloor(yScale), curveFactory, gaps, gapConnectorOpacity),
+            baseline ?? domainFloor(yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
         },
         axisId: axis,
         index,
@@ -110,6 +111,7 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
         curveFactory,
         gaps,
         gapConnectorOpacity,
+        decimate,
         axis,
         index,
     ]);
@@ -127,6 +129,25 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // And a legend row: the readout identity + the resolved area style (top line
+    // over the translucent fill), so a `<Legend>` swatch can never drift.
+    const legendRows = useMemo(() => {
+        const name = legendLabelFor(legend, label);
+        return name === null
+            ? null
+            : [
+                {
+                    label: name,
+                    swatch: {
+                        kind: 'area',
+                        line: style.color,
+                        fill: style.fill,
+                        fillOpacity: style.fillOpacity,
+                    },
+                },
+            ];
+    }, [legend, label, style]);
+    useLegendItems(container, slot, index, legendRows);
     return null;
 }
 //# sourceMappingURL=AreaChart.js.map

package/dist/BandChart.d.ts

@@ -1,6 +1,7 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type Curve } from './curve.js';
+import type { DecimateOption } from './decimate.js';
 export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The source series. A `TimeSeries` fills the envelope against the time axis;
@@ -23,7 +24,9 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * p5/p95 envelope, `inner` for p25/p75). The theme maps it to a
      * {@link BandStyle} (`theme.band[as] ?? theme.band.default`). **Omitted ⇒ the
      * `default` band style** — no per-component fill/opacity override (restyle via
-     * the theme, the single styling channel).
+     * the theme, the single styling channel). It's also the series identity for
+     * the tracker readout: with an `as`, the edge samples read `"<as> lower"` /
+     * `"<as> upper"` (else the raw column names).
      */
     as?: string;
     /**
@@ -39,6 +42,22 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * Denoise the underlying values with `smooth()`, not this.
      */
     curve?: Curve;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible envelope is denser than ~2 samples per device pixel, it is
+     * drawn from the per-pixel-column **min(lower) / max(upper)** — the widest band
+     * the samples span, so it covers the same pixels from O(plot width) points.
+     * Applies with a linear `curve`; pass `false` to always fill every sample, or
+     * `{ threshold }` to tune. Shares {@link LineChart}'s `DecimateOption`.
+     */
+    decimate?: DecimateOption;
+    /**
+     * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
+     * row's display name. **Omitted ⇒ a row named by the layer's readout
+     * identity** (`as`, else `"<lower>–<upper>"`). The swatch is the resolved
+     * band fill.
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -62,5 +81,5 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * </Layers>
  * ```
  */
-export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, index, }: BandChartProps<S, VS>): null;
+export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, decimate, legend, index, }: BandChartProps<S, VS>): null;
 //# sourceMappingURL=BandChart.d.ts.map

package/dist/BandChart.js

@@ -4,6 +4,7 @@ import { bandFromTimeSeries, bandFromValueSeries } from './data.js';
 import { bandExtent, drawBand } from './band.js';
 import { resolveCurve } from './curve.js';
 import { ContainerContext, LayersContext } from './context.js';
+import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
  * A variance-band draw layer: fills the envelope between the `lower` and `upper`
@@ -22,7 +23,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BandChart({ series, lower, upper, as: semantic, axis, curve, index = 0, }) {
+export function BandChart({ series, lower, upper, as: semantic, axis, curve, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BandChart> must be rendered inside a <ChartContainer>');
@@ -38,6 +39,14 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
     const { band } = container.theme;
     const style = (semantic !== undefined ? band[semantic] : undefined) ?? band.default;
     const curveFactory = resolveCurve(curve);
+    // Readout label per edge: with a semantic `as`, an edge reads under the series
+    // name + role (`iv lower`, `iv upper`) — the `as ?? column` convention Line /
+    // Scatter use and the exact shape BoxPlot's qLabel ships — so two bands (or a
+    // band and its centre line) merge readout keys by series, not by raw column
+    // names (F-charts-8 §3). With no `as`, the column name stands (self-evident).
+    const edgeLabel = useMemo(() => {
+        return (col, role) => semantic !== undefined ? `${semantic} ${role}` : col;
+    }, [semantic]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => bandExtent(bs),
@@ -62,8 +71,18 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
                     if (!Number.isFinite(lo) || !Number.isFinite(hi))
                         return [];
                     return [
-                        { x: bs.x[i], value: lo, color: style.fill, label: lower },
-                        { x: bs.x[i], value: hi, color: style.fill, label: upper },
+                        {
+                            x: bs.x[i],
+                            value: lo,
+                            color: style.fill,
+                            label: edgeLabel(lower, 'lower'),
+                        },
+                        {
+                            x: bs.x[i],
+                            value: hi,
+                            color: style.fill,
+                            label: edgeLabel(upper, 'upper'),
+                        },
                     ];
                 }
                 const e = series.nearest(x);
@@ -80,18 +99,40 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
                     !Number.isFinite(hi)) {
                     return [];
                 }
-                // Both edges, labelled by their column (e.g. p25 / p75), in the band's
-                // fill colour. A gap on either edge yields no readout (like the fill).
+                // Both edges, labelled by series + role under an `as` (else by their
+                // column, e.g. p25 / p75), in the band's fill colour. A gap on either
+                // edge yields no readout (like the fill).
                 return [
-                    { x: e.begin(), value: lo, color: style.fill, label: lower },
-                    { x: e.begin(), value: hi, color: style.fill, label: upper },
+                    {
+                        x: e.begin(),
+                        value: lo,
+                        color: style.fill,
+                        label: edgeLabel(lower, 'lower'),
+                    },
+                    {
+                        x: e.begin(),
+                        value: hi,
+                        color: style.fill,
+                        label: edgeLabel(upper, 'upper'),
+                    },
                 ];
             },
-            draw: (ctx, xScale, yScale) => drawBand(ctx, bs, xScale, yScale, style, curveFactory),
+            draw: (ctx, xScale, yScale) => drawBand(ctx, bs, xScale, yScale, style, curveFactory, decimate),
         },
         axisId: axis,
         index,
-    }), [bs, series, lower, upper, style, curveFactory, axis, index]);
+    }), [
+        bs,
+        series,
+        lower,
+        upper,
+        style,
+        curveFactory,
+        decimate,
+        axis,
+        index,
+        edgeLabel,
+    ]);
     // Stable per-instance slot (see useSlotKey): keeps this band's z-position +
     // identity across prop updates; the injected index drives the sort.
     const slot = useSlotKey();
@@ -106,6 +147,24 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // And a legend row: the series identity (`as`, else the edge columns as a
+    // span) + the resolved band fill, so a `<Legend>` swatch can never drift.
+    const legendRows = useMemo(() => {
+        const name = legendLabelFor(legend, semantic ?? `${lower}–${upper}`);
+        return name === null
+            ? null
+            : [
+                {
+                    label: name,
+                    swatch: {
+                        kind: 'band',
+                        fill: style.fill,
+                        opacity: style.opacity,
+                    },
+                },
+            ];
+    }, [legend, semantic, lower, upper, style]);
+    useLegendItems(container, slot, index, legendRows);
     return null;
 }
 //# sourceMappingURL=BandChart.js.map

package/dist/BarChart.d.ts

@@ -120,6 +120,17 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
+    /**
+     * This layer's `<Legend>` row(s): `false` ⇒ none (opt out), a string ⇒ the
+     * display name of a **one-row** layer. **Omitted ⇒** the single path (and a
+     * one-group stack) registers one row named by the layer identity
+     * (`as` ?? `column` ?? `id`); a **multi-group stack registers one row per
+     * group** (stack order, each group's resolved fill), where a rename string
+     * is ignored — group names come from the data. A per-bin-coloured histogram
+     * (`binColors`) is one series: its single row's swatch shows the group's
+     * base fill, not the per-bin palette.
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -169,5 +180,5 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, legend, index, }: BarChartProps<S, VS>): null;
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -3,6 +3,7 @@ import { Interval, ValueSeries } from 'pond-ts';
 import { barsFromTimeSeries, barsFromValueSeries, categoryStack, 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 { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
  * A bar / histogram draw layer. In its simplest form, one rectangle per event
@@ -47,7 +48,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -364,6 +365,38 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         registerSelectable(slot);
         return () => unregisterSelectable(slot);
     }, [registerSelectable, unregisterSelectable, slot, id]);
+    // Legend rows: a genuinely multi-group layer (a stack) registers **one row
+    // per group** in stack order, each with the same per-group fill resolution
+    // the canvas draws with; everything else — the single path, a one-group
+    // stack (horizontal single, categorical) — registers one row under the
+    // layer's identity. A `legend` string renames only a one-row layer (a
+    // multi-group layer has no single name to give); `legend={false}` opts all
+    // out. The layer's `id` rides every row (selection identity is the layer).
+    const legendRows = useMemo(() => {
+        if (legend === false)
+            return null;
+        if (groups !== undefined && groups.length > 1) {
+            return groups.map((g, i) => ({
+                label: g,
+                id,
+                swatch: { kind: 'bar', fill: stackStyle.fills[i] },
+            }));
+        }
+        const name = legendLabelFor(legend, label);
+        return name === null
+            ? null
+            : [
+                {
+                    label: name,
+                    id,
+                    swatch: {
+                        kind: 'bar',
+                        fill: groups !== undefined ? stackStyle.fills[0] : singleStyle.fill,
+                    },
+                },
+            ];
+    }, [legend, groups, stackStyle, label, id, singleStyle]);
+    useLegendItems(container, slot, index, legendRows);
     return null;
 }
 //# sourceMappingURL=BarChart.js.map

package/dist/BoxPlot.d.ts

@@ -1,6 +1,7 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type BoxShape } from './box.js';
+import type { DecimateOption } from './decimate.js';
 export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The source series. A `TimeSeries` plots against the time axis; a `ValueSeries`
@@ -88,6 +89,33 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
      * `'whisker'` shape (`'solid'`/`'none'` have no caps).
      */
     capWidth?: number;
+    /**
+     * Stable series identity — **gates selection + hover**, the same id-gated
+     * contract `<BarChart>` / `<ScatterChart>` carry. With an `id`, a click on a
+     * box (body or whisker — a range-only bid→ask segment included) selects it
+     * (`selected`/`onSelect`) and pointer-over lights it (`hovered`/`onHover`);
+     * the box matching the selection's `(id, key)` outlines. **Omitted ⇒
+     * display-only** (a click resolves to empty space). `key` is the box's `x`
+     * (its `begin`).
+     */
+    id?: string;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible boxes are denser than ~2 per device pixel, they are drawn as
+     * per-pixel-column **aggregate boxes** — whiskers widen to the column's reach
+     * (`min(lower)`/`max(upper)`), the body to its IQR envelope
+     * (`min(q1)`/`max(q3)`), the centre line to the first box's median. Pass `false`
+     * to draw every box at its own slot. Interaction is unaffected (hit-testing
+     * reads the source boxes). Shares {@link LineChart}'s `DecimateOption`.
+     */
+    decimate?: DecimateOption;
+    /**
+     * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
+     * row's display name. **Omitted ⇒ a row named by the layer's readout
+     * identity** (`as`, else `"<lower>–<upper>"`). The swatch is the resolved
+     * whisker style.
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -125,5 +153,5 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
  * </Layers>
  * ```
  */
-export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, index, }: BoxPlotProps<S, VS>): null;
+export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, id, decimate, legend, index, }: BoxPlotProps<S, VS>): null;
 //# sourceMappingURL=BoxPlot.d.ts.map