@pond-ts/charts 0.36.0 → 0.38.0

package/dist/annotations.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
 import { ContainerContext, RowContext, } from './context.js';
-import { flagChipStyle, flagChipX } from './chip.js';
+import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
  * User-authored **annotations** — marks you place *on* a chart, in a register
@@ -114,7 +114,7 @@ function useAnnotationFrame(name) {
  *  other rows, order regions, and serve snap targets), keyed by the caller's stable
  *  per-instance slot key; unregister on unmount. `xs` should be memoised by the
  *  caller so the effect only re-runs when the position actually moves. */
-function useRegisterAnnotation(container, key, id, rowKey, kind, xs, selected, selectable, editing, label) {
+function useRegisterAnnotation(container, key, id, rowKey, kind, xs, selected, selectable, editing, label, indicator) {
     const { registerAnnotation, unregisterAnnotation } = container;
     useEffect(() => () => unregisterAnnotation(key), [unregisterAnnotation, key]);
     useEffect(() => {
@@ -128,6 +128,7 @@ function useRegisterAnnotation(container, key, id, rowKey, kind, xs, selected, s
             selectable,
             editing,
             label,
+            indicator,
         });
     }, [
         registerAnnotation,
@@ -140,6 +141,7 @@ function useRegisterAnnotation(container, key, id, rowKey, kind, xs, selected, s
         selectable,
         editing,
         label,
+        indicator,
     ]);
 }
 /** Vertical px between stacked label lanes. */
@@ -338,7 +340,7 @@ function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onD
         } }));
 }
 /** A vertical line at an x position (a time, a distance, a lap boundary). */
-export function Marker({ at, label, id, selected = false, selectable = true, hovered, editing = false, onChange, }) {
+export function Marker({ at, label, id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, }) {
     const { container, row, ann } = useAnnotationFrame('Marker');
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
@@ -350,7 +352,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     const xs = useMemo(() => [at], [at]);
     // `label === false` (or '') ⇒ no chip; omitted ⇒ auto-label off the x formatter.
     const text = label === false ? '' : (label ?? container.formatTime(at));
-    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'marker', xs, selected, selectable, editing, text);
+    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'marker', xs, selected, selectable, editing, text, indicator);
     // No select/edit while a create tool is armed — the chart is in draw mode then.
     const select = id !== undefined && container.creating === null
         ? () => container.onSelectAnnotation?.(id)
@@ -371,7 +373,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
 }
 /** 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 function Baseline({ value, axis, label, id, selected = false, selectable = true, hovered, editing = false, onChange, }) {
+export function Baseline({ value, axis, label, labelSide = 'left', labelPosition = 'center', id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, }) {
     const { container, row, ann } = useAnnotationFrame('Baseline');
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
@@ -388,7 +390,7 @@ export function Baseline({ value, axis, label, id, selected = false, selectable
     // Baselines don't lane-pack (the label anchors at their y, not the top), so
     // this registered string is unused by `computeLabelLanes` — `|| ''` just
     // keeps it a string for `false`/'' (which mean "no label").
-    label || '');
+    label || '', indicator);
     // No select/edit while a create tool is armed — the chart is in draw mode then.
     const select = id !== undefined && container.creating === null
         ? () => container.onSelectAnnotation?.(id)
@@ -411,11 +413,27 @@ export function Baseline({ value, axis, label, id, selected = false, selectable
     const text = label === false ? '' : (label ?? (fmt ? fmt(value) : String(value)));
     // Handle pill near the right end (clears the left-anchored label).
     const handleX = w - 14;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: { top: `${y}px`, left: '2px', transform: 'translateY(-50%)' }, children: text }))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                    top: `${y}px`,
+                    [labelSide === 'right' ? 'right' : 'left']: '2px',
+                    // `center` rides on the line; `above` sits its bottom edge on the line.
+                    transform: labelPosition === 'above'
+                        ? 'translateY(-100%)'
+                        : 'translateY(-50%)',
+                }, children: text })), indicator &&
+                (() => {
+                    const half = container.theme.font.size / 2 + 1;
+                    return (_jsx("div", { style: {
+                            ...axisPillStyle(container.theme, ann.color),
+                            top: `${Math.max(half, Math.min(row.height - half, y))}px`,
+                            transform: 'translateY(-50%)',
+                            ...axisPillX(row.axisSides.get(axisId) ?? 'left', w),
+                        }, children: fmt ? fmt(value) : String(value) }));
+                })()] }));
 }
 /** 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 function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, }) {
+export function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, edges = true, }) {
     const { container, row, ann } = useAnnotationFrame('Region');
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
@@ -429,7 +447,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     const text = label === false
         ? ''
         : (label ?? `${container.formatTime(from)}–${container.formatTime(to)}`);
-    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'region', xs, selected, selectable, editing, text);
+    useRegisterAnnotation(container, selfKey, id, row.rowKey, 'region', xs, selected, selectable, editing, text, false);
     // No select/edit while a create tool is armed — the chart is in draw mode then.
     const select = id !== undefined && container.creating === null
         ? () => container.onSelectAnnotation?.(id)
@@ -460,7 +478,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     // region the other way instead of dead-ending at zero width.
     const edgeRef = useRef(null);
     const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, shapeRendering: "crispEdges" }));
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edge(xa), edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragStart: (px) => {
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edges && edge(xa), edges && edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragStart: (px) => {
                                     dragRef.current = { from, to, startPx: px };
                                 }, onDrag: (px) => {
                                     const s = dragRef.current;

package/dist/chip.d.ts

@@ -13,6 +13,42 @@ import type { ChartTheme } from './theme.js';
  * contrasting chip background) — a token to settle before this ships.
  */
 export declare function flagChipStyle(theme: ChartTheme): CSSProperties;
+/**
+ * Pick a readable text colour (near-black or white) for text drawn **on top of**
+ * `bg`, by its sRGB relative luminance. Handles `#rgb`/`#rrggbb` (the theme
+ * palette); any other CSS colour falls back to white. So a saturated blue/red/
+ * teal pill gets white text, a pale turquoise pill gets dark text.
+ */
+export declare function contrastText(bg: string): string;
+/**
+ * The **axis indicator pill** look — a *solid* filled tag in `color` with
+ * auto-contrast text (the ChartIQ / Yahoo price-tag). Distinct from
+ * {@link flagChipStyle} (a light in-plot value chip): an on-axis indicator reads
+ * as a saturated pill covering the tick, not a floating readout. Note: it does
+ * **not** set `lineHeight` — it inherits `normal`, matching a bare tick label, so
+ * a pill anchored at the same offset lines up with its tick-label neighbours (a
+ * forced lineHeight would shift the text off the tick baseline). Shared by
+ * {@link YAxisIndicator}, the crosshair axis pills, and the Baseline/Marker
+ * `indicator` pills.
+ */
+export declare function axisPillStyle(theme: ChartTheme, color: string): CSSProperties;
+/**
+ * A small triangle on an axis pill's **plot-facing edge**, pointing into the
+ * plot at the value (the callout tab). For a `right`-side pill (extending right
+ * across the gutter) it sits on the pill's left edge pointing left; for a `left`
+ * pill, the mirror. Render as an absolutely-positioned child of the pill (the
+ * pill is itself absolute, so it's the containing block); colour matches the pill.
+ */
+export declare function pointerStyle(side: 'left' | 'right', color: string): CSSProperties;
+/**
+ * CSS placing a value pill **on the axis gutter** at `side`: anchor its inner
+ * edge at the plot boundary (`plotWidth`) and let it overflow outward across the
+ * reserved gutter (the plot div doesn't clip), lifted with `zIndex` above the
+ * sibling axis column (rendered later in the row) so it covers the tick behind
+ * it. Shared by {@link YAxisIndicator}'s `placement='axis'` and the crosshair
+ * cursor's per-series value pills, so both sit identically on the axis.
+ */
+export declare function axisPillX(side: 'left' | 'right', plotWidth: number): CSSProperties;
 /**
  * Horizontal placement for a flag chip beside a vertical pole at plot-x `x`:
  * `FLAG_GAP` to the right, flipping to the left near the right edge so it stays

package/dist/chip.js

@@ -14,7 +14,9 @@ export function flagChipStyle(theme) {
     return {
         position: 'absolute',
         background: theme.chip?.background,
-        borderRadius: '3px',
+        // Square corners — a flag is a filled panel behind the number, not a pill
+        // (the rounded pill is reserved for axis indicators, see `axisPillStyle`).
+        borderRadius: '0',
         padding: '0 4px',
         fontFamily: theme.font.family,
         fontSize: `${theme.font.size}px`,
@@ -24,6 +26,88 @@ export function flagChipStyle(theme) {
         lineHeight: 1.5,
     };
 }
+/**
+ * Pick a readable text colour (near-black or white) for text drawn **on top of**
+ * `bg`, by its sRGB relative luminance. Handles `#rgb`/`#rrggbb` (the theme
+ * palette); any other CSS colour falls back to white. So a saturated blue/red/
+ * teal pill gets white text, a pale turquoise pill gets dark text.
+ */
+export function contrastText(bg) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(bg.trim());
+    const raw = m?.[1];
+    if (raw === undefined)
+        return '#ffffff';
+    const h = raw.length === 3
+        ? raw
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : raw;
+    const r = parseInt(h.slice(0, 2), 16) / 255;
+    const g = parseInt(h.slice(2, 4), 16) / 255;
+    const b = parseInt(h.slice(4, 6), 16) / 255;
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    return lum > 0.6 ? '#0b1220' : '#ffffff';
+}
+/**
+ * The **axis indicator pill** look — a *solid* filled tag in `color` with
+ * auto-contrast text (the ChartIQ / Yahoo price-tag). Distinct from
+ * {@link flagChipStyle} (a light in-plot value chip): an on-axis indicator reads
+ * as a saturated pill covering the tick, not a floating readout. Note: it does
+ * **not** set `lineHeight` — it inherits `normal`, matching a bare tick label, so
+ * a pill anchored at the same offset lines up with its tick-label neighbours (a
+ * forced lineHeight would shift the text off the tick baseline). Shared by
+ * {@link YAxisIndicator}, the crosshair axis pills, and the Baseline/Marker
+ * `indicator` pills.
+ */
+export function axisPillStyle(theme, color) {
+    return {
+        position: 'absolute',
+        background: color,
+        color: contrastText(color),
+        borderRadius: '3px',
+        padding: '0 4px',
+        fontFamily: theme.font.family,
+        fontSize: `${theme.font.size}px`,
+        fontVariantNumeric: 'tabular-nums',
+        whiteSpace: 'nowrap',
+        pointerEvents: 'none',
+    };
+}
+/**
+ * A small triangle on an axis pill's **plot-facing edge**, pointing into the
+ * plot at the value (the callout tab). For a `right`-side pill (extending right
+ * across the gutter) it sits on the pill's left edge pointing left; for a `left`
+ * pill, the mirror. Render as an absolutely-positioned child of the pill (the
+ * pill is itself absolute, so it's the containing block); colour matches the pill.
+ */
+export function pointerStyle(side, color) {
+    return {
+        position: 'absolute',
+        top: '50%',
+        transform: 'translateY(-50%)',
+        width: 0,
+        height: 0,
+        borderTop: '4px solid transparent',
+        borderBottom: '4px solid transparent',
+        ...(side === 'right'
+            ? { left: '-5px', borderRight: `5px solid ${color}` }
+            : { right: '-5px', borderLeft: `5px solid ${color}` }),
+    };
+}
+/**
+ * CSS placing a value pill **on the axis gutter** at `side`: anchor its inner
+ * edge at the plot boundary (`plotWidth`) and let it overflow outward across the
+ * reserved gutter (the plot div doesn't clip), lifted with `zIndex` above the
+ * sibling axis column (rendered later in the row) so it covers the tick behind
+ * it. Shared by {@link YAxisIndicator}'s `placement='axis'` and the crosshair
+ * cursor's per-series value pills, so both sit identically on the axis.
+ */
+export function axisPillX(side, plotWidth) {
+    return side === 'right'
+        ? { left: `${plotWidth}px`, zIndex: 3 }
+        : { right: `${plotWidth}px`, zIndex: 3 };
+}
 /** Gap (px) between a flag chip and its pole — the cursor staff or an annotation's
  *  line — so the chip floats just beside the pole rather than sitting on it. */
 const FLAG_GAP = 4;

package/dist/context.d.ts

@@ -233,6 +233,10 @@ export interface AnnotationSpec {
     /** The mark's resolved label text — used to pack overlapping top-flag labels
      *  (markers + regions) into stacked vertical lanes. */
     readonly label: string;
+    /** Whether this mark shows its value as an **axis-edge pill** — a marker on the
+     *  shared x-axis (drawn by `<XAxis>` at its `at`), a baseline on its y-axis
+     *  (drawn in place). Regions never set it. */
+    readonly indicator: boolean;
 }
 /**
  * A row's per-slot axis widths each side, **slot 0 nearest the plot** (so the
@@ -368,8 +372,12 @@ export interface TrackerInfo {
  * - `inline` — dots + a value chip beside each.
  * - `flag` — dots + value flags (a staffed flag from each point; the staff
  *   geometry lands in a later phase — for now flags stack at the top).
+ * - `crosshair` — the synced vertical line + a dot on each series, with each
+ *   series' value pinned to its y-axis edge (an on-axis pill) and the cursor
+ *   time pinned to the x-axis. The ChartIQ / trading-terminal readout. Values
+ *   snap to the series (the axis pills read like ticks), not the raw mouse Y.
  */
-export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag';
+export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair';
 /** A registered layer plus the axis id it draws against. */
 export interface LayerEntry {
     readonly layer: RowLayer;
@@ -396,6 +404,10 @@ export interface AxisSpec {
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;
+    /** Fractional headroom added to each side of the resolved domain (`0` = none). */
+    readonly pad: number;
+    /** Title placement; `'top'` makes the row reserve a header band above the plot. */
+    readonly labelPlacement: 'rotated' | 'top';
     /** Value formatting for the tick labels + the cursor readout ({@link AxisFormat}),
      *  or `undefined` for the scale's d3 default. */
     readonly format: AxisFormat | undefined;
@@ -427,6 +439,9 @@ export interface RowFrame {
      *  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[]>;
+    /** The side each axis sits on, keyed by id — so an axis-edge overlay (the
+     *  crosshair value pills) hugs the correct gutter. */
+    readonly axisSides: ReadonlyMap<string, 'left' | 'right'>;
     /** This row's cursor-mode override, or `undefined` to inherit the container's
      *  default ({@link ContainerFrame.cursor}). */
     readonly cursor: CursorMode | undefined;

package/dist/domain.d.ts

@@ -14,6 +14,11 @@
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>): [number, number];
+export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>, pad?: number): [number, number];
 //# sourceMappingURL=domain.d.ts.map

package/dist/domain.js

@@ -15,8 +15,22 @@ import { scaleLinear } from 'd3-scale';
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export function resolveYDomain(min, max, extents) {
+export function resolveYDomain(min, max, extents, pad = 0) {
+    const result = resolveBase(min, max, extents);
+    if (pad) {
+        const [lo, hi] = result;
+        const p = pad * (hi - lo);
+        return [lo - p, hi + p];
+    }
+    return result;
+}
+function resolveBase(min, max, extents) {
     // Both bounds explicit: trust them verbatim (allows an intentional flip).
     if (min !== undefined && max !== undefined)
         return [min, max];

package/dist/index.d.ts

@@ -45,6 +45,8 @@ 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 { YAxisIndicator, createLiveValue } from './indicators.js';
+export type { YAxisIndicatorProps, LiveValue } from './indicators.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

@@ -32,6 +32,9 @@ 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';
+// Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
+// `createLiveValue` is the high-frequency, isolated-repaint update path.
+export { YAxisIndicator, createLiveValue } from './indicators.js';
 export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';
 // CSS-custom-property → ChartTheme bridge: build a theme from a design system's

package/dist/indicators.d.ts

@@ -0,0 +1,105 @@
+import { type AxisFormat } from './format.js';
+/**
+ * A **live scalar** an axis indicator subscribes to, pushed imperatively from
+ * outside React — a WebSocket `onmessage`, a `requestAnimationFrame` loop, a
+ * tick handler. Backed by `useSyncExternalStore` on the consuming indicator:
+ * calling {@link LiveValue.set} re-renders **only the indicators subscribed to
+ * this value** — never the chart tree, never a canvas repaint. This is the path
+ * for a value that ticks many times a second (a live last-price tag), set
+ * independently of the series' own last point.
+ *
+ * Create one with {@link createLiveValue} and pass it to
+ * `<YAxisIndicator source={…}>`.
+ */
+export interface LiveValue {
+    /** Push a new value. Re-renders subscribed indicators only; a no-op if the
+     *  value is unchanged. Safe to call from outside React at any frequency. */
+    set(value: number): void;
+    /** @internal Store subscribe, for `useSyncExternalStore`. */
+    subscribe(onStoreChange: () => void): () => void;
+    /** @internal Current value snapshot, for `useSyncExternalStore`. */
+    getSnapshot(): number;
+}
+/**
+ * Create a {@link LiveValue} seeded at `initial`. Hold the returned object,
+ * call `.set(v)` from your data source, and hand it to
+ * `<YAxisIndicator source={…}>` — the pill repositions and relabels on each
+ * `set` without re-rendering the chart.
+ *
+ * ```ts
+ * const price = createLiveValue(0);
+ * ws.onmessage = (e) => price.set(JSON.parse(e.data).last); // outside React
+ * // <YAxisIndicator source={price} color="#4af" format=",.2f" />
+ * ```
+ */
+export declare function createLiveValue(initial: number): LiveValue;
+export interface YAxisIndicatorProps {
+    /**
+     * A static value to pin the pill at. Pass this **or** {@link source}. Updating
+     * `value` re-renders with its parent — fine for an occasional change; for a
+     * high-frequency tick use `source` so only the pill repaints.
+     */
+    value?: number;
+    /**
+     * A {@link LiveValue} to subscribe to — the high-frequency path. `.set(v)`
+     * moves and relabels the pill **without re-rendering the chart**. Takes
+     * precedence over {@link value} if both are given.
+     */
+    source?: LiveValue;
+    /** Which `<YAxis>` (by id) to position against; omit for the row's default axis. */
+    axis?: string;
+    /**
+     * Which edge the pill hugs. Default `right` — the conventional side for a live
+     * value tag. (Independent of the linked axis's side; set it to match.)
+     */
+    side?: 'left' | 'right';
+    /**
+     * Pill hue — the colour of the series / value it tracks. Defaults to the axis
+     * label colour (`theme.axis.label`).
+     */
+    color?: string;
+    /**
+     * Value formatting: a d3 format specifier (e.g. `',.2f'`, `'.1%'`) or a
+     * `(value) => string`. Omit to use the linked axis's own formatter, so the pill
+     * reads exactly like a tick. Pass a specifier for finer precision than the
+     * tick-calibrated default (a live price usually wants `',.2f'`, not the
+     * coarser tick rounding). See {@link AxisFormat}.
+     *
+     * An indicator **always shows the axis value** — there is no label override. A
+     * name/annotation belongs on a `<Baseline label>`'s near-line chip, not on the
+     * axis pill (an axis pill reads like a tick).
+     */
+    format?: AxisFormat;
+    /**
+     * Draw a thin dashed guide line from the pill across the plot (the ChartIQ
+     * "price line"). Default `false`.
+     */
+    line?: boolean;
+    /**
+     * Add a small triangle on the pill's plot-facing edge, pointing **into** the
+     * plot at the value (a callout tab). Default `false`.
+     */
+    pointer?: boolean;
+}
+/**
+ * A **value pill pinned to a y-axis edge** — the ChartIQ / Yahoo-Finance live
+ * price tag. Positions at `yScale(value)` on the linked axis and renders a chip
+ * (the solid {@link axisPillStyle} pill) at the plot's `side` edge, optionally
+ * with a dashed guide line across the plot.
+ *
+ * Render it as a child of `<Layers>` (alongside the chart layers), so it shares
+ * the plot's coordinate space:
+ *
+ * ```tsx
+ * <Layers>
+ *   <LineChart series={price} axis="usd" />
+ *   <YAxisIndicator source={liveLast} axis="usd" color="#4af" format=",.2f" line />
+ * </Layers>
+ * ```
+ *
+ * The value is **decoupled from the series' last point** — feed it whatever the
+ * live feed reports. For high-frequency updates pass a {@link LiveValue}
+ * ({@link source}); `.set()` repaints only the pill.
+ */
+export declare function YAxisIndicator({ value, source, axis, side, color, format, line, pointer, }: YAxisIndicatorProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=indicators.d.ts.map

package/dist/indicators.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useContext, useSyncExternalStore } from 'react';
+import { ContainerContext, RowContext } from './context.js';
+import { axisPillStyle, axisPillX, pointerStyle } from './chip.js';
+import { resolveAxisFormat } from './format.js';
+/**
+ * Create a {@link LiveValue} seeded at `initial`. Hold the returned object,
+ * call `.set(v)` from your data source, and hand it to
+ * `<YAxisIndicator source={…}>` — the pill repositions and relabels on each
+ * `set` without re-rendering the chart.
+ *
+ * ```ts
+ * const price = createLiveValue(0);
+ * ws.onmessage = (e) => price.set(JSON.parse(e.data).last); // outside React
+ * // <YAxisIndicator source={price} color="#4af" format=",.2f" />
+ * ```
+ */
+export function createLiveValue(initial) {
+    let value = initial;
+    const listeners = new Set();
+    return {
+        set(v) {
+            // Skip a redundant notify — a repeated identical tick shouldn't wake the
+            // subscriber (getSnapshot must be stable between real changes anyway).
+            if (v === value)
+                return;
+            value = v;
+            for (const listener of listeners)
+                listener();
+        },
+        subscribe(onStoreChange) {
+            listeners.add(onStoreChange);
+            return () => {
+                listeners.delete(onStoreChange);
+            };
+        },
+        getSnapshot() {
+            return value;
+        },
+    };
+}
+const noopSubscribe = () => () => { };
+/** The full-plot overlay the guide line paints into — above the data canvas,
+ *  inert to the pointer (matches the annotations' `overlayStyle`). */
+const overlayStyle = {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    pointerEvents: 'none',
+};
+const TICK_COUNT = 5;
+/**
+ * A **value pill pinned to a y-axis edge** — the ChartIQ / Yahoo-Finance live
+ * price tag. Positions at `yScale(value)` on the linked axis and renders a chip
+ * (the solid {@link axisPillStyle} pill) at the plot's `side` edge, optionally
+ * with a dashed guide line across the plot.
+ *
+ * Render it as a child of `<Layers>` (alongside the chart layers), so it shares
+ * the plot's coordinate space:
+ *
+ * ```tsx
+ * <Layers>
+ *   <LineChart series={price} axis="usd" />
+ *   <YAxisIndicator source={liveLast} axis="usd" color="#4af" format=",.2f" line />
+ * </Layers>
+ * ```
+ *
+ * The value is **decoupled from the series' last point** — feed it whatever the
+ * live feed reports. For high-frequency updates pass a {@link LiveValue}
+ * ({@link source}); `.set()` repaints only the pill.
+ */
+export function YAxisIndicator({ value, source, axis, side = 'right', color, format, line = false, pointer = false, }) {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('<YAxisIndicator> must be rendered inside a <ChartContainer>');
+    }
+    const row = useContext(RowContext);
+    if (row === null) {
+        throw new Error('<YAxisIndicator> must be rendered inside a <ChartRow>');
+    }
+    // One unconditional hook that covers both paths: with a `source`, subscribe to
+    // its store (a `set` re-renders only this component); without one, a stable
+    // no-op subscribe + a snapshot that reads the static `value` prop (which
+    // re-renders with the parent). Either way `v` is the current value.
+    const v = useSyncExternalStore(source ? source.subscribe : noopSubscribe, source ? source.getSnapshot : () => value ?? NaN);
+    const { theme } = container;
+    const axisId = axis ?? row.defaultAxisId;
+    const yScale = row.yScales.get(axisId);
+    // Axis not resolved yet (a layer mounts before its <YAxis>), or no value fed —
+    // draw nothing rather than guess.
+    if (yScale === undefined || !Number.isFinite(v))
+        return null;
+    const resolvedColor = color ?? theme.axis.label;
+    // A caller `format` resolves against the scale (string specifier or fn);
+    // otherwise reuse the axis's own formatter so the pill reads like a tick.
+    const fmt = format
+        ? resolveAxisFormat(yScale, TICK_COUNT, format)
+        : row.formats.get(axisId);
+    // An indicator always shows the axis value (no label override — a name belongs
+    // on a Baseline's near-line chip, not the axis pill).
+    const text = fmt ? fmt(v) : String(v);
+    const rawY = yScale(v);
+    // Clamp the pill's centre so an off-scale value keeps it inside the row rather
+    // than half-overflowing the edge (matches the y-tick clamp, F-charts-6).
+    const half = theme.font.size / 2 + 1;
+    const top = Math.max(half, Math.min(row.height - half, rawY));
+    return (_jsxs(_Fragment, { children: [line && (_jsx("svg", { width: container.plotWidth, height: row.height, style: overlayStyle, children: _jsx("line", { x1: 0, y1: rawY, x2: container.plotWidth, y2: rawY, stroke: resolvedColor, strokeWidth: 1, opacity: 0.5, strokeDasharray: "3 3", shapeRendering: "crispEdges" }) })), _jsxs("div", { style: {
+                    ...axisPillStyle(theme, resolvedColor),
+                    top: `${top}px`,
+                    ...axisPillX(side, container.plotWidth),
+                    transform: 'translateY(-50%)',
+                }, children: [pointer && _jsx("span", { style: pointerStyle(side, resolvedColor) }), text] })] }));
+}
+//# sourceMappingURL=indicators.js.map

package/dist/theme.d.ts

@@ -88,6 +88,17 @@ export interface ChartTheme {
         readonly grid: string;
         /** Gridline dash pattern (px on/off pairs); `[]` for solid. */
         readonly gridDash: readonly number[];
+        /**
+         * Typography for the axis **title** — the rotated y-axis unit strip and the
+         * x-axis label (distinct from the per-tick `label` colour above). Omit a
+         * field to fall back: `color` → `label`, `size` → `font.size + 1` (a touch
+         * larger than the ticks so the rotated strip reads), `opacity` → `0.85`.
+         */
+        readonly title?: {
+            readonly color?: string;
+            readonly size?: number;
+            readonly opacity?: number;
+        };
     };
     /** Label / tick typography. One source for axes + chrome. */
     readonly font: {

package/dist/tracker.d.ts

@@ -18,7 +18,7 @@ export declare const DEFAULT_CURSOR_MODE: CursorMode;
 export declare function cursorParts(mode: CursorMode): {
     readonly line: boolean;
     readonly dots: boolean;
-    readonly chip: 'none' | 'inline' | 'flag';
+    readonly chip: 'none' | 'inline' | 'flag' | 'axis';
 };
 /**
  * The crosshair's plot-pixel x from the tracker inputs. A controlled

package/dist/tracker.js

@@ -24,6 +24,10 @@ export function cursorParts(mode) {
             return { line: false, dots: true, chip: 'inline' };
         case 'flag':
             return { line: false, dots: true, chip: 'flag' };
+        case 'crosshair':
+            // Vertical line + per-series dots, values pinned to the axes (y pills in
+            // `Layers`, the x-time pill on `<XAxis>`).
+            return { line: true, dots: true, chip: 'axis' };
         case 'none':
             return { line: false, dots: false, chip: 'none' };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.36.0",
+  "version": "0.38.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.36.0",
-    "pond-ts": "^0.36.0",
+    "@pond-ts/react": "^0.38.0",
+    "pond-ts": "^0.38.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {