react-native-livechart 4.24.0 → 4.25.0

package/src/components/LiveChartSeries.tsx

@@ -59,6 +59,7 @@ import { useChartOverlayContext } from "../hooks/useChartOverlayContext";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { useCrosshairSeries } from "../hooks/useCrosshairSeries";
 import { useCrosshairVisibleOpacity } from "../hooks/useCrosshairVisibleOpacity";
+import { useLoadingLook } from "../hooks/useLoadingLook";
 import { useMarkers } from "../hooks/useMarkers";
 import { useMultiSeriesDegen } from "../hooks/useMultiSeriesDegen";
 import { useMultiSeriesLinePaths } from "../hooks/useMultiSeriesLinePaths";
@@ -517,6 +518,9 @@ function useLiveChartSeriesController(props: LiveChartSeriesProps) {
   // Resolve the loading shell: null = not loading, else the styled config.
   const loadingCfg = resolveLoading(loading);
   const loadingActive = loadingCfg !== null;
+  // The shell fades after `loading` turns off: it keeps the last loading
+  // config's look instead of the defaults.
+  const loadingLook = useLoadingLook(loadingCfg);
   // Multi-series is always lines, so only the reveal transition applies (no
   // candle↔line crossfade); `transitions.mode` is accepted but inert here.
   const transitionsCfg = resolveTransitions(transitions);
@@ -583,6 +587,7 @@ function useLiveChartSeriesController(props: LiveChartSeriesProps) {
   const {
     pack: degenPack,
     packRevision: degenPackRevision,
+    particleTimestamp: degenParticleTimestamp,
     shakeTransform: degenShakeTransform,
   } = useMultiSeriesDegen(engine, effectivePadding, degenCfg, onDegenShake);
 
@@ -786,11 +791,11 @@ function useLiveChartSeriesController(props: LiveChartSeriesProps) {
     reveal,
     loadingActive,
     // loading shell styling (null → not loading)
-    loadingLineColor: loadingCfg?.color,
-    loadingStrokeWidth: loadingCfg?.strokeWidth,
-    loadingAmplitude: loadingCfg?.amplitude,
-    loadingSpeed: loadingCfg?.speed,
-    loadingAxisLabels: loadingCfg?.axisLabels ?? true,
+    loadingLineColor: loadingLook?.color,
+    loadingStrokeWidth: loadingLook?.strokeWidth,
+    loadingAmplitude: loadingLook?.amplitude,
+    loadingSpeed: loadingLook?.speed,
+    loadingAxisLabels: loadingLook?.axisLabels ?? true,
     effectiveSeries,
     layoutHeight,
     onLayout,
@@ -800,6 +805,7 @@ function useLiveChartSeriesController(props: LiveChartSeriesProps) {
     lineStyles,
     degenPack,
     degenPackRevision,
+    degenParticleTimestamp,
     degenShakeTransform,
     yAxisEntries,
     xAxisEntries,
@@ -863,6 +869,7 @@ function SeriesYAxisLayer({
         gridStyle={gridStyleCfg}
         labelRightMargin={yAxisCfg.labelRightMargin}
         gridEndGap={yAxisCfg.gridEndGap}
+        minGap={yAxisCfg.minGap}
       />
     </Group>
   );
@@ -893,6 +900,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     degenCfg,
     degenPack,
     degenPackRevision,
+    degenParticleTimestamp,
     markersActive,
     markersSV,
     markerClusterCfg,
@@ -1007,7 +1015,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
           <DegenParticlesOverlay
             pack={degenPack}
             packRevision={degenPackRevision}
-            engine={engine}
+            particleTimestamp={degenParticleTimestamp}
             palette={palette}
             particleSlotCount={degenCfg.particleSlotCount}
             particleBurstDurationSec={degenCfg.particleBurstDurationSec}

package/src/components/LoadingOverlay.tsx

@@ -8,8 +8,15 @@ import {
   vec,
   type SkFont,
 } from "@shopify/react-native-skia";
-import { useRef } from "react";
-import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import { useCallback, useRef } from "react";
+import {
+  useAnimatedReaction,
+  useDerivedValue,
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
 import {
   BADGE_METRICS_DEFAULTS,
   EMPTY_STATE_METRICS_DEFAULTS,
@@ -25,7 +32,7 @@ import {
   type ReanimatedPathBuilder,
 } from "../hooks/usePathBuilder";
 import { drawSpline } from "../math/spline";
-import { buildSquigglyPts } from "../math/squiggly";
+import { buildSquigglyPts, squiggleClockSeconds } from "../math/squiggly";
 import type {
   BadgeMetrics,
   EmptyStateMetrics,
@@ -64,6 +71,8 @@ export function LoadingOverlay({
   badgeMetrics = BADGE_METRICS_DEFAULTS,
   emptyMetrics = EMPTY_STATE_METRICS_DEFAULTS,
   showAxisLabels = true,
+  isStatic = false,
+  isFrameLoopActive,
   lineColor,
   lineStrokeWidth,
   waveAmplitude = 14,
@@ -100,6 +109,10 @@ export function LoadingOverlay({
   emptyMetrics?: EmptyStateMetrics;
   /** Draw the skeleton Y-axis label placeholders. Default `true`. */
   showAxisLabels?: boolean;
+  /** `static` chart: no per-frame loops, so the squiggle holds still. */
+  isStatic?: boolean;
+  /** The chart's frame-loop gate: the squiggle holds still while it is off. */
+  isFrameLoopActive?: SharedValue<boolean>;
 }) {
   // Same left-inset formula as GridOverlay (only used when badge=true)
   const leftInset =
@@ -124,7 +137,37 @@ export function LoadingOverlay({
   const squigglyBuilder = usePathBuilder();
   const squigglyPtsRef = useRef<number[]>([]);
 
-  // Squiggly path — animated each frame via timestamp
+  // Squiggle clock: wall time, not `engine.timestamp` — a `nowOverride` freezes
+  // the engine clock between data updates, which froze the loading line with it
+  // (the pulse clock in DotOverlay has the same fix). Ticks only while the shell
+  // shows (loading, empty, or mid-reveal) on a chart whose frame loops run: never
+  // on a `static` chart, while `isFrameLoopActive` is off, or at wave speed 0.
+  const squiggleClock = useSharedValue(squiggleClockSeconds());
+  /* istanbul ignore next -- frame-callback worklet runs on the UI thread, not in Jest */
+  const squiggleFrames = useFrameCallback(() => {
+    if (isFrameLoopActive?.get() === false) return;
+    squiggleClock.value = squiggleClockSeconds();
+  }, false);
+  const setSquiggleTicking = useCallback(
+    (on: boolean) => squiggleFrames.setActive(on),
+    [squiggleFrames],
+  );
+  useAnimatedReaction(
+    () =>
+      !isStatic &&
+      waveSpeed !== 0 &&
+      isFrameLoopActive?.get() !== false &&
+      (isLoading.get() || isEmpty.value || morphT.get() < 1),
+    (ticking, previous) => {
+      if (ticking === previous) return;
+      // Start from now, not from wherever the clock stopped when the shell last hid:
+      // the callback only starts after a UI → JS → UI round trip.
+      if (ticking) squiggleClock.set(squiggleClockSeconds());
+      scheduleOnRN(setSquiggleTicking, ticking);
+    },
+  );
+
+  // Squiggly path — animated each frame by the squiggle clock
   const squigglyPath = useDerivedValue(() => {
     const b = squigglyBuilder.value;
     if (!isLoading.get() && !isEmpty.value && morphT.get() >= 1) {
@@ -134,7 +177,7 @@ export function LoadingOverlay({
       engine.canvasWidth.get(),
       engine.canvasHeight.get(),
       padding,
-      engine.timestamp.get(),
+      squiggleClock.get(),
       waveAmplitude,
       waveSpeed,
       squigglyPtsRef.current,
@@ -243,12 +286,10 @@ export function LoadingOverlay({
     return [0, t1, t2, 1];
   });
 
-  const gapGradEnd = useDerivedValue(() =>
-    vec(
-      Math.max(1, emptyGapLayout.get().gapRight - emptyGapLayout.get().gapLeft),
-      0,
-    ),
-  );
+  // Gradient coordinates are canvas coordinates, not relative to the Rect.
+  // Starting at (0, 0) shifts the mask left and exposes a rectangular band.
+  const gapGradStart = useDerivedValue(() => vec(emptyGapLayout.get().gapLeft, 0));
+  const gapGradEnd = useDerivedValue(() => vec(emptyGapLayout.get().gapRight, 0));
 
   const emptyLabelText = useDerivedValue(() =>
     isEmpty.value ? emptyText : "",
@@ -276,7 +317,7 @@ export function LoadingOverlay({
       >
         <Rect x={gapLeft} y={gapTop} width={gapWidth} height={gapHeight}>
           <LinearGradient
-            start={vec(0, 0)}
+            start={gapGradStart}
             end={gapGradEnd}
             colors={gapMaskColors}
             positions={gapGradientPositions}

package/src/components/YAxisOverlay.tsx

@@ -4,7 +4,13 @@ import {
   Path,
   type SkFont,
 } from "@shopify/react-native-skia";
-import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import { useState } from "react";
+import {
+  useAnimatedReaction,
+  useDerivedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
 import { BADGE_METRICS_DEFAULTS, MAX_Y_LABELS } from "../constants";
 import type { ResolvedGridStyleConfig } from "../core/resolveConfig";
 import {
@@ -63,6 +69,7 @@ export function YAxisOverlay({
   side = "right",
   labelRightMargin,
   gridEndGap = 0,
+  minGap = 36,
 }: {
   entries: SharedValue<YAxisEntry[]>;
   engine: ChartEngineLayout;
@@ -104,6 +111,8 @@ export function YAxisOverlay({
   labelRightMargin?: number;
   /** Gap between the grid-line end and the shared label column. */
   gridEndGap?: number;
+  /** The grid's `minGap`: bounds how many labelled lines the plot can hold. */
+  minGap?: number;
 }) {
   const gridColor = gridStyle?.color ?? palette.gridLine;
   const gridWidth = gridStyle?.strokeWidth ?? 1;
@@ -190,6 +199,33 @@ export function YAxisOverlay({
     return result;
   });
 
+  // The label pool starts at MAX_Y_LABELS and grows to the number of labels the
+  // grid produces. A tall plot (or a small `minGap`) carries more labelled grid
+  // lines than a fixed pool held, and the extra lines were drawn without labels —
+  // which ones depended on key order. It grows no further than a settled grid
+  // can need: labelled lines stay at least half a `minGap` apart (the grid's
+  // hysteresis floor). Lines still fading out after a zoom can briefly outnumber
+  // that; for those frames some lines go unlabelled, as before. The pool never
+  // shrinks: a chart that fits keeps its cost, and zooming back and forth
+  // doesn't remount labels.
+  const [labelSlots, setLabelSlots] = useState(MAX_Y_LABELS);
+  const growLabelSlots = (slots: number) =>
+    setLabelSlots((current) => Math.max(current, slots));
+  useAnimatedReaction(
+    () => {
+      const plotHeight =
+        engine.canvasHeight.get() - padding.top - padding.bottom;
+      const settledMax = Math.floor(plotHeight / (minGap / 2)) + 1;
+      return Math.min(labelEntries.get().length, settledMax);
+    },
+    // Runs on every pass of the mapper: ask once per new size.
+    (slots, previous) => {
+      if (slots > labelSlots && slots !== previous) {
+        scheduleOnRN(growLabelSlots, slots);
+      }
+    },
+  );
+
   return (
     <Group>
       {variant !== "labels" && (
@@ -207,7 +243,7 @@ export function YAxisOverlay({
         </Group>
       )}
       {variant !== "grid" &&
-        Array.from({ length: MAX_Y_LABELS }, (_, i) => (
+        Array.from({ length: labelSlots }, (_, i) => (
           <AnimatedLabel
             key={i}
             entries={labelEntries}

package/src/constants.ts

@@ -10,9 +10,9 @@ import type {
 export const MS_PER_FRAME_60FPS = 16.67;
 
 /**
- * Size of the pre-allocated Y-axis label pool — the most price labels the axis
- * ever renders at once. Caps both the dynamic (nice-interval) grid and the
- * fixed-`count` mode (see {@link YAxisConfig.count}).
+ * Initial size of the Y-axis label pool. The pool grows when the dynamic
+ * (nice-interval) grid produces more labels (a tall plot or a small `minGap`);
+ * the fixed-`count` mode stays capped at this (see {@link YAxisConfig.count}).
  */
 export const MAX_Y_LABELS = 15;
 

package/src/core/historyRangeCache.ts

@@ -0,0 +1,109 @@
+import type { CandlePoint, LiveChartPoint } from "../types";
+
+/** A fresh wrapper per SharedValue notification, including same-array modify(). */
+export interface HistoryRevision<T> {
+  data: T[];
+}
+
+/** Per-engine, one-entry cache. Only committed history belongs here. */
+export interface HistoryRangeCache {
+  revision: object | undefined;
+  data: LiveChartPoint[] | CandlePoint[] | undefined;
+  candle: boolean;
+  start: number;
+  end: number;
+  min: number;
+  max: number;
+  minTime: number;
+  maxTime: number;
+}
+
+export function makeHistoryRangeCache(): HistoryRangeCache {
+  "worklet";
+  return {
+    revision: undefined,
+    data: undefined,
+    candle: false,
+    start: -1,
+    end: -1,
+    min: Infinity,
+    max: -Infinity,
+    minTime: 0,
+    maxTime: 0,
+  };
+}
+
+/** Inclusive time bounds; the returned end index is exclusive. */
+function timeBound(
+  data: { time: number }[],
+  time: number,
+  upper: boolean,
+): number {
+  "worklet";
+  let lo = 0;
+  let hi = data.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (upper ? data[mid].time <= time : data[mid].time < time) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Reuse only when a trusted revision AND both visible index bounds match.
+ * Without a revision, always scan: identity/length cannot detect in-place edits.
+ * The caller owns the cache; live candles, references and animation stay outside.
+ */
+export function historyRange(
+  data: LiveChartPoint[] | CandlePoint[],
+  candle: boolean,
+  from: number,
+  to: number,
+  revision: object | undefined,
+  cache: HistoryRangeCache,
+): HistoryRangeCache {
+  "worklet";
+  const start = timeBound(data, from, false);
+  const end = to === Infinity ? data.length : timeBound(data, to, true);
+  if (
+    revision !== undefined &&
+    cache.revision === revision &&
+    cache.data === data &&
+    cache.candle === candle &&
+    cache.start === start &&
+    cache.end === end
+  )
+    return cache;
+
+  cache.revision = revision;
+  cache.data = data;
+  cache.candle = candle;
+  cache.start = start;
+  cache.end = end;
+  let min = Infinity;
+  let max = -Infinity;
+  let minTime = 0;
+  let maxTime = 0;
+  for (let i = start; i < end; i++) {
+    const point = data[i];
+    const low = candle
+      ? (point as CandlePoint).low
+      : (point as LiveChartPoint).value;
+    const high = candle ? (point as CandlePoint).high : low;
+    // Strict comparisons preserve the first occurrence when extrema tie.
+    if (low < min) {
+      min = low;
+      minTime = point.time;
+    }
+    if (high > max) {
+      max = high;
+      maxTime = point.time;
+    }
+  }
+  cache.min = min;
+  cache.max = max;
+  cache.minTime = minTime;
+  cache.maxTime = maxTime;
+  return cache;
+}

package/src/core/liveChartEngineTick.ts

@@ -1,5 +1,11 @@
 import type { CandleGap, CandlePoint, LiveChartPoint } from "../types";
 
+import {
+  historyRange,
+  makeHistoryRangeCache,
+  type HistoryRangeCache,
+} from "./historyRangeCache";
+
 import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
 import { thresholdRangeMinMax } from "../math/threshold";
@@ -79,6 +85,8 @@ export interface EngineTickInput {
   yRangeScale?: number;
   targetValue: number;
   points: LiveChartPoint[];
+  /** Internal notification revision for the selected history; omit to disable reuse. */
+  historyRevision?: object;
   /** Seconds since Unix epoch; defaults to `Date.now() / 1000` */
   nowSeconds?: number;
   /** Override the engine's "now" (unix seconds) — e.g. fill historical data edge-to-edge. */
@@ -187,6 +195,7 @@ export function advanceTimestampByPixel(
 export function tickLiveChartEngineFrame(
   state: EngineTickMutable,
   input: EngineTickInput,
+  historyCache?: HistoryRangeCache,
 ): void {
   "worklet";
   const baseNow = input.nowOverride ?? input.nowSeconds ?? Date.now() / 1000;
@@ -301,39 +310,22 @@ export function tickLiveChartEngineFrame(
 
   const winStart = state.timestamp - state.displayWindow;
 
-  let tMin = Infinity;
-  let tMax = -Infinity;
-  // Time of the running min / max — captured alongside the value so an extrema
-  // label can be pinned at the point's x. Holds the data extrema only (folded
-  // below with the live value / references for the Y range, but snapshotted
-  // before that into `extrema*` so the label tracks the real high/low).
-  let minTime = 0;
-  let maxTime = 0;
+  const candleMode = input.mode === "candle";
+  const history = historyRange(
+    candleMode ? (input.candles ?? []) : input.points,
+    candleMode,
+    winStart,
+    // Line feeds may lead the local clock. Preserve their inclusive live tail.
+    candleMode || scrolledBack ? state.timestamp : Infinity,
+    input.historyRevision,
+    historyCache ?? makeHistoryRangeCache(),
+  );
+  let tMin = history.min;
+  let tMax = history.max;
+  let minTime = history.minTime;
+  let maxTime = history.maxTime;
 
-  if (input.mode === "candle") {
-    const candles = input.candles;
-    if (candles && candles.length > 0) {
-      let lo = 0;
-      let hi = candles.length;
-      while (lo < hi) {
-        const mid = (lo + hi) >> 1;
-        if (candles[mid].time < winStart) lo = mid + 1;
-        else hi = mid;
-      }
-      for (let i = lo; i < candles.length; i++) {
-        if (candles[i].time > state.timestamp) break;
-        /* istanbul ignore next -- trivial min/max */
-        if (candles[i].low < tMin) {
-          tMin = candles[i].low;
-          minTime = candles[i].time;
-        }
-        /* istanbul ignore next -- trivial min/max */
-        if (candles[i].high > tMax) {
-          tMax = candles[i].high;
-          maxTime = candles[i].time;
-        }
-      }
-    }
+  if (candleMode) {
     const lc = input.liveCandle;
     // Fold the in-progress candle in only while its bucket is visible — when
     // scrolled back past it, the live candle must not stretch the Y range.
@@ -349,31 +341,6 @@ export function tickLiveChartEngineFrame(
         maxTime = lc.time;
       }
     }
-  } else {
-    const points = input.points;
-    let lo = 0;
-    let hi = points.length;
-    while (lo < hi) {
-      const mid = (lo + hi) >> 1;
-      if (points[mid].time < winStart) lo = mid + 1;
-      else hi = mid;
-    }
-    for (let i = lo; i < points.length; i++) {
-      // While scrolled back, stop at the frozen right edge (mirrors the candle
-      // scan) so newer points don't inflate the visible Y range. Following
-      // live, keep the tail inclusive — feed timestamps can run slightly ahead
-      // of the local clock and must not flicker out of the range.
-      if (scrolledBack && points[i].time > state.timestamp) break;
-      const v = points[i].value;
-      if (v < tMin) {
-        tMin = v;
-        minTime = points[i].time;
-      }
-      if (v > tMax) {
-        tMax = v;
-        maxTime = points[i].time;
-      }
-    }
   }
 
   // Snapshot the raw data extrema (value + time) before the live value /

package/src/core/resolveConfig.ts

@@ -545,7 +545,7 @@ const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
  * Resolves `yAxis` prop to a fully-typed config or null (disabled).
  * `true` → defaults, object → merged with defaults, falsy → null.
  * `count` is normalized to a non-negative integer (the grid math clamps the
- * upper bound to the label pool size).
+ * upper bound to `MAX_Y_LABELS`).
  */
 export function resolveYAxis(
   prop: boolean | YAxisConfig | undefined,

package/src/core/useHistoryRevision.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState } from "react";
+import { useSharedValue, type SharedValue } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import type { HistoryRevision } from "./historyRangeCache";
+
+// Reanimated's mapper IDs are positive. Separate IDs also let multiple charts
+// subscribe to the same feed without replacing each other's listeners.
+let nextHistoryListenerId = -1;
+
+/** Invalidate synchronously: a frame can run before derived mappers flush. */
+export function useHistoryRevision<T>(
+  data: SharedValue<T[]> | undefined,
+  source: SharedValue<T[]> | undefined = data,
+): SharedValue<HistoryRevision<T> | undefined> {
+  const revision = useSharedValue<HistoryRevision<T> | undefined>(undefined);
+  const [listenerId] = useState(() => nextHistoryListenerId--);
+  useEffect(() => {
+    scheduleOnUI(() => {
+      "worklet";
+      const refresh = () => {
+        "worklet";
+        revision.set({ data: data?.get() ?? [] });
+      };
+      data?.addListener(listenerId, refresh);
+      if (source !== data) source?.addListener(listenerId, refresh);
+      refresh();
+    });
+    return () =>
+      scheduleOnUI(() => {
+        "worklet";
+        data?.removeListener(listenerId);
+        if (source !== data) source?.removeListener(listenerId);
+      });
+  }, [data, source, revision, listenerId]);
+  return revision;
+}