@pond-ts/charts 0.31.2 → 0.33.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.31.2...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.33.0...HEAD
+[0.33.0]: https://github.com/pjm17971/pond-ts/compare/v0.32.0...v0.33.0
+[0.32.0]: https://github.com/pjm17971/pond-ts/compare/v0.31.2...v0.32.0
 [0.31.2]: https://github.com/pjm17971/pond-ts/compare/v0.31.1...v0.31.2
 [0.31.1]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...v0.31.1
 [0.31.0]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...3c4e8bd
@@ -26,6 +28,78 @@ patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
+## [0.33.0] — 2026-06-30
+
+A `@pond-ts/charts` release: a label opt-out for annotations plus interaction
+fixes from an adversarial review of the #306 annotation system. `pond-ts`,
+`@pond-ts/react`, and `@pond-ts/fit` carry no code changes — republished in
+lock-step (their `pond-ts` / `@pond-ts/react` peer ranges widen to `^0.33.0`).
+
+### Added
+
+- **Charts — annotation label opt-out.** `<Region>`, `<Marker>`, and
+  `<Baseline>` accept `label={false}` (or `label=""`) to render **no label
+  chip** — for an inert background mark (e.g. a `selectable={false}` highlight
+  band) where the auto-label would only show a raw axis value. Omitting `label`
+  still auto-labels; a string still renders it. `label` widens to
+  `string | false`. New `Highlight` story + Linux e2e baselines for the
+  `Annotations` stories. (#308)
+
+### Changed
+
+- **Charts — `<Region>` / `<Marker>` / `<Baseline>` with `label=""` now render
+  no chip** (previously an empty, zero-width chip). The label-less path; pass a
+  non-empty string for a visible label. (#308)
+
+### Fixed
+
+- **Charts — annotation edge-resize no longer inverts.** Dragging a `<Region>`
+  edge past the opposite one previously reported `{ from > to }`; it now pivots
+  around the fixed opposite edge, so the reported span stays ordered and a drag
+  either way re-opens the region instead of dead-ending at zero width. (#308)
+- **Charts — annotation drag releases on `pointercancel`.** A system gesture
+  takeover (which fires `pointercancel`, not `pointerup`) no longer leaves a mark
+  stuck mid-drag. (#308)
+- **Charts — single-annotation edit exits on an empty-plot click** even when the
+  mark is `editing` but not `selected`. (#308)
+
+## [0.32.0] — 2026-06-29
+
+A `@pond-ts/charts` release: value-axis support across the fill/bar layers, plus
+explicit y-axis ticks and the annotation primitives. `pond-ts`,
+`@pond-ts/react`, and `@pond-ts/fit` are unchanged this cycle — republished in
+lock-step at the same version.
+
+### Added
+
+- **Charts — explicit y-axis ticks.** `<YAxis ticks={[{ at, label }]}>` places
+  ticks (and their gridlines) at chosen values with custom labels, mirroring
+  `<XAxis ticks>`; `ticks={[]}` draws none. (#303)
+- **Charts — value-axis (`ValueSeries`) support for `<AreaChart>`,
+  `<BandChart>`, and `<BarChart>`.** Each now accepts a `ValueSeries`
+  (`series.byValue('dist')`) and plots against its monotonic value axis
+  (distance, cumulative work, …), not just time — joining `<LineChart>`, which
+  already did. The container infers the x-axis kind from the data, so there is
+  no axis-type prop. `BarChart` derives each bar's span from neighbour spacing
+  on a point-keyed value axis (the splits/laps case). (#304, #307)
+- **Charts — annotations: `<Region>`, `<Marker>`, `<Baseline>`.** User-authored
+  marks in a distinct register — a shaded x-span, a vertical x line, and a
+  horizontal value line — with flag labels, a three-level depth ramp, and opt-in
+  interaction modes (inspect-select, single-edit, drag-resize, create-tool
+  gestures) coordinated by the container (cross-row guide lines,
+  snap-to-guideline, z-order). Adds `ChartContainer` annotation props
+  (`creating` / `editAnnotations` / `onCreate` / `onSelectAnnotation` /
+  `onHoverAnnotation` / `onEditAnnotation` / `snap`) and a `ChartTheme.annotation`
+  depth theme. (#306)
+
+### Changed
+
+- **Charts — the fill/bar layer `series` prop widens (additive).**
+  `AreaChartProps` / `BandChartProps` / `BarChartProps` now accept
+  `TimeSeries | ValueSeries`; the new second generic defaults, so existing
+  one-type-argument uses (`AreaChartProps<S>`, `<AreaChart<S>>`) compile
+  unchanged. (#304, #307)
+
 ## [0.31.2] — 2026-06-29
 
 ### Fixed

package/dist/AreaChart.d.ts

@@ -1,9 +1,15 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } 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>;
+export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` fills against the time axis; a
+     * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
+     * container infers which from the data, no axis-type prop (mirrors
+     * `<LineChart>`). Either way `column` names the numeric value to fill from.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to fill from. */
     column: string;
     /**
@@ -81,5 +87,5 @@ export interface AreaChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, index, }: AreaChartProps<S>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, index, }: AreaChartProps<S, VS>): null;
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,5 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { fromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { fromTimeSeries, fromValueSeries } 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';
@@ -43,7 +44,9 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     if (layers === null) {
         throw new Error('<AreaChart> must be rendered inside a <Layers>');
     }
-    const cs = useMemo(() => fromTimeSeries(series, column), [series, column]);
+    const cs = useMemo(() => series instanceof ValueSeries
+        ? fromValueSeries(series, column)
+        : 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;
@@ -56,17 +59,27 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => areaExtent(cs, baseline),
-            xKind: 'time',
+            // The container infers the shared x scale's kind from its layers — a
+            // ValueSeries plots on a value axis, a TimeSeries on time.
+            xKind: series instanceof ValueSeries ? 'value' : '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]) {
+            sampleAt: (x) => {
+                // No readout past the data (tracker policy — nearest clamps to an
+                // endpoint outside the span); bounds from the columnar x axis.
+                if (cs.length === 0 || x < cs.x[0] || x > cs.x[cs.length - 1]) {
                     return [];
                 }
-                const e = series.nearest(time);
+                if (series instanceof ValueSeries) {
+                    // Value axis: bisect the axis for the nearest row, read y from `cs`.
+                    const i = series.nearestIndex(x);
+                    if (i < 0)
+                        return [];
+                    const v = cs.y[i];
+                    return Number.isFinite(v)
+                        ? [{ x: cs.x[i], value: v, color: style.color, label }]
+                        : [];
+                }
+                const e = series.nearest(x);
                 if (e === undefined)
                     return [];
                 // get() wants a literal key; column is a runtime string. Cast the

package/dist/BandChart.d.ts

@@ -1,8 +1,15 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } 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>;
+export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` fills the envelope against the time axis;
+     * a `ValueSeries` (`series.byValue('dist')`) against its value axis — the
+     * container infers which from the data, no axis-type prop (mirrors
+     * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
+     * edge columns.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
     /** 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`). */
@@ -51,5 +58,5 @@ export interface BandChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function BandChart<S extends SeriesSchema>({ series, lower, upper, as: semantic, axis, curve, index, }: BandChartProps<S>): null;
+export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, index, }: BandChartProps<S, VS>): null;
 //# sourceMappingURL=BandChart.d.ts.map

package/dist/BandChart.js

@@ -1,5 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { bandFromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { bandFromTimeSeries, bandFromValueSeries } from './data.js';
 import { bandExtent, drawBand } from './band.js';
 import { resolveCurve } from './curve.js';
 import { ContainerContext, LayersContext } from './context.js';
@@ -30,7 +31,9 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
     if (layers === null) {
         throw new Error('<BandChart> must be rendered inside a <Layers>');
     }
-    const bs = useMemo(() => bandFromTimeSeries(series, lower, upper), [series, lower, upper]);
+    const bs = useMemo(() => series instanceof ValueSeries
+        ? bandFromValueSeries(series, lower, upper)
+        : 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;
@@ -38,17 +41,32 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, ind
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => bandExtent(bs),
-            xKind: 'time',
+            // The container infers the shared x scale's kind from its layers — a
+            // ValueSeries plots on a value axis, a TimeSeries on time.
+            xKind: series instanceof ValueSeries ? 'value' : '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]) {
+            sampleAt: (x) => {
+                // No readout past the data (tracker policy — nearest clamps); bounds
+                // from the columnar x axis.
+                if (bs.length === 0 || x < bs.x[0] || x > bs.x[bs.length - 1]) {
                     return [];
                 }
-                const e = series.nearest(time);
+                if (series instanceof ValueSeries) {
+                    // Value axis: bisect the axis for the nearest row, read both edges
+                    // from `bs`. A gap on either edge yields no readout (like the fill).
+                    const i = series.nearestIndex(x);
+                    if (i < 0)
+                        return [];
+                    const lo = bs.lower[i];
+                    const hi = bs.upper[i];
+                    if (!Number.isFinite(lo) || !Number.isFinite(hi))
+                        return [];
+                    return [
+                        { x: bs.x[i], value: lo, color: style.fill, label: lower },
+                        { x: bs.x[i], value: hi, color: style.fill, label: upper },
+                    ];
+                }
+                const e = series.nearest(x);
                 if (e === undefined)
                     return [];
                 // get() wants a literal key; lower/upper are runtime strings. Cast the

package/dist/BarChart.d.ts

@@ -1,12 +1,17 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
-export interface BarChartProps<S extends SeriesSchema> {
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
-     * 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}).
+     * The source series. **Interval / timeRange-keyed** `TimeSeries` 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}). A **`ValueSeries`**
+     * (`series.byValue('dist')`) bars against its value axis — also point-keyed, so
+     * the same neighbour-spacing span applies (see {@link barsFromValueSeries}); the
+     * container infers the x-kind from the data, no axis-type prop (mirrors the
+     * other layers).
      */
-    series: TimeSeries<S>;
+    series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column for the bar height. */
     column: string;
     /**
@@ -58,9 +63,10 @@ export interface BarChartProps<S extends SeriesSchema> {
  * 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).
+ * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
+ * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
+ * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is
+ * neighbour-derived like a point `TimeSeries` (see {@link barsFromValueSeries}).
  *
  * ```tsx
  * <Layers>
@@ -68,5 +74,5 @@ export interface BarChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema>({ series, column, as: semantic, axis, gap, index, }: BarChartProps<S>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, gap, index, }: BarChartProps<S, VS>): null;
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -1,5 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { barsFromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { barsFromTimeSeries, barsFromValueSeries } 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';
@@ -25,9 +26,10 @@ import { useSlotKey } from './use-slot-key.js';
  * 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).
+ * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
+ * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
+ * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is
+ * neighbour-derived like a point `TimeSeries` (see {@link barsFromValueSeries}).
  *
  * ```tsx
  * <Layers>
@@ -44,7 +46,9 @@ export function BarChart({ series, column, as: semantic, axis, gap, index = 0, }
     if (layers === null) {
         throw new Error('<BarChart> must be rendered inside a <Layers>');
     }
-    const bs = useMemo(() => barsFromTimeSeries(series, column), [series, column]);
+    const bs = useMemo(() => series instanceof ValueSeries
+        ? barsFromValueSeries(series, column)
+        : 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;
@@ -69,7 +73,9 @@ export function BarChart({ series, column, as: semantic, axis, gap, index = 0, }
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => barExtent(bs),
-            xKind: 'time',
+            // The container infers the shared x scale's kind from its layers — a
+            // ValueSeries bars on a value axis, a TimeSeries on time.
+            xKind: series instanceof ValueSeries ? 'value' : '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

package/dist/ChartContainer.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { TimeRange } from 'pond-ts';
-import { type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
+import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
 import { type AxisFormat } from './format.js';
 import { type ChartTheme } from './theme.js';
 export interface ChartContainerProps {
@@ -82,6 +82,49 @@ export interface ChartContainerProps {
      * axis.
      */
     cursorTime?: boolean;
+    /**
+     * Enter **annotation-edit mode**: suppresses the data cursor and makes editable
+     * annotations (those given an `onChange`) interactive — hovering one reveals its
+     * handles + highlights it, and dragging edits it. **Default `false`.** Pairs
+     * with each annotation's `onChange` (where the edit goes); this is the mode that
+     * turns the affordances on and gets the cursor out of the way.
+     */
+    editAnnotations?: boolean;
+    /**
+     * The armed annotation **creation tool** (the consumer's toolbar sets it), or
+     * `null`/omitted for idle. When set, the plot captures a create gesture — a
+     * preview tracks the pointer, and on release {@link onCreate} fires. The consumer
+     * then adds the mark, disarms (back to `null`), and selects it (spring-loaded);
+     * keep it set to place several. Requires {@link editAnnotations}.
+     */
+    creating?: AnnotationKind | null;
+    /** Fired when a create gesture completes (on release). See {@link CreateSpec}. */
+    onCreate?: (spec: CreateSpec) => void;
+    /**
+     * Fired when an annotation is clicked (its `id`), the plot is clicked empty
+     * (`null`), or a region is double-clicked (the shortcut into edit). The consumer
+     * holds the selected id and sets each mark's `selected={id === sel}`.
+     */
+    onSelectAnnotation?: (id: string | null) => void;
+    /**
+     * Fired when the pointer enters an annotation (its `id`) or leaves it (`null`).
+     * Mirror it to a controlled `hovered` prop on each mark to sync hover both ways
+     * (e.g. a legend row ↔ the mark). Fires in any mode.
+     */
+    onHoverAnnotation?: (id: string | null) => void;
+    /**
+     * Fired when a mark is **double-clicked** — the request to edit just that one
+     * (set its `editing` prop in response). Single click selects (inspect); double
+     * click edits. Works in any mode.
+     */
+    onEditAnnotation?: (id: string) => void;
+    /**
+     * Snap mode (the toolbar's "Snap"). **Default `true`.** When on, a dragged
+     * mark snaps to other marks' **guidelines** (their x-positions, within a few
+     * px) so spans align; off = free placement. (Snapping to the nearest data
+     * sample is not implemented — guideline alignment only.)
+     */
+    snap?: 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
@@ -102,5 +145,5 @@ export interface ChartContainerProps {
  * {@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;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } f
 import { scaleLinear, scaleTime } from 'd3-scale';
 import { ContainerContext, } from './context.js';
 import { maxSlotWidths, sum } from './slots.js';
+import { computeLabelLanes } from './annotations.js';
 import { resolveCursorX, DEFAULT_CURSOR_MODE } from './tracker.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 import { TimeAxis } from './TimeAxis.js';
@@ -30,7 +31,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, timeFormat, theme, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -91,6 +92,21 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             return next;
         });
     }, []);
+    // Annotations register here so the container can do what a mark can't in
+    // isolation: draw its guide line across other rows, order regions, serve snap
+    // targets. Keyed by per-instance slot key (same discipline as the sources).
+    const [annotationMap, setAnnotationMap] = useState(() => new Map());
+    const registerAnnotation = useCallback((key, spec) => setAnnotationMap((m) => new Map(m).set(key, spec)), []);
+    const unregisterAnnotation = useCallback((key) => {
+        setAnnotationMap((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const annotations = useMemo(() => Array.from(annotationMap.values()), [annotationMap]);
     // The shared x scale's kind, **inferred from the registered layers**: a
     // ValueSeries row plots on a value axis, a TimeSeries on time. A container
     // has one shared x (the synced cursor's whole point), so the rows must agree
@@ -238,6 +254,9 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         const values = Array.from(sources.values()).flatMap((s) => s.sampleAt(time));
         cb({ time, values });
     }, [cursorX, xScale, sources, plotWidth]);
+    // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
+    // close-in-x labels don't collide; chips read their lane back off the frame.
+    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v)), [annotations, xScale]);
     const frame = useMemo(() => ({
         timeRange: [d0, d1],
         width,
@@ -256,9 +275,20 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setHovered,
         cursor,
         cursorTime,
+        editAnnotations,
+        creating,
+        snap,
+        onCreate,
+        onSelectAnnotation,
+        onHoverAnnotation,
+        onEditAnnotation,
         formatTime,
         registerTrackerSource,
         unregisterTrackerSource,
+        registerAnnotation,
+        unregisterAnnotation,
+        annotations,
+        labelLanes,
         xScale,
         xKind: resolvedKind,
         panZoom,
@@ -285,9 +315,20 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         setHovered,
         cursor,
         cursorTime,
+        editAnnotations,
+        creating,
+        snap,
+        onCreate,
+        onSelectAnnotation,
+        onHoverAnnotation,
+        onEditAnnotation,
         formatTime,
         registerTrackerSource,
         unregisterTrackerSource,
+        registerAnnotation,
+        unregisterAnnotation,
+        annotations,
+        labelLanes,
         xScale,
         resolvedKind,
         panZoom,

package/dist/ChartRow.js

@@ -92,6 +92,7 @@ export function ChartRow({ height, cursor, children }) {
                 min: undefined,
                 max: undefined,
                 format: undefined,
+                tickValues: undefined,
                 index: 0,
             },
         ], [realAxes]);
@@ -152,12 +153,25 @@ export function ChartRow({ height, cursor, children }) {
         }
         return map;
     }, [effectiveAxes, yScales]);
+    // Explicit tick values per axis (axes that set `<YAxis ticks>`) — so Layers
+    // draws the row's gridlines at the same positions the axis labels, instead of
+    // d3's auto-picked ticks.
+    const tickValues = useMemo(() => {
+        const map = new Map();
+        for (const ax of effectiveAxes) {
+            if (ax.tickValues)
+                map.set(ax.id, ax.tickValues);
+        }
+        return map;
+    }, [effectiveAxes]);
     const frame = useMemo(() => ({
         height,
         cursor,
         isFirstRow,
+        rowKey,
         yScales,
         formats,
+        tickValues,
         defaultAxisId,
         axisSlots,
         registerAxis,
@@ -169,8 +183,10 @@ export function ChartRow({ height, cursor, children }) {
         height,
         cursor,
         isFirstRow,
+        rowKey,
         yScales,
         formats,
+        tickValues,
         defaultAxisId,
         axisSlots,
         registerAxis,