react-native-livechart 4.22.2 → 4.24.0

package/src/hooks/useChartColors.ts

@@ -1,3 +1,4 @@
+import type { SharedValue } from "react-native-reanimated";
 import type { ResolvedGradientConfig } from "../core/resolveConfig";
 import type { ChartPadding } from "../draw/line";
 import { parseColorRgb } from "../theme";
@@ -12,9 +13,10 @@ export interface ChartColors {
   gradientTopColor: string;
   /** Bottom gradient stop — custom opacity or palette default. */
   gradientBottomColor: string;
-  /** Gradient color stops (top → bottom). Custom `colors` when provided, else the
-   *  2-stop `[gradientTopColor, gradientBottomColor]` fallback. */
-  gradientColors: string[];
+  /** Gradient color stops (top → bottom). Custom `colors` when provided (static
+   *  or animated), else the 2-stop `[gradientTopColor, gradientBottomColor]`
+   *  fallback. */
+  gradientColors: string[] | SharedValue<string[]>;
   /** Stop positions matching `gradientColors`, or undefined for even spacing. */
   gradientPositions: number[] | undefined;
 }
@@ -45,16 +47,28 @@ export function useChartColors(
       : palette.fillBottom;
 
   const customColors = gradientCfg?.colors;
-  const hasCustomColors = Array.isArray(customColors) && customColors.length >= 2;
-  const gradientColors = hasCustomColors
-    ? customColors
-    : [gradientTopColor, gradientBottomColor];
-  const gradientPositions =
-    hasCustomColors &&
-    gradientCfg?.positions !== undefined &&
-    gradientCfg.positions.length === customColors.length
-      ? gradientCfg.positions
-      : undefined;
+  const positions = gradientCfg?.positions;
+  const staticColors = Array.isArray(customColors) ? customColors : undefined;
+  const hasStaticColors = staticColors !== undefined && staticColors.length >= 2;
+  // An animated `colors` can't be measured on the JS thread without reading it
+  // during render, so it's trusted to hold ≥2 stops and to match `positions`.
+  const isAnimatedColors = customColors !== undefined && staticColors === undefined;
+
+  let gradientColors: string[] | SharedValue<string[]> = [
+    gradientTopColor,
+    gradientBottomColor,
+  ];
+  let gradientPositions: number[] | undefined;
+  if (isAnimatedColors) {
+    gradientColors = customColors;
+    gradientPositions = positions;
+  } else if (hasStaticColors) {
+    gradientColors = staticColors;
+    gradientPositions =
+      positions !== undefined && positions.length === staticColors.length
+        ? positions
+        : undefined;
+  }
 
   return {
     backgroundColor,

package/src/hooks/useDegen.ts

@@ -46,6 +46,7 @@ export function useDegen(
   momentumSV: SharedValue<Momentum>,
   cfg: ResolvedDegenConfig | null,
   onShake?: (payload: DegenShakePayload) => void,
+  isFrameLoopActive?: SharedValue<boolean>,
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
@@ -186,6 +187,7 @@ export function useDegen(
   useFrameCallback(
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
+      if (isFrameLoopActive?.get() === false) return;
       const now = engine.timestamp.get();
       const buf = pack.get();
       const slots = slotCountSV.get();

package/src/hooks/useMarkers.ts

@@ -55,6 +55,8 @@ export function useMarkers(
   lineLinear = false,
   /** Collision config; default `"anchored"` (no stacking). */
   cluster: ResolvedMarkerCluster = ANCHORED_CLUSTER,
+  /** Runtime gate shared with the chart engine. */
+  isFrameLoopActive?: SharedValue<boolean>,
 ): {
   projected: SharedValue<ProjectedMarker[]>;
   tapGesture: ReturnType<typeof Gesture.Tap>;
@@ -80,6 +82,7 @@ export function useMarkers(
   const markerFrameCallback = useFrameCallback(
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
+      if (isFrameLoopActive?.get() === false) return;
       const cache = cacheRef.current!;
       if (!active) {
         if (projected.get().length > 0) projected.set([]);

package/src/hooks/useReferenceDrag.ts

@@ -12,6 +12,7 @@ import type { ChartPadding } from "../draw/line";
 import {
   clampToBounds,
   nearestDraggableIndex,
+  referenceDragOwnsTouch,
   referenceValueOut,
   resolveDragIntent,
 } from "../math/referenceDrag";
@@ -257,17 +258,21 @@ export function useReferenceDrag(
     activated.set(false);
   };
 
-  // Geometric hit-test shared with the scrub gesture: is (x,y) within reach of a
-  // draggable line's handle? The scrub's `onStart` consults this to bail on a
-  // press over a line, so it never drops a crosshair there even though it activates
-  // independently of this manual-activation pan (the `Exclusive` priority alone
-  // doesn't hold scrub back while this gesture is merely pressed). x is unused —
-  // a Form-A line spans the full width, so only the y-reach matters.
+  // Hit-test shared with the scrub gesture: does this drag own the touch? The
+  // scrub's `onStart` consults it to bail, so it never drops a crosshair on a
+  // line even though it activates independently of this manual-activation pan
+  // (the `Exclusive` priority alone doesn't hold scrub back — not while this
+  // gesture is merely pressed, and not while it is dragging either). Once a line
+  // is grabbed the answer is yes regardless of position: the scrub asks with its
+  // touch-DOWN point, which a longer drag has carried the line away from, so the
+  // geometric test alone said "no line here" and a crosshair opened mid-drag.
+  // Otherwise it is the y-reach around the handles (x is unused — a Form-A line
+  // spans the full width).
   /* istanbul ignore next -- worklet, runs on the UI thread */
   const hitTest = (_x: number, y: number): boolean => {
     "worklet";
     if (!anyDraggable) return false;
-    return nearestDraggableIndex(handleYs.get(), y, GRAB_SLOP) >= 0;
+    return referenceDragOwnsTouch(dragIndex.get(), handleYs.get(), y, GRAB_SLOP);
   };
 
   const gesture = Gesture.Pan()

package/src/hooks/useReferenceLine.ts

@@ -1,4 +1,5 @@
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import { useRef } from "react";
 
 import type { SkFont } from "@shopify/react-native-skia";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
@@ -7,7 +8,10 @@ import {
   type YAxisEntry,
 } from "../draw/grid";
 import type { ChartPadding } from "../draw/line";
-import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import {
+  measureFontTextWidth,
+  type TextWidthCache,
+} from "../lib/measureFontTextWidth";
 import {
   classifyReferenceEdge,
   referenceLineForm,
@@ -120,6 +124,7 @@ function badgeGeometry(
   x1: number,
   x2: number,
   font: SkFont,
+  textWidthCache?: TextWidthCache,
 ): BadgeGeometry {
   "worklet";
   // Measure the icon's visual bounds (not just width): `SkiaText` draws from the
@@ -129,7 +134,9 @@ function badgeGeometry(
   // price-pill centering in computeActionBadgeLayout.
   const iconBounds = icon ? font.measureText(icon) : null;
   const iconW = iconBounds ? iconBounds.width : 0;
-  const textW = text ? measureFontTextWidth(font, text) : 0;
+  const textW = text
+    ? measureFontTextWidth(font, text, textWidthCache)
+    : 0;
 
   let contentW = 0;
   let count = 0;
@@ -310,6 +317,7 @@ export function useReferenceLine(
   const form = line ? referenceLineForm(line) : "none";
   // Badge presentation depends only on the (stable) line props — resolve once.
   const badge = line ? resolveReferenceBadge(line) : null;
+  const textWidthCacheRef = useRef<TextWidthCache>({});
 
   return useDerivedValue<ReferenceLineLayout>(() => {
     if (!line || form === "none") return INVISIBLE;
@@ -447,7 +455,16 @@ export function useReferenceLine(
         ? chartTop + OFF_AXIS_EDGE_INSET
         : chartBottom - OFF_AXIS_EDGE_INSET;
       const text = referenceBadgeText(line, badge, v, formatValue, true);
-      const g = badgeGeometry(badge.position, badge.icon, text, true, x1, x2, font);
+      const g = badgeGeometry(
+        badge.position,
+        badge.icon,
+        text,
+        true,
+        x1,
+        x2,
+        font,
+        textWidthCacheRef.current,
+      );
       return {
         ...INVISIBLE,
         visible: true,
@@ -476,7 +493,16 @@ export function useReferenceLine(
     // In-range pill badge (the `badge` config, not the legacy off-axis-only flag).
     if (badge && badge.inRange) {
       const text = referenceBadgeText(line, badge, v, formatValue, false);
-      const g = badgeGeometry(badge.position, badge.icon, text, false, x1, x2, font);
+      const g = badgeGeometry(
+        badge.position,
+        badge.icon,
+        text,
+        false,
+        x1,
+        x2,
+        font,
+        textWidthCacheRef.current,
+      );
       return {
         ...INVISIBLE,
         visible: true,

package/src/hooks/useTradeStream.ts

@@ -28,6 +28,8 @@ export function useTradeStream(
   active: boolean,
   /** Static charts run no loops: register without starting. Default `true`. */
   autostart = true,
+  /** Runtime gate shared with the chart engine. */
+  isFrameLoopActive?: SharedValue<boolean>,
 ): SharedValue<TradeMarker[]> {
   const markers = useSharedValue<TradeMarker[]>([]);
   const state = useSharedValue<TradeStreamState>(createTradeStreamState());
@@ -37,6 +39,7 @@ export function useTradeStream(
       frameInfo,
     ) => {
       "worklet";
+      if (isFrameLoopActive?.get() === false) return;
       if (!active) {
         if (markers.get().length > 0) markers.set([]);
         return;

package/src/index.ts

@@ -75,6 +75,7 @@ export type {
   LegendStyle,
   LineConfig,
   LiveChartCoreProps,
+  LiveChartFrameStats,
   LiveChartHandle,
   LiveChartMetrics,
   LiveChartMetricsOverride,

package/src/lib/measureFontTextWidth.ts

@@ -1,10 +1,34 @@
 import type { SkFont } from "@shopify/react-native-skia";
 
+/** Caller-owned last-value cache for repeated UI-thread text measurement. */
+export interface TextWidthCache {
+  /** Font used for the cached measurement. */
+  font?: SkFont;
+  /** Text used for the cached measurement. */
+  text?: string;
+  /** Cached width. */
+  width?: number;
+}
+
 /**
  * Horizontal layout width for `text` via Skia `measureText` (replaces deprecated `getTextWidth`).
  * Marked worklet for use inside Reanimated `useDerivedValue`.
  */
-export function measureFontTextWidth(font: SkFont, text: string): number {
+export function measureFontTextWidth(
+  font: SkFont,
+  text: string,
+  cache?: TextWidthCache,
+): number {
   "worklet";
-  return font.measureText(text).width;
+  if (cache?.font === font && cache.text === text && cache.width !== undefined) {
+    return cache.width;
+  }
+
+  const width = font.measureText(text).width;
+  if (cache) {
+    cache.font = font;
+    cache.text = text;
+    cache.width = width;
+  }
+  return width;
 }

package/src/math/referenceDrag.ts

@@ -43,6 +43,25 @@ export function nearestDraggableIndex(
   return best;
 }
 
+/**
+ * Whether the reference-drag gesture owns the current touch — the answer the
+ * scrub's activation guard needs. A **grabbed** line (`dragIndex >= 0`, pressed
+ * or already dragging) owns the touch outright, wherever the asking gesture says
+ * the finger is: the scrub pan can activate mid-drag and asks with its
+ * touch-DOWN point, which a longer drag has carried the line away from. With no
+ * line grabbed, it is the geometric reach test around the handles.
+ */
+export function referenceDragOwnsTouch(
+  dragIndex: number,
+  handleYs: number[],
+  y: number,
+  slop: number,
+): boolean {
+  "worklet";
+  if (dragIndex >= 0) return true;
+  return nearestDraggableIndex(handleYs, y, slop) >= 0;
+}
+
 /**
  * Resolve a grabbed line's drag intent from the touch travel (px) since the grab.
  * Once a line is grabbed it **owns** the touch: any drag past `threshold` px in

package/src/types.ts

@@ -16,6 +16,16 @@ export interface LiveChartPoint {
   value: number;
 }
 
+/** Development counters for continuous engine-frame state updates. */
+export interface LiveChartFrameStats {
+  /** Frame callbacks that ran while the chart was live. */
+  frames: number;
+  /** Frames that changed at least one tracked engine value. */
+  published: number;
+  /** Frames whose tracked engine values were unchanged. */
+  skipped: number;
+}
+
 /** Direction of recent price movement, used for dot/badge coloring and degen effects. */
 export type Momentum = "up" | "down" | "flat";
 
@@ -457,8 +467,18 @@ export interface LineConfig {
    * noise reduction.
    */
   simplify?: number;
-  /** Line color override. Defaults to palette-derived accent. */
-  color?: string;
+  /**
+   * Line color override. Defaults to palette-derived accent.
+   *
+   * Pass a `SharedValue<string>` to animate the stroke color on the UI thread
+   * (for example with `interpolateColor`) without re-rendering. The animated
+   * color reaches the stroke and the built-in scrub selection dot. The parts
+   * that derive from the line color at render time (a custom
+   * `selectionDot.component`'s `color`, the segment base color, the area-dot
+   * tint, and the threshold split stroke's rest color) use the palette line
+   * color instead.
+   */
+  color?: string | SharedValue<string>;
   /**
    * Two or more CSS color strings → horizontal gradient along the stroke
    * (left → right). Takes precedence over `color` when set.
@@ -628,10 +648,18 @@ export interface GradientConfig {
   topOpacity?: number;
   /** Opacity at the bottom of the gradient. Default `0`. */
   bottomOpacity?: number;
-  /** Explicit gradient color stops (top → bottom) for the area fill. Overrides
-   *  topOpacity/bottomOpacity when provided. Must have at least 2 entries. */
-  colors?: string[];
-  /** Optional stop positions (0..1, ascending) matching `colors` length. */
+  /**
+   * Explicit gradient color stops (top → bottom) for the area fill. Overrides
+   * topOpacity/bottomOpacity when provided. Must have at least 2 entries.
+   *
+   * Pass a `SharedValue<string[]>` to animate the stops on the UI thread
+   * without re-rendering. Keep at least 2 entries in it at all times.
+   */
+  colors?: string[] | SharedValue<string[]>;
+  /**
+   * Optional stop positions (0..1, ascending) matching `colors` length. With
+   * animated `colors`, the positions apply as given, so keep the lengths equal.
+   */
   positions?: number[];
 }
 
@@ -707,6 +735,9 @@ export interface VolumeConfig {
 
 /** Y-axis grid configuration. */
 export interface YAxisConfig {
+  /** Price-label side. For left placement, reserve the label gutter with insets.left.
+   * Right-side float/labelRightMargin options do not affect left labels. Default "right". */
+  side?: "left" | "right";
   /** Minimum pixel gap between grid lines. Default `36`. */
   minGap?: number;
   /**
@@ -2664,6 +2695,23 @@ export interface LiveChartProps extends LiveChartCoreProps {
    *  switching back to live restarts the suspended loops and catches up. Frame the data
    *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
   static?: boolean;
+  /**
+   * Runtime gate for continuous frame work. Set this SharedValue to `false`
+   * while a parent scroll gesture needs the UI thread; data keeps updating and
+   * the chart catches up when it becomes `true`. Unlike {@link static}, this
+   * keeps pan, zoom, scrub, and draggable reference-line gestures mounted.
+   *
+   * @experimental
+   */
+  isFrameLoopActive?: SharedValue<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
+   * one SharedValue write per active engine frame.
+   *
+   * @experimental
+   */
+  debugFrameStats?: SharedValue<LiveChartFrameStats>;
   /**
    * Render a custom overlay floated over the chart canvas, handed a price↔pixel /
    * time↔pixel {@link ChartOverlayContext} so it can track the auto-rescaling axis