@pond-ts/charts 0.31.1 → 0.32.0

package/dist/Layers.js

@@ -1,10 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
 import { drawGrid } from './grid.js';
 import { cursorParts } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange } from './viewport.js';
+import { flagChipStyle, flagChipX } from './chip.js';
 import { ContainerContext, LayersContext, RowContext, } from './context.js';
 /** Gridline tick count — matches the axes (`YAxis`/`TimeAxis`) so they align. */
 const GRID_TICKS = 5;
@@ -48,7 +49,7 @@ export function Layers({ children }) {
     }), [row.registerLayer, row.unregisterLayer]);
     const background = container.theme.background;
     const { grid: gridColor, gridDash } = container.theme.axis;
-    const { layers, yScales, formats, defaultAxisId } = row;
+    const { layers, yScales, formats, defaultAxisId, tickValues } = row;
     // x geometry is shared and lives on the container (uniform across rows).
     const { xScale, plotWidth } = container;
     const draw = useCallback((ctx, w, h) => {
@@ -59,8 +60,13 @@ export function Layers({ children }) {
         // Gridlines behind the data, from the same ticks the axes label: vertical
         // from the shared time scale, horizontal from the row's default y-axis.
         const gridY = yScales.get(defaultAxisId);
+        // Explicit `<YAxis ticks>` drive the gridlines too, so they align with the
+        // axis labels; otherwise d3 auto-picks (the default).
+        const explicitY = tickValues.get(defaultAxisId);
         const xTicks = xScale.ticks(GRID_TICKS).map((d) => xScale(d));
-        const yTicks = gridY ? gridY.ticks(GRID_TICKS).map((t) => gridY(t)) : [];
+        const yTicks = gridY
+            ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
+            : [];
         drawGrid(ctx, xTicks, yTicks, w, h, gridColor, gridDash);
         for (const entry of layers) {
             const yScale = yScales.get(entry.axisId ?? defaultAxisId);
@@ -68,7 +74,16 @@ export function Layers({ children }) {
                 continue;
             entry.layer.draw(ctx, xScale, yScale);
         }
-    }, [layers, yScales, xScale, defaultAxisId, background, gridColor, gridDash]);
+    }, [
+        layers,
+        yScales,
+        xScale,
+        defaultAxisId,
+        tickValues,
+        background,
+        gridColor,
+        gridDash,
+    ]);
     // Interaction overlay: the cursor marks live on a DOM/SVG overlay above the
     // data, so hovering never repaints the data canvas (whose `draw` doesn't depend
     // on the cursor). Reading the container's cursorX — set by whichever row the
@@ -79,7 +94,13 @@ export function Layers({ children }) {
     // Cursor mode: the row's override, else the container default. One mode per
     // row (the synced vertical line is shared across rows); each layer renders the
     // mode in its own way. `parts` decomposes it into {line, dots, chip}.
-    const parts = cursorParts(row.cursor ?? container.cursor);
+    // Editing suppresses the data cursor — the marks get the surface (hover/drag),
+    // and a crosshair would just be noise. True in global edit mode *and* while a
+    // single annotation is being edited (the double-click target).
+    const editingActive = container.editAnnotations || container.annotations.some((a) => a.editing);
+    const parts = editingActive
+        ? cursorParts('none')
+        : cursorParts(row.cursor ?? container.cursor);
     const cursorColor = container.theme.cursor ?? container.theme.axis.label;
     // Only read a time when the cursor is within the plot. An out-of-bounds
     // controlled trackerPosition hides the cursor, so the dots + chips hide too —
@@ -181,9 +202,31 @@ export function Layers({ children }) {
     });
     // Pointer-down position, to tell a click (select) from the tail of a drag/pan.
     const clickStartRef = useRef(null);
+    // Create gesture (when a tool is armed): `createPt` is the live pointer driving
+    // the preview on the hovered row; `drawFrom` is a region's fixed start edge (px)
+    // once pressed. `drawFromRef` mirrors it for the stable up-handler to read.
+    const [createPt, setCreatePt] = useState(null);
+    const [drawFrom, setDrawFrom] = useState(null);
+    const drawFromRef = useRef(null);
     const handlePointerDown = useCallback((e) => {
         clickStartRef.current = { x: e.clientX, y: e.clientY };
         const c = containerRef.current;
+        if (c.creating !== null) {
+            // Armed: a region presses to fix its start edge; a line just tracks until
+            // release. Capture so the draw can continue outside the plot.
+            if (c.creating === 'region') {
+                const px = e.clientX - e.currentTarget.getBoundingClientRect().left;
+                drawFromRef.current = px;
+                setDrawFrom(px);
+            }
+            try {
+                e.currentTarget.setPointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
         if (!c.panZoom)
             return;
         const r = c.timeRange;
@@ -201,6 +244,13 @@ export function Layers({ children }) {
     }, []);
     const handlePointerMove = useCallback((e) => {
         const c = containerRef.current;
+        if (c.creating !== null) {
+            const rect = e.currentTarget.getBoundingClientRect();
+            const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+            setCreatePt({ x: px, y: e.clientY - rect.top });
+            c.setHoverX(px); // share the preview x so other rows draw a guide there
+            return;
+        }
         const drag = dragRef.current;
         if (drag) {
             // Pan from the start range by the total drag — right → earlier (−dt).
@@ -227,6 +277,48 @@ export function Layers({ children }) {
         c.setHovered(hit);
     }, []);
     const handlePointerUp = useCallback((e) => {
+        const c = containerRef.current;
+        if (c.creating !== null) {
+            const rect = e.currentTarget.getBoundingClientRect();
+            const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+            const py = e.clientY - rect.top;
+            if (c.creating === 'marker') {
+                c.onCreate?.({ kind: 'marker', at: +c.xScale.invert(px) });
+            }
+            else if (c.creating === 'baseline') {
+                const r = rowRef.current;
+                const ys = r.yScales.get(r.defaultAxisId);
+                if (ys) {
+                    c.onCreate?.({
+                        kind: 'baseline',
+                        value: ys.invert(py),
+                        axis: r.defaultAxisId,
+                    });
+                }
+            }
+            else if (c.creating === 'region') {
+                const fromPx = drawFromRef.current;
+                // Need a real drag — a click (no span) creates nothing.
+                if (fromPx !== null && Math.abs(px - fromPx) > DRAG_SLOP) {
+                    const a = +c.xScale.invert(fromPx);
+                    const b = +c.xScale.invert(px);
+                    c.onCreate?.({
+                        kind: 'region',
+                        from: Math.min(a, b),
+                        to: Math.max(a, b),
+                    });
+                }
+            }
+            drawFromRef.current = null;
+            setDrawFrom(null);
+            try {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
         if (dragRef.current) {
             dragRef.current = null;
             try {
@@ -239,17 +331,36 @@ export function Layers({ children }) {
     }, []);
     const handlePointerLeave = useCallback(() => {
         const c = containerRef.current;
+        if (c.creating !== null) {
+            // Leaving mid-arm cancels the preview (and an in-progress region draw).
+            setCreatePt(null);
+            drawFromRef.current = null;
+            setDrawFrom(null);
+            c.setHoverX(null);
+            return;
+        }
         c.setHoverX(null);
         c.setHovered(null);
     }, []);
     // Click selection: ignore the click that ends a drag/pan (moved past a few px),
     // else hit-test the row's layers top-down and select — or clear on a miss.
     const handleClick = useCallback((e) => {
+        if (containerRef.current.creating !== null)
+            return; // the draw owns the click
         const start = clickStartRef.current;
         if (start &&
             Math.hypot(e.clientX - start.x, e.clientY - start.y) > DRAG_SLOP)
             return;
         const c = containerRef.current;
+        // A click that reached the plot (no mark's DragArea claimed it) is an empty
+        // click. Deselect / exit edit when the consumer is tracking annotations — in
+        // global edit mode, or whenever a mark is currently active (a selected mark, or
+        // the single-edit target, which also reads as selected). Marks stop their own
+        // clicks in DragArea, so this only fires on true empty space.
+        if (c.editAnnotations || c.annotations.some((a) => a.selected)) {
+            c.onSelectAnnotation?.(null);
+            return;
+        }
         const r = rowRef.current;
         const rect = e.currentTarget.getBoundingClientRect();
         const hit = resolveSelection(r.layers, e.clientX - rect.left, e.clientY - rect.top, c.xScale, (axisId) => r.yScales.get(axisId ?? r.defaultAxisId));
@@ -281,19 +392,9 @@ export function Layers({ children }) {
     // dot ('inline', clamped within the row) or stack at the top of the flag staff
     // ('flag'). line / point / none draw no chips — surface values off-chart.
     const flagLineHeight = container.theme.font.size + 5;
-    const chipStyle = {
-        position: 'absolute',
-        background: container.theme.chip?.background,
-        border: `1px solid ${gridColor}`,
-        borderRadius: '3px',
-        padding: '0 4px',
-        fontFamily: container.theme.font.family,
-        fontSize: `${container.theme.font.size}px`,
-        fontVariantNumeric: 'tabular-nums',
-        whiteSpace: 'nowrap',
-        pointerEvents: 'none',
-        lineHeight: 1.5,
-    };
+    // Cursor chips share the annotation label look (filled, no outline) — one
+    // source of truth so a flag and a placed label read as the same object.
+    const chipStyle = flagChipStyle(container.theme);
     // Show the cursor's time atop the readout (opt-in via `cursorTime`), whenever
     // the cursor is active (any mode that draws marks). A single chip at the cursor
     // x, top of the row; for `flag` it sits above the value chips (which shift down).
@@ -304,96 +405,135 @@ export function Layers({ children }) {
         cursorTime !== null &&
         (parts.line || parts.dots) &&
         row.isFirstRow;
-    // Flag stacking geometry: chips stack from `flagBase` (below the time chip when
-    // shown); each staff rises from its dot up to `stackBottom` (the stack's foot).
+    // Flag geometry: each value flies as a flag from the top of its own staff — the
+    // chip's top sits at `flagBase` (just below the time chip when shown) and the
+    // staff drops from there to the dot. (Chips share that top and spread by x, so
+    // near-coincident flags can overlap — a de-overlap heuristic is a follow-up.)
     const flagTop = 2;
     const flagBase = flagTop + (showTime ? flagLineHeight : 0);
-    const stackBottom = flagBase + trackerSamples.length * flagLineHeight;
     // The cursor-time chip caps the readout. In `flag` mode it tops the flag stack,
     // so anchor it to the stack's x (the nearest sample's point) so time + flag +
     // staff + dot read as one column; otherwise it labels the cursor line at cursorX.
     const timeX = parts.chip === 'flag' && trackerSamples.length > 0
         ? trackerSamples[0].px
         : cursorX;
+    // Cross-row guide lines: the x-positions of annotations on the OTHER rows
+    // (markers + region edges), so a mark on one row reads against this row's data +
+    // the shared x axis. A mark's own row skips itself; baselines cast no vertical
+    // guide (empty `xs`). Faint + dashed so they read as reference, not data.
+    const guideXs = container.annotations
+        .filter((a) => a.rowKey !== row.rowKey)
+        .flatMap((a) => a.xs)
+        .map((xv) => xScale(xv));
+    const guideColor = container.theme.annotation?.color ?? gridColor;
+    // Create preview: while a tool is armed, the hovered row (the one with
+    // `createPt`) shows a cursor-style line tracking the pointer — vertical for
+    // marker/region, horizontal for baseline, a span once a region is being dragged.
+    // The OTHER rows show the faint guide at the shared preview x (markers/regions).
+    const creating = container.creating;
+    let createPreview = null;
+    if (creating !== null && createPt !== null) {
+        if (creating === 'baseline') {
+            createPreview = (_jsx("line", { x1: 0, y1: createPt.y, x2: plotWidth, y2: createPt.y, stroke: guideColor, strokeWidth: 1, opacity: 0.85, shapeRendering: "crispEdges" }));
+        }
+        else if (drawFrom !== null) {
+            const l = Math.min(drawFrom, createPt.x);
+            const w = Math.abs(createPt.x - drawFrom);
+            createPreview = (_jsxs(_Fragment, { children: [_jsx("rect", { x: l, y: 0, width: w, height: row.height, fill: guideColor, opacity: 0.12 }), _jsx("line", { x1: drawFrom, y1: 0, x2: drawFrom, y2: row.height, stroke: guideColor, strokeWidth: 1, opacity: 0.85, strokeDasharray: "3 2", shapeRendering: "crispEdges" }), _jsx("line", { x1: createPt.x, y1: 0, x2: createPt.x, y2: row.height, stroke: guideColor, strokeWidth: 1, opacity: 0.85, shapeRendering: "crispEdges" })] }));
+        }
+        else {
+            createPreview = (_jsx("line", { x1: createPt.x, y1: 0, x2: createPt.x, y2: row.height, stroke: guideColor, strokeWidth: 1, opacity: 0.85, shapeRendering: "crispEdges" }));
+        }
+    }
+    else if (creating !== null && creating !== 'baseline' && cursorX !== null) {
+        // Another row — the faint preview guide at the shared pointer x.
+        createPreview = (_jsx("line", { x1: cursorX, y1: 0, x2: cursorX, y2: row.height, stroke: guideColor, strokeWidth: 1, opacity: 0.22, strokeDasharray: "2 3", shapeRendering: "crispEdges" }));
+    }
     // Inject each draw layer's JSX position so it registers its declaration order
     // (z-stack: lower index at the back), independent of mount timing.
     const indexedChildren = Children.map(children, (child, index) => isValidElement(child)
         ? cloneElement(child, { index })
         : child);
-    return (_jsxs(LayersContext.Provider, { value: registry, children: [_jsxs("div", { ref: plotRef, style: {
-                    position: 'relative',
-                    width: `${plotWidth}px`,
-                    height: `${row.height}px`,
-                    cursor: 'crosshair',
-                    // Let pan/zoom own touch gestures (no native scroll) when enabled.
-                    touchAction: container.panZoom ? 'none' : 'auto',
-                }, onPointerMove: handlePointerMove, onPointerDown: handlePointerDown, onPointerUp: handlePointerUp, onPointerCancel: handlePointerUp, onPointerLeave: handlePointerLeave, onClick: handleClick, children: [_jsx(Canvas, { width: plotWidth, height: row.height, draw: draw }), _jsxs("svg", { width: plotWidth, height: row.height, style: {
-                            position: 'absolute',
-                            top: 0,
-                            left: 0,
-                            pointerEvents: 'none',
-                        }, children: [parts.line &&
-                                cursorX !== null &&
-                                cursorX >= 0 &&
-                                cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&
-                                trackerSamples.map((s, i) => s.py > stackBottom ? (_jsx("line", { x1: s.px, y1: stackBottom, x2: s.px, y2: s.py, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `staff-${i}`)) : null), parts.chip === 'flag' &&
-                                trackerFlags.map((f, i) => {
-                                    // One horizontal row of values → a single-line chip.
-                                    const flagBottom = flagBase + flagLineHeight;
-                                    return f.topPy > flagBottom ? (_jsx("line", { x1: f.px, y1: flagBottom, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null;
-                                }), parts.dots &&
-                                trackerSamples.map((s, i) => (_jsx("circle", { cx: s.px, cy: s.py, r: 3, fill: s.color, stroke: background, strokeWidth: background ? 1 : 0 }, `dot-${i}`)))] }), showTime && timeX !== null && cursorTime !== null && (_jsx("div", { style: {
+    return (_jsx(LayersContext.Provider, { value: registry, children: _jsxs("div", { ref: plotRef, style: {
+                position: 'relative',
+                width: `${plotWidth}px`,
+                height: `${row.height}px`,
+                // Edit mode: a plain cursor on the plot (the annotations supply their
+                // own grab/resize cursors); crosshair only when the data cursor is live
+                // (suppressed in single-annotation edit too, not just global edit).
+                cursor: editingActive ? 'default' : 'crosshair',
+                // The turquoise edit border — the "you're in *global* Edit" signal (not
+                // single-annotation edit). Inset shadow so it doesn't shift layout.
+                boxShadow: container.editAnnotations
+                    ? `inset 0 0 0 1px ${guideColor}`
+                    : undefined,
+                // Let pan/zoom own touch gestures (no native scroll) when enabled.
+                touchAction: container.panZoom ? 'none' : 'auto',
+            }, onPointerMove: handlePointerMove, onPointerDown: handlePointerDown, onPointerUp: handlePointerUp, onPointerCancel: handlePointerUp, onPointerLeave: handlePointerLeave, onClick: handleClick, children: [_jsx(Canvas, { width: plotWidth, height: row.height, draw: draw }), guideXs.length > 0 && (_jsx("svg", { width: plotWidth, height: row.height, style: {
+                        position: 'absolute',
+                        top: 0,
+                        left: 0,
+                        pointerEvents: 'none',
+                    }, children: guideXs.map((gx, i) => (_jsx("line", { x1: gx, y1: 0, x2: gx, y2: row.height, stroke: guideColor, strokeWidth: 1, opacity: 0.22, strokeDasharray: "2 3", shapeRendering: "crispEdges" }, i))) })), createPreview !== null && (_jsx("svg", { width: plotWidth, height: row.height, style: {
+                        position: 'absolute',
+                        top: 0,
+                        left: 0,
+                        pointerEvents: 'none',
+                    }, children: createPreview })), indexedChildren, _jsxs("svg", { width: plotWidth, height: row.height, style: {
+                        position: 'absolute',
+                        top: 0,
+                        left: 0,
+                        pointerEvents: 'none',
+                    }, children: [parts.line &&
+                            cursorX !== null &&
+                            cursorX >= 0 &&
+                            cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&
+                            trackerSamples.map((s, i) => s.py > flagBase ? (_jsx("line", { x1: s.px, y1: flagBase, x2: s.px, y2: s.py, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `staff-${i}`)) : null), parts.chip === 'flag' &&
+                            trackerFlags.map((f, i) => f.topPy > flagBase ? (_jsx("line", { x1: f.px, y1: flagBase, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null), parts.dots &&
+                            trackerSamples.map((s, i) => (_jsx("circle", { cx: s.px, cy: s.py, r: 3, fill: s.color, stroke: background, strokeWidth: background ? 1 : 0 }, `dot-${i}`)))] }), showTime && timeX !== null && cursorTime !== null && (_jsx("div", { style: {
+                        ...chipStyle,
+                        top: `${flagTop}px`,
+                        left: timeX > plotWidth * LABEL_FLIP_FRACTION
+                            ? undefined
+                            : `${timeX + 4}px`,
+                        right: timeX > plotWidth * LABEL_FLIP_FRACTION
+                            ? `${plotWidth - timeX + 4}px`
+                            : undefined,
+                        color: cursorColor,
+                    }, children: formatTime(cursorTime) })), parts.chip === 'inline' &&
+                    trackerSamples.map((s, i) => {
+                        // Flip the chip left of its dot near the right edge so it stays in-plot.
+                        const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;
+                        // Clamp within the row so a chip near the top/bottom isn't clipped by
+                        // (or spilling into) the neighbouring row. Chip-vs-chip de-overlap is
+                        // a later refinement; this keeps each chip inside its own row.
+                        const top = Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, s.py));
+                        return (_jsx("div", { style: {
+                                ...chipStyle,
+                                top: `${top}px`,
+                                transform: 'translateY(-50%)',
+                                left: flip ? undefined : `${s.px + 8}px`,
+                                right: flip ? `${plotWidth - s.px + 8}px` : undefined,
+                                color: s.color,
+                            }, children: s.format(s.value) }, i));
+                    }), parts.chip === 'flag' &&
+                    cursorX !== null &&
+                    trackerSamples.map((s, i) => (
+                    // The flag flies from the top of its staff — chip top at the staff top
+                    // (`flagBase`), beside the pole at the point's x (shared `flagChipX`).
+                    _jsx("div", { style: {
+                            ...chipStyle,
+                            top: `${flagBase}px`,
+                            ...flagChipX(s.px, plotWidth),
+                            color: s.color,
+                        }, children: s.format(s.value) }, i))), parts.chip === 'flag' &&
+                    trackerFlags.map((f, i) => (_jsx("div", { style: {
                             ...chipStyle,
-                            top: `${flagTop}px`,
-                            left: timeX > plotWidth * LABEL_FLIP_FRACTION
-                                ? undefined
-                                : `${timeX + 4}px`,
-                            right: timeX > plotWidth * LABEL_FLIP_FRACTION
-                                ? `${plotWidth - timeX + 4}px`
-                                : undefined,
-                            color: cursorColor,
-                        }, children: formatTime(cursorTime) })), parts.chip === 'inline' &&
-                        trackerSamples.map((s, i) => {
-                            // Flip the chip left of its dot near the right edge so it stays in-plot.
-                            const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;
-                            // Clamp within the row so a chip near the top/bottom isn't clipped by
-                            // (or spilling into) the neighbouring row. Chip-vs-chip de-overlap is
-                            // a later refinement; this keeps each chip inside its own row.
-                            const top = Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, s.py));
-                            return (_jsx("div", { style: {
-                                    ...chipStyle,
-                                    top: `${top}px`,
-                                    transform: 'translateY(-50%)',
-                                    left: flip ? undefined : `${s.px + 8}px`,
-                                    right: flip ? `${plotWidth - s.px + 8}px` : undefined,
-                                    color: s.color,
-                                }, children: s.format(s.value) }, i));
-                        }), parts.chip === 'flag' &&
-                        cursorX !== null &&
-                        trackerSamples.map((s, i) => {
-                            // Each flag caps its own staff — anchored to the data point's x
-                            // (`s.px`), riding the point with the dot + staff, not the cursor.
-                            // Flip left near the right edge so it stays in-plot.
-                            const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;
-                            return (_jsx("div", { style: {
-                                    ...chipStyle,
-                                    top: `${flagBase + i * flagLineHeight}px`,
-                                    left: flip ? undefined : `${s.px + 4}px`,
-                                    right: flip ? `${plotWidth - s.px + 4}px` : undefined,
-                                    color: s.color,
-                                }, children: s.format(s.value) }, i));
-                        }), parts.chip === 'flag' &&
-                        trackerFlags.map((f, i) => {
-                            const flip = f.px > plotWidth * LABEL_FLIP_FRACTION;
-                            return (_jsx("div", { style: {
-                                    ...chipStyle,
-                                    top: `${flagBase}px`,
-                                    left: flip ? undefined : `${f.px + 4}px`,
-                                    right: flip ? `${plotWidth - f.px + 4}px` : undefined,
-                                    display: 'flex',
-                                    flexDirection: 'row',
-                                    gap: '6px',
-                                }, children: f.lines.map((l, j) => (_jsx("span", { style: { color: l.color }, children: l.text }, j))) }, `boxflag-${i}`));
-                        })] }), indexedChildren] }));
+                            top: `${flagBase}px`,
+                            ...flagChipX(f.px, plotWidth),
+                            display: 'flex',
+                            flexDirection: 'row',
+                            gap: '6px',
+                        }, children: f.lines.map((l, j) => (_jsx("span", { style: { color: l.color }, children: l.text }, j))) }, `boxflag-${i}`)))] }) }));
 }
 //# sourceMappingURL=Layers.js.map

package/dist/YAxis.d.ts

@@ -22,6 +22,21 @@ export interface YAxisProps {
      * (e.g. `',.2f'`) when you want finer readout precision. See {@link AxisFormat}.
      */
     format?: AxisFormat;
+    /**
+     * Explicit ticks — `{ at, label }` in axis-value units — instead of the
+     * scale's automatic ticks, driving BOTH the labels and the row's gridlines so
+     * the two align. The y-axis counterpart of `<XAxis ticks>` (same shape): the
+     * lever for a non-uniform axis like pace, where the caller chooses round-pace
+     * positions and their own `m:ss` labels (`{ at: -300, label: '5:00' }`). `at`
+     * values outside `[min, max]` extrapolate off-plot (the scale does not clamp).
+     * Pass `[]` to draw none. For a live / animating chart, **memoize the array** —
+     * an inline `ticks={[…]}` is a fresh reference each render and re-registers the
+     * axis (like `format`; harmless for a static chart).
+     */
+    ticks?: ReadonlyArray<{
+        readonly at: number;
+        readonly label: string;
+    }>;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
     /**
@@ -38,5 +53,5 @@ export interface YAxisProps {
  * 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;
+export declare function YAxis({ id, side, label, min, max, format, ticks, width, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -13,7 +13,7 @@ const TICK_COUNT = 5;
  * 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, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, width = DEFAULT_WIDTH, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -22,7 +22,16 @@ export function YAxis({ id, side = 'left', label, min, max, format, width = DEFA
     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]);
+    const spec = useMemo(() => ({
+        id,
+        side,
+        width,
+        min,
+        max,
+        format,
+        tickValues: ticks?.map((t) => t.at),
+        index,
+    }), [id, side, width, min, max, format, ticks, 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
@@ -37,10 +46,17 @@ export function YAxis({ id, side = 'left', label, min, max, format, width = DEFA
     }, [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;
+    // Explicit `{ at, label }` ticks render verbatim (each label at its `at`),
+    // overriding the auto-picked d3 ticks; otherwise label the scale's ticks via `fmt`.
+    const tickList = ticks
+        ? ticks.map((t) => ({ value: t.at, label: t.label }))
+        : (yScale ? yScale.ticks(TICK_COUNT) : []).map((t) => ({
+            value: t,
+            label: fmt(t),
+        }));
     // 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
@@ -60,13 +76,13 @@ export function YAxis({ id, side = 'left', label, min, max, format, width = DEFA
                 fontSize: `${theme.font.size}px`,
                 color: theme.axis.label,
             }, children: [yScale &&
-                    ticks.map((t) => (_jsx("div", { style: {
+                    tickList.map(({ value, label }) => (_jsx("div", { style: {
                             position: 'absolute',
-                            top: `${yScale(t)}px`,
+                            top: `${yScale(value)}px`,
                             [side === 'left' ? 'right' : 'left']: '4px',
                             transform: 'translateY(-50%)',
                             whiteSpace: 'nowrap',
-                        }, children: fmt(t) }, t))), _jsx("div", { style: {
+                        }, children: label }, value))), _jsx("div", { style: {
                         position: 'absolute',
                         [side === 'left' ? 'left' : 'right']: '1px',
                         top: 0,

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