react-native-livechart 4.11.0 → 4.12.0

package/src/hooks/useChartPaths.ts

@@ -1,13 +1,28 @@
 import { Skia, type SkPath } from "@shopify/react-native-skia";
 import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type {
+  ChartEngineEdge,
+  ChartEngineScroll,
+  SingleEngineState,
+} from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
 import { drawSpline, makeSplineScratch } from "../math/spline";
 import { sampleThresholdYAt, thresholdSampleSpanX } from "../math/threshold";
 import { blendPtsY, squigglifyPts } from "../math/squiggly";
 import { usePathBuilder } from "./usePathBuilder";
 
+/** Selects the synthetic right-edge line tip without coupling chart geometry
+ * to badge or live-indicator presentation options. */
+export function resolveLineTipValue(
+  displayValue: number,
+  edgeValue: number,
+  viewEnd: number | null,
+): number {
+  "worklet";
+  return viewEnd == null ? displayValue : edgeValue;
+}
+
 /**
  * Builds the `linePath` / `fillPath` with `Skia.PathBuilder`s reused across
  * frames (one per curve, held in a SharedValue) and finalized with `detach()` —
@@ -20,7 +35,7 @@ import { usePathBuilder } from "./usePathBuilder";
  * fillPath.
  */
 export function useChartPaths(
-  engine: SingleEngineState,
+  engine: SingleEngineState & ChartEngineScroll & ChartEngineEdge,
   padding: ChartPadding,
   morphT?: SharedValue<number>,
   /** When set, also build `thresholdFillPath` — the band between the line and this
@@ -28,14 +43,6 @@ export function useChartPaths(
   thresholdY?: SharedValue<number>,
   /** Draw the line/fill as a straight polyline instead of the monotone cubic. */
   linear = false,
-  /**
-   * Value at the visible window's right edge (engine `edgeValue`). With
-   * `followViewEdge`, the line's right-edge tip uses this instead of the live
-   * `displayValue` — so while time-scrolled the line ends at the last visible
-   * price rather than dropping to the (off-screen) live value.
-   */
-  edgeValue?: SharedValue<number>,
-  followViewEdge = false,
   /** Loading squiggle wave amplitude (px) for the reveal morph. Default 14. */
   squiggleAmplitude = 14,
   /** Loading squiggle wave speed multiplier for the reveal morph. Default 1. */
@@ -79,11 +86,14 @@ export function useChartPaths(
     const cache = cacheRef.current!;
     cache.ptsTick = !cache.ptsTick;
     const buf = cache.ptsTick ? cache.ptsA : cache.ptsB;
-    // While scrolled back with `followViewEdge`, tip the line at the view-edge
-    // price (engine `edgeValue`) instead of the live value — otherwise the line
-    // drops from the last visible point to the off-screen live value at the edge.
-    const tipValue =
-      followViewEdge && edgeValue ? edgeValue.get() : engine.displayValue.get();
+    // A historical window must end at its own right-edge price. Badge and
+    // live-indicator options affect overlays only; they must not distort the
+    // plotted series by connecting history to the off-screen live value.
+    const tipValue = resolveLineTipValue(
+      engine.displayValue.get(),
+      engine.edgeValue.get(),
+      engine.viewEnd.get(),
+    );
     const realPts = buildLinePoints(
       engine.data.get(),
       tipValue,

package/src/hooks/useCrosshair.ts

@@ -40,6 +40,7 @@ import {
 import {
   delayedPanTouchCancelled,
   delayedPanTouchDown,
+  delayedPanTouchMove,
   delayedPanTouchUp,
   resetDelayedPanGuard,
   shouldStartDelayedPan,
@@ -152,6 +153,12 @@ export function useCrosshair(
    * exclusion (the default; scrub covers the whole plot).
    */
   scrubBottomExclude = 0,
+  /**
+   * True while the time-scroll pan owns the touch. The hold-to-scrub pan refuses
+   * to activate while set, so a drag that already started scrolling can never
+   * mature into a scrub (see `delayedPanGuard.shouldStartDelayedPan`).
+   */
+  scrollActive?: SharedValue<boolean>,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -162,6 +169,18 @@ export function useCrosshair(
   // lifecycle helpers are also used by LiveChartSeries and unit-tested directly.
   const fingerDown = useSharedValue(false);
   const panActivated = useSharedValue(false);
+  // Where and when the current touch went down, for the stationary-hold and
+  // stale-timer guards (see delayedPanGuard).
+  const downX = useSharedValue(0);
+  const downY = useSharedValue(0);
+  const downAtMs = useSharedValue(0);
+  // Latched once the finger leaves the hold slop: this touch is a drag, so its
+  // long-press timer must not be honored even if it still fires.
+  const holdBroken = useSharedValue(false);
+  // Inert stand-in so the guard always has a latch to read when the controller
+  // wires no time-scroll (hooks must be created unconditionally).
+  const noScrollActive = useSharedValue(false);
+  const scrollActiveSV = scrollActive ?? noScrollActive;
   // Where the crosshair line should start (canvas Y) so it stops at a top-pinned
   // custom tooltip instead of running through it. -1 = no top tooltip → the line
   // starts at padding.top. Written by CustomTooltipOverlay, read by CrosshairOverlay.
@@ -505,9 +524,33 @@ export function useCrosshair(
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     .onTouchesDown(
-      /* istanbul ignore next */ () => {
+      /* istanbul ignore next */ (e) => {
         "worklet";
-        delayedPanTouchDown(longPressMs, fingerDown);
+        delayedPanTouchDown(
+          longPressMs,
+          e,
+          fingerDown,
+          downX,
+          downY,
+          downAtMs,
+          holdBroken,
+        );
+      },
+    )
+    // Stationary hold: drift beyond the slop while the long-press is still
+    // pending fails the pan, so a drag can never mature into a scrub.
+    .onTouchesMove(
+      /* istanbul ignore next */ (e, manager) => {
+        "worklet";
+        delayedPanTouchMove(
+          longPressMs,
+          e,
+          manager,
+          panActivated,
+          downX,
+          downY,
+          holdBroken,
+        );
       },
     )
     .onTouchesUp(
@@ -535,7 +578,17 @@ export function useCrosshair(
     .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
-        if (!shouldStartDelayedPan(longPressMs, fingerDown, panActivated)) return;
+        if (
+          !shouldStartDelayedPan(
+            longPressMs,
+            fingerDown,
+            panActivated,
+            downAtMs,
+            holdBroken,
+            scrollActiveSV,
+          )
+        )
+          return;
         if (!enabled) return;
         // Scrub-action: once a reticle is placed, drag adjusts it (2D — the Y is
         // the price). The ephemeral live-scrub never engages, so scrubActive
@@ -600,7 +653,7 @@ export function useCrosshair(
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        resetDelayedPanGuard(fingerDown, panActivated);
+        resetDelayedPanGuard(fingerDown, panActivated, holdBroken);
         // A lock-adjust drag leaves the reticle in place (scrubActive was never
         // set); a live-scrub clears its crosshair. Always clear scrubActive so a
         // stray scrub can never linger behind a placed reticle.

package/src/hooks/useCrosshairSeries.ts

@@ -1,14 +1,19 @@
+import type { SkFont } from "@shopify/react-native-skia";
 import { Gesture } from "react-native-gesture-handler";
 import {
   useAnimatedReaction,
   useDerivedValue,
   useSharedValue,
+  type DerivedValue,
+  type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
+import type { ResolvedPerSeriesTooltipConfig } from "../core/resolveConfig";
 import type { MultiEngineState } from "../core/useLiveChartEngine";
 import { type ChartPadding } from "../draw/line";
 import type { ScrubPointMulti } from "../types";
 import {
+  computePerSeriesTooltipLayout,
   deriveScrubValueSeries,
   interpolateSeriesAtTime,
 } from "./crosshairSeries";
@@ -24,15 +29,26 @@ import {
 import {
   delayedPanTouchCancelled,
   delayedPanTouchDown,
+  delayedPanTouchMove,
   delayedPanTouchUp,
   resetDelayedPanGuard,
   shouldStartDelayedPan,
 } from "./delayedPanGuard";
 
 /**
- * LiveChartSeries crosshair + scrub. No tooltip — data is delivered via
- * `onScrub` worklet callback on the UI thread.
+ * LiveChartSeries crosshair + scrub. The optional per-series tooltip is
+ * calculated on the UI thread alongside the callback payload.
  */
+interface CrosshairSeriesTooltipOptions {
+  config: ResolvedPerSeriesTooltipConfig;
+  formatValue: (value: number) => string;
+  formatTime: (time: number) => string;
+  font: SkFont;
+  colors: string[];
+  /** Current-time anchor used to clamp the live bucket's range end. */
+  maxTime: SharedValue<number> | DerivedValue<number>;
+}
+
 export function useCrosshairSeries(
   engine: MultiEngineState,
   padding: ChartPadding,
@@ -42,6 +58,13 @@ export function useCrosshairSeries(
   panGestureDelay = 0,
   onGestureStart?: () => void,
   onGestureEnd?: () => void,
+  /**
+   * True while the time-scroll pan owns the touch. The hold-to-scrub pan refuses
+   * to activate while set, so a drag that already started scrolling can never
+   * mature into a scrub (see `delayedPanGuard.shouldStartDelayedPan`).
+   */
+  scrollActive?: SharedValue<boolean>,
+  tooltip?: CrosshairSeriesTooltipOptions,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -52,6 +75,18 @@ export function useCrosshairSeries(
   // the final pointer has already lifted on iOS.
   const fingerDown = useSharedValue(false);
   const panActivated = useSharedValue(false);
+  // Where and when the current touch went down, for the stationary-hold and
+  // stale-timer guards (see delayedPanGuard).
+  const downX = useSharedValue(0);
+  const downY = useSharedValue(0);
+  const downAtMs = useSharedValue(0);
+  // Latched once the finger leaves the hold slop: this touch is a drag, so its
+  // long-press timer must not be honored even if it still fires.
+  const holdBroken = useSharedValue(false);
+  // Inert stand-in so the guard always has a latch to read when the controller
+  // wires no time-scroll (hooks must be created unconditionally).
+  const noScrollActive = useSharedValue(false);
+  const scrollActiveSV = scrollActive ?? noScrollActive;
 
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
@@ -94,7 +129,27 @@ export function useCrosshairSeries(
     ),
   );
 
-  const tooltipLayout = useSharedValue(HIDDEN_TOOLTIP);
+  const tooltipLayout = useDerivedValue(() => {
+    if (!tooltip) return HIDDEN_TOOLTIP;
+    return computePerSeriesTooltipLayout(
+      scrubActive.get(),
+      scrubX.get(),
+      scrubTime.get(),
+      engine.series.get(),
+      engine.displaySeriesValues.get(),
+      tooltip.colors,
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      padding,
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      tooltip.maxTime.get(),
+      tooltip.formatValue,
+      tooltip.formatTime,
+      tooltip.font,
+      tooltip.config,
+    );
+  });
 
   /* istanbul ignore next */
   function handleGestureStart() {
@@ -169,9 +224,33 @@ export function useCrosshairSeries(
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     .onTouchesDown(
-      /* istanbul ignore next */ () => {
+      /* istanbul ignore next */ (e) => {
         "worklet";
-        delayedPanTouchDown(panGestureDelay, fingerDown);
+        delayedPanTouchDown(
+          panGestureDelay,
+          e,
+          fingerDown,
+          downX,
+          downY,
+          downAtMs,
+          holdBroken,
+        );
+      },
+    )
+    // Stationary hold: drift beyond the slop while the long-press is still
+    // pending fails the pan, so a drag can never mature into a scrub.
+    .onTouchesMove(
+      /* istanbul ignore next */ (e, manager) => {
+        "worklet";
+        delayedPanTouchMove(
+          panGestureDelay,
+          e,
+          manager,
+          panActivated,
+          downX,
+          downY,
+          holdBroken,
+        );
       },
     )
     .onTouchesUp(
@@ -199,7 +278,16 @@ export function useCrosshairSeries(
     .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
-        if (!shouldStartDelayedPan(panGestureDelay, fingerDown, panActivated))
+        if (
+          !shouldStartDelayedPan(
+            panGestureDelay,
+            fingerDown,
+            panActivated,
+            downAtMs,
+            holdBroken,
+            scrollActiveSV,
+          )
+        )
           return;
         if (!enabled) return;
         scrubX.set(e.x);
@@ -218,7 +306,7 @@ export function useCrosshairSeries(
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        resetDelayedPanGuard(fingerDown, panActivated);
+        resetDelayedPanGuard(fingerDown, panActivated, holdBroken);
         scrubActive.set(false);
         if (gestureStarted.get()) {
           gestureStarted.set(false);

package/src/hooks/useMomentum.ts

@@ -13,16 +13,23 @@ import type { Momentum, MomentumConfig } from "../types";
 export function resolveMomentumProp(
   prop: boolean | Momentum | MomentumConfig,
   data: readonly { time: number; value: number }[],
+  endTime?: number,
 ): Momentum {
   "worklet";
   if (prop === false) return "flat";
   if (prop === true)
-    return detectMomentum(data as { time: number; value: number }[]);
+    return detectMomentum(
+      data as { time: number; value: number }[],
+      undefined,
+      undefined,
+      endTime,
+    );
   if (typeof prop === "object")
     return detectMomentum(
       data as { time: number; value: number }[],
       prop.lookback,
       prop.threshold,
+      endTime,
     );
   return prop;
 }

package/src/hooks/usePanScroll.ts

@@ -57,6 +57,20 @@ export interface UsePanScrollOptions {
    * a stray scrub doesn't linger behind the pan.
    */
   onScrollStart?: () => void;
+  /**
+   * Set true for as long as this gesture owns the touch, cleared on finalize.
+   * The hold-to-scrub pan reads it and refuses to activate mid-scroll — RNGH's
+   * `Gesture.Race` declares no relation between the two pans, so this latch is
+   * the only thing stopping the scrub's long-press timer from firing while the
+   * chart is already being dragged. See `delayedPanGuard.shouldStartDelayedPan`.
+   */
+  scrollActive?: SharedValue<boolean>;
+  /**
+   * True while the scrub crosshair owns the touch. Scrolling is inert while set,
+   * so an engaged scrub locks the chart in place and the finger only moves the
+   * price indicator. Cleared when the finger lifts (the scrub pan's finalize).
+   */
+  scrubActive?: SharedValue<boolean>;
 }
 
 /**
@@ -134,6 +148,8 @@ export function usePanScroll({
   enabled,
   mode = "holdToScrub",
   onScrollStart,
+  scrollActive,
+  scrubActive,
 }: UsePanScrollOptions): ReturnType<typeof Gesture.Pan> {
   const { viewEnd, liveEdge, displayWindow, canvasWidth, canvasHeight } = engine;
   const padLeft = padding.left;
@@ -150,10 +166,21 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      // Stop an in-flight fling FIRST. `withDecay` keeps writing `viewEnd` after
+      // the finger lifts, and `Gesture.Race` declares no relation between the two
+      // pans, so this can run while a scrub is already engaged. Bailing out below
+      // without cancelling left the decay sliding the window underneath the
+      // crosshair — the opposite of the lock the scrub is meant to hold.
       cancelAnimation(viewEnd);
-      // Anchor at the current right edge so the first delta is relative to where
-      // the window sits (the live edge when we were following).
-      if (viewEnd.get() == null) viewEnd.set(liveEdge.get());
+      // An engaged scrub locks the chart: the finger moves the price indicator
+      // across a fixed window, so a scroll that activates underneath it must do
+      // nothing further (and must not claim the touch via `scrollActive`).
+      if (scrubActive?.get()) return;
+      scrollActive?.set(true);
+      // Keep `null` while following live. `onChange` resolves it to the current
+      // live edge before applying the first delta. Materializing that same edge
+      // here would falsely signal "scrolled back" between start and change,
+      // briefly collapsing the floating-axis gutter on a forward-only overdrag.
       onScrollStart?.();
     };
 
@@ -161,6 +188,7 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     (e: { changeX: number }) => {
       "worklet";
+      if (scrubActive?.get()) return;
       const win = displayWindow.get();
       const chartW = canvasWidth.get() - padLeft - padRight;
       if (chartW <= 0) return;
@@ -174,6 +202,7 @@ export function usePanScroll({
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     (e: { velocityX: number }) => {
       "worklet";
+      if (scrubActive?.get()) return;
       if (viewEnd.get() == null) return;
       const win = displayWindow.get();
       const chartW = canvasWidth.get() - padLeft - padRight;
@@ -194,6 +223,16 @@ export function usePanScroll({
       );
     };
 
+  // Release the touch claim on every terminal state (END, FAIL, CANCEL), not just
+  // onEnd — a scroll that fails its offset clamps never reaches onEnd, and a
+  // stuck `scrollActive` would block scrub for the rest of the session.
+  const onFinalize =
+    /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
+    () => {
+      "worklet";
+      scrollActive?.set(false);
+    };
+
   if (mode === "axisDrag") {
     return Gesture.Pan()
       .enabled(enabled)
@@ -235,7 +274,8 @@ export function usePanScroll({
       )
       .onStart(onStart)
       .onChange(onChange)
-      .onEnd(onEnd);
+      .onEnd(onEnd)
+      .onFinalize(onFinalize);
   }
 
   // holdToScrub (default): a one-finger drag anywhere scrolls. Activate on
@@ -249,5 +289,6 @@ export function usePanScroll({
     .failOffsetY([-HOLD_SCRUB_FAIL_Y_PX, HOLD_SCRUB_FAIL_Y_PX])
     .onStart(onStart)
     .onChange(onChange)
-    .onEnd(onEnd);
+    .onEnd(onEnd)
+    .onFinalize(onFinalize);
 }

package/src/index.ts

@@ -77,6 +77,7 @@ export type {
   MomentumConfig,
   MotionMetrics,
   MultiSeriesDotConfig,
+  PerSeriesTooltipConfig,
   PulseConfig,
   ReferenceLine,
   ReferenceLineBadgeConfig,

package/src/math/lerp.ts

@@ -12,6 +12,13 @@ export function lerp(
   dt = MS_PER_FRAME_60FPS,
 ): number {
   "worklet";
+  // speed >= 1 means "snap in one frame". Computing it through the exponential
+  // would evaluate 0 ** (dt / frame), which is Infinity for a negative frame
+  // delta. When current === target, the resulting 0 * -Infinity becomes NaN
+  // and is permanent once written back into a SharedValue. No broader guard:
+  // NaN inputs must keep propagating (the engine tick relies on a NaN
+  // displayValue staying NaN so the y-range block stays skipped).
+  if (speed >= 1) return target;
   const factor = 1 - Math.pow(1 - speed, dt / MS_PER_FRAME_60FPS);
   return current + (target - current) * factor;
 }

package/src/math/momentum.ts

@@ -9,15 +9,32 @@ export function detectMomentum(
   points: LiveChartPoint[],
   lookback = 20,
   threshold = 0.12,
+  endTime?: number,
 ): Momentum {
   "worklet";
-  if (points.length < 5) return "flat";
+  // `badge.followViewEdge` needs momentum at the historical window edge rather
+  // than at the live dataset tail. Points are chronological, so find the first
+  // sample after the inclusive cutoff without allocating a sliced array on the
+  // UI thread. With no cutoff, preserve the normal live-tail behavior.
+  let end = points.length;
+  if (endTime !== undefined) {
+    let lo = 0;
+    let hi = points.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (points[mid].time <= endTime) lo = mid + 1;
+      else hi = mid;
+    }
+    end = lo;
+  }
+
+  if (end < 5) return "flat";
 
-  const start = Math.max(0, points.length - lookback);
+  const start = Math.max(0, end - lookback);
 
   let min = Infinity;
   let max = -Infinity;
-  for (let i = start; i < points.length; i++) {
+  for (let i = start; i < end; i++) {
     const v = points[i].value;
     if (v < min) min = v;
     if (v > max) max = v;
@@ -25,9 +42,9 @@ export function detectMomentum(
   const range = max - min;
   if (range === 0) return "flat";
 
-  const tailStart = Math.max(start, points.length - 5);
+  const tailStart = Math.max(start, end - 5);
   const first = points[tailStart].value;
-  const last = points[points.length - 1].value;
+  const last = points[end - 1].value;
   const delta = last - first;
 
   const absThreshold = range * threshold;

package/src/math/referenceLines.ts

@@ -44,6 +44,44 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   return out;
 }
 
+/**
+ * Stable React keys for an ordered reference-line list. A caller-supplied `id`
+ * keeps the key stable across reordering; the visual config is a deterministic
+ * fallback for legacy lines. Equal fallback signatures receive a suffix so they
+ * remain distinct siblings.
+ */
+export function referenceLineReactKeys(
+  lines: readonly ReferenceLine[],
+): string[] {
+  const occurrences = new Map<string, number>();
+  const keys: string[] = [];
+  for (const line of lines) {
+    const base = line.id ?? stableReferenceLineSignature(line);
+    const occurrence = occurrences.get(base) ?? 0;
+    occurrences.set(base, occurrence + 1);
+    keys.push(`${base}:${occurrence}`);
+  }
+  return keys;
+}
+
+/** Serializes render-relevant config without callback identity churn. */
+function stableReferenceLineSignature(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableReferenceLineSignature).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const entries: string[] = [];
+    for (const key of Object.keys(record).sort()) {
+      const entry = record[key];
+      if (typeof entry === "function" || entry === undefined) continue;
+      entries.push(`${key}:${stableReferenceLineSignature(entry)}`);
+    }
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+
 /**
  * Fully-resolved badge **style/shape** + anchor — the resolved counterpart of
  * {@link BadgeStyleConfig} (`position` / `icon` / `showText` plus the style knobs).