@pond-ts/charts 0.37.0 → 0.39.0

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

@@ -11,6 +11,14 @@ import type { AxisFormat } from './format.js';
  * time→pixel `xScale` follow. Y scales stay per-row (row-local data), on the
  * {@link RowFrame}.
  */
+/** Where a top-flag label sits: its lane (0 = top; overlapping labels stack
+ *  down) and the chip text to render — the merged label for the representative of
+ *  a coincident-marker group, `null` for the members folded into it, else the
+ *  mark's own label. Computed by `computeLabelLanes`. */
+export interface LabelPlacement {
+    readonly lane: number;
+    readonly label: string | null;
+}
 export interface ContainerFrame {
     readonly timeRange: readonly [number, number];
     readonly width: number;
@@ -39,6 +47,22 @@ export interface ContainerFrame {
     readonly cursorX: number | null;
     /** Set the hovered plot-pixel x; a row's event surface calls this on pointer move. */
     setHoverX(x: number | null): void;
+    /**
+     * The hovered plot-pixel **y** and the row it's in — for the free-form
+     * crosshair's horizontal line + value readout (which are row-specific, unlike
+     * the shared vertical `cursorX`). `null` when not hovering a plot. Hover-driven
+     * only (no controlled equivalent).
+     */
+    readonly cursorY: number | null;
+    readonly cursorRowKey: symbol | null;
+    /** Set the hovered plot-pixel y + its row; the event surface calls this on move. */
+    setHoverY(y: number | null, rowKey: symbol | null): void;
+    /**
+     * `cursor="crosshair"` **y** snapping. **Default `true`** — the reticle centres
+     * on the nearest data point's value. `false` — the y follows the pointer freely
+     * (`yScale.invert`). The x always snaps to the data grid either way.
+     */
+    readonly crosshairSnap: boolean;
     /**
      * The selected mark, or `null`. Shared across rows (single selection). A layer
      * highlights the mark matching **both** the key (epoch ms) and the series
@@ -146,10 +170,20 @@ export interface ContainerFrame {
     /** Every registered annotation — read by each row to draw the *other* rows'
      *  guides, and by a drag to find snap targets. */
     readonly annotations: readonly AnnotationSpec[];
-    /** Vertical lane (0 = top) for each top-flag label, by slot key — overlapping
-     *  marker/region labels stack into lower lanes instead of colliding. A key absent
-     *  from the map (or mapping to 0) sits in the top lane. */
-    readonly labelLanes: ReadonlyMap<symbol, number>;
+    /** Per-key top-flag {@link LabelPlacement} — the lane (0 = top; overlapping
+     *  labels stack down) + the chip text (merged for the representative of a
+     *  coincident-marker group, `null` for the folded-in members). A key absent
+     *  from the map sits at lane 0 with its own label. */
+    readonly labelLanes: ReadonlyMap<symbol, LabelPlacement>;
+    /**
+     * The annotation currently being **dragged** (its slot key), or `null`. Set on
+     * drag-start, cleared on release. The lane packers (label lanes + x-axis pill
+     * lanes) exclude it so the *static* marks don't reshuffle as the dragged one
+     * crosses them — only the mark under the pointer moves; it settles on release.
+     */
+    readonly draggingKey: symbol | null;
+    /** Mark/clear the actively-dragged annotation; a mark's drag calls this. */
+    setDragging(key: symbol | null): void;
     /**
      * The armed creation tool, or `null` (idle). Set by the consumer's toolbar;
      * when non-null the plot captures a **create gesture** (draw a new mark) instead
@@ -233,6 +267,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 +406,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;
@@ -431,6 +473,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/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/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,11 @@ export function cursorParts(mode) {
             return { line: false, dots: true, chip: 'inline' };
         case 'flag':
             return { line: false, dots: true, chip: 'flag' };
+        case 'crosshair':
+            // A single reticle (not per-series): `Layers` draws the dashed vertical +
+            // full-width horizontal lines, the centre dot, and one value pill itself
+            // (so no generic line/dots here); the x-time pill is on `<XAxis>`.
+            return { line: false, dots: false, chip: 'axis' };
         case 'none':
             return { line: false, dots: false, chip: 'none' };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.37.0",
+  "version": "0.39.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.37.0",
-    "pond-ts": "^0.37.0",
+    "@pond-ts/react": "^0.39.0",
+    "pond-ts": "^0.39.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {