@pond-ts/charts 0.31.0

package/dist/ScatterChart.js

@@ -0,0 +1,139 @@
+import { useContext, useEffect, useMemo } from 'react';
+import { fromTimeSeries } from './data.js';
+import { drawScatter, hitTestScatter, nearestIndex, scatterExtent, } from './scatter.js';
+import { resolveEncoding, } from './encoding.js';
+import { ContainerContext, LayersContext } from './context.js';
+import { useSlotKey } from './use-slot-key.js';
+/**
+ * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * with **data-driven radius + colour** (the signed-off exception — encode from
+ * columns via scales, not a per-event style callback). Reads `column` into a
+ * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
+ * {@link Layers} (scaling against its `axis`), and renders nothing to the DOM —
+ * the row draws it.
+ *
+ * **Interactions.** Hover snaps the tracker dot to the nearest point
+ * (`sampleAt`), and that sample flows to the container's `onTrackerChanged` —
+ * the nearest-point readout. Scatter reuses the shared tracker rather than
+ * adding a separate `onNearest` channel, so a scatter reads out exactly like a
+ * line. Click selection hit-tests each point's disc (`hitTest`); the selected
+ * point (matching both its key and this series' label) gets a highlight ring.
+ *
+ * ```tsx
+ * <Layers>
+ *   <ScatterChart
+ *     series={s}
+ *     column="price"
+ *     radius={{ column: 'volume', range: [3, 14] }}
+ *     color={{ column: 'change', range: ['#e8836b', '#15B3A6'] }}
+ *   />
+ * </Layers>
+ * ```
+ */
+export function ScatterChart({ series, column, as: semantic, axis, radius, color, label, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
+    }
+    const layers = useContext(LayersContext);
+    if (layers === null) {
+        throw new Error('<ScatterChart> must be rendered inside a <Layers>');
+    }
+    const cs = useMemo(() => fromTimeSeries(series, column), [series, column]);
+    // Styling: semantic identifier → theme scatter style. The single styling
+    // channel for the base mark.
+    const { scatter } = container.theme;
+    const style = (semantic !== undefined ? scatter[semantic] : undefined) ?? scatter.default;
+    // Series identity for the readout + selection match (the `as` role, else the
+    // column name).
+    const seriesLabel = semantic ?? column;
+    const { font } = container.theme;
+    // Resolve the data-driven encoding once per data/encoding change. The reader
+    // pulls a named numeric column to a Float64Array (gaps NaN) — the same path
+    // fromTimeSeries uses; an unknown / non-numeric column throws there (eager,
+    // so a typo surfaces at render, not silently as base-styled points).
+    const encoding = useMemo(() => resolveEncoding(cs, style.radius, style.color, radius, color, (col) => fromTimeSeries(series, col).y), [cs, style.radius, style.color, radius, color, series]);
+    // Per-point label accessor: a column name reads that field, `true` reads the
+    // plotted column, anything else (false / omitted) ⇒ no labels.
+    const labelAt = useMemo(() => {
+        if (label === undefined || label === false)
+            return undefined;
+        const field = label === true ? column : label;
+        return (i) => {
+            // series.at(i) is O(1) per row (columnar eventAt cache), so a label per
+            // point stays cheap. The field is a runtime string → cast off the literal-
+            // keyed get (mirrors the value reads).
+            const e = series.at(i);
+            if (e === undefined)
+                return undefined;
+            const v = e.get(field);
+            return v === undefined || v === null ? undefined : String(v);
+        };
+    }, [label, column, series]);
+    // The point's stable key is its event begin (epoch ms) — the same as cs.x[i],
+    // which is the key column's begin buffer. Used for selection identity.
+    const keyAt = useMemo(() => (i) => cs.x[i], [cs]);
+    const entry = useMemo(() => ({
+        layer: {
+            yExtent: () => scatterExtent(cs),
+            xKind: 'time',
+            xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
+            sampleAt: (time) => {
+                // No readout past the data (tracker policy — the dot snaps to a drawn
+                // mark, never extrapolates past the span); bounds from the time axis.
+                if (cs.length === 0 ||
+                    time < cs.x[0] ||
+                    time > cs.x[cs.length - 1]) {
+                    return [];
+                }
+                // Nearest *drawn* point by index (skips gaps) — O(log N). Reading by
+                // index gives the value, the snap-to x, and the encoded colour in one
+                // shot, so the readout swatch matches the mark the user sees.
+                const i = nearestIndex(cs, time);
+                if (i < 0)
+                    return [];
+                return [
+                    {
+                        x: cs.x[i],
+                        value: cs.y[i],
+                        color: encoding.colorAt(i),
+                        label: seriesLabel,
+                    },
+                ];
+            },
+            hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, seriesLabel),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, seriesLabel),
+        },
+        axisId: axis,
+        index,
+    }), [
+        cs,
+        series,
+        column,
+        style,
+        seriesLabel,
+        encoding,
+        keyAt,
+        labelAt,
+        font,
+        container.selected,
+        axis,
+        index,
+    ]);
+    // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
+    // fixed across data/style/selection updates (no jump to the front on 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' nearest-point
+    // 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=ScatterChart.js.map

package/dist/TimeAxis.d.ts

@@ -0,0 +1,9 @@
+import { type XAxisProps } from './XAxis.js';
+/**
+ * The time-flavoured preset of {@link XAxis} — `<TimeAxis />` is `<XAxis />`.
+ * Kept as the familiar name for time charts (and what the container auto-renders);
+ * the axis kind still follows the data, so on a value container it ticks as a
+ * value axis. Forwards every {@link XAxisProps} (`format`, `label`, `side`, …).
+ */
+export declare function TimeAxis(props?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TimeAxis.d.ts.map

package/dist/TimeAxis.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { XAxis } from './XAxis.js';
+/**
+ * The time-flavoured preset of {@link XAxis} — `<TimeAxis />` is `<XAxis />`.
+ * Kept as the familiar name for time charts (and what the container auto-renders);
+ * the axis kind still follows the data, so on a value container it ticks as a
+ * value axis. Forwards every {@link XAxisProps} (`format`, `label`, `side`, …).
+ */
+export function TimeAxis(props = {}) {
+    return _jsx(XAxis, { ...props });
+}
+//# sourceMappingURL=TimeAxis.js.map

package/dist/XAxis.d.ts

@@ -0,0 +1,39 @@
+import { type AxisFormat } from './format.js';
+export interface XAxisProps {
+    /**
+     * Tick / cursor value formatting — a d3 format/time specifier string or a
+     * `(value) => string`. **Omitted ⇒ the container's shared formatter** (so the
+     * axis and the cursor readout agree), which is the d3 multi-scale time format
+     * for a time axis or the number default for a value axis. The specifier is
+     * resolved against the axis's kind (time vs value).
+     */
+    format?: AxisFormat;
+    /** A label drawn centred below (or above) the ticks — e.g. `Distance (m)`. */
+    label?: string;
+    /** Which edge the axis sits on. **Default `'bottom'`.** Declaration order in
+     *  the `<ChartContainer>` places it; `side` orients the ticks + label. */
+    side?: 'top' | 'bottom';
+    /** Strip height in px. Defaults to fit the ticks (+ the label line if any). */
+    height?: number;
+    /**
+     * Explicit ticks — `{ at, label }` in axis-value units — instead of the
+     * scale's automatic ticks. The value-axis lever for e.g. lap markers placed at
+     * their cumulative-distance positions (`{ at: lap.endMeters, label: 'Lap 3' }`).
+     */
+    ticks?: ReadonlyArray<{
+        readonly at: number;
+        readonly label: string;
+    }>;
+}
+/**
+ * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
+ * child of {@link ChartContainer}, rendered as DOM chrome (crisp text,
+ * themeable) under (or over) the rows, aligned to the plot. It reads the
+ * container's resolved `xScale` + `xKind` — so a **time** container ticks on
+ * wall-clock boundaries and a **value** container (a `ValueSeries` row) ticks as
+ * numbers, with no axis-type prop here; the kind follows the data.
+ *
+ * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
+ */
+export declare function XAxis({ format, label, side, height, ticks: customTicks, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useContext } from 'react';
+import { ContainerContext } from './context.js';
+import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
+/** Tick strip height (mark + value label) in CSS px. */
+const TICK_STRIP = 22;
+/** Extra height reserved for an axis `label` line. */
+const LABEL_STRIP = 16;
+const TICK_COUNT = 5;
+/**
+ * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
+ * child of {@link ChartContainer}, rendered as DOM chrome (crisp text,
+ * themeable) under (or over) the rows, aligned to the plot. It reads the
+ * container's resolved `xScale` + `xKind` — so a **time** container ticks on
+ * wall-clock boundaries and a **value** container (a `ValueSeries` row) ticks as
+ * numbers, with no axis-type prop here; the kind follows the data.
+ *
+ * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
+ */
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, } = {}) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
+    }
+    const { xScale, plotWidth, leftGutter, theme, formatTime, xKind } = container;
+    // Tick formatter: an explicit `format` is resolved against the axis kind
+    // (a time specifier through the time scale, a number specifier through the
+    // value scale); otherwise the container's shared formatter — the one the
+    // cursor readout uses, so a tick and the cursor read identically.
+    const fmt = format === undefined
+        ? formatTime
+        : xKind === 'time'
+            ? resolveTimeFormat(xScale, TICK_COUNT, format)
+            : resolveAxisFormat(xScale, TICK_COUNT, format);
+    const placed = customTicks
+        ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
+        : xScale.ticks(TICK_COUNT).map((d) => ({
+            x: xScale(d),
+            label: fmt(+d),
+        }));
+    const stripHeight = height ?? TICK_STRIP + (label ? LABEL_STRIP : 0);
+    const onTop = side === 'top';
+    return (_jsxs("div", { style: {
+            position: 'relative',
+            marginLeft: `${leftGutter}px`,
+            width: `${plotWidth}px`,
+            height: `${stripHeight}px`,
+            // The plot-facing edge carries the rule; a top axis rules its bottom.
+            [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${theme.axis.grid}`,
+            fontFamily: theme.font.family,
+            fontSize: `${theme.font.size}px`,
+            color: theme.axis.label,
+        }, children: [placed.map((t, i) => {
+                // End-align the edge labels so they stay within [0, plotWidth].
+                const labelTransform = i === 0
+                    ? 'none'
+                    : i === placed.length - 1
+                        ? 'translateX(-100%)'
+                        : 'translateX(-50%)';
+                return (_jsxs(Fragment, { children: [_jsx("div", { style: {
+                                position: 'absolute',
+                                left: `${t.x}px`,
+                                [onTop ? 'bottom' : 'top']: 0,
+                                width: '1px',
+                                height: '4px',
+                                background: theme.axis.grid,
+                            } }), _jsx("div", { style: {
+                                position: 'absolute',
+                                left: `${t.x}px`,
+                                [onTop ? 'bottom' : 'top']: '6px',
+                                transform: labelTransform,
+                                whiteSpace: 'nowrap',
+                            }, children: t.label })] }, `${t.x}-${i}`));
+            }), label !== undefined && (_jsx("div", { style: {
+                    position: 'absolute',
+                    left: 0,
+                    width: '100%',
+                    textAlign: 'center',
+                    [onTop ? 'top' : 'bottom']: 0,
+                    opacity: 0.7,
+                    whiteSpace: 'nowrap',
+                }, children: label }))] }));
+}
+//# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -0,0 +1,42 @@
+import { type AxisFormat } from './format.js';
+export interface YAxisProps {
+    /** Identifier a chart links to via its `axis` prop (and the first declared is
+     *  the row's default). */
+    id: string;
+    /**
+     * Which side of the plot the gutter sits on. Author left axes *before*
+     * `<Layers>` in JSX and right axes *after* — the row lays children out in
+     * order. Default `left`.
+     */
+    side?: 'left' | 'right';
+    /** Display label / unit (e.g. `bpm`); defaults to `id`. */
+    label?: string;
+    /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
+    min?: number;
+    max?: number;
+    /**
+     * Value formatting for the tick labels (and the cursor readout, which matches):
+     * a d3 format specifier string (e.g. `'.0%'`, `',.2f'`) or a `(value) => string`
+     * function. Omit for the scale's d3 default — which is calibrated to the tick
+     * step, so a between-ticks readout rounds to tick precision; pass a specifier
+     * (e.g. `',.2f'`) when you want finer readout precision. See {@link AxisFormat}.
+     */
+    format?: AxisFormat;
+    /** Gutter width in CSS pixels (default 50). */
+    width?: number;
+    /**
+     * @internal Declaration position among the row's children, injected by
+     * `ChartRow` so the first-declared axis stays the default. Do not set.
+     */
+    index?: number;
+}
+/**
+ * A y-axis for a {@link ChartRow}, rendered as DOM chrome (not canvas) so the
+ * text is crisp, themeable, and accessible. Registers its id / side / width /
+ * domain with the row, which reserves the gutter (shrinking `plotWidth`) and
+ * computes this axis's scale from the charts linked to it; the gutter then draws
+ * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
+ * (default: the first axis).
+ */
+export declare function YAxis({ id, side, label, min, max, format, width, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useEffect, useMemo } from 'react';
+import { ContainerContext, RowContext } from './context.js';
+import { resolveAxisFormat } from './format.js';
+import { useSlotKey } from './use-slot-key.js';
+const DEFAULT_WIDTH = 50;
+const TICK_COUNT = 5;
+/**
+ * A y-axis for a {@link ChartRow}, rendered as DOM chrome (not canvas) so the
+ * text is crisp, themeable, and accessible. Registers its id / side / width /
+ * domain with the row, which reserves the gutter (shrinking `plotWidth`) and
+ * computes this axis's scale from the charts linked to it; the gutter then draws
+ * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
+ * (default: the first axis).
+ */
+export function YAxis({ id, side = 'left', label, min, max, format, width = DEFAULT_WIDTH, index = 0, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
+    }
+    const row = useContext(RowContext);
+    if (row === null) {
+        throw new Error('<YAxis> must be rendered inside a <ChartRow>');
+    }
+    const spec = useMemo(() => ({ id, side, width, min, max, format, index }), [id, side, width, min, max, format, index]);
+    // A stable per-instance slot (see useSlotKey) keeps this axis in a fixed
+    // registry position, so a min/max/side change updates in place rather than
+    // re-appending (which would move the first axis behind a later one and
+    // silently rebind the row's default-axis charts).
+    const slot = useSlotKey();
+    const { registerAxis, unregisterAxis } = row;
+    // Unregister on unmount only (deps are stable, so cleanup never runs early).
+    useEffect(() => () => unregisterAxis(slot), [unregisterAxis, slot]);
+    // Register on mount + update in place on every spec change — no reorder.
+    useEffect(() => {
+        registerAxis(slot, spec);
+    }, [registerAxis, slot, spec]);
+    const { theme } = container;
+    const yScale = row.yScales.get(id);
+    const ticks = yScale ? yScale.ticks(TICK_COUNT) : [];
+    // Same formatter the readout uses (resolved per axis on the row), so a tick and
+    // a cursor value read identically.
+    const fmt = yScale ? resolveAxisFormat(yScale, TICK_COUNT, format) : String;
+    // The row reserves a slot per axis column (the widest in that column across
+    // rows). Size the box to the slot and align this axis's own (narrower)
+    // content toward the plot — left axes flush right, right axes flush left — so
+    // axes line up column-by-column. Keyed by this instance's slot key (not `id`,
+    // which may repeat across a mirror). Falls back to own width until reserved.
+    const slotWidth = row.axisSlots.get(slot) ?? width;
+    return (_jsx("div", { style: {
+            flex: `0 0 ${slotWidth}px`,
+            display: 'flex',
+            justifyContent: side === 'left' ? 'flex-end' : 'flex-start',
+            height: `${row.height}px`,
+        }, children: _jsxs("div", { style: {
+                position: 'relative',
+                width: `${width}px`,
+                height: `${row.height}px`,
+                fontFamily: theme.font.family,
+                fontSize: `${theme.font.size}px`,
+                color: theme.axis.label,
+            }, children: [yScale &&
+                    ticks.map((t) => (_jsx("div", { style: {
+                            position: 'absolute',
+                            top: `${yScale(t)}px`,
+                            [side === 'left' ? 'right' : 'left']: '4px',
+                            transform: 'translateY(-50%)',
+                            whiteSpace: 'nowrap',
+                        }, children: fmt(t) }, t))), _jsx("div", { style: {
+                        position: 'absolute',
+                        [side === 'left' ? 'left' : 'right']: '1px',
+                        top: 0,
+                        bottom: 0,
+                        width: `${theme.font.size + 2}px`,
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        fontSize: `${theme.font.size - 1}px`,
+                        opacity: 0.7,
+                        pointerEvents: 'none',
+                    }, children: _jsx("span", { style: {
+                            whiteSpace: 'nowrap',
+                            transform: `rotate(${side === 'left' ? -90 : 90}deg)`,
+                        }, children: label ?? id }) })] }) }));
+}
+//# sourceMappingURL=YAxis.js.map

package/dist/annotations.d.ts

@@ -0,0 +1,110 @@
+import { type AnnotationSpec } from './context.js';
+/**
+ * Greedy left→right lane packing for the **top-flag** labels (markers + regions): a
+ * label that would overlap the one to its left drops to the next free lane below,
+ * so close-in-x labels stack instead of colliding (and a dragged label slides under
+ * its neighbour). Returns slot-key → lane (0 = top). Baselines, whose labels anchor
+ * at the left at their own y, don't participate.
+ */
+export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number): Map<symbol, number>;
+export interface MarkerProps {
+    /** x position in axis units — epoch ms on a time axis, the value on a value
+     *  axis. (The generalisation of the mockup's "time line": a mark at an x, time
+     *  or value.) */
+    at: number;
+    /** Chip label; omit to auto-label with the shared x formatter (the axis's). */
+    label?: string;
+    /** Stable consumer id — a click reports it via the container's
+     *  `onSelectAnnotation`, so the consumer can track which mark is selected. */
+    id?: string;
+    /** Controlled selection — brightens to the front (level 1). Handles are an
+     *  edit-mode hover affordance, not a selection cue. Ignored if not `selectable`. */
+    selected?: boolean;
+    /** Whether the mark responds to hover + selection (default `true`). When
+     *  `false` it's inert background context — drawn at the back (level 3) always,
+     *  no hover, no select, no edit. */
+    selectable?: boolean;
+    /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
+     *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
+    hovered?: boolean;
+    /** When `true`, this mark is in **single-annotation edit** (the double-click
+     *  target): handles stay out, it's draggable, and it reads as level 1 — while
+     *  other marks stay static. Independent of the container's global
+     *  `editAnnotations`. Pair with `onEditAnnotation` (the consumer holds an
+     *  `editingId` and sets `editing={editingId === id}`). */
+    editing?: boolean;
+    /** Make the marker **editable** (in edit mode): dragging its line reports the
+     *  new `at` (controlled — wire it back to `at`). The whole line moves. */
+    onChange?: (at: number) => void;
+}
+/** A vertical line at an x position (a time, a distance, a lap boundary). */
+export declare function Marker({ at, label, id, selected, selectable, hovered, editing, onChange, }: MarkerProps): import("react/jsx-runtime").JSX.Element;
+export interface BaselineProps {
+    /** y value in the linked axis's units. */
+    value: number;
+    /** Which `<YAxis>` (by id) to measure against; omit for the row's default axis. */
+    axis?: string;
+    /** Chip label; omit to format `value` with that axis's formatter. */
+    label?: string;
+    /** Stable consumer id — a click reports it via `onSelectAnnotation`. */
+    id?: string;
+    /** Controlled selection — brightens to the front (level 1). Handles are an
+     *  edit-mode hover affordance, not a selection cue. Ignored if not `selectable`. */
+    selected?: boolean;
+    /** Whether the baseline responds to hover + selection (default `true`). When
+     *  `false` it's inert background context — drawn at the back (level 3) always. */
+    selectable?: boolean;
+    /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
+     *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
+    hovered?: boolean;
+    /** When `true`, this mark is in **single-annotation edit** (the double-click
+     *  target): handles stay out, it's draggable, and it reads as level 1 — while
+     *  other marks stay static. Independent of the container's global
+     *  `editAnnotations`. Pair with `onEditAnnotation` (the consumer holds an
+     *  `editingId` and sets `editing={editingId === id}`). */
+    editing?: boolean;
+    /** Make the baseline **editable** (in edit mode): dragging it vertically reports
+     *  the new `value` (controlled — wire it back to `value`). */
+    onChange?: (value: number) => void;
+}
+/** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
+ *  Its label anchors at the left, at the line's height. */
+export declare function Baseline({ value, axis, label, id, selected, selectable, hovered, editing, onChange, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
+export interface RegionProps {
+    /** Start x in axis units (time or value). */
+    from: number;
+    /** End x in axis units. */
+    to: number;
+    /** Chip label; omit to auto-label `from–to` with the shared x formatter. */
+    label?: string;
+    /** Stable consumer id — a click (or double-click outside edit) reports it via
+     *  `onSelectAnnotation`. */
+    id?: string;
+    /** Controlled selection — brightens to the front (level 1; the body too). Edge
+     *  handles are an edit-mode hover affordance, not a selection cue. Ignored if not
+     *  `selectable`. */
+    selected?: boolean;
+    /** Whether the region responds to hover + selection (default `true`). When
+     *  `false` it's inert background context — drawn at the back (level 3) always,
+     *  and the double-click hit-test skips it. */
+    selectable?: boolean;
+    /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
+     *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
+    hovered?: boolean;
+    /** When `true`, this mark is in **single-annotation edit** (the double-click
+     *  target): handles stay out, it's draggable, and it reads as level 1 — while
+     *  other marks stay static. Independent of the container's global
+     *  `editAnnotations`. Pair with `onEditAnnotation` (the consumer holds an
+     *  `editingId` and sets `editing={editingId === id}`). */
+    editing?: boolean;
+    /** Make the region **editable** (in edit mode): drag the body to move it (both
+     *  edges shift), drag an edge to resize. Reports the new `{ from, to }`. */
+    onChange?: (next: {
+        from: number;
+        to: number;
+    }) => void;
+}
+/** A shaded span over an x range — a lap, a zone, a selected interval. Its label
+ *  flies as a flag off the left edge. */
+export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, }: RegionProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=annotations.d.ts.map