react-native-livechart 4.4.0 → 4.5.0

package/src/core/resolveConfig.ts

@@ -14,6 +14,7 @@ import type {
   LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
+  LoadingConfig,
   MarkerClusterConfig,
   DotConfig,
   DotRingConfig,
@@ -29,6 +30,7 @@ import type {
   ThresholdConfig,
   ThresholdLineConfig,
   TradeEvent,
+  TransitionConfig,
   ValueLineConfig,
   VolumeConfig,
   XAxisConfig,
@@ -45,6 +47,8 @@ import {
   EMPTY_STATE_METRICS_DEFAULTS,
   FADE_EDGE_WIDTH,
   GRID_METRICS_DEFAULTS,
+  LOADING_WAVE_AMPLITUDE,
+  LOADING_WAVE_SPEED,
   MOTION_METRICS_DEFAULTS,
   RETURN_TO_LIVE_MS,
 } from "../constants";
@@ -165,6 +169,8 @@ export interface ResolvedScrubConfig {
   tooltipShowTime: boolean;
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay: number;
+  /** Fade markers + reference lines out while scrubbing. */
+  hideOverlaysOnScrub: boolean;
 }
 
 export interface ResolvedScrubActionConfig {
@@ -477,6 +483,32 @@ export function resolveReturnToLiveMs(
   return d > 0 ? d : 0;
 }
 
+/**
+ * Resolved transition durations. `undefined` for a field means "use the
+ * component's built-in default" (so we don't duplicate the default constants
+ * here); a number is an explicit duration in ms (clamped to ≥ 0).
+ */
+export interface ResolvedTransitionConfig {
+  reveal: number | undefined;
+  mode: number | undefined;
+}
+
+const clampMs = (v: number | undefined): number | undefined =>
+  v == null ? undefined : v > 0 ? v : 0;
+
+/**
+ * Resolves the `transitions` prop. `false` → all transitions instant (`0`);
+ * `true` / omitted → defaults (both `undefined` = use the built-in durations);
+ * an object → per-transition overrides (an omitted field keeps its default).
+ */
+export function resolveTransitions(
+  prop: boolean | TransitionConfig | undefined,
+): ResolvedTransitionConfig {
+  if (prop === false) return { reveal: 0, mode: 0 };
+  if (prop == null || prop === true) return { reveal: undefined, mode: undefined };
+  return { reveal: clampMs(prop.reveal), mode: clampMs(prop.mode) };
+}
+
 const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
   format: undefined,
   color: undefined,
@@ -571,6 +603,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   tooltipShowValue: true,
   tooltipShowTime: true,
   panGestureDelay: 0,
+  hideOverlaysOnScrub: false,
 };
 
 /**
@@ -590,6 +623,36 @@ export function resolveScrub(
   return resolved;
 }
 
+export interface ResolvedLoadingConfig {
+  /** undefined → palette.gridLine */
+  color: string | undefined;
+  /** undefined → the chart's line strokeWidth */
+  strokeWidth: number | undefined;
+  /** Base breathing-wave amplitude (px). */
+  amplitude: number;
+  /** Breathing-wave speed multiplier. */
+  speed: number;
+}
+
+const LOADING_DEFAULTS: ResolvedLoadingConfig = {
+  color: undefined,
+  strokeWidth: undefined,
+  amplitude: LOADING_WAVE_AMPLITUDE,
+  speed: LOADING_WAVE_SPEED,
+};
+
+/**
+ * Resolves the `loading` prop to a fully-typed config or null (not loading).
+ * `true` → defaults (loading on, built-in look), object → merged with defaults
+ * (loading on, restyled), `false` / omitted → null. So a non-null result is the
+ * "is loading" flag and carries the resolved styling.
+ */
+export function resolveLoading(
+  prop: boolean | LoadingConfig | undefined,
+): ResolvedLoadingConfig | null {
+  return resolveToggle(prop, LOADING_DEFAULTS, false);
+}
+
 const SCRUB_ACTION_DEFAULTS: ResolvedScrubActionConfig = {
   icon: "+",
   background: undefined,

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,55 @@ 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 when data first appears (and the
+   * fade-out when it goes away or `loading` toggles). This is what plays on a
+   * timeframe change and when a `line` chart's data appears (e.g. switching from
+   * candle to line). Default `600`. `0` = instant.
+   */
+  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,11 +1668,27 @@ 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).
-   */
-  loading?: boolean;
+   *
+   * `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 | 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