@pond-ts/charts 0.31.2 → 0.32.0

package/dist/context.d.ts

@@ -75,6 +75,13 @@ export interface ContainerFrame {
     /** Show the cursor's time atop the in-chart readout (when a row's cursor draws
      *  one), formatted by {@link formatTime} to match the time axis. */
     readonly cursorTime: boolean;
+    /**
+     * Whether the chart is in **annotation-edit mode** — suppresses the data cursor
+     * and makes editable annotations interactive (hovering reveals their handles +
+     * highlights them, dragging edits them). Set by the container's
+     * `editAnnotations` prop; annotations read it to switch from inert to interactive.
+     */
+    readonly editAnnotations: boolean;
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
      *  shared by `<TimeAxis>` and the cursor-time readout. */
     readonly formatTime: (epochMs: number) => string;
@@ -127,6 +134,105 @@ export interface ContainerFrame {
     registerRow(key: symbol): () => void;
     /** The first (topmost) row's key, or `null` before any row has registered. */
     readonly firstRowKey: symbol | null;
+    /**
+     * Register an annotation (`<Region>`/`<Marker>`/`<Baseline>`) so the container
+     * can coordinate what a mark can't do in isolation: draw each mark's **guide
+     * line** across the *other* rows, resolve cross-region z-order, and serve
+     * **snap targets** to a drag. Keyed by the mark's per-instance slot key;
+     * unregister on unmount.
+     */
+    registerAnnotation(key: symbol, spec: AnnotationSpec): void;
+    unregisterAnnotation(key: symbol): void;
+    /** Every registered annotation — read by each row to draw the *other* rows'
+     *  guides, and by a drag to find snap targets. */
+    readonly annotations: readonly AnnotationSpec[];
+    /** Vertical lane (0 = top) for each top-flag label, by slot key — overlapping
+     *  marker/region labels stack into lower lanes instead of colliding. A key absent
+     *  from the map (or mapping to 0) sits in the top lane. */
+    readonly labelLanes: ReadonlyMap<symbol, number>;
+    /**
+     * The armed creation tool, or `null` (idle). Set by the consumer's toolbar;
+     * when non-null the plot captures a **create gesture** (draw a new mark) instead
+     * of panning, and fires {@link onCreate} on release. While armed, existing
+     * marks' edit handles stand down so the draw owns the surface.
+     */
+    readonly creating: AnnotationKind | null;
+    /**
+     * Snap mode — the toolbar's "Snap". When on, a dragged mark snaps to other
+     * marks' **guidelines** (their x-positions) so spans align; off = free
+     * placement. Read by {@link snapToGuides}. (Data-sample snapping — landing on a
+     * clean `5:12` rather than `5:11:47` — is a future extension, not yet wired.)
+     */
+    readonly snap: boolean;
+    /** Fired when a create gesture completes (on release). The consumer adds the
+     *  mark, disarms ({@link creating} → `null`), and selects it. `undefined` ⇒
+     *  creation is a no-op (the gesture still previews but commits nothing). */
+    readonly onCreate: ((spec: CreateSpec) => void) | undefined;
+    /** Fired when a mark is clicked (reports its `id`) or the plot is clicked empty
+     *  (`null`) — the consumer updates its selection. A double-click on a region
+     *  fires it too (the shortcut into a focused edit). */
+    readonly onSelectAnnotation: ((id: string | null) => void) | undefined;
+    /** Fired when the pointer enters a mark (reports its `id`) or leaves it (`null`),
+     *  so the consumer can mirror hover out-of-band (e.g. a legend row). Pairs with a
+     *  mark's controlled `hovered` prop to sync hover both ways. Works in any mode. */
+    readonly onHoverAnnotation: ((id: string | null) => void) | undefined;
+    /** Fired when a mark is **double-clicked** — the request to edit just that one.
+     *  The consumer flips it into single-annotation edit (sets its `editing` prop),
+     *  while the rest stay static. Distinct from {@link onSelectAnnotation} (single
+     *  click = inspect-select). Works in any mode. */
+    readonly onEditAnnotation: ((id: string) => void) | undefined;
+}
+/** The kind of an annotation, and of a creation tool. */
+export type AnnotationKind = 'region' | 'marker' | 'baseline';
+/** What a completed create gesture reports to {@link ContainerFrame.onCreate} —
+ *  the new mark's kind + position in axis units (+ the y-axis id for a baseline).
+ *  (Which row a mark lands on is the consumer's call for now; multi-row routing is
+ *  a follow-up.) */
+export type CreateSpec = {
+    readonly kind: 'marker';
+    readonly at: number;
+} | {
+    readonly kind: 'baseline';
+    readonly value: number;
+    readonly axis: string;
+} | {
+    readonly kind: 'region';
+    readonly from: number;
+    readonly to: number;
+};
+/**
+ * A registered annotation as the container sees it — enough to draw its guide
+ * line on other rows, order it against other marks, and offer it as a snap target.
+ */
+export interface AnnotationSpec {
+    /** The mark's per-instance slot key — its identity in the registry. */
+    readonly key: symbol;
+    /** The consumer's stable id (its `id` prop), if any — what a click /
+     *  double-click reports via {@link ContainerFrame.onSelectAnnotation}, so the
+     *  consumer knows which mark to select. */
+    readonly id: string | undefined;
+    readonly kind: AnnotationKind;
+    /** The row it lives on (its `<ChartRow>`'s key), so a row skips its own marks
+     *  when drawing guides. */
+    readonly rowKey: symbol;
+    /**
+     * Its vertical-guide x-position(s) in **axis units** (the shared x): a marker's
+     * `[at]`, a region's `[from, to]`. Empty for a baseline — a horizontal line
+     * casts no vertical guide.
+     */
+    readonly xs: readonly number[];
+    /** Whether it's currently selected (controlled by the consumer). */
+    readonly selected: boolean;
+    /** Whether it's in single-annotation edit (the double-click target). The plot
+     *  suppresses the data cursor while any mark is editing, as it does in global
+     *  edit mode. */
+    readonly editing: boolean;
+    /** Whether it accepts hover + selection. A non-selectable region is skipped by
+     *  the double-click hit-test (it's inert background context). */
+    readonly selectable: boolean;
+    /** The mark's resolved label text — used to pack overlapping top-flag labels
+     *  (markers + regions) into stacked vertical lanes. */
+    readonly label: string;
 }
 /**
  * A row's per-slot axis widths each side, **slot 0 nearest the plot** (so the
@@ -293,6 +399,9 @@ export interface AxisSpec {
     /** Value formatting for the tick labels + the cursor readout ({@link AxisFormat}),
      *  or `undefined` for the scale's d3 default. */
     readonly format: AxisFormat | undefined;
+    /** Explicit tick values (from `<YAxis ticks>`), driving BOTH the axis labels
+     *  and the row's gridlines so they align; `undefined` auto-picks from the scale. */
+    readonly tickValues: readonly number[] | undefined;
     /**
      * Declaration position among the row's children, injected by `ChartRow`. The
      * row sorts axes by this, so the **first declared** axis is the default
@@ -314,12 +423,19 @@ export interface RowFrame {
      *  against its scale) — used by both the tick labels and the cursor readout, so
      *  a value reads identically in both. */
     readonly formats: ReadonlyMap<string, (value: number) => string>;
+    /** Explicit tick values per axis id (from {@link AxisSpec.tickValues}), for axes
+     *  that set `<YAxis ticks>` — so `Layers` draws gridlines at the same positions
+     *  the axis labels. Absent id ⇒ that axis auto-picks. */
+    readonly tickValues: ReadonlyMap<string, readonly number[]>;
     /** This row's cursor-mode override, or `undefined` to inherit the container's
      *  default ({@link ContainerFrame.cursor}). */
     readonly cursor: CursorMode | undefined;
     /** Whether this is the first (topmost) row — the shared cursor-time chip shows
      *  here only, not repeated on every row. Derived from {@link ContainerFrame.firstRowKey}. */
     readonly isFirstRow: boolean;
+    /** This row's per-instance key — annotations register it so the container can
+     *  draw a mark's guide on the *other* rows (a row skips its own marks). */
+    readonly rowKey: symbol;
     /** The axis a layer uses when it names none (the first declared, or implicit). */
     readonly defaultAxisId: string;
     /**

package/dist/data.d.ts

@@ -118,6 +118,20 @@ export declare function fromValueSeries<VS extends ValueSeriesSchema>(series: Va
  * @throws TypeError if `lower` or `upper` is not a numeric column.
  */
 export declare function bandFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, lower: string, upper: string): BandSeries;
+/**
+ * Build a {@link BandSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link bandFromTimeSeries}. The x axis is the series' monotonic value axis
+ * (`axisValues()`, e.g. cumulative distance) instead of time; `lower`/`upper`
+ * name the two numeric edge columns (typically `rollingByColumn` percentiles).
+ * The resulting `BandSeries` is identical in shape — the chart draws it exactly
+ * as a time band, only the x scale differs (a value scale rather than
+ * `scaleTime`). A sample with either edge missing reads as a gap in the fill
+ * (same contract as {@link bandFromTimeSeries}).
+ *
+ * @throws RangeError if `lower` or `upper` does not exist.
+ * @throws TypeError if `lower` or `upper` is not a numeric column.
+ */
+export declare function bandFromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, lower: string, upper: string): BandSeries;
 /**
  * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
  * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
@@ -151,4 +165,24 @@ export declare function boxFromTimeSeries<S extends SeriesSchema>(series: TimeSe
  * @throws TypeError if `column` is not a numeric column.
  */
 export declare function barsFromTimeSeries<S extends SeriesSchema>(series: TimeSeries<S>, column: string): BarSeries;
+/**
+ * Build a {@link BarSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link barsFromTimeSeries}. A `ValueSeries` is **point-keyed** on its value
+ * axis (one axis value per row, no per-row span), so — exactly like the
+ * point-keyed `time` case of {@link barsFromTimeSeries} — each bar is centred on
+ * its axis value and synthesises a span from **neighbour spacing**: it reaches
+ * halfway to each neighbour (a Voronoi cell on the value axis). The first / last
+ * bars mirror their single adjacent gap; a lone point (length 1) keeps zero
+ * width and falls back to the renderer's `minWidth`.
+ *
+ * For evenly-spaced contiguous keys (e.g. uniform splits centred on their
+ * midpoints) the cell boundaries land exactly on the segment boundaries; for
+ * unevenly-spaced keys a boundary sits at the midpoint between adjacent centres
+ * (a slight drift from a true segment edge — fine for the bar look; key an
+ * interval/timeRange `TimeSeries` instead if exact edges matter).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function barsFromValueSeries<VS extends ValueSeriesSchema>(series: ValueSeries<VS>, column: string): BarSeries;
 //# sourceMappingURL=data.d.ts.map

package/dist/data.js

@@ -33,6 +33,31 @@ function readNumericColumn(series, column) {
     }
     return out;
 }
+/**
+ * Read a numeric column from a `ValueSeries` into a `Float64Array`, missing
+ * cells as `NaN` — the value-axis sibling of {@link readNumericColumn}, sharing
+ * its per-element `read(i)` rationale (the bulk reader is tree-shaken away in
+ * bundled browser builds).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+function readValueColumn(series, column) {
+    const col = series.column(column);
+    if (col === undefined) {
+        throw new RangeError(`unknown column '${column}'`);
+    }
+    if (col.kind !== 'number') {
+        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
+    }
+    const length = series.length;
+    const out = new Float64Array(length);
+    for (let i = 0; i < length; i += 1) {
+        const v = col.read(i);
+        out[i] = v === undefined ? NaN : v;
+    }
+    return out;
+}
 /** The key column's `begin` buffer aligned to the logical length (zero-copy). */
 function timeAxis(series) {
     // `begin` may carry trailing capacity beyond the logical length; subarray so
@@ -78,21 +103,12 @@ export function fromTimeSeries(series, column) {
  * @throws TypeError if `column` is not a numeric column.
  */
 export function fromValueSeries(series, column) {
-    const col = series.column(column);
-    if (col === undefined) {
-        throw new RangeError(`unknown column '${column}'`);
-    }
-    if (col.kind !== 'number') {
-        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
-    }
-    const length = series.length;
-    const y = new Float64Array(length);
-    for (let i = 0; i < length; i += 1) {
-        const v = col.read(i);
-        y[i] = v === undefined ? NaN : v;
-    }
     // axisValues() is the key buffer already trimmed to length (zero-copy).
-    return { x: series.axisValues(), y, length };
+    return {
+        x: series.axisValues(),
+        y: readValueColumn(series, column),
+        length: series.length,
+    };
 }
 /**
  * Build a {@link BandSeries} from a pond `TimeSeries` — two numeric columns for
@@ -111,6 +127,27 @@ export function bandFromTimeSeries(series, lower, upper) {
         length: series.length,
     };
 }
+/**
+ * Build a {@link BandSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link bandFromTimeSeries}. The x axis is the series' monotonic value axis
+ * (`axisValues()`, e.g. cumulative distance) instead of time; `lower`/`upper`
+ * name the two numeric edge columns (typically `rollingByColumn` percentiles).
+ * The resulting `BandSeries` is identical in shape — the chart draws it exactly
+ * as a time band, only the x scale differs (a value scale rather than
+ * `scaleTime`). A sample with either edge missing reads as a gap in the fill
+ * (same contract as {@link bandFromTimeSeries}).
+ *
+ * @throws RangeError if `lower` or `upper` does not exist.
+ * @throws TypeError if `lower` or `upper` is not a numeric column.
+ */
+export function bandFromValueSeries(series, lower, upper) {
+    return {
+        x: series.axisValues(),
+        lower: readValueColumn(series, lower),
+        upper: readValueColumn(series, upper),
+        length: series.length,
+    };
+}
 /**
  * Build a {@link BoxSeries} from a pond `TimeSeries` — five numeric quantile
  * columns (`lower`/`q1`/`median`/`q3`/`upper`) sharing the series' interval time
@@ -194,4 +231,42 @@ export function barsFromTimeSeries(series, column) {
     }
     return { begin, end, y, length: n };
 }
+/**
+ * Build a {@link BarSeries} from a pond `ValueSeries` — the value-axis sibling
+ * of {@link barsFromTimeSeries}. A `ValueSeries` is **point-keyed** on its value
+ * axis (one axis value per row, no per-row span), so — exactly like the
+ * point-keyed `time` case of {@link barsFromTimeSeries} — each bar is centred on
+ * its axis value and synthesises a span from **neighbour spacing**: it reaches
+ * halfway to each neighbour (a Voronoi cell on the value axis). The first / last
+ * bars mirror their single adjacent gap; a lone point (length 1) keeps zero
+ * width and falls back to the renderer's `minWidth`.
+ *
+ * For evenly-spaced contiguous keys (e.g. uniform splits centred on their
+ * midpoints) the cell boundaries land exactly on the segment boundaries; for
+ * unevenly-spaced keys a boundary sits at the midpoint between adjacent centres
+ * (a slight drift from a true segment edge — fine for the bar look; key an
+ * interval/timeRange `TimeSeries` instead if exact edges matter).
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function barsFromValueSeries(series, column) {
+    const y = readValueColumn(series, column);
+    const n = series.length;
+    // axisValues() is the monotonic key buffer (zero-copy) — must not be mutated,
+    // so synthesise the spans into fresh buffers.
+    const ax = series.axisValues();
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const x = ax[i];
+        // Half-gap to the previous neighbour (mirror the next gap at the left edge).
+        const prevGap = i > 0 ? x - ax[i - 1] : i + 1 < n ? ax[i + 1] - x : 0;
+        // Half-gap to the next neighbour (mirror the previous gap at the right edge).
+        const nextGap = i + 1 < n ? ax[i + 1] - x : i > 0 ? x - ax[i - 1] : 0;
+        begin[i] = x - prevGap / 2;
+        end[i] = x + nextGap / 2;
+    }
+    return { begin, end, y, length: n };
+}
 //# sourceMappingURL=data.js.map

package/dist/index.d.ts

@@ -42,6 +42,9 @@ export { BoxPlot } from './BoxPlot.js';
 export type { BoxPlotProps } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
 export type { BarChartProps } from './BarChart.js';
+export { Region, Baseline, Marker } from './annotations.js';
+export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
+export type { AnnotationKind, CreateSpec } from './context.js';
 export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
 export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, } from './data.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';

package/dist/index.js

@@ -29,6 +29,9 @@ export { AreaChart } from './AreaChart.js';
 export { ScatterChart } from './ScatterChart.js';
 export { BoxPlot } from './BoxPlot.js';
 export { BarChart } from './BarChart.js';
+// Annotations — user-authored marks in the turquoise register (distinct from the
+// data): a shaded span, a horizontal value line, a vertical x line.
+export { Region, Baseline, Marker } from './annotations.js';
 export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 //# sourceMappingURL=index.js.map

package/dist/theme.d.ts

@@ -115,6 +115,24 @@ export interface ChartTheme {
     readonly gap?: {
         readonly connectorOpacity: number;
     };
+    /**
+     * The **annotation register** — the styling for *user-authored* marks
+     * (`<Region>` / `<Baseline>` / `<Marker>`), deliberately a distinct hue from
+     * the data's `line`/`area`/… so a mark you place never reads as data (the
+     * "data stays foam, marks are turquoise" rule). `color` is the shared register
+     * hue (lines, region edges + fill, handles, label text); the region fill draws
+     * at `fillOpacity`. **Luminosity encodes depth** — brighter reads as forward,
+     * dimmer as further back. `depth` is the three-level ramp: `[0]` = level 1
+     * (forward / brightest — a selected mark, or an edit-mode line), `[1]` = level 2
+     * (mid — a hovered mark, or an edit-mode region body), `[2]` = level 3 (back —
+     * the resting, backgrounded state). Cross-row guides draw fainter still (a
+     * notional level 4, set in `Layers`). Falls back to a built-in turquoise.
+     */
+    readonly annotation?: {
+        readonly color: string;
+        readonly fillOpacity: number;
+        readonly depth: readonly [number, number, number];
+    };
 }
 /** A resolved line style: stroke colour + width (px). */
 export interface LineStyle {

package/dist/theme.js

@@ -107,6 +107,12 @@ export const defaultTheme = {
     cursor: '#64748b',
     chip: { background: '#ffffff' },
     gap: { connectorOpacity: 0.5 },
+    // Teal marks register — distinct from the blue data, reads on the light ground.
+    annotation: {
+        color: '#0d9488',
+        fillOpacity: 0.1,
+        depth: [1, 0.7, 0.4],
+    },
 };
 /**
  * The estela theme — estela's real `@estela/ui` palette as *one theme*, on its
@@ -228,5 +234,12 @@ export const estelaTheme = {
     cursor: '#7FE2D2', // --es-reef (bright tracker on the dark ground)
     chip: { background: '#0B4E58' }, // --es-deep (panel behind readout text)
     gap: { connectorOpacity: 0.5 },
+    // Marks register: --es-reef, estela's bright attention turquoise (the same hue
+    // as the cursor / selected highlight) — distinct from the foam (white) data.
+    annotation: {
+        color: '#7FE2D2', // --es-reef
+        fillOpacity: 0.1,
+        depth: [1, 0.7, 0.4],
+    },
 };
 //# sourceMappingURL=theme.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.31.0",
-    "pond-ts": "^0.31.0",
+    "@pond-ts/react": "^0.32.0",
+    "pond-ts": "^0.32.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {