react-native-livechart 2.0.1 → 3.1.0

package/src/hooks/useDegen.ts

@@ -20,6 +20,8 @@ export function useDegen(
   momentumSV: SharedValue<Momentum>,
   cfg: ResolvedDegenConfig | null,
   onShake?: (payload: DegenShakePayload) => void,
+  /** Static charts run no loops: register the frame callback without starting it. */
+  isStatic = false,
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
@@ -248,6 +250,10 @@ export function useDegen(
       }
       prevActiveCount.set(activeCount);
     },
+    // Static charts register the callback but never start it, so no degen frame
+    // loop runs. Live charts keep the default (autostart) loop unchanged. The
+    // controller also forces `cfg` to null in static, so degen is doubly off.
+    !isStatic,
   );
 
   const shakeTransform = useDerivedValue(() => {

package/src/hooks/useMarkers.ts

@@ -30,6 +30,8 @@ export function useMarkers(
   onMarkerHover?: (event: MarkerHoverEvent | null) => void,
   seriesSV?: SharedValue<SeriesConfig[]>,
   lineData?: SharedValue<LiveChartPoint[]>,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ): { projected: SharedValue<ProjectedMarker[]>; tapGesture: ReturnType<typeof Gesture.Tap> } {
   const projected = useSharedValue<ProjectedMarker[]>([]);
   const cacheRef = useRef<{
@@ -73,6 +75,7 @@ export function useMarkers(
       });
       projected.set(buf);
     },
+    autostart,
   );
 
   const tapGesture = Gesture.Tap().onEnd(

package/src/hooks/useMultiSeriesLinePaths.ts

@@ -5,51 +5,46 @@ import { MAX_MULTI_SERIES } from "../constants";
 import type { MultiEngineState } from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
 import { drawSpline, makeSplineScratch } from "../math/spline";
+import { usePathBuilders } from "./usePathBuilder";
 
 /**
- * One derived shared value holding up to `MAX_MULTI_SERIES` Skia paths (unused slots are empty paths).
+ * One derived shared value holding up to `MAX_MULTI_SERIES` Skia paths (unused
+ * slots reuse one cached empty path).
  *
- * Each slot ping-pongs between two persistent `SkPath`s so `MultiSeriesStroke`'s
- * per-slot `useDerivedValue(() => paths.value[index])` sees a fresh reference each
- * tick (otherwise Reanimated's setter short-circuits and Skia never repaints).
- * No new JSI-backed `SkPath` is allocated per frame. See {@link useChartPaths}
- * for the memory rationale.
+ * Each visible series' path is built into a per-slot `Skia.PathBuilder` (reused
+ * across frames via a SharedValue) and finalized with `detach()` — a fresh
+ * immutable `SkPath` per frame, so `MultiSeriesStroke`'s per-slot
+ * `useDerivedValue(() => paths.value[index])` repaints without the two-SkPath
+ * ping-pong. Only visible series allocate a path.
  */
 export function useMultiSeriesLinePaths(
   engine: MultiEngineState,
   padding: ChartPadding,
-): SharedValue<ReturnType<typeof Skia.Path.Make>[]> {
+): SharedValue<SkPath[]> {
+  const builders = usePathBuilders(MAX_MULTI_SERIES);
+
   const poolRef = useRef<{
-    a: SkPath[];
-    b: SkPath[];
-    tick: boolean;
+    empty: SkPath;
     ptsBuf: number[];
     scratch: ReturnType<typeof makeSplineScratch>;
   } | null>(null);
   if (poolRef.current === null) {
-    const a: SkPath[] = [];
-    const b: SkPath[] = [];
-    for (let i = 0; i < MAX_MULTI_SERIES; i++) {
-      a.push(Skia.Path.Make());
-      b.push(Skia.Path.Make());
-    }
-    // One point buffer + spline scratch, reused across slots (built sequentially)
-    // and across frames — no per-frame, per-series array allocation.
-    poolRef.current = { a, b, tick: false, ptsBuf: [] as number[], scratch: makeSplineScratch() };
+    poolRef.current = {
+      empty: Skia.Path.Make(),
+      ptsBuf: [] as number[],
+      scratch: makeSplineScratch(),
+    };
   }
 
   return useDerivedValue(() => {
     const pool = poolRef.current!;
-    pool.tick = !pool.tick;
-    const slots = pool.tick ? pool.a : pool.b;
+    const slots = builders.value;
     const s = engine.series.get();
     const displays = engine.displaySeriesValues.get();
-    const out: ReturnType<typeof Skia.Path.Make>[] = [];
+    const out: SkPath[] = [];
     for (let i = 0; i < MAX_MULTI_SERIES; i++) {
-      const path = slots[i];
-      path.reset();
       if (i >= s.length) {
-        out.push(path);
+        out.push(pool.empty);
         continue;
       }
       const pts = buildLinePoints(
@@ -66,10 +61,13 @@ export function useMultiSeriesLinePaths(
       );
       const n = pts.length >> 1;
       if (n >= 2) {
-        path.moveTo(pts[0], pts[1]);
-        drawSpline(path, pts, pool.scratch);
+        const b = slots[i];
+        b.moveTo(pts[0], pts[1]);
+        drawSpline(b, pts, pool.scratch);
+        out.push(b.detach());
+      } else {
+        out.push(pool.empty);
       }
-      out.push(path);
     }
     return out;
   });

package/src/hooks/usePathBuilder.ts

@@ -0,0 +1,42 @@
+import { Skia } from "@shopify/react-native-skia";
+import { useMemo } from "react";
+import { useSharedValue, type SharedValue } from "react-native-reanimated";
+
+/** A `Skia.PathBuilder` instance (typed without depending on a named export). */
+export type ReanimatedPathBuilder = ReturnType<typeof Skia.PathBuilder.Make>;
+
+/**
+ * A `Skia.PathBuilder` made accessible inside Reanimated worklets.
+ *
+ * Unlike `SkPath`, an `SkPathBuilder` is **not** a Reanimated-shareable host
+ * object: stashing one in a `useRef` and reading it from a `useDerivedValue`
+ * worklet yields `undefined`. Wrapping it in a `SharedValue` is the supported
+ * way to cross the JS→UI boundary, so the builder is created once on the JS
+ * thread and reused every frame on the UI thread.
+ *
+ * Per-frame usage in a worklet:
+ *
+ *   const b = builder.value;
+ *   b.moveTo(x, y); b.lineTo(...);   // emit verbs
+ *   return b.detach();               // fresh immutable SkPath; resets the builder
+ *
+ * `detach()` returns a new `SkPath` and resets the builder for the next frame,
+ * so the returned reference changes every frame and Reanimated notifies
+ * subscribers without the two-path ping-pong the mutable-`SkPath` pool needs.
+ */
+export function usePathBuilder(): SharedValue<ReanimatedPathBuilder> {
+  const builder = useMemo(() => Skia.PathBuilder.Make(), []);
+  return useSharedValue(builder);
+}
+
+/** Like {@link usePathBuilder} but a fixed-length array of builders (e.g. one per series). */
+export function usePathBuilders(
+  count: number,
+): SharedValue<ReanimatedPathBuilder[]> {
+  const builders = useMemo(() => {
+    const arr: ReanimatedPathBuilder[] = [];
+    for (let i = 0; i < count; i++) arr.push(Skia.PathBuilder.Make());
+    return arr;
+  }, [count]);
+  return useSharedValue(builders);
+}

package/src/hooks/useTradeStream.ts

@@ -25,6 +25,8 @@ export function useTradeStream(
   tradeStream: SharedValue<TradeEvent[]>,
   padding: ChartPadding,
   active: boolean,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ): SharedValue<TradeMarker[]> {
   const markers = useSharedValue<TradeMarker[]>([]);
   const state = useSharedValue<TradeStreamState>(createTradeStreamState());
@@ -58,6 +60,7 @@ export function useTradeStream(
       const chartH = chartBottom - chartTop;
       markers.set(projectLabels(s, chartTop, chartH));
     },
+    autostart,
   );
 
   return markers;

package/src/index.ts

@@ -28,6 +28,7 @@ export { useTradeStream } from "./hooks/useTradeStream";
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export type {
+  AxisLabelConfig,
   BadgeConfig,
   BadgeMetrics,
   BadgeVariant,
@@ -67,6 +68,9 @@ export type {
   ScrubPointCore,
   ScrubPointMulti,
   ScrubSeriesValue,
+  SelectionDotConfig,
+  SelectionDotProps,
+  SelectionDotRingConfig,
   SeriesConfig,
   ThemeMode,
   TradeEvent,

package/src/math/spline.ts

@@ -1,4 +1,3 @@
-import type { SkPath } from "@shopify/react-native-skia";
 import type { LiveChartPoint } from "../types";
 
 /**
@@ -33,7 +32,28 @@ export function makeSplineScratch(): SplineScratch {
  *
  * @see https://github.com/benjitaylor/liveline
  */
-export function drawSpline(path: SkPath, pts: number[], scratch?: SplineScratch) {
+/**
+ * Minimal structural sink for {@link drawSpline}: just the verb-emitting methods
+ * it calls. Both `SkPath` and `SkPathBuilder` satisfy it, so the spline can be
+ * built into either a mutable `SkPath` or a `Skia.PathBuilder`.
+ */
+export type SplinePathSink = {
+  lineTo: (x: number, y: number) => unknown;
+  cubicTo: (
+    c1x: number,
+    c1y: number,
+    c2x: number,
+    c2y: number,
+    x: number,
+    y: number,
+  ) => unknown;
+};
+
+export function drawSpline(
+  path: SplinePathSink,
+  pts: number[],
+  scratch?: SplineScratch,
+) {
   "worklet";
   const n = pts.length >> 1;
   if (n < 2) return;

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ComponentType, ReactElement } from "react";
 import type { ViewStyle } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 
@@ -150,6 +151,11 @@ 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. */
+  positions?: number[];
 }
 
 /** Value badge pill configuration. */
@@ -170,6 +176,24 @@ export interface YAxisConfig {
   minGap?: number;
 }
 
+/**
+ * Axis edge label — the value floated at the plot's top or bottom edge
+ * (Robinhood-style high/low). Pass `topLabel`/`bottomLabel` as `true` for the
+ * batteries-included value label (the chart's current top/bottom Y-axis bound,
+ * updated each frame), an object to configure it, or `{ render }` to float a
+ * fully custom element instead.
+ */
+export interface AxisLabelConfig {
+  /** Formatter for the built-in value. Defaults to the chart's `formatValue`. */
+  format?: (v: number) => string;
+  /** Text color. Defaults to a muted label color (`palette.gridLabel`). */
+  color?: string;
+  /** Horizontal alignment within the plot width. Default `"right"`. */
+  position?: "left" | "right";
+  /** Full custom element, floated at the edge. Overrides the built-in value label. */
+  render?: () => ReactElement | null;
+}
+
 /** X-axis (time) configuration. */
 export interface XAxisConfig {
   /** Minimum pixel gap between time labels. Default `60`. */
@@ -213,6 +237,55 @@ export interface ScrubConfig {
   panGestureDelay?: number;
 }
 
+/**
+ * Props passed to a custom {@link SelectionDotConfig.component} — the dot drawn
+ * at the scrub intersection while scrubbing. All positional inputs are
+ * SharedValues so the dot animates on the UI thread without re-renders.
+ */
+export interface SelectionDotProps {
+  /** Scrub X in canvas px. */
+  x: SharedValue<number>;
+  /** Scrub Y in canvas px (the line/value intersection). */
+  y: SharedValue<number>;
+  /** Whether scrubbing is active. */
+  active: SharedValue<boolean>;
+  /** Crosshair fade opacity (0..1), already ramped. */
+  opacity: SharedValue<number>;
+  /** Resolved dot color (accent/series color). */
+  color: string;
+  /** Suggested dot radius in px. */
+  size: number;
+}
+
+/** Outer ring drawn around the built-in selection dot (the subtle halo). */
+export interface SelectionDotRingConfig {
+  /** Ring color. Defaults to the dot color. */
+  color?: string;
+  /** Ring thickness in pixels — how far the halo extends past the dot. Default `2`. */
+  width?: number;
+}
+
+/**
+ * Selection-dot styling — the dot drawn at the scrub intersection while
+ * scrubbing. Pass `selectionDot={false}` to hide it, an object to configure the
+ * built-in dot, or `{ component }` to supply a fully custom Skia dot.
+ */
+export interface SelectionDotConfig {
+  /** Dot radius in px. Default `4`. */
+  size?: number;
+  /** Dot color. Defaults to the line / leading-series color. */
+  color?: string;
+  /**
+   * Outer ring around the dot. `true`/config = on, `false` = off. Default on.
+   */
+  ring?: boolean | SelectionDotRingConfig;
+  /**
+   * Fully custom Skia dot — receives the scrub position as SharedValues. When
+   * set, the `size` / `color` / `ring` knobs are ignored.
+   */
+  component?: ComponentType<SelectionDotProps>;
+}
+
 /** Left-edge fade — soft erase so the chart blends into the left gutter (web liveline parity). */
 export interface LeftEdgeFadeConfig {
   /**
@@ -695,6 +768,20 @@ export interface LiveChartCoreProps {
   yAxis?: boolean | YAxisConfig;
   /** X-axis time labels. `true` = defaults, `false` = hidden, or pass `XAxisConfig`. Default `true`. */
   xAxis?: boolean | XAxisConfig;
+  /**
+   * Label floated at the top edge of the plot area. `true` = the built-in value
+   * label showing the chart's current TOP Y-axis bound (updated each frame),
+   * `false`/omitted = none, or pass `AxisLabelConfig` to configure it (or supply
+   * a custom `render`). Default off.
+   */
+  topLabel?: boolean | AxisLabelConfig;
+  /**
+   * Label floated at the bottom edge of the plot area. `true` = the built-in
+   * value label showing the chart's current BOTTOM Y-axis bound (updated each
+   * frame), `false`/omitted = none, or pass `AxisLabelConfig` (or a custom
+   * `render`). Default off.
+   */
+  bottomLabel?: boolean | AxisLabelConfig;
   /** Reference lines / bands drawn into the chart. Supports all three `ReferenceLine` forms. */
   referenceLines?: ReferenceLine[];
   /** Per-instance grid-line styling. Pass an object to override color / width / dash / opacity. */
@@ -737,6 +824,16 @@ export interface LiveChartCoreProps {
   accessibilityRole?: "image" | "none" | "adjustable" | "summary";
   /** Crosshair scrubbing on hover/drag. `true` = defaults, `false` = disabled, or pass `ScrubConfig`. Default `true`. */
   scrub?: boolean | ScrubConfig;
+  /**
+   * Selection dot drawn at the scrub intersection while scrubbing. `true`/omitted
+   * = built-in dot, `false` = hidden, or pass `SelectionDotConfig` (`size`,
+   * `color`, `ring`, or a custom `component`). Default `true`.
+   */
+  selectionDot?: boolean | SelectionDotConfig;
+  /** Called once when the user starts scrubbing/panning the chart. */
+  onGestureStart?: () => void;
+  /** Called once when the user stops scrubbing/panning the chart. */
+  onGestureEnd?: () => void;
   /**
    * Fade out chart content on the left (destination-out style). `true` = defaults, `false` = off,
    * or pass `LeftEdgeFadeConfig`. Default `true`.
@@ -796,6 +893,10 @@ export interface LiveChartProps extends LiveChartCoreProps {
   data: SharedValue<LiveChartPoint[]>;
   /** Latest live value for smooth interpolation between data updates. */
   value: SharedValue<number>;
+  /** Render once with no per-frame animation loop — for many small charts (sparklines)
+   *  in a list. Pulse/scrub/degen and the entry animation are disabled. Frame the data
+   *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
+  static?: boolean;
   /** Called when the user scrubs the crosshair. `null` when scrub ends. */
   onScrub?: (point: ScrubPoint | null) => void;
   /**