@pond-ts/charts 0.31.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# pond-ts
+
+**Highly optimised, fully typed Timeseries library for TypeScript**
+
+Schema-driven events, composable batch transforms, push-based streaming
+ingest, multi-entity partitioning, and an optional React integration —
+all strict TypeScript end to end, all immutable.
+
+**pond-ts** is the TypeScript-first successor to
+[pondjs](https://github.com/esnet/pond), rewritten from scratch with a
+focus on type safety, composability, and the live-streaming patterns
+that pondjs never grew.
+
+```sh
+npm install pond-ts                 # core
+npm install @pond-ts/react          # React hooks (optional)
+```
+
+- **Typed schemas** — declare once, every transform downstream narrows
+  off it. `event.get('cpu')` returns `number | undefined` straight from
+  the schema; no `as` casts.
+- **Batch + streaming with the same vocabulary** — `filter`, `map`,
+  `aggregate`, `rolling`, `diff`, `rate`, `fill`, `cumulative`,
+  `sample`, `reduce` all exist on both `TimeSeries` and `LiveSeries`.
+- **Multi-entity by construction** — `partitionBy('host')` routes per
+  entity; `rolling` / `aggregate` / `fill` / `sample` over a partitioned
+  view all become per-entity automatically.
+- **Bounded-memory streaming** — retention policies, eviction-aware
+  views, and sampling decouple downstream window length
+  from event rate at firehose loads (up to 500k events/sec on a
+  single node.js instance.)
+- **Triggers** — for control of rolling emission cadences. Synchronised
+  partitioned rolling fires across partitions on every boundary.
+- **Typed column extraction** — `series.column('cpu')` returns a
+  schema-narrowed typed column with single-pass reductions
+  (`min`/`max`/`sum`/`mean`/`stdev`/`median`/`percentile`/`minMax`),
+  index downsampling (`bin`), and a zero-copy `toFloat64Array()` for
+  canvas / WebGL draw loops — no per-event allocation on the hot path.
+- **No legacy baggage**
+
+## Quick start: batch
+
+```ts
+import { Sequence, TimeSeries } from 'pond-ts';
+
+const schema = [
+  { name: 'time', kind: 'time' },
+  { name: 'cpu', kind: 'number' },
+  { name: 'requests', kind: 'number' },
+  { name: 'host', kind: 'string' },
+] as const;
+
+const cpu = TimeSeries.fromJSON({
+  name: 'cpu',
+  schema,
+  rows: [
+    ['2025-01-01T00:00:00Z', 0.31, 120, 'host1'],
+    ['2025-01-01T00:01:00Z', 0.44, 135, 'host2'],
+    ['2025-01-01T00:02:00Z', 0.52, 141, 'host1'],
+    ['2025-01-01T00:03:00Z', 0.48, 128, 'host1'],
+    ['2025-01-01T00:04:00Z', 0.63, 166, 'host3'],
+  ],
+});
+
+const byMinute = cpu.aggregate(Sequence.every('1m'), {
+  cpu: 'avg',
+  requests: 'sum',
+  host: 'last',
+});
+
+const bands = cpu.baseline('cpu', { window: '2m', sigma: 2 });
+//    ^ appends rolling avg / sd / upper / lower in one pass.
+
+const anomalies = cpu.outliers('cpu', { window: '2m', sigma: 2 });
+//    ^ schema-preserving filter — same columns, just the spikes.
+```
+
+The full batch surface (`align`, `rolling`, `smooth`, `groupBy`, `join`,
+`reduce`, `diff`, `rate`, `fill`, `dedupe`, `materialize`, `sample`,
+`partitionBy`, `pivotByGroup`, …) follows the same shape: TimeSeries
+in, TimeSeries out, schema preserved.
+
+## Quick start: live (streaming)
+
+```ts
+import { LiveSeries, Sequence } from 'pond-ts';
+
+// 1. Same schema; this is a live append buffer with retention.
+const live = new LiveSeries({
+  name: 'cpu',
+  schema,
+  retention: { maxAge: '10m' }, // keep only the last 10 minutes
+});
+
+// 2. Push as events arrive. Each push is validated against the schema.
+live.push([Date.now(), 0.45, 128, 'api-1']);
+
+// 3. Compose live views — incremental, push-driven, eviction-aware.
+const recentAvg = live.rolling('5m', { cpu: 'avg' });
+recentAvg.on('event', (e) => render(e.get('cpu')));
+
+// 4. Snapshot to a TimeSeries for batch analytics at any time.
+const snap = live.toTimeSeries();
+```
+
+The full live surface (`filter`, `map`, `select`, `window`, `aggregate`,
+`rolling`, `reduce`, `diff`, `rate`, `pctChange`, `fill`, `cumulative`,
+`sample`) is incremental — events flow, views emit, retention bounds
+memory.
+
+## Quick start: multi-entity
+
+`partitionBy` routes events into per-key buffers. Every stateful
+operator downstream of `partitionBy` runs per-partition automatically:
+
+```ts
+const perHost = cpu
+  .partitionBy('host')
+  .rolling('5m', { cpu: 'avg', cpu_sd: 'stdev' });
+
+// .collect() fans the per-partition outputs back into a flat TimeSeries
+// with the partition key auto-injected as a column.
+const flat = perHost.collect();
+```
+
+Same shape on the live side — `live.partitionBy('host')` returns a
+`LivePartitionedSeries` whose `rolling` / `fill` / `diff` / `sample`
+methods all maintain per-partition state.
+
+## Quick start: bounded-memory sampling
+
+At firehose rates, a long rolling baseline blows the heap. `sample({
+stride: N })` decouples baseline length from event rate; chain it
+between `partitionBy` and `rolling`:
+
+```ts
+// Per-host 1-in-10 stride feeding a per-host 5m baseline.
+live
+  .partitionBy('host')
+  .sample({ stride: 10 })
+  .rolling('5m', { cpu_avg: 'avg', cpu_sd: 'stdev' });
+```
+
+For visualization, the snapshot side ships reservoir sampling too —
+single-pass Algorithm R, sorted by key, fixed point count regardless of
+source size:
+
+```ts
+const points = series.sample({ reservoir: { size: 500 } }).toRows();
+// 500 uncorrelated points drawn uniformly from the source.
+```
+
+## Performance
+
+pond-ts is faster on **every** comparable operation, with no regressions —
+a **~17x** geometric-mean speedup across the measurable ops, plus a handful
+of transforms (`select` / `rename`) that are **effectively instant** (O(1)
+column rebinds, below the timer's resolution). The advantage grows with data
+size.
+
+| Category          | Speedup (N=16k)                                      | Notes                                         |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------- |
+| **Rate**          | ~120x                                                | Single columnar walk vs Pipeline              |
+| **Fill**          | 77–87x                                               | Single columnar pass vs Pipeline per strategy |
+| **Aggregation**   | 57–82x                                               | O(N+B) bucketing vs O(N×B) Pipeline           |
+| **Statistics**    | 18–80x                                               | Typed-array reduce vs ImmutableJS iteration   |
+| **Alignment**     | 42x                                                  | Forward cursor vs repeated binary search      |
+| **Construction**  | 13x                                                  | Columnar intake vs ImmutableJS wrapping       |
+| **Chained**       | 8x                                                   | Derived constructors vs per-step Pipeline     |
+| **Transforms**    | `select`/`rename` instant; `collapse` 30x; `map` ~4x | Column reshapes vs Pipeline                   |
+| **Event access**  | 6x                                                   | Array indexing vs ImmutableJS `get()`         |
+| **Serialization** | 4x                                                   | Lightweight columnar representation           |
+
+See the [full benchmark results](website/docs/reference/benchmarks.mdx)
+for detailed numbers. Run locally:
+
+```sh
+npm run build && node packages/core/bench/vs-pondjs.cjs
+```
+
+## Documentation
+
+The full guide is at **<https://pjm17971.github.io/pond-ts/>**.
+
+- **[Start here](https://pjm17971.github.io/pond-ts/docs/)**
+  — five-minute walkthrough with batch, live, and React examples.
+- **[Concepts](https://pjm17971.github.io/pond-ts/docs/start-here/concepts)**
+  — temporal keys, sequences, windowing, partitioning, triggers, late
+  data.
+- **[Transforms reference](https://pjm17971.github.io/pond-ts/docs/pond-ts/transforms/queries)**
+  — every batch operator (queries, aggregation, alignment, rolling,
+  smoothing, sampling, cleaning, reshape, anomaly detection).
+- **[Live reference](https://pjm17971.github.io/pond-ts/docs/pond-ts/live/live-series)**
+  — `LiveSeries`, live transforms, triggering.
+- **[How-to guides](https://pjm17971.github.io/pond-ts/docs/how-to-guides)**
+  — building a dashboard, ingesting messy data.
+- **[API reference (auto-generated)](https://pjm17971.github.io/pond-ts/generated-api/core/)**
+  — TypeDoc output, every public class and method.
+- **[CHANGELOG](./CHANGELOG.md)** — what shipped in each release.
+
+## Examples
+
+- **[pond-ts-dashboard](https://github.com/pjm17971/pond-ts-dashboard)**
+  — a working React dashboard that streams synthetic per-host CPU /
+  request metrics, computes per-host rolling baselines, flags anomalies
+  against ±σ bands, and renders everything as live line and bar charts
+  (~600 lines of TypeScript). Walked through end-to-end in
+  [Building a dashboard](website/docs/how-to-guides/dashboard-guide.mdx).
+
+## Develop
+
+The repo is an npm-workspaces monorepo with two published packages
+(`pond-ts`, `@pond-ts/react`). Node 18+ for runtime; Node 20+ for the
+docs site (Docusaurus).
+
+```sh
+npm install         # one-time, hoists deps for both packages
+npm run build       # build both packages
+npm test            # runtime + type-level tests on both packages
+npm run format      # prettier write across the repo
+npm run verify      # format check + build + test (CI parity)
+```
+
+`packages/core/` is the `pond-ts` package; `packages/react/` is
+`@pond-ts/react`. Docs live in `website/`.
+
+## License
+
+MIT

package/dist/AreaChart.d.ts

@@ -0,0 +1,85 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type Curve } from './curve.js';
+import { type GapMode } from './gaps.js';
+export interface AreaChartProps<S extends SeriesSchema> {
+    /** The source series. Its key column supplies the time axis. */
+    series: TimeSeries<S>;
+    /** Name of the numeric value column to fill from. */
+    column: string;
+    /**
+     * The series' semantic identifier — what the data _is_ / how it should read
+     * (e.g. `elevation`, or a signed-traffic role like `in` / `out`). The theme
+     * maps it to an {@link AreaStyle} (`theme.area[as] ?? theme.area.default`) —
+     * outline colour/width + the graded fill. **Omitted ⇒ the `default` style**;
+     * there's no per-component colour/style override (restyle via the theme, the
+     * single styling channel).
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this area scales against — picks the *scale*,
+     * where `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * The value the fill rests on — the flat edge opposite the value line. Two
+     * forms:
+     *
+     * - **Omitted ⇒ the axis's lower bound** (the bottom of the plot): the
+     *   elevation form — fill from the line down to the floor, shade grading down.
+     * - **A number (e.g. `0`) ⇒ a fixed baseline**: the above/below-axis form —
+     *   values above it fill up, below it fill down, each side's shade fading
+     *   toward the baseline. For the esnet two-colour traffic look, compose two
+     *   `<AreaChart>`s (an "in" column and an "out" column, distinct `as` roles).
+     *
+     * A fixed baseline is pulled into the auto-fit domain so the baseline line is
+     * always visible (an above/below area with `baseline={0}` shows the zero
+     * axis).
+     */
+    baseline?: number;
+    /**
+     * Render-time path interpolation for the outline + fill edge — a view concern
+     * (denoise the data with pond's `smooth()` upstream). **Omitted ⇒ `'linear'`**
+     * (straight segments). `'monotone'` is a smooth edge that still passes through
+     * points.
+     */
+    curve?: Curve;
+    /**
+     * How a **gap** (a coast / dropout — a run of NaN in `column`) is rendered (a
+     * {@link GapMode}). **Omitted ⇒ `'empty'`**: the fill *and* outline break at
+     * the gap, leaving a hole (the honest default). `'none'` fills + bridges
+     * straight across. For `'dashed'` / `'step'` / `'fade'` the **fill stays
+     * broken** and only the **outline** gets the inferred connector across the gap
+     * — a faint dashed straight bridge, a faint flat dashed line at the average of
+     * the edge values, or estela's fade-to-baseline (which drops to this area's own
+     * `baseline`, the fill floor). Shared with `<LineChart>` — one concept. (The
+     * `'dashed'` / `'step'` connector faintness is the theme's `gap.connectorOpacity`.)
+     */
+    gaps?: GapMode;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * An area draw layer: fills between a value `column` and a `baseline`, with a
+ * graded (gradient) shade — opaque at the line, transparent at the baseline —
+ * and an outline stroke on top. Reads `column` into a {@link ChartSeries}
+ * (columnar, gaps as NaN), registers into the enclosing {@link Layers} (scaling
+ * against its `axis`), and renders nothing to the DOM — the row draws it. The
+ * fill + outline break at gaps rather than spanning them.
+ *
+ * Two forms via `baseline` (see {@link AreaChartProps.baseline}): omit it for
+ * the **elevation** form (rest on the axis floor) or pass `0` for the
+ * **above/below-axis** form (positive up, negative down). The esnet two-colour
+ * traffic look composes two layers, each with its own `as` role:
+ *
+ * ```tsx
+ * <Layers>
+ *   <AreaChart series={s} column="in"  baseline={0} as="in" />
+ *   <AreaChart series={s} column="out" baseline={0} as="out" />
+ * </Layers>
+ * ```
+ */
+export declare function AreaChart<S extends SeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, index, }: AreaChartProps<S>): null;
+//# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -0,0 +1,119 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { fromTimeSeries } from './data.js';
+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 { 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
+ *  d3 `ScaleLinear` (it carries `.domain()`); the {@link RowLayer} type narrows
+ *  it to the call signature, so this reads the bound through a localized,
+ *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
+function domainFloor(yScale) {
+    const d = yScale.domain?.();
+    return d && d.length > 0 ? d[0] : 0;
+}
+/**
+ * An area draw layer: fills between a value `column` and a `baseline`, with a
+ * graded (gradient) shade — opaque at the line, transparent at the baseline —
+ * and an outline stroke on top. Reads `column` into a {@link ChartSeries}
+ * (columnar, gaps as NaN), registers into the enclosing {@link Layers} (scaling
+ * against its `axis`), and renders nothing to the DOM — the row draws it. The
+ * fill + outline break at gaps rather than spanning them.
+ *
+ * Two forms via `baseline` (see {@link AreaChartProps.baseline}): omit it for
+ * the **elevation** form (rest on the axis floor) or pass `0` for the
+ * **above/below-axis** form (positive up, negative down). The esnet two-colour
+ * traffic look composes two layers, each with its own `as` role:
+ *
+ * ```tsx
+ * <Layers>
+ *   <AreaChart series={s} column="in"  baseline={0} as="in" />
+ *   <AreaChart series={s} column="out" baseline={0} as="out" />
+ * </Layers>
+ * ```
+ */
+export function AreaChart({ series, column, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<AreaChart> must be rendered inside a <Layers>');
+    }
+    const cs = useMemo(() => fromTimeSeries(series, column), [series, column]);
+    // Styling: semantic identifier → theme area style. The single styling channel.
+    const { area } = container.theme;
+    const style = (semantic !== undefined ? area[semantic] : undefined) ?? area.default;
+    // Series identity for the readout (the `as` role, else the column name).
+    const label = semantic ?? column;
+    const curveFactory = resolveCurve(curve);
+    // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
+    // falling back to the shared default so a theme without it still renders faint.
+    const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => areaExtent(cs, baseline),
+            xKind: 'time',
+            xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
+            sampleAt: (time) => {
+                // No readout past the data (tracker policy — core's nearest() clamps
+                // to an endpoint outside the span); bounds from the columnar time axis.
+                if (cs.length === 0 ||
+                    time < cs.x[0] ||
+                    time > cs.x[cs.length - 1]) {
+                    return [];
+                }
+                const e = series.nearest(time);
+                if (e === undefined)
+                    return [];
+                // get() wants a literal key; column is a runtime string. Cast the
+                // *event* (not the method — that would detach `this`) to a
+                // string-keyed get; runtime-safe read + guard.
+                const v = e.get(column);
+                // The readout dot rides the value line (not the baseline), coloured by
+                // the outline stroke. A gap yields no readout (like the fill).
+                return typeof v === 'number' && Number.isFinite(v)
+                    ? [{ x: e.begin(), value: v, color: style.color, label }]
+                    : [];
+            },
+            draw: (ctx, xScale, yScale) => drawArea(ctx, cs, xScale, yScale, style, 
+            // 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),
+        },
+        axisId: axis,
+        index,
+    }), [
+        cs,
+        series,
+        column,
+        style,
+        label,
+        baseline,
+        curveFactory,
+        gaps,
+        gapConnectorOpacity,
+        axis,
+        index,
+    ]);
+    // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
+    // fixed across series/style/prop updates (no jump to the front on live update).
+    const slot = useSlotKey();
+    useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
+    useEffect(() => {
+        layers.registerLayer(slot, entry);
+    }, [layers, slot, entry]);
+    // Also a tracker source: the container fans in this series' value at the
+    // cursor for the (outside-the-chart) readout.
+    const { registerTrackerSource, unregisterTrackerSource } = container;
+    useEffect(() => () => unregisterTrackerSource(slot), [unregisterTrackerSource, slot]);
+    useEffect(() => {
+        registerTrackerSource(slot, entry.layer);
+    }, [registerTrackerSource, slot, entry.layer]);
+    return null;
+}
+//# sourceMappingURL=AreaChart.js.map

package/dist/BandChart.d.ts

@@ -0,0 +1,55 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type Curve } from './curve.js';
+export interface BandChartProps<S extends SeriesSchema> {
+    /** The source series. Its key column supplies the time axis. */
+    series: TimeSeries<S>;
+    /** Name of the numeric column for the band's lower edge (e.g. `p25`). */
+    lower: string;
+    /** Name of the numeric column for the band's upper edge (e.g. `p75`). */
+    upper: string;
+    /**
+     * The band's semantic identifier — what the spread _is_ (e.g. `outer` for a
+     * 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).
+     */
+    as?: string;
+    /**
+     * Which `<YAxis>` (by its `id`) this band scales against — the *scale*, where
+     * `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * Render-time edge interpolation — both edges drawn with this curve. **Omitted
+     * ⇒ `'linear'`.** Prefer a **symmetric** curve (`'natural'`/`'basis'`) to
+     * smooth a sparse aggregated envelope (RTC's `interpolation`) — `'monotone'`
+     * assumes increasing x and smooths the right→left lower edge asymmetrically.
+     * Denoise the underlying values with `smooth()`, not this.
+     */
+    curve?: Curve;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A variance-band draw layer: fills the envelope between the `lower` and `upper`
+ * columns of `series` (typically `rollingByColumn` percentiles), gap-aware, and
+ * registers itself into the enclosing {@link Layers}. Renders nothing to the
+ * DOM — the row draws it.
+ *
+ * Compose two for a two-tone spread — author the wider band first so it sits
+ * behind (declaration order = z-order, back-to-front), then the line on top:
+ *
+ * ```tsx
+ * <Layers>
+ *   <BandChart series={s} lower="p5"  upper="p95" as="outer" />
+ *   <BandChart series={s} lower="p25" upper="p75" as="inner" />
+ *   <LineChart series={s} column="p50" />
+ * </Layers>
+ * ```
+ */
+export declare function BandChart<S extends SeriesSchema>({ series, lower, upper, as: semantic, axis, curve, index, }: BandChartProps<S>): null;
+//# sourceMappingURL=BandChart.d.ts.map

package/dist/BandChart.js

@@ -0,0 +1,93 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { bandFromTimeSeries } from './data.js';
+import { bandExtent, drawBand } from './band.js';
+import { resolveCurve } from './curve.js';
+import { ContainerContext, LayersContext } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A variance-band draw layer: fills the envelope between the `lower` and `upper`
+ * columns of `series` (typically `rollingByColumn` percentiles), gap-aware, and
+ * registers itself into the enclosing {@link Layers}. Renders nothing to the
+ * DOM — the row draws it.
+ *
+ * Compose two for a two-tone spread — author the wider band first so it sits
+ * behind (declaration order = z-order, back-to-front), then the line on top:
+ *
+ * ```tsx
+ * <Layers>
+ *   <BandChart series={s} lower="p5"  upper="p95" as="outer" />
+ *   <BandChart series={s} lower="p25" upper="p75" as="inner" />
+ *   <LineChart series={s} column="p50" />
+ * </Layers>
+ * ```
+ */
+export function BandChart({ series, lower, upper, as: semantic, axis, curve, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<BandChart> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<BandChart> must be rendered inside a <Layers>');
+    }
+    const bs = useMemo(() => bandFromTimeSeries(series, lower, upper), [series, lower, upper]);
+    // Styling: semantic identifier → theme band style. The single styling channel.
+    const { band } = container.theme;
+    const style = (semantic !== undefined ? band[semantic] : undefined) ?? band.default;
+    const curveFactory = resolveCurve(curve);
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => bandExtent(bs),
+            xKind: 'time',
+            xExtent: () => bs.length === 0 ? null : [bs.x[0], bs.x[bs.length - 1]],
+            sampleAt: (time) => {
+                // No readout past the data (tracker policy — nearest() clamps); bounds
+                // from the columnar time axis.
+                if (bs.length === 0 ||
+                    time < bs.x[0] ||
+                    time > bs.x[bs.length - 1]) {
+                    return [];
+                }
+                const e = series.nearest(time);
+                if (e === undefined)
+                    return [];
+                // get() wants a literal key; lower/upper are runtime strings. Cast the
+                // *event* (not the method — detaching `this` breaks `get`).
+                const ev = e;
+                const lo = ev.get(lower);
+                const hi = ev.get(upper);
+                if (typeof lo !== 'number' ||
+                    !Number.isFinite(lo) ||
+                    typeof hi !== 'number' ||
+                    !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).
+                return [
+                    { x: e.begin(), value: lo, color: style.fill, label: lower },
+                    { x: e.begin(), value: hi, color: style.fill, label: upper },
+                ];
+            },
+            draw: (ctx, xScale, yScale) => drawBand(ctx, bs, xScale, yScale, style, curveFactory),
+        },
+        axisId: axis,
+        index,
+    }), [bs, series, lower, upper, style, curveFactory, axis, index]);
+    // 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();
+    useEffect(() => () => layers.unregisterLayer(slot), [layers, slot]);
+    useEffect(() => {
+        layers.registerLayer(slot, entry);
+    }, [layers, slot, entry]);
+    // Also a tracker source: the container fans in the band edges 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=BandChart.js.map