@pond-ts/charts 0.70.0 → 0.71.0

package/dist/context.d.ts

@@ -84,23 +84,18 @@ export interface ContainerFrame {
      *  The values are on {@link CursorFrame} ({@link CursorContext}). */
     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;
-    /**
-     * `cursor="region"` buckets — the intervals (from `cursorSequence`) realized
-     * over the current view, sorted + non-overlapping. `Layers` finds the one under
-     * the pointer and shades it (mapped through `xScale`, so on a trading-time axis
-     * the closed part of the bucket collapses). `undefined` when no `cursorSequence`
-     * is set.
+     * `<RangeCursor>` buckets — the intervals (from its `sequence`, or a
+     * `<MultiSelector sequence>`, or a bar layer's bins) realized over the
+     * current view, sorted + non-overlapping. `Layers` finds the one under the
+     * pointer and shades it (mapped through `xScale`, so on a trading-time axis
+     * the closed part of the bucket collapses). `undefined` when there is
+     * nothing to snap to.
      */
     readonly cursorBuckets: readonly Interval[] | undefined;
     /**
      * The `region`-cursor **drag anchor** in axis units (epoch ms on a time axis,
      * the axis value on a value axis), or `null` when not dragging. A drag on a
-     * region cursor (only when {@link onRegionSelect} is set) records the press
+     * range cursor (only when its `onDragRelease` is set) records the press
      * position here; the band then spans from the anchor's bucket to the pointer's
      * bucket (extending bucket by bucket), or freeform when there are no buckets.
      * Cleared on release.
@@ -128,18 +123,6 @@ export interface ContainerFrame {
     readonly previewSpans: readonly SpanSelection[];
     /** Set / clear the live sweep preview (see {@link previewSpans}). */
     setPreviewSpans(spans: readonly SpanSelection[]): void;
-    /**
-     * One-shot callback fired when a `region`-cursor **drag** is released, with the
-     * selected `[lo, hi]` span in **axis units** — epoch ms on a time axis, the axis
-     * value on a value axis (snapped to the `cursorSequence` buckets when present,
-     * else the raw drag span). The neutral numeric pair mirrors the container's
-     * polymorphic `range` input (which never takes the axis *kind* from its value);
-     * a time-axis consumer who wants a `TimeRange` constructs one from the pair.
-     * Providing it is what makes the region cursor **draggable**; the cursor does
-     * not keep the range (it reverts to the single-bucket highlight). Typical use:
-     * zoom the view, or map the span onto a subscription's range params.
-     */
-    readonly onRegionSelect: ((range: readonly [number, number]) => void) | undefined;
     /**
      * A stable sink for per-repaint {@link DrawStatsFrame}s, or `undefined` when no
      * `onDrawStats` consumer is subscribed — the `undefined` is the signal for
@@ -148,13 +131,6 @@ export interface ContainerFrame {
      * `onDrawStats` arrow doesn't thrash the draw memo.
      */
     readonly reportDrawStats: ((frame: DrawStatsFrame) => void) | undefined;
-    /**
-     * Require a modifier key held to start a region-drag — set to `'shift'` to make
-     * plain drag **pan** and **shift**-drag select, when `panZoom` is on. Only
-     * enforced while pan is enabled (with no pan there's no gesture to share, so the
-     * modifier is optional). `undefined` ⇒ a region-drag preempts pan.
-     */
-    readonly regionSelectModifier: 'shift' | undefined;
     /**
      * The selected marks — **empty when nothing is selected**, never `null`.
      * Shared across rows, insertion-ordered. A layer highlights every mark
@@ -243,13 +219,6 @@ export interface ContainerFrame {
      * plain single-mark hover, exactly as before.
      */
     setHovered(hit: SelectInfo | null, rowKey?: symbol, block?: readonly SelectInfo[]): void;
-    /** The default in-chart cursor presentation for all rows ({@link CursorMode});
-     *  a row may override it via its own `cursor`. */
-    readonly cursor: CursorMode;
-    /** Show the cursor's time atop the in-chart readout (when a row's cursor draws
-     *  one), formatted by {@link formatReadout} (else {@link formatTime}, matching
-     *  the time axis). */
-    readonly cursorTime: boolean;
     /**
      * Whether the chart is in **annotation-edit mode** — suppresses the data cursor
      * and makes editable annotations interactive (hovering reveals their handles +
@@ -259,10 +228,10 @@ export interface ContainerFrame {
     readonly editAnnotations: boolean;
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
      *  shared by `<TimeAxis>` and (absent {@link formatReadout}) the cursor-time
-     *  readout. Shaped by the container `timeFormat` only, never `cursorFormat`. */
+     *  readout. Shaped by the container `timeFormat` only, never a cursor `format`. */
     readonly formatTime: (epochMs: number) => string;
     /**
-     * The **readout** channel — defined only when the container's `cursorFormat`
+     * The **readout** channel — defined only when a mounted cursor's `format`
      * is set (time or value axis; a category axis reads names). Readout
      * consumers — the crosshair x pill and in-plot cursor time, marker axis
      * indicators, annotation auto-labels — read `formatReadout ?? <their label
@@ -274,7 +243,7 @@ export interface ContainerFrame {
      * The IANA zone the time axis renders in — the container's resolved
      * `timeZone` (explicit prop, else the calendar's), canonical id; `undefined`
      * when the axis is in the runtime's local zone. For a consumer's own
-     * formatter (`timeFormat` / `cursorFormat` functions receive epoch ms) to
+     * formatter (`timeFormat` / cursor `format` functions receive epoch ms) to
      * read the same zone the ticks do.
      */
     readonly timeZone: string | undefined;
@@ -289,13 +258,13 @@ export interface ContainerFrame {
      *  custom format owns the whole label, so the ladder mustn't second-line it. */
     readonly xFormatCustom: boolean;
     /**
-     * Whether an explicit container `cursorFormat` shaped {@link formatReadout} —
+     * Whether an explicit cursor `format` shaped {@link formatReadout} —
      * as opposed to the axis kind supplying its own default readout (the elapsed
      * axis's finer duration). The two are indistinguishable from the field alone,
      * and `<XAxis>` must tell them apart to honour the documented pill precedence
-     * `cursorFormat → axis format → container`: a **`cursorFormat`** outranks an
+     * `cursor format → axis format → container`: a cursor **`format`** outranks an
      * explicit `<XAxis format>`, a **default** does not. Without this the elapsed
-     * default silently occupied the `cursorFormat` slot and a wall-clock strip's
+     * default silently occupied the cursor `format` slot and a wall-clock strip's
      * pill read durations (issue #540, finding 2).
      */
     readonly xReadoutCustom: boolean;
@@ -359,7 +328,7 @@ export interface ContainerFrame {
      * fact behind {@link resolveSweep} (which builds the per-drag gesture and is
      * for the pointer-down path). Rows read this to decide the **resting block
      * preview**: with one in scope over a sweep-capable row, the shared brush
-     * band becomes the resting cursor (replacing the implicit line shim) and
+     * band becomes the resting cursor (when no cursor component is mounted) and
      * hover lights the whole snap block a drag would select. Identity changes
      * when the selector registry does, so it is safe in render memos.
      */
@@ -502,8 +471,7 @@ export interface ContainerFrame {
     readonly firstRowKey: symbol | null;
     /**
      * Register a mounted **cursor** ({@link CursorEntry}) — the `<LineCursor>` /
-     * `<CrosshairCursor>` / … presets (and the deprecation shim synthesizing them
-     * from the legacy string props) call this, keyed by the component's
+     * `<CrosshairCursor>` / … presets call this, keyed by the component's
      * per-instance slot key. The container resolves the per-row effective set
      * (row mounts override container mounts — see `effectiveCursorEntries`) and
      * the rows/`<XAxis>` render the registered slots. Update is in place;
@@ -658,8 +626,6 @@ export declare const ContainerContext: import("react").Context<ContainerFrame |
  *
  * The cursor *time* is **not** here — each consumer derives it locally from
  * `cursorX` + its own `xScale` (an in-bounds `xScale.invert`), as before.
- * ({@link ContainerFrame} still carries a `cursorTime` **boolean** — the
- * unrelated "show time in the readout" config flag.)
  */
 export interface CursorFrame {
     /**
@@ -750,8 +716,13 @@ export interface RowLayer {
      * when the layer was given no `as`.
      */
     readonly as?: string | undefined;
-    /** This layer's finite-value `[min, max]`, or `null` if it has none. */
-    yExtent(): [number, number] | null;
+    /**
+     * This layer's finite-value `[min, max]`, or `null` if it has none. `scale`
+     * is the kind of the axis the extent is being fitted to, for a layer whose
+     * extent depends on it (an area's zero baseline has no position on a log
+     * axis, so it must not be pulled into one).
+     */
+    yExtent(scale?: YScaleKind): [number, number] | null;
     /**
      * The **kind of x axis** this layer's data lives on — `'time'` for a
      * `TimeSeries`, `'value'` for a `ValueSeries`, `'category'` for a categorical
@@ -787,7 +758,7 @@ export interface RowLayer {
     binCategories?(): readonly string[] | null;
     /**
      * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
-     * **shared snap buckets**. When present (and no `cursorSequence` is set), a
+     * **shared snap buckets**. When present (and no cursor `sequence` is set), a
      * region drag snaps bar by bar and a `<MultiSelector>` sweep's band extends
      * bar by bar, so a histogram gets bin-aligned selection for free. Only a
      * **vertical** bar layer publishes them — a horizontal chart puts the value
@@ -811,8 +782,8 @@ export interface RowLayer {
      * {@link BoxPlot} implements it (low/q1/median/q3/high on one flag at the box's
      * top-centre); line/area/bar/scatter omit it and use the per-sample flag from
      * {@link sampleAt}. `null` when nothing is under the cursor. (`sampleAt` still
-     * fans the same values to the off-chart readout; `cursorFlag` is the in-chart
-     * presentation only.)
+     * fans the same values to the off-chart readout and to the crosshair, which
+     * snaps to them; `cursorFlag` only replaces the per-series dots and chips.)
      */
     cursorFlag?(time: number): CursorFlag | null;
     /**
@@ -1164,7 +1135,7 @@ export interface SelectModifiers {
     readonly metaKey: boolean;
     /**
      * **Note the conflict:** `shift` is already the drag chord for
-     * `<ChartContainer regionSelectModifier="shift">` on a continuous axis, so a
+     * `<RangeCursor dragModifier="shift">` on a continuous axis, so a
      * shift-click there may also be the start of a region drag. Reported for
      * completeness; think before you give it a second meaning. (There is
      * deliberately no derived `range` flag for this reason — an ordinal range
@@ -1234,9 +1205,8 @@ export interface SelectorEntry {
 }
 /**
  * The span a completed `<RangeCursor>` drag reports to `onDragRelease` —
- * **one uniform shape with an optional y** (interaction RFC A3.3), not the
- * bare pair the legacy `onRegionSelect` used, and not a polymorphic union a
- * consumer must narrow.
+ * **one uniform shape with an optional y** (interaction RFC A3.3), not a bare
+ * pair and not a polymorphic union a consumer must narrow.
  *
  * `x` is `[lo, hi]` in **axis units** — epoch ms on a time axis, the axis
  * value (strike, distance, …) on a value axis — snapped to the cursor's
@@ -1377,22 +1347,23 @@ export interface TrackerInfo {
     readonly values: readonly TrackerSample[];
 }
 /**
- * The in-chart cursor presentation for a row (the synced vertical line is shared
- * across rows). Exclusive modes — pick one:
+ * What a `<CrosshairCursor>` is **snapped to** — the one data point its reticle
+ * centres on, handed to `<CrosshairCursor onSnap>`. The same fields as a
+ * {@link TrackerSample} (the point's `x` and `value`, the series `label` and
+ * `color`, the optional `readout`), plus the y axis it was read against and the
+ * value exactly as the crosshair's axis pill shows it.
  *
- * - `none` — no in-chart cursor.
- * - `line` — the synced vertical line only, no per-series marks (pair with an
- *   off-chart readout via {@link onTrackerChanged}).
- * - `point` — a dot on each series at the cursor, no line.
- * - `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.
+ * Where {@link TrackerInfo} lists *every* series at the cursor time, this is
+ * the single one the reticle picked — the series nearest the pointer's height
+ * in the row being hovered.
  */
-export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair' | 'region';
+export interface CursorSnap extends TrackerSample {
+    /** The id of the `<YAxis>` the value is measured against (the row's default
+     *  axis id when the layer names none). */
+    readonly axisId: string;
+    /** The value formatted by that axis's formatter — the axis pill's text. */
+    readonly formatted: string;
+}
 /**
  * How a cursor wants the shared `cursorX` snapped, **declared, resolved by the
  * container** (interaction RFC A2.3). The x-snap consults each layer's
@@ -1418,6 +1389,13 @@ export type CursorSnapX = 'none' | 'sample' | 'sequence';
 export interface ResolvedCursorSample {
     readonly px: number;
     readonly py: number;
+    /** The sample's raw x (epoch ms on a time axis) — what `px` was scaled from. */
+    readonly x: number;
+    /** The sample's raw value — what `py` and `formatted` were made from. */
+    readonly value: number;
+    /** The layer's `readout` source value, when it has one (see
+     *  {@link TrackerSample.readout}). */
+    readonly readout?: number;
     readonly axisId: string;
     readonly side: 'left' | 'right';
     /** Distance in px from the plot's `side` edge to this axis's inner edge —
@@ -1463,8 +1441,18 @@ export interface ResolvedCursorFrame {
      *  it is drawing in the row the pointer is in). */
     readonly hoveredRowKey: symbol | null;
     /** Per-series resolved measurements at the cursor time (empty when the
-     *  effective cursors declared no need for them, or nothing is hovered). */
+     *  effective cursors declared no need for them, or nothing is hovered). A
+     *  layer that consolidates its readout into one flag (BoxPlot) is left out:
+     *  per-series dots and chips would repeat that flag. */
     readonly samples: readonly ResolvedCursorSample[];
+    /**
+     * The crosshair's candidates: every layer's resolved samples, **including**
+     * a consolidated-flag layer's (a box plot's five quantiles). The reticle
+     * picks one value, so a box's quantiles are things it can land on rather
+     * than marks that would repeat the box's flag. Empty unless a cursor
+     * declared {@link CursorWants.reticle}.
+     */
+    readonly reticleSamples: readonly ResolvedCursorSample[];
     /** Resolved consolidated flags (BoxPlot) — the flag cursor's one-chip form. */
     readonly flags: readonly ResolvedCursorFlag[];
     /**
@@ -1608,8 +1596,11 @@ export interface CursorSpec {
 /** What a cursor needs the container to resolve per pointer move — declared at
  *  registration so a line-only cursor never pays for per-sample measurement. */
 export interface CursorWants {
-    /** Per-series {@link ResolvedCursorSample}s (dots, chips, the reticle pick). */
+    /** Per-series {@link ResolvedCursorSample}s (dots, chips). */
     readonly samples: boolean;
+    /** {@link ResolvedCursorFrame.reticleSamples} — the crosshair's pick,
+     *  box plots included. */
+    readonly reticle: boolean;
     /** Consolidated {@link ResolvedCursorFlag}s (the flag cursor only). */
     readonly flags: boolean;
     /** The range band (+ the degenerate band line). */
@@ -1629,18 +1620,6 @@ export interface CursorEntry {
     /** Mount scope: a row's key when mounted inside a `<ChartRow>` (the per-row
      *  override), `null` when mounted at the container (the default for all rows). */
     readonly rowKey: symbol | null;
-    /** Synthesized by the deprecation shim from the legacy string props. A scope
-     *  with any non-legacy (component-mounted) cursor drops its legacy entries —
-     *  mounting a component overrides the string prop during the window. */
-    readonly legacy: boolean;
-    /**
-     * The shim entry nobody asked for: the container's `'line'` **default**,
-     * synthesized with no `cursor` prop set. A mounted `<MultiSelector>`'s
-     * resting block preview (the brush band as the resting cursor) replaces
-     * only these — an explicitly chosen cursor, component-mounted or via the
-     * legacy string prop, still wins.
-     */
-    readonly implicit?: boolean;
     /**
      * Whether this cursor owns **snap and gesture** (RFC A2.5): at most one per
      * scope (dev-warned otherwise), resolved to the hovered row's innermost
@@ -1649,22 +1628,31 @@ export interface CursorEntry {
     readonly ownsGesture: boolean;
     readonly wants: CursorWants;
     /** The range cursor's bucket sequence (realized by the container into the
-     *  shared snap buckets — the `cursorSequence` successor). */
+     *  shared snap buckets). */
     readonly sequence?: Sequence | BoundedSequence | undefined;
-    /** The range cursor's drag-release callback (the `onRegionSelect`
-     *  successor) — read by the brush recognizer (`resolveRangeDrag`), which
+    /** The range cursor's drag-release callback — read by the brush recognizer (`resolveRangeDrag`), which
      *  wraps it into the range-drag session. Only a `<RangeCursor>` sets it. */
     readonly onDragRelease?: ((span: RangeSpan) => void) | undefined;
     /** Whether the range drag is live — **resolved** at build time
      *  (`enableDrag ?? !!onDragRelease`), so `false` here means frozen: the
      *  gesture is off even though the callback is wired (§6's OFF switch). */
     readonly enableDrag?: boolean | undefined;
-    /** The modifier the range drag needs (the `regionSelectModifier`
-     *  successor) — only enforced while pan is enabled. */
+    /** The modifier the range drag needs — only enforced while pan is
+     *  enabled. */
     readonly dragModifier?: 'shift' | undefined;
-    /** The cursor's readout format (the `cursorFormat` successor) — resolved by
-     *  the container into the shared readout channel. */
+    /** The cursor's readout format — resolved by the container into the shared
+     *  readout channel. */
     readonly format?: CursorFormat | undefined;
+    /**
+     * The crosshair's snap report (`<CrosshairCursor onSnap>`). A row calls it
+     * with its render frame when it is the hovered row, and with `null` when the
+     * pointer is elsewhere; the cursor picks the snapped sample from the frame
+     * and calls the consumer only when that pick changes. Only set when the
+     * consumer passed `onSnap`, so a crosshair nobody listens to never picks or
+     * builds a report (each row still looks up its snap owner, two short
+     * filters over the registered cursors).
+     */
+    readonly reportSnap?: ((f: ResolvedCursorFrame | null) => void) | undefined;
 }
 /** A registered layer plus the axis id it draws against. */
 export interface LayerEntry {
@@ -1846,9 +1834,6 @@ export interface RowFrame {
      *  is absent. The other half of matching an axis-edge pill to its axis (see
      *  {@link axisOffsets}) — the pill takes this colour, else the theme's. */
     readonly axisColors: ReadonlyMap<string, string>;
-    /** This row's cursor-mode override, or `undefined` to inherit the container's
-     *  default ({@link ContainerFrame.cursor}). */
-    readonly cursor: CursorMode | undefined;
     /** Whether this is the first (topmost) row — the shared cursor-time chip shows
      *  here only, not repeated on every row. Derived from {@link ContainerFrame.firstRowKey}. */
     readonly isFirstRow: boolean;

package/dist/cursors.d.ts

@@ -1,34 +1,49 @@
 import type { Sequence, BoundedSequence } from 'pond-ts';
-import { type CursorEntry, type CursorMode, type RangeSpan } from './context.js';
+import { type CursorEntry, type CursorSnap, type RangeSpan } from './context.js';
 import type { CursorFormat } from './format.js';
 export interface LineCursorProps {
     /** Show the cursor's time atop the readout (once, on the first row),
      *  formatted by the container's readout channel. Default `false`. */
     showTime?: boolean;
+    /** The readout format for the time this cursor shows (and for marker
+     *  indicators + annotation auto-labels) — the shared readout channel; see
+     *  {@link CrosshairCursorProps.format}. */
+    format?: CursorFormat;
 }
-/** The synced vertical cursor **line** — `cursor="line"` as a component (the
- *  container default during the deprecation window). Pair with an off-chart
- *  readout via `onTrackerChanged`. */
-export declare function LineCursor({ showTime }?: LineCursorProps): null;
+/** The synced vertical cursor **line**. Pair with an off-chart readout via
+ *  `onTrackerChanged`. */
+export declare function LineCursor({ showTime, format }?: LineCursorProps): null;
 export interface PointCursorProps {
     /** Show the cursor's time atop the readout (first row). Default `false`. */
     showTime?: boolean;
+    /** The readout format for the time this cursor shows (and for marker
+     *  indicators + annotation auto-labels) — the shared readout channel; see
+     *  {@link CrosshairCursorProps.format}. */
+    format?: CursorFormat;
 }
-/** A **dot on each series** at the cursor, no line — `cursor="point"`. */
-export declare function PointCursor({ showTime }?: PointCursorProps): null;
+/** A **dot on each series** at the cursor, no line. */
+export declare function PointCursor({ showTime, format, }?: PointCursorProps): null;
 export interface InlineCursorProps {
     /** Show the cursor's time atop the readout (first row). Default `false`. */
     showTime?: boolean;
+    /** The readout format for the time this cursor shows (and for marker
+     *  indicators + annotation auto-labels) — the shared readout channel; see
+     *  {@link CrosshairCursorProps.format}. */
+    format?: CursorFormat;
 }
-/** Dots **plus a value chip beside each** — `cursor="inline"`. */
-export declare function InlineCursor({ showTime }?: InlineCursorProps): null;
+/** Dots **plus a value chip beside each**. */
+export declare function InlineCursor({ showTime, format, }?: InlineCursorProps): null;
 export interface FlagCursorProps {
     /** Show the cursor's time atop the flag stack (first row). Default `false`. */
     showTime?: boolean;
+    /** The readout format for the time this cursor shows (and for marker
+     *  indicators + annotation auto-labels) — the shared readout channel; see
+     *  {@link CrosshairCursorProps.format}. */
+    format?: CursorFormat;
 }
-/** Dots + **staffed value flags** stacked near the top of the row —
- *  `cursor="flag"`. A `cursorFlag` layer (BoxPlot) consolidates onto one flag. */
-export declare function FlagCursor({ showTime }?: FlagCursorProps): null;
+/** Dots + **staffed value flags** stacked near the top of the row — a `cursorFlag` layer (BoxPlot)
+ *  consolidates onto one flag. */
+export declare function FlagCursor({ showTime, format }?: FlagCursorProps): null;
 export interface CrosshairCursorProps {
     /**
      * Reticle **y** snapping. **Default `true`** — the reticle centres on the
@@ -41,15 +56,49 @@ export interface CrosshairCursorProps {
      *  **Default `true`** — the time pill is the crosshair's readout; there is
      *  no per-row time chip to opt into. */
     showTime?: boolean;
-    /** Readout format for the x-axis time pill — the `cursorFormat` successor,
-     *  resolved by the container into the shared readout channel (it also
-     *  shapes marker indicators + annotation auto-labels, as `cursorFormat`
-     *  did). */
+    /**
+     * The **cursor / marker readout** format — the x-axis time pill, marker
+     * axis indicators, and annotation auto-labels — **independent of the tick
+     * labels** on both axis kinds: it does **not** disqualify the `dateStyle`
+     * ladder (time), and it never moves the tick labels (value). It beats an
+     * explicit `<XAxis format>` for the **readout only** — pill precedence is
+     * `format → axis format → container` — so terse ticks can pair with a
+     * precise readout (`+2.0σ` labels, `+1.83σ` pill).
+     *
+     * **Omitted ⇒ the axis's own formatter.** On a time axis that default is
+     * grain-aware: the readout formats at the axis's granularity, so a
+     * day-or-coarser axis reads a **date** (never a time-of-day) and a sub-day
+     * axis reads date + clock. On a value axis it is the tick formatter.
+     *
+     * A d3 specifier **string** formats uniformly (time specifier on a time
+     * axis, number specifier on a value axis); a **function**
+     * `(value, { grain, defaultText }) => string` receives the axis's resolved
+     * coarse grain (`undefined` on a value axis) and the default readout text,
+     * so it can branch on the zoom level and pass `defaultText` through. One
+     * channel per chart: when several mounted cursors set `format`, the first
+     * mounted wins. (A category axis reads names, and a `transform`ed axis's
+     * pill speaks its derived unit — neither consults it.)
+     */
     format?: CursorFormat;
+    /**
+     * Tells you what the reticle is **snapped to** — the series (`label`,
+     * `color`, `axisId`) and the point (`x`, `value`, `formatted`) its centre dot
+     * sits on — and `null` when it lets go (the pointer leaves the chart, or
+     * moves to a row with no data under it). Fires only when the snapped point
+     * **changes**, not on every pointer move.
+     *
+     * Reports the pointer's snap only: with `snap={false}` the reticle follows
+     * the pointer rather than a series, so this stays `null`; and a reticle
+     * shown by a controlled `trackerPosition` with no pointer on the chart
+     * reports `null` too. For every series' value at the cursor time, use the
+     * container's `onTrackerChanged`.
+     */
+    onSnap?: (snap: CursorSnap | null) => void;
 }
-/** The inspection **reticle** — `cursor="crosshair"`: dashed cross lines, a
- *  centre dot, the value pinned to its y axis, the time pinned to the x axis. */
-export declare function CrosshairCursor({ snap, showTime, format, }?: CrosshairCursorProps): null;
+/** The inspection **reticle**: dashed cross lines, a
+ *  centre dot in the snapped series' colour, the value pinned to its y axis,
+ *  the time pinned to the x axis. */
+export declare function CrosshairCursor({ snap, showTime, format, onSnap, }?: CrosshairCursorProps): null;
 export interface RangeCursorProps {
     /**
      * The bucketing for the hover band **and the drag's snap** — a pond
@@ -57,7 +106,8 @@ export interface RangeCursorProps {
      * trading calendar's sessions). A drag extends **bucket by bucket** over
      * these. **Omit ⇒ freeform**: the cursor renders as a plain line and a drag
      * spans the raw `[lo, hi]` (a bar/histogram layer's bins still snap both
-     * when present). Time axis only, like `cursorSequence`. Pass a stable
+     * when present). Time axis only; on a category axis the band always
+     * snaps to the slot under the pointer. Pass a stable
      * reference (the buckets memoize on it).
      */
     sequence?: Sequence | BoundedSequence;
@@ -75,8 +125,11 @@ export interface RangeCursorProps {
      * so drag-to-zoom is `onDragRelease={(s) => setRange(s.x)}`.
      *
      * The drag **preempts pan** unless {@link dragModifier} shares the gesture.
-     * Continuous x only (a category axis is excluded, as for the legacy
-     * `onRegionSelect`).
+     * Continuous x only: on a **category** axis the hover band still shades the
+     * slot under the pointer, but the drag never starts — a numeric span means
+     * nothing there, and dragging across bars is `<MultiSelector>`'s gesture
+     * (it reports the bars). The container dev-warns when this is wired on a
+     * category axis.
      */
     onDragRelease?: (span: RangeSpan) => void;
     /**
@@ -94,44 +147,26 @@ export interface RangeCursorProps {
      * and you want **plain drag to pan, shift-drag to select**. **Only
      * enforced while pan is enabled** (with pan off there is no gesture
      * conflict, so either drag selects). Omitted ⇒ the drag preempts pan.
-     * The `regionSelectModifier` successor.
      */
     dragModifier?: 'shift';
 }
 /**
- * The **range** cursor — `cursor="region"` as a component (RFC A4.1 renames
+ * The **range** cursor (RFC A4.1 names
  * it for what it emits: a live extent — and, dragged, exactly what
  * `ChartContainer.range` accepts — against the annotation `<Region>`'s fixed
- * mark). Hover shades the bucket under the pointer; wiring
+ * mark). Hover shades the bucket under the pointer (on a category axis, the
+ * slot); wiring
  * {@link RangeCursorProps.onDragRelease} adds the drag, which fires once on
  * release and reverts (RFC §6: a region is deliberately a cursor **and** a
  * drag that fires and resets). The gesture rides the shared brush recognizer
  * (`brush.tsx`) — one engine arbitrating every drag claim on the plot.
  */
 export declare function RangeCursor({ sequence, onDragRelease, enableDrag, dragModifier, }?: RangeCursorProps): null;
-/**
- * The deprecation shim (internal): synthesizes the preset equivalent of a
- * legacy `cursor` string — the container's `cursor` prop (or its `'line'`
- * default), and `<ChartRow cursor>` inside a row. Registers as `legacy`, so a
- * component-mounted cursor in the same scope overrides it.
- */
-export declare function LegacyCursor({ mode, showTime, snap, sequence, implicit, }: {
-    mode: CursorMode;
-    /** The container's `cursorTime` (the in-plot time readout opt-in). */
-    showTime: boolean;
-    /** The container's `crosshairSnap` (the reticle y-snap). */
-    snap: boolean;
-    sequence?: Sequence | BoundedSequence | undefined;
-    /** This shim carries the container's un-asked-for `'line'` DEFAULT (no
-     *  `cursor` prop set) — the only cursor a mounted `<MultiSelector>`'s
-     *  resting block preview replaces (see {@link CursorEntry.implicit}). */
-    implicit?: boolean;
-}): null;
 /**
  * The cursors in effect for a row: the row's own mounts when it has any (the
- * per-row override — nearest mount wins, exactly `row.cursor ?? container
- * .cursor`'s semantics), else the container-scoped mounts. Within a scope,
- * component mounts shadow the legacy shim.
+ * per-row override — nearest mount wins), else the container-scoped mounts.
+ * A row that wants no cursor while its siblings have one mounts the cursors
+ * per row rather than at the container.
  */
 export declare function effectiveCursorEntries(all: readonly CursorEntry[], rowKey: symbol): readonly CursorEntry[];
 /** The scope's single snap/gesture owner (RFC A2.5) — first mount wins; the
@@ -153,9 +188,4 @@ export declare function xAxisCursorEntries(all: readonly CursorEntry[], hoveredR
 export declare function warnOnDuplicateGestureOwners(all: readonly CursorEntry[], warned: {
     current: boolean;
 }): void;
-/** @internal The dev deprecation notice for a legacy cursor prop — one line
- *  naming the replacement, shared by the container and row shims. */
-export declare function legacyCursorWarning(lines: readonly string[]): string;
-/** @internal The preset name a legacy `cursor` mode maps to (for warnings). */
-export declare function presetNameFor(mode: CursorMode): string;
 //# sourceMappingURL=cursors.d.ts.map