react-native-livechart 4.4.0 → 4.6.0

package/src/core/useLiveChartEngine.ts

@@ -5,7 +5,7 @@
  *
  * @see https://github.com/benjitaylor/liveline
  */
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   cancelAnimation,
   Easing,
@@ -62,6 +62,13 @@ export interface EngineConfig {
    * {@link LiveChartProps.static}.
    */
   static?: boolean;
+  /**
+   * Opaque key that snaps the framing to its target in one frame whenever it
+   * changes (the next tick bypasses `smoothing` for the window, Y-range, and
+   * value, then normal easing resumes). Lets a timeframe / dataset switch land
+   * instantly while live ticks stay smooth. See {@link LiveChartProps.snapKey}.
+   */
+  snapKey?: string | number;
   mode?: "line" | "candle";
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -193,6 +200,12 @@ export interface EngineFrameRefs {
   liveEdgeSV?: SharedValue<number>;
   /** Receives the smoothed right-edge value each frame. Optional for callers/tests. */
   edgeValueSV?: SharedValue<number>;
+  /**
+   * One-shot "snap the framing this frame" flag (set by the `snapKey` effect).
+   * Consumed and cleared by {@link applyLiveChartEngineFrame} after the tick.
+   * Optional for callers/tests.
+   */
+  snapSV?: SharedValue<boolean>;
   modeSV: SharedValue<"line" | "candle">;
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -212,6 +225,9 @@ export function applyLiveChartEngineFrame(
 ): void {
   "worklet";
   const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
+  // One-shot settle: a `snapKey` change set this flag; consume it for this tick
+  // and clear it below so only this frame snaps (live ticks stay smoothed).
+  const snap = sv.snapSV?.value ?? false;
   const state = {
     displayValue: sv.displayValue.value,
     displayMin: sv.displayMin.value,
@@ -243,6 +259,7 @@ export function applyLiveChartEngineFrame(
     points: sv.data.value,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    snap,
     viewEnd: sv.viewEndSV?.value,
     returnT: sv.returnTSV?.value,
     returnFrom: sv.returnFromSV?.value,
@@ -262,6 +279,13 @@ export function applyLiveChartEngineFrame(
   sv.extremaMaxValue.value = state.extremaMaxValue;
   sv.extremaMinTime.value = state.extremaMinTime;
   sv.extremaMaxTime.value = state.extremaMaxTime;
+  // Clear the one-shot snap so the next frame eases normally again — but only
+  // once a real (measured) frame consumed it. The tick early-returns on a
+  // zero-size canvas (before applying the snap), so keep the flag pending until
+  // the canvas has laid out, or a snap arriving pre-layout would be dropped.
+  if (snap && sv.snapSV && sv.canvasWidth.value !== 0 && sv.canvasHeight.value !== 0) {
+    sv.snapSV.value = false;
+  }
 }
 
 export function useLiveChartEngine(
@@ -352,6 +376,20 @@ export function useLiveChartEngine(
   // no useDerivedValue bridging, no closure serialization per tick.
   const { data, value, candles, liveCandle } = config;
 
+  // One-shot "snap the framing" flag. The effect below flips it to `true` when
+  // `snapKey` changes; the next frame consumes it (bypassing `smoothing` for the
+  // window / range / value) and clears it, so a timeframe / dataset switch lands
+  // in one frame while live ticks stay smoothed. See `snapKey`.
+  const snapSV = useSharedValue(false);
+  // Compare against the previous key (not a "first render" flag) so React 18
+  // StrictMode's double-invoked mount effect can't fire a spurious snap.
+  const lastSnapKey = useRef(config.snapKey);
+  useEffect(() => {
+    if (config.snapKey === lastSnapKey.current) return;
+    lastSnapKey.current = config.snapKey;
+    snapSV.set(true);
+  }, [config.snapKey, snapSV]);
+
   // Static charts run zero per-frame loops. `isStaticSV` gates both the
   // frame-callback autostart and the one-shot settle reaction below.
   const isStaticSV = useDerivedValue(() => config.static ?? false);
@@ -385,6 +423,7 @@ export function useLiveChartEngine(
     viewWindowSV: viewWindow,
     liveEdgeSV: liveEdge,
     edgeValueSV: edgeValue,
+    snapSV,
     modeSV,
     candles,
     liveCandle,

package/src/core/useLiveChartSeriesEngine.ts

@@ -1,4 +1,4 @@
-import { useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   cancelAnimation,
   Easing,
@@ -41,6 +41,13 @@ export interface MultiSeriesEngineConfig {
    * {@link RETURN_TO_LIVE_MS}. Resolved from `timeScroll.returnToLive`. See #164.
    */
   returnToLiveMs?: number;
+  /**
+   * Opaque key that snaps the framing to its target in one frame whenever it
+   * changes (the next tick bypasses `smoothing` for the window, Y-range, and
+   * series tips, then normal easing resumes). Lets a timeframe / dataset switch
+   * land instantly while live ticks stay smooth. See {@link LiveChartSeriesProps.snapKey}.
+   */
+  snapKey?: string | number;
 }
 
 export interface MultiEngineFrameRefs {
@@ -74,6 +81,12 @@ export interface MultiEngineFrameRefs {
   viewWindowSV?: SharedValue<number | null>;
   /** Receives the computed live edge each frame. Optional for callers/tests. */
   liveEdgeSV?: SharedValue<number>;
+  /**
+   * One-shot "snap the framing this frame" flag (set by the `snapKey` effect).
+   * Consumed and cleared by {@link applyLiveChartSeriesEngineFrame} after the
+   * tick. Optional for callers/tests.
+   */
+  snapSV?: SharedValue<boolean>;
   extremaMinValue: SharedValue<number>;
   extremaMaxValue: SharedValue<number>;
   extremaMinTime: SharedValue<number>;
@@ -110,6 +123,9 @@ export function applyLiveChartSeriesEngineFrame(
 ): void {
   "worklet";
   const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
+  // One-shot settle: a `snapKey` change set this flag; consume it for this tick
+  // and clear it below so only this frame snaps (live ticks stay smoothed).
+  const snap = sv.snapSV?.value ?? false;
   const seriesSnap = sv.series.value;
   const curDv = sv.displaySeriesValues.value;
   const curOp = sv.seriesOpacities.value;
@@ -157,6 +173,7 @@ export function applyLiveChartSeriesEngineFrame(
     series: seriesSnap,
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
+    snap,
     viewEnd: sv.viewEndSV?.value,
     returnT: sv.returnTSV?.value,
     returnFrom: sv.returnFromSV?.value,
@@ -173,6 +190,12 @@ export function applyLiveChartSeriesEngineFrame(
   sv.extremaMaxValue.value = state.extremaMaxValue;
   sv.extremaMinTime.value = state.extremaMinTime;
   sv.extremaMaxTime.value = state.extremaMaxTime;
+  // Clear the one-shot snap so the next frame eases normally again — but only
+  // once a real (measured) frame consumed it (the tick early-returns on a
+  // zero-size canvas before applying the snap). See applyLiveChartEngineFrame.
+  if (snap && sv.snapSV && sv.canvasWidth.value !== 0 && sv.canvasHeight.value !== 0) {
+    sv.snapSV.value = false;
+  }
 }
 
 /**
@@ -234,6 +257,16 @@ export function useLiveChartSeriesEngine(
   const value = useSharedValue(0);
   const displayValue = useSharedValue(0);
 
+  // One-shot "snap the framing" flag — flipped by the effect when `snapKey`
+  // changes, consumed + cleared by the next frame (mirrors useLiveChartEngine).
+  const snapSV = useSharedValue(false);
+  const lastSnapKey = useRef(config.snapKey);
+  useEffect(() => {
+    if (config.snapKey === lastSnapKey.current) return;
+    lastSnapKey.current = config.snapKey;
+    snapSV.set(true);
+  }, [config.snapKey, snapSV]);
+
   const { series } = config;
 
   // Reused per-frame output buffers (ping-ponged) — see applyLiveChartSeriesEngineFrame.
@@ -273,6 +306,7 @@ export function useLiveChartSeriesEngine(
         returnFromSV: returnFrom,
         viewWindowSV: viewWindow,
         liveEdgeSV: liveEdge,
+        snapSV,
         extremaMinValue,
         extremaMaxValue,
         extremaMinTime,

package/src/hooks/useChartPaths.ts

@@ -35,6 +35,10 @@ export function useChartPaths(
    */
   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. */
+  squiggleSpeed = 1,
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
@@ -86,7 +90,13 @@ export function useChartPaths(
     // Compute squiggly Y values at the same X positions as the real line
     const centerY =
       (engine.canvasHeight.get() - padding.bottom + padding.top) / 2;
-    const squigglyPts = squigglifyPts(realPts, engine.timestamp.get(), centerY);
+    const squigglyPts = squigglifyPts(
+      realPts,
+      engine.timestamp.get(),
+      centerY,
+      squiggleAmplitude,
+      squiggleSpeed,
+    );
 
     // Blend center-out: centre of chart reveals first, edges last
     return blendPtsY(

package/src/hooks/useChartReveal.ts

@@ -60,6 +60,8 @@ export function useChartReveal(
   hasData: SharedValue<boolean>,
   /** Static charts skip the entry ramp: morphT snaps to its target, no `withTiming`. */
   isStatic = false,
+  /** Reveal/collapse duration (ms). Default {@link CHART_REVEAL_DURATION_MS}; `0` snaps. */
+  revealDuration: number = CHART_REVEAL_DURATION_MS,
 ): ChartRevealState {
   // Best-guess initial so the common case — a live chart that already has data
   // and isn't loading — paints fully revealed with no flash. The reaction below
@@ -85,15 +87,18 @@ export function useChartReveal(
         return;
       }
       if (prev !== chartVisible) {
+        // 0ms → withTiming resolves on the next frame (effectively a snap), so an
+        // explicit `transitions={{ reveal: 0 }}` / `transitions={false}` removes
+        // the grow-in without a special-case branch.
         morphT.set(
           withTiming(chartVisible ? 1 : 0, {
-            duration: CHART_REVEAL_DURATION_MS,
+            duration: revealDuration,
             easing: Easing.out(Easing.cubic),
           }),
         );
       }
     },
-    [hasData, isStatic],
+    [hasData, isStatic, revealDuration],
   );
 
   const isEmpty = useDerivedValue(() => !isLoading.get() && !hasData.get());

package/src/hooks/useModeBlend.ts

@@ -7,7 +7,7 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 
-const MODE_BLEND_DURATION_MS = 300;
+export const MODE_BLEND_DURATION_MS = 300;
 
 export interface ModeBlendState {
   /** 0 = fully line, 1 = fully candle */
@@ -28,17 +28,19 @@ export interface ModeBlendState {
 export function useModeBlend(
   isCandle: boolean,
   lineOpacity: SharedValue<number>,
+  /** Crossfade duration (ms). Default {@link MODE_BLEND_DURATION_MS}; `0` snaps. */
+  duration: number = MODE_BLEND_DURATION_MS,
 ): ModeBlendState {
   const modeBlend = useSharedValue(isCandle ? 1 : 0);
 
   useEffect(() => {
     modeBlend.set(
       withTiming(isCandle ? 1 : 0, {
-        duration: MODE_BLEND_DURATION_MS,
+        duration,
         easing: Easing.inOut(Easing.ease),
       }),
     );
-  }, [isCandle, modeBlend]);
+  }, [isCandle, modeBlend, duration]);
 
   const lineGroupOpacity = useDerivedValue(
     () => lineOpacity.get() * (1 - modeBlend.get()),

package/src/index.ts

@@ -64,6 +64,7 @@ export type {
   LiveChartPoint,
   LiveChartProps,
   LiveChartSeriesProps,
+  LoadingConfig,
   Marker,
   MarkerClusterConfig,
   MarkerGroupBadge,
@@ -97,6 +98,7 @@ export type {
   ThresholdLineConfig,
   TooltipRenderProps,
   TradeEvent,
+  TransitionConfig,
   ValueLineConfig,
   VisibleRange,
   VolumeConfig,

package/src/math/squiggly.ts

@@ -4,16 +4,26 @@ import type { ChartPadding } from "../draw/line";
  * Composite sine squiggly — two overlapping frequencies with a breathing
  * amplitude envelope. Matches the original web LiveChart loading animation.
  *
- * amplitude = 14 * (0.4 + 0.6 * sin(0.8 * t))   // 5.6 → 22.4px breathing range
- * y = centerY + amplitude * (sin(0.035*x + 1.2*t) + 0.45*sin(0.08*x + 2.1*t))
+ * amplitude = base * (0.4 + 0.6 * sin(0.8 * t·speed))   // 0.4×→1.0× base
+ * y = centerY + amplitude * (sin(0.035*x + 1.2*t·speed) + 0.45*sin(0.08*x + 2.1*t·speed))
+ *
+ * `base` (default `14`) scales the wave height; `speed` (default `1`) scales the
+ * time phase so the ripple/breathing runs faster or slower (`0` freezes it).
  */
-export function squigglyYAt(x: number, centerY: number, t: number): number {
+export function squigglyYAt(
+  x: number,
+  centerY: number,
+  t: number,
+  base = 14,
+  speed = 1,
+): number {
   "worklet";
-  const amplitude = 14 * (0.4 + 0.6 * Math.sin(0.8 * t));
+  const ts = t * speed;
+  const amplitude = base * (0.4 + 0.6 * Math.sin(0.8 * ts));
   return (
     centerY +
     amplitude *
-      (Math.sin(0.035 * x + 1.2 * t) + 0.45 * Math.sin(0.08 * x + 2.1 * t))
+      (Math.sin(0.035 * x + 1.2 * ts) + 0.45 * Math.sin(0.08 * x + 2.1 * ts))
   );
 }
 
@@ -27,6 +37,8 @@ export function buildSquigglyPts(
   canvasHeight: number,
   padding: ChartPadding,
   t: number,
+  base = 14,
+  speed = 1,
 ): number[] {
   "worklet";
   const leftEdge = padding.left;
@@ -41,7 +53,7 @@ export function buildSquigglyPts(
   for (let i = 0; i < count; i++) {
     const x = leftEdge + Math.min(i * step, chartW);
     pts[i * 2] = x;
-    pts[i * 2 + 1] = squigglyYAt(x, centerY, t);
+    pts[i * 2 + 1] = squigglyYAt(x, centerY, t, base, speed);
   }
   return pts;
 }
@@ -54,13 +66,15 @@ export function squigglifyPts(
   flatPts: number[],
   t: number,
   centerY: number,
+  base = 14,
+  speed = 1,
 ): number[] {
   "worklet";
   const n = flatPts.length;
   const out: number[] = new Array(n);
   for (let i = 0; i < n; i += 2) {
     out[i] = flatPts[i];
-    out[i + 1] = squigglyYAt(flatPts[i], centerY, t);
+    out[i + 1] = squigglyYAt(flatPts[i], centerY, t, base, speed);
   }
   return out;
 }

package/src/types.ts

@@ -720,6 +720,23 @@ export interface ScrubConfig {
    * Default `0`.
    */
   panGestureDelay?: number;
+  /**
+   * Fade the annotation overlays — buy/sell **markers** and **reference lines**
+   * (both the built-in Skia tags/lines and any custom `renderMarker` /
+   * `renderReferenceLine` RN views) — out while scrubbing, so they don't clutter
+   * the crosshair read-out. Reverses on release.
+   *
+   * The fade is driven by the **scrub-active** state (not the crosshair's
+   * edge-proximity fade, which would resurface the overlays as the crosshair
+   * nears the live dot) and eased on the UI thread over `SCRUB_OVERLAY_FADE_MS`.
+   * It animates only a **group opacity** — the marker atlas and reference-line
+   * geometry are left intact (still one batched draw each), so it's far cheaper
+   * than emptying / rebuilding overlay data per scrub. The leading dot is
+   * governed separately by `selectionDot`.
+   *
+   * `false` / omitted keeps the overlays visible while scrubbing (default).
+   */
+  hideOverlaysOnScrub?: boolean;
 }
 
 /**
@@ -1586,6 +1603,60 @@ export interface VisibleRange {
   following: boolean;
 }
 
+/**
+ * Per-transition animation durations (ms). Passed as the object form of
+ * {@link LiveChartCoreProps.transitions} to tune or disable the built-in
+ * animations. Omit a field to keep its default; `0` makes that transition
+ * instant (snap). Setting `transitions={false}` is shorthand for all `0`.
+ */
+export interface TransitionConfig {
+  /**
+   * Reveal / collapse transition — the grow-in **opacity** fade when data first
+   * appears (and the fade-out when it goes away or `loading` toggles). This is
+   * the fade that plays on a timeframe change and when a `line` chart's data
+   * appears (e.g. switching from candle to line). Default `600`. `0` = instant.
+   *
+   * Note this animates opacity only, not geometry: it does not control the time
+   * window / Y-range *easing* on a timeframe or dataset change (that's
+   * `smoothing`). To make that framing settle in one frame instead of sliding,
+   * use {@link LiveChartCoreProps.snapKey}.
+   */
+  reveal?: number;
+  /**
+   * Candle ↔ line crossfade duration when `mode` changes. Single-series
+   * `LiveChart` only (multi-series is always lines). Default `300`. `0` = instant.
+   */
+  mode?: number;
+}
+
+/**
+ * Styling for the breathing-line loading shell (the {@link LiveChartCoreProps.loading}
+ * state). Every field is optional — pass it as the object form of `loading` to
+ * restyle the shell; omit a field to keep its default.
+ */
+export interface LoadingConfig {
+  /**
+   * Color of the loading squiggle **and** the skeleton Y-axis placeholders.
+   * Default: the theme's `gridLine` color.
+   */
+  color?: string;
+  /**
+   * Stroke width (px) of the loading squiggle. Default: the chart's line
+   * `strokeWidth`.
+   */
+  strokeWidth?: number;
+  /**
+   * Base wave amplitude (px) of the breathing squiggle — it breathes between
+   * `0.4×` and `1.0×` this. Default `14`.
+   */
+  amplitude?: number;
+  /**
+   * Multiplier on the breathing-wave animation cadence: `>1` ripples faster,
+   * `<1` slower, `0` freezes it. Default `1`.
+   */
+  speed?: number;
+}
+
 /** Props shared between `LiveChart` and `LiveChartSeries`. */
 export interface LiveChartCoreProps {
   /** Color scheme. Default `"dark"`. */
@@ -1602,17 +1673,57 @@ export interface LiveChartCoreProps {
   timeWindow?: number;
   /** Freeze chart scrolling. Resume catches up to real time. Default `false`. */
   paused?: boolean;
+  /**
+   * Tune or disable the built-in transition animations. `true` / omitted keeps
+   * the defaults; `false` makes them all instant (no grow-in on data
+   * appear/timeframe change, no candle↔line crossfade); a {@link TransitionConfig}
+   * sets per-transition durations in ms (`reveal`, `mode`), where `0` snaps that
+   * one. Live value tracking is governed separately by `smoothing`; static-entry
+   * suppression by `static`.
+   */
+  transitions?: boolean | TransitionConfig;
   /**
    * Breathing-line loading shell. When this becomes `false`, the chart reveals
    * only if there is data (≥2 line points or ≥2 committed candles).
+   *
+   * `true` shows the shell with the defaults; pass a {@link LoadingConfig} to
+   * restyle it — `color` / `strokeWidth` for the squiggle + skeleton, `amplitude`
+   * / `speed` for the breathing wave. `false` / omitted is "not loading". Toggle
+   * between the config and `false` as data loads (e.g. `loading={isLoading && cfg}`).
+   * The loading→live reveal duration is governed separately by
+   * {@link TransitionConfig.reveal} (the `transitions` prop).
    */
-  loading?: boolean;
+  loading?: boolean | LoadingConfig;
   /**
    * Value-lerp speed — how quickly the drawn value, time window, and Y-range chase
    * their targets each frame (0 = frozen, 1 = instant). Equivalent to liveline's
    * `lerpSpeed`. Default `0.08`.
    */
   smoothing?: number;
+  /**
+   * Snap the framing to its target in a single frame whenever this key changes —
+   * without giving up smooth live ticks. On a timeframe / dataset switch, the
+   * window, Y-range, and value otherwise *ease* toward their new targets over
+   * `smoothing`, which reads as a slide. Bump `snapKey` at that moment and the
+   * next frame jumps straight to the new framing (no slide), then normal
+   * `smoothing` resumes for subsequent live ticks.
+   *
+   * Pass any value that changes once per discrete view change — the current
+   * timeframe id, or a counter you increment when you swap the `data` / `candles`
+   * array for a different range:
+   *
+   * ```tsx
+   * const [tf, setTf] = useState("1H");
+   * <LiveChart data={data} value={value} timeWindow={windowFor(tf)} snapKey={tf} />
+   * ```
+   *
+   * Unlike `transitions` (which only governs the reveal fade and the candle↔line
+   * crossfade — opacity, not geometry) and `static` (which turns off the live
+   * loop entirely), `snapKey` settles only the geometry and only for one frame.
+   * Leaves the timestamp / time-scroll position untouched. Omit to keep easing on
+   * every change (the default).
+   */
+  snapKey?: string | number;
   /** Tight Y-axis — small value moves fill the full chart height. Default `false`. */
   exaggerate?: boolean;
   /**