react-native-livechart 3.11.0 → 4.0.0

package/src/hooks/useReferenceLine.ts

@@ -18,10 +18,20 @@ export interface ReferenceLineLayout {
   y: number;
   /** Band bottom-edge y (value/time band); equals `y` for a plain line. */
   yBottom: number;
-  /** Left x extent. */
+  /** Left x extent of the plot (badge / label / connector anchor). */
   x1: number;
-  /** Right x extent. */
+  /** Right x extent of the plot (badge / label / connector anchor). */
   x2: number;
+  /**
+   * Left x of the **drawn** line / band. Equals {@link x1} normally, or `0`
+   * (canvas edge) when the line is full-width. Decoupled from {@link x1} so the
+   * line can run through the gutter while the badge/label stays in the plot.
+   */
+  lineX1: number;
+  /** Right x of the drawn line / band: {@link x2} normally, or the canvas width when full-width. */
+  lineX2: number;
+  /** Stroke the plain horizontal line (true for a plain Form-A line, or a full-width badged line). */
+  drawLine: boolean;
   /** Resolved label text (with appended value when `showValue`); "" when hidden. */
   label: string;
   labelX: number;
@@ -54,6 +64,9 @@ const INVISIBLE: ReferenceLineLayout = {
   yBottom: -1,
   x1: 0,
   x2: 0,
+  lineX1: 0,
+  lineX2: 0,
+  drawLine: false,
   label: "",
   labelX: 0,
   labelY: -1,
@@ -96,7 +109,7 @@ interface BadgeGeometry {
  * inside the pill, with a dashed connector running to the opposite edge.
  */
 function badgeGeometry(
-  position: "left" | "right",
+  position: "left" | "center" | "right",
   icon: string,
   text: string,
   hasChevron: boolean,
@@ -134,7 +147,9 @@ function badgeGeometry(
   const pillX =
     position === "right"
       ? x2 - BADGE_EDGE_INSET - pillW
-      : x1 + BADGE_EDGE_INSET;
+      : position === "center"
+        ? (x1 + x2) / 2 - pillW / 2
+        : x1 + BADGE_EDGE_INSET;
 
   let cursor = pillX + BADGE_PAD_X;
   let chevronCx = -1;
@@ -159,13 +174,14 @@ function badgeGeometry(
       connStart = x1;
       connEnd = end;
     }
-  } else {
+  } else if (position === "left") {
     const start = pillX + pillW + 4;
     if (start < x2) {
       connStart = start;
       connEnd = x2;
     }
   }
+  // "center" floats the pill at the value with no connector.
 
   return { pillX, pillW, iconX, textX, chevronCx, connStart, connEnd };
 }
@@ -213,6 +229,8 @@ export function computeReferenceBadgeRect(
   dMax: number,
   font: SkFont,
   formatValue: (value: number) => string,
+  /** Live value override (e.g. a dragged value), defaulting to `line.value`. */
+  valueOverride?: number,
 ): ReferenceBadgeRect | null {
   "worklet";
   const badge = resolveReferenceBadge(line);
@@ -228,7 +246,7 @@ export function computeReferenceBadgeRect(
 
   const x1 = padding.left;
   const x2 = canvasWidth - padding.right;
-  const v = line.value;
+  const v = valueOverride ?? line.value;
   const edge = classifyReferenceEdge(v, dMin, dMax);
 
   let y: number;
@@ -267,6 +285,14 @@ export function useReferenceLine(
   line: ReferenceLine | undefined,
   formatValue: (v: number) => string,
   font: SkFont,
+  /**
+   * Per-line live value overrides (e.g. dragged values), index-aligned with the
+   * chart's `referenceLines`. When provided and the slot at {@link index} holds a
+   * number, the Form-A line tracks that value instead of the static `line.value`,
+   * so a drag updates the rendered line/badge on the UI thread. Omit for static lines.
+   */
+  dragValues?: SharedValue<number[]>,
+  index = 0,
 ): SharedValue<ReferenceLineLayout> {
   const form = line ? referenceLineForm(line) : "none";
   // Badge presentation depends only on the (stable) line props — resolve once.
@@ -284,6 +310,11 @@ export function useReferenceLine(
     const chartH = chartBottom - chartTop;
     const x1 = padding.left;
     const x2 = w - padding.right;
+    // Full-width lines/bands run edge-to-edge through the gutters (0..canvas);
+    // the badge/label anchor (x1/x2) stays at the plot edges either way.
+    const fullWidth = line.fullWidth ?? false;
+    const lineX1 = fullWidth ? 0 : x1;
+    const lineX2 = fullWidth ? w : x2;
 
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;
@@ -320,6 +351,9 @@ export function useReferenceLine(
         yBottom: chartBottom,
         x1: bx1,
         x2: bx2,
+        // Time band is vertical and time-bounded — full-width does not apply.
+        lineX1: bx1,
+        lineX2: bx2,
         label,
         labelX,
         labelY: chartTop - fm.ascent + 2,
@@ -361,6 +395,8 @@ export function useReferenceLine(
         yBottom: yBot,
         x1,
         x2,
+        lineX1,
+        lineX2,
         label,
         labelX,
         labelY: yTop - fm.ascent + 2,
@@ -369,7 +405,11 @@ export function useReferenceLine(
 
     // ── Form A — horizontal line (with optional pill badge) ──────────────────
     if (line.value === undefined) return INVISIBLE;
-    const v = line.value;
+    // Effective value: a live drag override (if present) else the static prop.
+    const v =
+      dragValues && dragValues.value[index] != null
+        ? dragValues.value[index]
+        : line.value;
     const edge = classifyReferenceEdge(v, dMin, dMax);
 
     // Off-screen: pin the badge to the nearest edge with a chevron (when a badge
@@ -418,6 +458,10 @@ export function useReferenceLine(
         yBottom: y,
         x1,
         x2,
+        lineX1,
+        lineX2,
+        // Full-width: the edge-to-edge line replaces the dashed connector.
+        drawLine: fullWidth,
         label: text,
         labelX: g.textX,
         labelY: y - baselineOffset,
@@ -426,8 +470,8 @@ export function useReferenceLine(
         pillW: g.pillW,
         iconX: g.iconX,
         icon: badge.icon,
-        connStart: g.connStart,
-        connEnd: g.connEnd,
+        connStart: fullWidth ? -1 : g.connStart,
+        connEnd: fullWidth ? -1 : g.connEnd,
       };
     }
 
@@ -449,6 +493,9 @@ export function useReferenceLine(
       yBottom: y,
       x1,
       x2,
+      lineX1,
+      lineX2,
+      drawLine: true,
       label,
       labelX,
       labelY: y - baselineOffset,

package/src/hooks/useReferenceLinePress.ts

@@ -1,6 +1,6 @@
 import type { SkFont } from "@shopify/react-native-skia";
 import { Gesture } from "react-native-gesture-handler";
-import { useDerivedValue } from "react-native-reanimated";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
@@ -33,6 +33,9 @@ export function useReferenceLinePress(
   /** Touch-target inflation around each pill, in px. */
   hitSlop: number,
   onPress?: (line: ReferenceLine, index: number) => void,
+  /** Per-line live value overrides (dragged values) so a draggable line's hit-rect
+   *  tracks the drag, index-aligned with `lines`. */
+  dragValues?: SharedValue<number[]>,
 ): {
   tapGesture: ReturnType<typeof Gesture.Tap>;
   hitTest: (x: number, y: number) => boolean;
@@ -47,9 +50,20 @@ export function useReferenceLinePress(
     const dMin = engine.displayMin.value;
     const dMax = engine.displayMax.value;
     const out: (ReferenceBadgeRect | null)[] = [];
+    const dv = dragValues?.value;
     for (let i = 0; i < lines.length; i++) {
       out.push(
-        computeReferenceBadgeRect(lines[i], w, h, padding, dMin, dMax, font, formatValue),
+        computeReferenceBadgeRect(
+          lines[i],
+          w,
+          h,
+          padding,
+          dMin,
+          dMax,
+          font,
+          formatValue,
+          dv ? dv[i] : undefined,
+        ),
       );
     }
     return out;

package/src/hooks/useVisibleRange.ts

@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useRef } from "react";
+import {
+  useAnimatedReaction,
+  type SharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+import type { VisibleRange } from "../types";
+
+export type { VisibleRange };
+
+/** Engine SharedValues the visible-range reaction reads. */
+export interface VisibleRangeEngineRefs {
+  timestamp: SharedValue<number>;
+  displayWindow: SharedValue<number>;
+  viewEnd: SharedValue<number | null>;
+}
+
+export interface UseVisibleRangeOptions {
+  engine: VisibleRangeEngineRefs;
+  /** Earliest retained time (unix seconds) — used for the `onReachStart` trigger. */
+  minTime: SharedValue<number>;
+  /** Fires (throttled to ~1 Hz) when the visible window's edges change. */
+  onVisibleRangeChange?: (range: VisibleRange) => void;
+  /**
+   * Fires once when the window's left edge comes within one window-width of the
+   * earliest retained data — the cue to lazily page in older history. Re-arms
+   * after the edge moves back out.
+   */
+  onReachStart?: () => void;
+}
+
+/**
+ * Throttle key for a visible range: integer seconds of each edge plus the
+ * near-start flag. The reaction emits only when this changes, so a live chart
+ * (whose right edge slides every frame) notifies at most ~once per second rather
+ * than per frame, and `onReachStart` edge-triggers off the trailing flag.
+ */
+export function rangeSignature(
+  startSec: number,
+  endSec: number,
+  near: boolean,
+): string {
+  "worklet";
+  return `${Math.round(startSec)}|${Math.round(endSec)}|${near ? 1 : 0}`;
+}
+
+/** Whether the window's left edge is within `threshold` seconds of the oldest data. */
+export function isNearStart(
+  winStart: number,
+  minTime: number,
+  threshold: number,
+): boolean {
+  "worklet";
+  return winStart <= minTime + threshold;
+}
+
+/**
+ * Bridges the UI-thread visible window to JS paging callbacks. A reaction watches
+ * the window edges and `scheduleOnRN`s `onVisibleRangeChange` (throttled) and
+ * `onReachStart` (edge-triggered near the oldest data). Inert when both callbacks
+ * are absent. Used by both `LiveChart` and `LiveChartSeries`.
+ */
+export function useVisibleRange({
+  engine,
+  minTime,
+  onVisibleRangeChange,
+  onReachStart,
+}: UseVisibleRangeOptions): void {
+  // Latest callbacks behind refs so the (deps-stable) dispatchers below always
+  // call the current prop without re-subscribing the reaction each render.
+  const rangeCb = useRef(onVisibleRangeChange);
+  const reachCb = useRef(onReachStart);
+  useEffect(() => {
+    rangeCb.current = onVisibleRangeChange;
+    reachCb.current = onReachStart;
+  }, [onVisibleRangeChange, onReachStart]);
+
+  const emitRange = useCallback(
+    /* istanbul ignore next -- dispatched via scheduleOnRN from the UI thread, not in Jest */
+    (startSec: number, endSec: number, following: boolean) => {
+      rangeCb.current?.({ startSec, endSec, following });
+    },
+    [],
+  );
+  const emitReachStart = useCallback(
+    /* istanbul ignore next -- dispatched via scheduleOnRN from the UI thread, not in Jest */
+    () => {
+      reachCb.current?.();
+    },
+    [],
+  );
+
+  const active = onVisibleRangeChange != null || onReachStart != null;
+
+  useAnimatedReaction(
+    /* istanbul ignore next -- Reanimated reaction worklet; runs on the UI thread, not in Jest */
+    () => {
+      if (!active) return ""; // inert — never changes, so the reaction never fires
+      const end = engine.timestamp.value;
+      const win = engine.displayWindow.value;
+      const start = end - win;
+      return rangeSignature(start, end, isNearStart(start, minTime.value, win));
+    },
+    /* istanbul ignore next -- Reanimated reaction; dispatches on the JS thread, not exercised under Jest */
+    (curr, prev) => {
+      if (!active || curr === "" || curr === prev) return;
+      const end = engine.timestamp.value;
+      const win = engine.displayWindow.value;
+      const start = end - win;
+      const following = engine.viewEnd.value == null;
+      const near = isNearStart(start, minTime.value, win);
+      const wasNear = typeof prev === "string" && prev.endsWith("|1");
+      scheduleOnRN(emitRange, start, end, following);
+      if (near && !wasNear) scheduleOnRN(emitReachStart);
+    },
+    [active, emitRange, emitReachStart],
+  );
+}

package/src/index.ts

@@ -25,6 +25,10 @@ export { MONO_FONT_FAMILY } from "./lib/monoFontFamily";
 export { useDegen } from "./hooks/useDegen";
 export { useTradeStream } from "./hooks/useTradeStream";
 
+// ── renderOverlay bridge hooks (reactive price→Y / time→X for custom overlays) ──
+
+export { usePriceY, useTimeX } from "./hooks/useChartOverlayContext";
+
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export type {
@@ -32,10 +36,14 @@ export type {
   AxisLabelConfig,
   BadgeConfig,
   BadgeMetrics,
+  BadgeStyleConfig,
   BadgeVariant,
   CandleMetrics,
   CandlePoint,
   ChartInsets,
+  ChartOverlayContext,
+  ChartPlotRect,
+  ChartScale,
   ChartSegment,
   DegenOptions,
   DegenShakePayload,
@@ -57,8 +65,11 @@ export type {
   LiveChartProps,
   LiveChartSeriesProps,
   Marker,
-  MarkerHoverEvent,
+  MarkerClusterConfig,
   MarkerKind,
+  MarkerPressEvent,
+  MarkerRenderContext,
+  MarkerSide,
   Momentum,
   MomentumConfig,
   MotionMetrics,
@@ -66,6 +77,8 @@ export type {
   PulseConfig,
   ReferenceLine,
   ReferenceLineBadgeConfig,
+  ReferenceLineGroupingConfig,
+  ReferenceLineRenderProps,
   ScrubActionConfig,
   ScrubActionPoint,
   ScrubConfig,
@@ -83,6 +96,9 @@ export type {
   TooltipRenderProps,
   TradeEvent,
   ValueLineConfig,
+  VisibleRange,
+  VolumeConfig,
   XAxisConfig,
   YAxisConfig,
+  ZoomConfig,
 } from "./types";

package/src/math/markerCluster.ts

@@ -0,0 +1,214 @@
+import type { Marker, MarkerSide } from "../types";
+import type { ProjectedMarker } from "./markers";
+
+/**
+ * Resolved {@link LiveChartProps.markerCluster} config (see `resolveMarkerCluster`).
+ */
+export interface ResolvedMarkerCluster {
+  /** `"anchored"` = no collision handling (glyphs overlap). `"stacked"` = fan +
+   *  collapse co-located markers. */
+  mode: "anchored" | "stacked";
+  /** Fraction (0–1) that adjacent co-located glyphs overlap when fanned. The fan
+   *  step is `glyphHeight * (1 - overlap)`; `glyphHeight` is a slightly generous
+   *  primitive estimate, so the *visible* overlap runs a touch lower. */
+  overlap: number;
+  /** Extra px between a sided glyph and its anchor. */
+  gap: number;
+  /** Collapse a co-located run to a single count badge once it exceeds this many. */
+  maxBeforeGroup: number;
+}
+
+export interface ClusterMarkersOpts {
+  config: ResolvedMarkerCluster;
+}
+
+/** Glyph box used when `marker.size` is unset — mirrors `markerAtlas.DEFAULT_ICON_SIZE`. */
+const DEFAULT_GLYPH = 16;
+
+/**
+ * Estimated vertical (≈ horizontal) footprint of a marker glyph in px. Derived
+ * from primitives only (no font metrics / atlas), so the hit-test hook and the
+ * overlays compute identical offsets from identical inputs — keeping the drawn
+ * and hit-tested positions in sync. Not pixel-exact with the atlas cell; the
+ * generous default `markerHitRadius` absorbs the small difference.
+ */
+export function glyphHeight(m: Marker): number {
+  "worklet";
+  const size = m.size ?? DEFAULT_GLYPH;
+  // The pill badge adds padding + a background ring around the icon glyph.
+  return m.pill ? size + 8 : size;
+}
+
+function sideOf(m: Marker): MarkerSide {
+  "worklet";
+  return m.side ?? "center";
+}
+
+/**
+ * Axis-anchored kinds (graduation stem, clawback box) whose geometry is pinned
+ * to the baseline — they aren't fixed-size glyphs, so they don't stack or
+ * collapse. Mirrors `markerAtlas.isConnectorMarker` (duplicated to keep this
+ * math module free of the Skia-importing draw layer).
+ */
+function isConnector(m: Marker): boolean {
+  "worklet";
+  return !m.image && !m.icon && (m.kind === "graduation" || m.kind === "clawback");
+}
+
+/** Stable rank so the index sort groups markers by side. */
+function sideRank(side: MarkerSide): number {
+  "worklet";
+  return side === "above" ? 0 : side === "center" ? 1 : 2;
+}
+
+/**
+ * Lay out one co-located bucket `idx[s..e)` (already ordered by time), mutating
+ * `proj`. All glyphs sit at the same `side` height (above / below / on the line)
+ * and fan out HORIZONTALLY with a slight overlap — the "( ) ) )" stacked-coins
+ * look, centered on the time anchor. When the bucket is larger than
+ * `maxBeforeGroup` it collapses instead: one representative (the newest) is
+ * flagged `isGrouped` with `groupCount`, the rest are `hidden` and point back via
+ * `groupRep` (so a tap can gather the members).
+ */
+function layoutBucket(
+  markers: Marker[],
+  proj: ProjectedMarker[],
+  idx: number[],
+  s: number,
+  e: number,
+  side: MarkerSide,
+  opts: ClusterMarkersOpts,
+): void {
+  "worklet";
+  const count = e - s;
+  const anchorX = proj[idx[s]].x;
+  const anchorY = proj[idx[s]].y;
+  const { gap, maxBeforeGroup } = opts.config;
+
+  // Tallest glyph in the bucket sets the side offset and the horizontal step.
+  let h = 0;
+  for (let k = s; k < e; k++) {
+    const gh = glyphHeight(markers[idx[k]]);
+    if (gh > h) h = gh;
+  }
+  const sideDy =
+    side === "above" ? -(h / 2 + gap) : side === "below" ? h / 2 + gap : 0;
+
+  if (count > maxBeforeGroup) {
+    // Collapse to a count badge at the representative (newest = last by time).
+    const rep = idx[e - 1];
+    for (let k = s; k < e; k++) {
+      const p = proj[idx[k]];
+      p.groupRep = rep;
+      if (idx[k] === rep) {
+        p.x = anchorX;
+        p.y = anchorY + sideDy;
+        p.isGrouped = true;
+        p.groupCount = count;
+        p.hidden = false;
+      } else {
+        p.hidden = true;
+      }
+    }
+    return;
+  }
+
+  // Horizontal overlapping fan, centered on the anchor x. Glyphs share the side
+  // height. Positions run right→left as the bucket order advances, so the newest
+  // (last, highest array index) sits LEFTMOST — and since the overlay draws in
+  // array order, it paints on top: a left-over-right cascade ("(" over ")" over ")").
+  const step = h * (1 - opts.config.overlap);
+  for (let j = 0; j < count; j++) {
+    const p = proj[idx[s + j]];
+    p.x = anchorX + ((count - 1) / 2 - j) * step;
+    p.y = anchorY + sideDy;
+    p.hidden = false;
+    p.isGrouped = false;
+    p.groupCount = 0;
+    p.groupRep = -1;
+  }
+}
+
+/**
+ * Collision pass over projected markers, mutating `proj` in place.
+ *
+ * `"anchored"` mode only applies each marker's {@link Marker.side} offset (a lone
+ * glyph sitting above/below its anchor); it does no bucketing, so charts that
+ * don't use `side` are untouched. `"stacked"` mode additionally buckets
+ * co-located markers (same side, overlapping x/y) and fans or collapses them.
+ *
+ * Runs every frame on the UI thread, so grouping is zoom/scroll-reactive. Reads
+ * the *raw* projected positions from `projectMarkers` and overwrites them.
+ */
+export function clusterMarkers(
+  markers: Marker[],
+  proj: ProjectedMarker[],
+  opts: ClusterMarkersOpts,
+): void {
+  "worklet";
+  const n = markers.length;
+
+  if (opts.config.mode !== "stacked") {
+    // Side-only: shift sided glyphs off their anchor; no neighbor interaction.
+    for (let i = 0; i < n; i++) {
+      const p = proj[i];
+      if (!p.visible || isConnector(markers[i])) continue;
+      const side = sideOf(markers[i]);
+      if (side === "center") continue;
+      const off = glyphHeight(markers[i]) / 2 + opts.config.gap;
+      p.y += side === "above" ? -off : off;
+    }
+    return;
+  }
+
+  // Collect visible indices, then order by (side, x, y, time) so co-located
+  // same-side markers are adjacent and fan in time order.
+  const idx: number[] = [];
+  for (let i = 0; i < n; i++) if (proj[i].visible && !isConnector(markers[i])) idx.push(i);
+  idx.sort((a, b) => {
+    const sr = sideRank(sideOf(markers[a])) - sideRank(sideOf(markers[b]));
+    if (sr !== 0) return sr;
+    if (proj[a].x !== proj[b].x) return proj[a].x - proj[b].x;
+    if (proj[a].y !== proj[b].y) return proj[a].y - proj[b].y;
+    return markers[a].time - markers[b].time;
+  });
+
+  // Sweep into buckets: same side and within a glyph of the bucket's anchor in
+  // BOTH axes (so two markers at the same time but far apart in value don't merge).
+  let s = 0;
+  while (s < idx.length) {
+    const side = sideOf(markers[idx[s]]);
+    const startX = proj[idx[s]].x;
+    const startY = proj[idx[s]].y;
+    const colPx = glyphHeight(markers[idx[s]]);
+    let e = s + 1;
+    while (
+      e < idx.length &&
+      sideOf(markers[idx[e]]) === side &&
+      Math.abs(proj[idx[e]].x - startX) <= colPx &&
+      Math.abs(proj[idx[e]].y - startY) <= colPx
+    ) {
+      e++;
+    }
+    layoutBucket(markers, proj, idx, s, e, side, opts);
+    s = e;
+  }
+}
+
+/**
+ * Markers belonging to the collapsed cluster whose representative is `repIndex`
+ * (ordered by time). Call after {@link clusterMarkers} has populated `proj`.
+ */
+export function clusterMembers(
+  markers: Marker[],
+  proj: ProjectedMarker[],
+  repIndex: number,
+): Marker[] {
+  "worklet";
+  const out: Marker[] = [];
+  for (let i = 0; i < markers.length; i++) {
+    if (proj[i] && proj[i].groupRep === repIndex) out.push(markers[i]);
+  }
+  out.sort((a, b) => a.time - b.time);
+  return out;
+}