react-native-livechart 4.24.0 → 4.25.0

package/src/hooks/useMarkers.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from "react";
 import { Gesture } from "react-native-gesture-handler";
 import {
+  useAnimatedReaction,
   useFrameCallback,
   useSharedValue,
   type SharedValue,
@@ -57,6 +58,8 @@ export function useMarkers(
   cluster: ResolvedMarkerCluster = ANCHORED_CLUSTER,
   /** Runtime gate shared with the chart engine. */
   isFrameLoopActive?: SharedValue<boolean>,
+  /** Experimental input-driven projection instead of continuous frames; defaults to false. */
+  autoSleep = false,
 ): {
   projected: SharedValue<ProjectedMarker[]>;
   tapGesture: ReturnType<typeof Gesture.Tap>;
@@ -79,7 +82,7 @@ export function useMarkers(
       onMarkerPress?.(event);
     };
 
-  const markerFrameCallback = useFrameCallback(
+  const project =
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
       if (isFrameLoopActive?.get() === false) return;
@@ -111,13 +114,24 @@ export function useMarkers(
         maxY: engine.canvasHeight.get(),
       });
       projected.set(buf);
+    };
+  const legacyActive = autostart && !autoSleep;
+  const markerFrameCallback = useFrameCallback(project, legacyActive);
+  useAnimatedReaction(
+    () => {
+      if (!autoSleep || !autostart) return null;
+      return [active, markers.get(), engine.canvasWidth.get(), engine.canvasHeight.get(),
+        engine.timestamp.get(), engine.displayWindow.get(), engine.displayMin.get(),
+        engine.displayMax.get(), seriesSV?.get(), lineData?.get(), isFrameLoopActive?.get()];
+    },
+    (inputs) => {
+      if (inputs !== null) project();
     },
-    autostart,
   );
   useEffect(() => {
     // Reanimated does not reactively apply later `autostart` values.
-    markerFrameCallback.setActive(autostart);
-  }, [autostart, markerFrameCallback]);
+    markerFrameCallback.setActive(legacyActive);
+  }, [legacyActive, markerFrameCallback]);
 
   const tapGesture = Gesture.Tap().onEnd(
     /* istanbul ignore next -- gesture worklet runs on UI thread, not in Jest */ (

package/src/hooks/useMultiSeriesDegen.ts

@@ -30,6 +30,7 @@ export function useMultiSeriesDegen(
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
+  particleTimestamp: SharedValue<number>;
   shakeTransform: DerivedValue<
     [{ translateX: number }, { translateY: number }]
   >;
@@ -37,6 +38,7 @@ export function useMultiSeriesDegen(
   const MAX_SLOTS = 80;
   const pack = useSharedValue(new Float64Array(MAX_SLOTS * DEGEN_STRIDE));
   const packRevision = useSharedValue(0);
+  const particleTimestamp = useSharedValue(0);
   // Per-series previous momentum (0 = flat, 1 = up, 2 = down), index-aligned to series.
   const prevMoms = useSharedValue<number[]>([]);
   const writeRot = useSharedValue(0);
@@ -131,9 +133,10 @@ export function useMultiSeriesDegen(
   ]);
 
   useFrameCallback(
-    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ (frame) => {
       "worklet";
-      const now = engine.timestamp.get();
+      // Effect timing is independent of the quantized/pinned viewport clock.
+      const now = frame.timestamp / 1000;
       const buf = pack.get();
       const slots = slotCountSV.get();
 
@@ -242,6 +245,7 @@ export function useMultiSeriesDegen(
       );
 
       if (activeCount > 0 || prevActiveCount.get() > 0) {
+        particleTimestamp.set(now);
         packRevision.set(packRevision.get() + 1);
       }
       prevActiveCount.set(activeCount);
@@ -256,5 +260,5 @@ export function useMultiSeriesDegen(
     ];
   });
 
-  return { pack, packRevision, shakeTransform };
+  return { pack, packRevision, particleTimestamp, shakeTransform };
 }

package/src/hooks/usePanScroll.ts

@@ -22,6 +22,8 @@ export type PanScrollGestureMode = "holdToScrub" | "axisDrag";
 
 /** Engine SharedValues the pan-scroll gesture reads/writes (subset of the engine state). */
 export interface PanScrollEngineRefs {
+  /** Wake a demand-driven engine before reading the gesture bounds. */
+  wake?: () => void;
   /** Absolute right-edge time to freeze at, or `null` to follow the live edge. */
   viewEnd: SharedValue<number | null>;
   /** Right-edge time the engine would use if following live (advances each frame). */
@@ -263,10 +265,13 @@ export function usePanScroll({
     },
   );
 
+  const wakeEngine = engine.wake;
+
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      wakeEngine?.();
       // 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

package/src/hooks/usePinchZoom.ts

@@ -10,6 +10,8 @@ import { FOLLOW_SNAP, panLowerBound, panUpperBound } from "./usePanScroll";
 
 /** Engine SharedValues the pinch-zoom gesture reads/writes. */
 export interface PinchZoomEngineRefs {
+  /** Wake a demand-driven engine before reading the gesture bounds. */
+  wake?: () => void;
   /** Visible-window width override in seconds, or `null` to follow `timeWindow`. */
   viewWindow: SharedValue<number | null>;
   /** Absolute right-edge time, or `null` to follow the live edge (shared with pan). */
@@ -170,10 +172,13 @@ export function usePinchZoom({
   const startWindow = useSharedValue(timeWindow);
   const startViewEnd = useSharedValue(0);
 
+  const wakeEngine = engine.wake;
+
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
     () => {
       "worklet";
+      wakeEngine?.();
       cancelAnimation(viewEnd);
       cancelAnimation(viewWindow);
       const edge = liveEdge.get();

package/src/hooks/useVolumeRange.ts

@@ -0,0 +1,40 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { CandlePoint } from "../types";
+import {
+  visibleMaxVolume,
+  volumeEndIndex,
+  volumeStartIndex,
+} from "../draw/volumeRange";
+
+/**
+ * Primitive index outputs suppress downstream scans while the window glides
+ * within the same buckets. The maximum also depends directly on candles, so
+ * every notified data revision (including same-length replacement or modify)
+ * invalidates it. Array length and object identity are never cache keys.
+ */
+export function useVolumeRange(
+  candles: SharedValue<CandlePoint[]> | undefined,
+  timestamp: SharedValue<number>,
+  window: SharedValue<number>,
+  width: SharedValue<number>,
+  active: boolean,
+) {
+  const start = useDerivedValue(() =>
+    !active || !candles
+      ? 0
+      : volumeStartIndex(
+          candles.get(),
+          timestamp.get() - window.get(),
+          width.get(),
+        ),
+  );
+  const end = useDerivedValue(() =>
+    !active || !candles ? 0 : volumeEndIndex(candles.get(), timestamp.get()),
+  );
+  const max = useDerivedValue(() =>
+    !active || !candles
+      ? 0
+      : visibleMaxVolume(candles.get(), start.get(), end.get()),
+  );
+  return { start, end, max };
+}

package/src/hooks/useXAxis.ts

@@ -167,11 +167,16 @@ export function useXAxis(
       const edgeAlpha =
         fromEdge >= fadeZone ? 1 : fromEdge <= 0 ? 0 : fromEdge / fadeZone;
 
-      const target = xAxisKeyIsTarget(key, targetKeys) ? edgeAlpha : 0;
+      const isTarget = xAxisKeyIsTarget(key, targetKeys);
+      const target = isTarget ? edgeAlpha : 0;
       let next = lerp(label.alpha, target, FADE, MS_PER_FRAME_60FPS);
       if (Math.abs(next - target) < 0.02) next = target;
 
-      if (next < 0.01 && target === 0) {
+      // Only a key that left the target set is deleted once it has faded out. A
+      // target key can sit at alpha 0 (the set spans one interval past each edge,
+      // outside the plot); deleting it would re-create it on the next run and
+      // write `labelAlphas`, this mapper's own input, every frame.
+      if (next < 0.01 && !isTarget) {
         delete alphas[key];
         cacheChanged = true;
       } else {
@@ -182,7 +187,12 @@ export function useXAxis(
       }
     }
 
-    if (cacheChanged) labelAlphas.set(alphas);
+    // Publish only a changed final cache so this derived value cannot keep
+    // waking itself after the engine sleeps. Off-screen target keys are retained
+    // above; this equality check also guards against other no-op cache updates.
+    if (cacheChanged && !sameXAxisLabels(previousAlphas, alphas)) {
+      labelAlphas.set(alphas);
+    }
 
     // Collect visible labels
     const raw: XAxisEntry[] = [];
@@ -226,3 +236,17 @@ export function useXAxis(
 
   return { xAxisEntries, font };
 }
+
+export function sameXAxisLabels(
+  previous: Record<number, { alpha: number; text: string }>,
+  next: Record<number, { alpha: number; text: string }>,
+): boolean {
+  "worklet";
+  const keys = Object.keys(next);
+  if (keys.length !== Object.keys(previous).length) return false;
+  for (let i = 0; i < keys.length; i++) {
+    const key = Number(keys[i]);
+    if (!previous[key] || previous[key].alpha !== next[key].alpha || previous[key].text !== next[key].text) return false;
+  }
+  return true;
+}

package/src/hooks/useYAxis.ts

@@ -28,7 +28,15 @@ export function useYAxis(
   const yAxisEntries = useDerivedValue(() => {
     const dt = MS_PER_FRAME_60FPS;
 
-    const alphas = labelAlphas.get();
+    // SharedValue payloads may be frozen after crossing the JS/UI boundary.
+    // Copy before computeGridEntries adds, updates, or removes label keys.
+    const previousAlphas = labelAlphas.get();
+    const alphas: Record<number, number> = {};
+    const previousKeys = Object.keys(previousAlphas);
+    for (let i = 0; i < previousKeys.length; i++) {
+      const key = Number(previousKeys[i]);
+      alphas[key] = previousAlphas[key];
+    }
     const result = computeGridEntries(
       engine.displayMin.get(),
       engine.displayMax.get(),
@@ -46,7 +54,15 @@ export function useYAxis(
     );
 
     prevInterval.set(result.interval);
-    labelAlphas.set(alphas);
+    // This derived value also reads the cache. Only publish actual changes so
+    // a settled axis doesn't keep scheduling itself with fresh object identities.
+    const nextKeys = Object.keys(alphas);
+    let cacheChanged = nextKeys.length !== previousKeys.length;
+    for (let i = 0; i < nextKeys.length && !cacheChanged; i++) {
+      const key = Number(nextKeys[i]);
+      if (alphas[key] !== previousAlphas[key]) cacheChanged = true;
+    }
+    if (cacheChanged) labelAlphas.set(alphas);
 
     return result.entries;
   });

package/src/math/spline.ts

@@ -60,6 +60,9 @@ export function drawSpline(
   startPoint = 0,
   /** Last point index to draw (exclusive). Defaults to the full array. */
   endPoint = pts.length >> 1,
+  /** Optional paired sinks receive identical verbs from the same curve math. */
+  second?: SplinePathSink,
+  third?: SplinePathSink,
 ) {
   "worklet";
   const start = Math.max(0, startPoint);
@@ -70,12 +73,16 @@ export function drawSpline(
     for (let i = 1; i < n; i++) {
       const point = (start + i) * 2;
       path.lineTo(pts[point], pts[point + 1]);
+      second?.lineTo(pts[point], pts[point + 1]);
+      third?.lineTo(pts[point], pts[point + 1]);
     }
     return;
   }
   if (n === 2) {
     const point = (start + 1) * 2;
     path.lineTo(pts[point], pts[point + 1]);
+    second?.lineTo(pts[point], pts[point + 1]);
+    third?.lineTo(pts[point], pts[point + 1]);
     return;
   }
 
@@ -123,14 +130,15 @@ export function drawSpline(
     const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     const hi = h[i];
-    path.cubicTo(
-      pts[i2] + hi / 3,
-      pts[i2 + 1] + (m[i] * hi) / 3,
-      pts[j2] - hi / 3,
-      pts[j2 + 1] - (m[i + 1] * hi) / 3,
-      pts[j2],
-      pts[j2 + 1],
-    );
+    const x1 = pts[i2] + hi / 3;
+    const y1 = pts[i2 + 1] + (m[i] * hi) / 3;
+    const x2 = pts[j2] - hi / 3;
+    const y2 = pts[j2 + 1] - (m[i + 1] * hi) / 3;
+    const x = pts[j2],
+      y = pts[j2 + 1];
+    path.cubicTo(x1, y1, x2, y2, x, y);
+    second?.cubicTo(x1, y1, x2, y2, x, y);
+    third?.cubicTo(x1, y1, x2, y2, x, y);
   }
 }
 

package/src/math/squiggly.ts

@@ -27,6 +27,18 @@ export function squigglyYAt(
   );
 }
 
+/**
+ * The squiggle's clock, in seconds: wall time. The loading shell
+ * (`LoadingOverlay`) and the reveal's morph (`useChartPaths`) both phase their
+ * wave on it rather than on `engine.timestamp`, which a `nowOverride` freezes
+ * between data updates (freezing the loading line with it). Sharing one clock
+ * keeps the wave continuous where the shell hands over to the morph.
+ */
+export function squiggleClockSeconds(): number {
+  "worklet";
+  return Date.now() / 1000;
+}
+
 /**
  * Build a flat [x0,y0,x1,y1,...] point array for a standalone squiggly line
  * spanning the full chart area (used in loading / empty state).

package/src/types.ts

@@ -757,8 +757,8 @@ export interface YAxisConfig {
    * numbers; they track the live range each frame.
    *
    * `minGap` still acts as a floor: if `count` labels won't fit at least
-   * `minGap` px apart, the count is reduced to what fits. Clamped to at most 15
-   * (the label pool size). Omit (or `0`) for the default dynamic grid.
+   * `minGap` px apart, the count is reduced to what fits. Clamped to at most 15.
+   * Omit (or `0`) for the default dynamic grid.
    */
   count?: number;
   /**
@@ -2704,6 +2704,15 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * @experimental
    */
   isFrameLoopActive?: SharedValue<boolean>;
+  /**
+   * Experimental single-series demand scheduling. Stop engine frames after a
+   * paused, parked, or fixed-time chart settles; shared input changes and
+   * gestures wake it on the UI thread. Default false. Live scrolling, pulse,
+   * loading/reveal, and enabled degen/trade effects keep the engine awake.
+   * Does not cache a bitmap or disable gestures. `static` takes precedence.
+   * @experimental
+   */
+  autoSleep?: boolean;
   /**
    * Optional development counter for engine frames that did or did not change
    * tracked engine values. It is not a count of Skia redraws. Supplying it adds