@pond-ts/charts 0.31.0

package/dist/BarChart.d.ts

@@ -0,0 +1,72 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+export interface BarChartProps<S extends SeriesSchema> {
+    /**
+     * The source series. **Interval / timeRange-keyed** 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}).
+     */
+    series: TimeSeries<S>;
+    /** Name of the numeric value column for the bar height. */
+    column: 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).
+     */
+    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.**
+     */
+    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.
+     */
+    gap?: number;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    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).
+ *
+ * **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}).
+ *
+ * **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).
+ *
+ * **Distance domain is deferred** — v1 bars scale on the shared **time** xScale
+ * only. estela's distance-domain (records over a monotonic value axis) needs
+ * value-axis support that isn't built yet (charts RFC perf section).
+ *
+ * ```tsx
+ * <Layers>
+ *   <BarChart series={hourlyVolume} column="count" />
+ * </Layers>
+ * ```
+ */
+export declare function BarChart<S extends SeriesSchema>({ series, column, as: semantic, axis, gap, index, }: BarChartProps<S>): null;
+//# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -0,0 +1,137 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { barsFromTimeSeries } from './data.js';
+import { barAt, barExtent, barIndexAtTime, drawBars, resolveBarBaseline, } from './bars.js';
+import { ContainerContext, LayersContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A bar draw layer: one rectangle per event, spanning the key's `[begin, end]`
+ * (inset by `gap`) from the axis baseline to a numeric `column`'s value. Reads
+ * the key endpoints + column into a {@link BarSeries}, registers into the
+ * enclosing {@link Layers} (scaling against its `axis`), and renders nothing to
+ * the DOM — the row draws it. A gap (missing value) is skipped (no bar).
+ *
+ * **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}).
+ *
+ * **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).
+ *
+ * **Distance domain is deferred** — v1 bars scale on the shared **time** xScale
+ * only. estela's distance-domain (records over a monotonic value axis) needs
+ * value-axis support that isn't built yet (charts RFC perf section).
+ *
+ * ```tsx
+ * <Layers>
+ *   <BarChart series={hourlyVolume} column="count" />
+ * </Layers>
+ * ```
+ */
+export function BarChart({ series, column, as: semantic, axis, gap, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<BarChart> must be rendered inside a <Layers>');
+    }
+    const bs = useMemo(() => barsFromTimeSeries(series, column), [series, column]);
+    // Styling: semantic identifier → theme bar style. The single styling channel.
+    const { bar } = container.theme;
+    const style = (semantic !== undefined ? bar[semantic] : undefined) ?? bar.default;
+    // Series identity for the readout + selection match (the `as` role, else the
+    // column name).
+    const label = semantic ?? column;
+    // The gap prop overrides the theme default; otherwise the style carries it.
+    const gapPx = gap ?? style.gap;
+    // The current selection, narrowed to what the highlight match needs (key +
+    // label). Read here so a selection change re-registers the layer (in the deps)
+    // → the data canvas repaints with the highlight. Infrequent (a click).
+    const selected = container.selected;
+    const selection = useMemo(() => selected === null ? null : { key: selected.key, label: selected.label }, [selected]);
+    // The transient hover-highlight, narrowed to the match key (key + label) like
+    // the selection. Read here so a hover change re-registers the layer → the data
+    // canvas repaints with the lit bar. Deduped in the container, so this only
+    // fires on a bar transition (not every pointer move).
+    const hoveredMark = container.hovered;
+    const hover = useMemo(() => hoveredMark === null
+        ? null
+        : { key: hoveredMark.key, label: hoveredMark.label }, [hoveredMark]);
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => barExtent(bs),
+            xKind: 'time',
+            xExtent: () => bs.length === 0 ? null : [bs.begin[0], bs.end[bs.length - 1]],
+            sampleAt: (time) => {
+                // The flag belongs to the bar **under the cursor** — the bar whose
+                // span `[begin, end]` contains `time` (barIndexAtTime), NOT
+                // nearest-by-begin (which flips to the next bar past a wide bar's
+                // midpoint, landing the flag on the wrong bar). For a point key the
+                // span is the neighbour-derived Voronoi cell (`barsFromTimeSeries`
+                // widens `begin === end` into one), so the cells tile the axis and a
+                // moving cursor always lands in one. Before the first / after the last
+                // bar → no readout, matching the line/area tracker.
+                if (bs.length === 0)
+                    return [];
+                const i = barIndexAtTime(bs, time);
+                if (i < 0)
+                    return [];
+                const v = bs.y[i];
+                if (!Number.isFinite(v))
+                    return []; // a gap bar (missing value) reads nothing
+                // Anchor at the bar's **top-centre** (RFC): the span's centre time
+                // `(begin + end) / 2` (the bucket mid for an interval key; the Voronoi
+                // cell centre — ~on the point — for a point key), at `yScale(value)` =
+                // the bar top. A tall bar (top above the flag stack) drops the staff for
+                // free (the shared `s.py > stackBottom` rule).
+                return [
+                    {
+                        x: (bs.begin[i] + bs.end[i]) / 2,
+                        value: v,
+                        color: style.fill,
+                        label,
+                    },
+                ];
+            },
+            hitTest: (px, py, xScale, yScale) => {
+                const baseline = resolveBarBaseline(yScale);
+                const hit = barAt(bs, px, py, xScale, yScale, baseline, gapPx, style.minWidth);
+                if (hit === null)
+                    return null;
+                const [, begin, value] = hit;
+                // key = the bar's begin (its stable identity); colour = the resolved
+                // fill; label = this series' identity (so the highlight targets the
+                // exact clicked series, not another sharing the timestamp).
+                return { key: begin, value, color: style.fill, label };
+            },
+            draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, style, resolveBarBaseline(yScale), gapPx, label, selection, hover),
+        },
+        axisId: axis,
+        index,
+    }), [bs, series, column, style, label, gapPx, selection, hover, axis, index]);
+    // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
+    // fixed across series/style/selection updates (no jump to the front).
+    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=BarChart.js.map

package/dist/BoxPlot.d.ts

@@ -0,0 +1,77 @@
+import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { type BoxShape } from './box.js';
+export interface BoxPlotProps<S extends SeriesSchema> {
+    /** The source series. Its interval key column supplies the time axis (the box
+     *  x-span is the key's `[begin, end)`). */
+    series: TimeSeries<S>;
+    /** Name of the numeric column for the lower whisker end (e.g. `p5` / `min`). */
+    lower: string;
+    /** Name of the numeric column for the box bottom — first quartile (e.g. `p25`). */
+    q1: string;
+    /** Name of the numeric column for the median line (e.g. `p50`). */
+    median: string;
+    /** Name of the numeric column for the box top — third quartile (e.g. `p75`). */
+    q3: string;
+    /** Name of the numeric column for the upper whisker end (e.g. `p95` / `max`). */
+    upper: string;
+    /**
+     * The box series' semantic identifier — what the spread _is_ (e.g. `latency`).
+     * The theme maps it to a {@link BoxStyle} (`theme.box[as] ?? theme.box.default`
+     * — box fill/outline, median, whisker). **Omitted ⇒ the `default` box 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 box scales against — the *scale*, where
+     * `as` picks the *style*. **Omitted ⇒ the row's default axis.**
+     */
+    axis?: string;
+    /**
+     * Total horizontal inset between adjacent boxes in px (half each side), so they
+     * breathe — see `barSpanPx`. **Omitted ⇒ `0`** (boxes fill their interval span
+     * edge-to-edge). A box narrower than 1px after the inset collapses to a 1px
+     * mark centred in its slot, so a thin bucket stays visible.
+     */
+    gap?: number;
+    /**
+     * How each box renders its spread — `'whisker'` (default; thin stems + caps),
+     * `'solid'` (the candlestick look: a light outer bar over the full range with a
+     * darker inner q1→q3 box, no stems), or `'none'` (the q1→q3 box only, no spread
+     * marks). See {@link BoxShape}.
+     */
+    shape?: BoxShape;
+    /** Draw the median (centre) line across each box. Always optional; default
+     *  `true`. (The `median` prop above names the *column*; this toggles the line.) */
+    showMedian?: boolean;
+    /**
+     * @internal Declaration position among the `<Layers>` children, injected by
+     * `Layers` so z-order follows JSX order. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
+ * band. Reads five **pre-computed quantile columns** of `series` (typically a
+ * `rolling`/`aggregate` percentile pass — the chart does **not** compute them)
+ * into a {@link BoxSeries} and draws one box per key: the q1→q3 box, the median
+ * line, and whiskers out to lower/upper, over the key's interval x-span. Gap-aware
+ * (a key missing any quantile draws nothing) and registers itself into the
+ * enclosing {@link Layers}. Renders nothing to the DOM — the row draws it.
+ *
+ * There's no baseline — a box is a spread, not a bar to a floor; the y-domain
+ * auto-fits the whisker reach (lower→upper).
+ *
+ * ```tsx
+ * <Layers>
+ *   <BoxPlot
+ *     series={q}
+ *     lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
+ *     as="latency"
+ *     gap={6}
+ *   />
+ * </Layers>
+ * ```
+ */
+export declare function BoxPlot<S extends SeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, index, }: BoxPlotProps<S>): null;
+//# sourceMappingURL=BoxPlot.d.ts.map

package/dist/BoxPlot.js

@@ -0,0 +1,137 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { boxFromTimeSeries } from './data.js';
+import { boxExtent, boxIndexAtTime, drawBox, isFiniteBox, } from './box.js';
+import { ContainerContext, LayersContext, } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/** Whisker collapse floor (px) — a too-thin box still draws a 1px mark. */
+const MIN_BOX_WIDTH_PX = 1;
+/**
+ * A discrete box-and-whisker draw layer — the bar-chart analog of the variance
+ * band. Reads five **pre-computed quantile columns** of `series` (typically a
+ * `rolling`/`aggregate` percentile pass — the chart does **not** compute them)
+ * into a {@link BoxSeries} and draws one box per key: the q1→q3 box, the median
+ * line, and whiskers out to lower/upper, over the key's interval x-span. Gap-aware
+ * (a key missing any quantile draws nothing) and registers itself into the
+ * enclosing {@link Layers}. Renders nothing to the DOM — the row draws it.
+ *
+ * There's no baseline — a box is a spread, not a bar to a floor; the y-domain
+ * auto-fits the whisker reach (lower→upper).
+ *
+ * ```tsx
+ * <Layers>
+ *   <BoxPlot
+ *     series={q}
+ *     lower="p5" q1="p25" median="p50" q3="p75" upper="p95"
+ *     as="latency"
+ *     gap={6}
+ *   />
+ * </Layers>
+ * ```
+ */
+export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, axis, gap = 0, shape = 'whisker', showMedian = true, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<BoxPlot> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<BoxPlot> must be rendered inside a <Layers>');
+    }
+    const bx = useMemo(() => boxFromTimeSeries(series, { lower, q1, median, q3, upper }), [series, lower, q1, median, q3, upper]);
+    // Styling: semantic identifier → theme box style. The single styling channel.
+    const { box } = container.theme;
+    const style = (semantic !== undefined ? box[semantic] : undefined) ?? box.default;
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => boxExtent(bx),
+            xKind: 'time',
+            xExtent: () => bx.length === 0 ? null : [bx.x[0], bx.xEnd[bx.length - 1]],
+            sampleAt: (time) => {
+                // The readout reads the box **under the cursor** (boxIndexAtTime — span
+                // containment, not nearest-by-begin which flips past a wide box's
+                // midpoint), anchored at the box **centre** `(x + xEnd) / 2`. Outside
+                // every box → no readout. Off-chart fan-in only; the in-chart flag is
+                // `cursorFlag`.
+                if (bx.length === 0)
+                    return [];
+                const i = boxIndexAtTime(bx, time);
+                if (i < 0)
+                    return [];
+                const at = (bx.x[i] + bx.xEnd[i]) / 2;
+                const samples = [];
+                // The median is the primary readout (median colour); the four quantile
+                // edges ride the whisker colour, each labelled by its own column. A
+                // single non-finite quantile is omitted (a gap key yields nothing — all
+                // five missing — but a malformed partial set still reads what it has).
+                push(samples, at, bx.upper[i], style.whisker, upper);
+                push(samples, at, bx.q3[i], style.whisker, q3);
+                push(samples, at, bx.median[i], style.median, median);
+                push(samples, at, bx.q1[i], style.whisker, q1);
+                push(samples, at, bx.lower[i], style.whisker, lower);
+                return samples;
+            },
+            cursorFlag: (time) => {
+                // The in-chart `flag`: all five values on **one** flag at the box's
+                // top-centre. The staff rises from `upper` (the mark's top); the values
+                // run high→low across one horizontal row (Layers renders them
+                // left→right), each coloured to its box piece. All-or-nothing — a gap
+                // box (any quantile non-finite, not drawn) shows no flag.
+                if (bx.length === 0)
+                    return null;
+                const i = boxIndexAtTime(bx, time);
+                if (i < 0 || !isFiniteBox(bx, i))
+                    return null;
+                return {
+                    x: (bx.x[i] + bx.xEnd[i]) / 2,
+                    topValue: bx.upper[i],
+                    lines: [
+                        { value: bx.upper[i], color: style.whisker, label: upper },
+                        { value: bx.q3[i], color: style.whisker, label: q3 },
+                        { value: bx.median[i], color: style.median, label: median },
+                        { value: bx.q1[i], color: style.whisker, label: q1 },
+                        { value: bx.lower[i], color: style.whisker, label: lower },
+                    ],
+                };
+            },
+            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian),
+        },
+        axisId: axis,
+        index,
+    }), [
+        bx,
+        series,
+        lower,
+        q1,
+        median,
+        q3,
+        upper,
+        style,
+        gap,
+        shape,
+        showMedian,
+        axis,
+        index,
+    ]);
+    // Stable per-instance slot (see useSlotKey): keeps this box'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 box quantiles 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;
+}
+/** Append a tracker sample for a quantile, skipping a non-finite value. */
+function push(out, x, value, color, label) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        out.push({ x, value, color, label });
+    }
+}
+//# sourceMappingURL=BoxPlot.js.map

package/dist/Canvas.d.ts

@@ -0,0 +1,37 @@
+import { type CSSProperties } from 'react';
+/**
+ * A draw callback. The 2D context it receives is already transformed to device
+ * pixels, so draw in **CSS-pixel coordinates** (`0..width`, `0..height`) and it
+ * renders crisply at any device-pixel ratio. The context is freshly transformed
+ * and cleared before each invocation.
+ */
+export type CanvasDraw = (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+export interface CanvasProps {
+    /** CSS width in pixels. */
+    width: number;
+    /** CSS height in pixels. */
+    height: number;
+    /** Synchronous draw callback, invoked after every (re)size or prop change. */
+    draw: CanvasDraw;
+    /**
+     * Device-pixel-ratio override (defaults to `window.devicePixelRatio || 1`).
+     * Exposed so tests can pin a deterministic backing-buffer size; production
+     * callers leave it unset.
+     */
+    dpr?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The DPR-aware `<canvas>` primitive every chart draw layer sits on. It sizes
+ * the backing buffer to `width*dpr × height*dpr`, keeps the CSS box at
+ * `width × height`, applies `setTransform(dpr, …)` so the {@link CanvasDraw}
+ * callback works in CSS-pixel coordinates, clears, and calls `draw`.
+ *
+ * Drawing runs in `useLayoutEffect` (synchronous, before paint) so there is no
+ * flash of an unsized or empty canvas. Setting `canvas.width`/`height` resets
+ * all context state, so the transform is re-applied on every run — see trap #7
+ * in `docs/rfcs/charts.md`.
+ */
+export declare function Canvas({ width, height, draw, dpr, className, style, }: CanvasProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Canvas.d.ts.map

package/dist/Canvas.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from 'react';
+/**
+ * The DPR-aware `<canvas>` primitive every chart draw layer sits on. It sizes
+ * the backing buffer to `width*dpr × height*dpr`, keeps the CSS box at
+ * `width × height`, applies `setTransform(dpr, …)` so the {@link CanvasDraw}
+ * callback works in CSS-pixel coordinates, clears, and calls `draw`.
+ *
+ * Drawing runs in `useLayoutEffect` (synchronous, before paint) so there is no
+ * flash of an unsized or empty canvas. Setting `canvas.width`/`height` resets
+ * all context state, so the transform is re-applied on every run — see trap #7
+ * in `docs/rfcs/charts.md`.
+ */
+export function Canvas({ width, height, draw, dpr, className, style, }) {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const canvas = ref.current;
+        if (!canvas)
+            return;
+        const ratio = dpr ?? (typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1);
+        // Resizing the backing buffer clears it and resets context state, so this
+        // must happen before the transform + draw.
+        canvas.width = Math.round(width * ratio);
+        canvas.height = Math.round(height * ratio);
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return; // SSR / headless environments without a 2D backend
+        ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+        ctx.clearRect(0, 0, width, height);
+        draw(ctx, width, height);
+    }, [width, height, dpr, draw]);
+    return (_jsx("canvas", { ref: ref, className: className, style: {
+            width: `${width}px`,
+            height: `${height}px`,
+            display: 'block',
+            ...style,
+        } }));
+}
+//# sourceMappingURL=Canvas.js.map

package/dist/ChartContainer.d.ts

@@ -0,0 +1,106 @@
+import { type ReactNode } from 'react';
+import type { TimeRange } from 'pond-ts';
+import { type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
+import { type AxisFormat } from './format.js';
+import { type ChartTheme } from './theme.js';
+export interface ChartContainerProps {
+    /**
+     * The shared x **domain** `[begin, end]` — a tuple, or a `TimeRange`
+     * (`series.timeRange()`). Units follow the data: epoch-ms for a time axis,
+     * the value units (distance, …) for a value axis. **Omit to auto-fit** to the
+     * rows' extents. The axis *kind* is never taken from here — it's inferred from
+     * the data — so a tuple stays a time domain on a time chart.
+     */
+    range?: readonly [number, number] | TimeRange;
+    /** Total width in CSS pixels (plot + axis gutters). */
+    width: number;
+    /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
+    rowGap?: number;
+    /**
+     * Auto-render the shared x axis under the rows. **Default `true`.** Set
+     * `false` for a bare plot (a sparkline), or when you place your own `<XAxis>`
+     * child (e.g. with a label, custom ticks, or on `side="top"`). Named
+     * `showAxis` (not `axis`) to avoid clashing with a layer's `axis` prop, which
+     * picks *which* `<YAxis>` it scales against — a different axis entirely.
+     */
+    showAxis?: boolean;
+    /**
+     * Controlled tracker position (epoch ms) — pins the synced crosshair across
+     * rows. Omit for uncontrolled (the chart tracks the pointer itself); pass
+     * `null` to force it hidden. See {@link onTrackerChanged}.
+     */
+    trackerPosition?: number | null;
+    /**
+     * In-chart cursor presentation — the default for all rows (a row may override
+     * via `<ChartRow cursor>`). **Default `'line'`** — the synced vertical line,
+     * with values surfaced *outside* the chart via {@link onTrackerChanged}.
+     * `'point'` / `'inline'` / `'flag'` add per-series marks; `'none'` hides it.
+     * See {@link CursorMode}.
+     */
+    cursor?: CursorMode;
+    /**
+     * Fires on pointer move with the hovered time + every series' value there (so
+     * you can render a readout outside the chart), and `null` on leave.
+     */
+    onTrackerChanged?: (info: TrackerInfo | null) => void;
+    /**
+     * Controlled selection — the selected mark (echo the `onSelect` arg back), or
+     * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
+     * internally; pass `null` to force nothing selected). Selectable layers
+     * (`BarChart`, `BoxPlot`, `ScatterChart`) highlight the mark matching both its
+     * key and series — so two series sharing a timestamp don't both light up.
+     */
+    selected?: SelectInfo | null;
+    /**
+     * Fires when a selectable layer's mark is clicked, with the hit mark, or `null`
+     * when a click misses every mark (clears the selection). Notification only —
+     * works in both controlled and uncontrolled mode.
+     */
+    onSelect?: (hit: SelectInfo | null) => void;
+    /**
+     * Enable pan/zoom: drag the plot to pan the time range, wheel to zoom around
+     * the cursor. **Default off** — so it doesn't capture drag/scroll unless asked.
+     */
+    panZoom?: boolean;
+    /**
+     * Controlled view range — fires on pan/zoom with the new `[start, end]`. Wire
+     * it back to `range` for a controlled chart; omit for uncontrolled (the
+     * container holds the view internally). **Uncontrolled + `panZoom` seeds the
+     * internal view from `range` whenever it isn't actively holding one — so
+     * toggling `panZoom` on, or a controlled→uncontrolled switch, starts from the
+     * current range, not the mount-time one. Once uncontrolled, later `range`
+     * changes are ignored so they can't fight the user's pan. To drive the range
+     * externally — or to follow a live sliding window — use controlled mode (this
+     * callback).**
+     */
+    onTimeRangeChange?: (range: [number, number]) => void;
+    /** Zoom-in floor — the minimum visible duration in ms. Default `1`. */
+    minDuration?: number;
+    /**
+     * Show the cursor's time atop the in-chart readout (when a row's `cursor` draws
+     * one). **Default `false`.** Formatted by {@link timeFormat} to match the time
+     * axis.
+     */
+    cursorTime?: boolean;
+    /**
+     * Time-axis value formatting — a d3 time specifier string (e.g. `'%H:%M'`) or a
+     * `(epochMs) => string` function ({@link AxisFormat}); applies to both the time
+     * axis labels and the cursor-time readout. **Omitted ⇒ d3's multi-scale time
+     * format** (`12 PM`, `12:10`, …).
+     */
+    timeFormat?: AxisFormat;
+    /** Visual theme for all rows; defaults to {@link defaultTheme}. */
+    theme?: ChartTheme;
+    children?: ReactNode;
+}
+/**
+ * The top of the chart layout (react-timeseries-charts-style). Owns the shared
+ * **x geometry**: it collects each row's per-slot gutter widths, reserves each
+ * slot's max across rows (so the innermost axis aligns column-by-column and
+ * every row's plot left-aligns), and from the slot sums derives `plotWidth` and
+ * the shared time `xScale`. It renders its rows (separated by `rowGap`) then one
+ * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
+ * (`<YAxis>`).
+ */
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ChartContainer.d.ts.map