react-native-livechart 4.11.0 → 4.13.0

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";
@@ -17,22 +22,36 @@ import {
   computeScrubDotY,
   computeScrubTime,
   HIDDEN_TOOLTIP,
+  resolveScrubHitSlop,
   SCRUB_ACTIVATE_X_PX,
   SCRUB_FAIL_Y_PX,
+  startPlainScrub,
   type CrosshairState,
+  updatePlainScrub,
 } from "./crosshairShared";
 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 +61,18 @@ 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,
+  /**
+   * Reject scrub starts beyond either horizontal plot edge and clamp active
+   * drags to those bounds. Default `false`.
+   */
+  clampToPlot = false,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -52,6 +83,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 +137,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 +232,33 @@ export function useCrosshairSeries(
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     .onTouchesDown(
-      /* istanbul ignore next */ () => {
+      /* istanbul ignore next */ (e) => {
+        "worklet";
+        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";
-        delayedPanTouchDown(panGestureDelay, fingerDown);
+        delayedPanTouchMove(
+          panGestureDelay,
+          e,
+          manager,
+          panActivated,
+          downX,
+          downY,
+          holdBroken,
+        );
       },
     )
     .onTouchesUp(
@@ -199,12 +286,27 @@ 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);
-        scrubActive.set(true);
-        gestureStarted.set(true);
+        startPlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampToPlot,
+          scrubX,
+          scrubActive,
+          gestureStarted,
+        );
         if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
@@ -212,13 +314,20 @@ export function useCrosshairSeries(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;
-        scrubX.set(e.x);
+        updatePlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampToPlot,
+          scrubX,
+          scrubActive,
+        );
       },
     )
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        resetDelayedPanGuard(fingerDown, panActivated);
+        resetDelayedPanGuard(fingerDown, panActivated, holdBroken);
         scrubActive.set(false);
         if (gestureStarted.get()) {
           gestureStarted.set(false);
@@ -238,6 +347,12 @@ export function useCrosshairSeries(
     .activeOffsetX([-SCRUB_ACTIVATE_X_PX, SCRUB_ACTIVATE_X_PX])
     .failOffsetY([-SCRUB_FAIL_Y_PX, SCRUB_FAIL_Y_PX]);
 
+  // Gate by touch-down position so outside starts fail before activation and
+  // remain available to competing/parent gestures. Accepted pans keep tracking
+  // outside because `shouldCancelWhenOutside(false)` is set above.
+  const scrubHitSlop = resolveScrubHitSlop(padding, clampToPlot);
+  if (scrubHitSlop) gesture = gesture.hitSlop(scrubHitSlop);
+
   return {
     scrubX,
     scrubActive,

package/src/hooks/useCrosshairVisibleOpacity.ts

@@ -0,0 +1,57 @@
+import {
+  useDerivedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { computeCrosshairOpacity } from "./crosshairShared";
+
+/**
+ * Opacity for the visible crosshair UI. The trailing-content dim keeps using
+ * the edge-faded opacity directly, independent of this setting.
+ */
+export function useCrosshairVisibleOpacity(
+  scrubX: SharedValue<number>,
+  canvasWidth: SharedValue<number>,
+  paddingRight: number,
+  active: SharedValue<number> | SharedValue<boolean>,
+  fade: boolean,
+  fadeDistance = 4,
+) {
+  return useDerivedValue(
+    () =>
+      resolveCrosshairVisibleOpacity(
+        Boolean(active.get()),
+        scrubX.get(),
+        canvasWidth.get(),
+        paddingRight,
+        fade,
+        fadeDistance,
+      ),
+    [
+      scrubX,
+      canvasWidth,
+      paddingRight,
+      active,
+      fade,
+      fadeDistance,
+    ],
+  );
+}
+
+export function resolveCrosshairVisibleOpacity(
+  active: boolean,
+  scrubX: number,
+  canvasWidth: number,
+  paddingRight: number,
+  fade: boolean,
+  fadeDistance = 4,
+): number {
+  "worklet";
+  if (!fade) return active ? 1 : 0;
+  return computeCrosshairOpacity(
+    active,
+    scrubX,
+    canvasWidth,
+    paddingRight,
+    fadeDistance,
+  );
+}

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/hooks/useReferenceLine.ts

@@ -2,6 +2,10 @@ import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { SkFont } from "@shopify/react-native-skia";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import {
+  rightAnchoredYAxisColumnLayout,
+  type YAxisEntry,
+} from "../draw/grid";
 import type { ChartPadding } from "../draw/line";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import {
@@ -293,6 +297,14 @@ export function useReferenceLine(
    */
   dragValues?: SharedValue<number[]>,
   index = 0,
+  /** Y-axis labels used to match the right-anchored grid endpoint. */
+  yAxisEntries?: SharedValue<YAxisEntry[]>,
+  /** Enables clipping when set; matches {@link YAxisConfig.labelRightMargin}. */
+  labelRightMargin?: number,
+  /** Gap before the label column; matches {@link YAxisConfig.gridEndGap}. */
+  gridEndGap = 0,
+  /** Font used by the Y-axis labels; badge font overrides must not move the line. */
+  yAxisFont: SkFont = font,
 ): SharedValue<ReferenceLineLayout> {
   const form = line ? referenceLineForm(line) : "none";
   // Badge presentation depends only on the (stable) line props — resolve once.
@@ -314,7 +326,20 @@ export function useReferenceLine(
     // 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 yAxisColumn =
+      form === "line" &&
+      !fullWidth &&
+      yAxisEntries !== undefined &&
+      labelRightMargin !== undefined
+        ? rightAnchoredYAxisColumnLayout(
+            w,
+            yAxisEntries.value,
+            yAxisFont,
+            labelRightMargin,
+            gridEndGap,
+          )
+        : null;
+    const lineX2 = fullWidth ? w : (yAxisColumn?.gridEndX ?? x2);
 
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;

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).