react-native-livechart 2.0.1 → 3.1.0

package/src/components/ValueLineOverlay.tsx

@@ -1,14 +1,9 @@
-import {
-  DashPathEffect,
-  Path,
-  Skia,
-  type SkPath,
-} from "@shopify/react-native-skia";
-import { useRef } from "react";
+import { DashPathEffect, Path } from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { ChartPadding } from "../draw/line";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { usePathBuilder } from "../hooks/usePathBuilder";
 
 /**
  * A dashed horizontal line that tracks the live display value — sitting at
@@ -29,30 +24,16 @@ export function ValueLineOverlay({
   intervals: [number, number];
   color: string;
 }) {
-  // Ping-pong persistent paths — avoid allocating a JSI-backed SkPath per frame.
-  const cacheRef = useRef<{
-    a: SkPath;
-    b: SkPath;
-    tick: boolean;
-  } | null>(null);
-  if (cacheRef.current === null) {
-    cacheRef.current = {
-      a: Skia.Path.Make(),
-      b: Skia.Path.Make(),
-      tick: false,
-    };
-  }
+  const builder = usePathBuilder();
 
   const path = useDerivedValue(() => {
-    const cache = cacheRef.current!;
-    cache.tick = !cache.tick;
-    const p = cache.tick ? cache.a : cache.b;
-    p.reset();
+    const b = builder.value;
     const y = dotY.get();
-    if (y < 0) return p;
-    p.moveTo(padding.left, y);
-    p.lineTo(engine.canvasWidth.get() - padding.right, y);
-    return p;
+    if (y >= 0) {
+      b.moveTo(padding.left, y);
+      b.lineTo(engine.canvasWidth.get() - padding.right, y);
+    }
+    return b.detach();
   });
 
   return (

package/src/components/XAxisOverlay.tsx

@@ -1,15 +1,9 @@
-import {
-  Group,
-  Path,
-  Skia,
-  type SkFont,
-  type SkPath,
-} from "@shopify/react-native-skia";
-import { useRef } from "react";
+import { Group, Path, type SkFont } from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import type { XAxisEntry } from "../hooks/useXAxis";
+import { usePathBuilder } from "../hooks/usePathBuilder";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import type { LiveChartPalette } from "../types";
 import { AnimatedLabel } from "./AnimatedLabel";
@@ -31,40 +25,26 @@ export function XAxisOverlay({
   palette: LiveChartPalette;
   font: SkFont;
 }) {
-  const axisCacheRef = useRef<{
-    a: SkPath;
-    b: SkPath;
-    tick: boolean;
-  } | null>(null);
-  if (axisCacheRef.current === null) {
-    axisCacheRef.current = {
-      a: Skia.Path.Make(),
-      b: Skia.Path.Make(),
-      tick: false,
-    };
-  }
+  const axisBuilder = usePathBuilder();
 
   const axisPath = useDerivedValue(() => {
     "worklet";
-    const axisCache = axisCacheRef.current!;
-    axisCache.tick = !axisCache.tick;
-    const path = axisCache.tick ? axisCache.a : axisCache.b;
-    path.reset();
+    const b = axisBuilder.value;
     const w = engine.canvasWidth.get();
     const h = engine.canvasHeight.get();
     const lineY = h - padding.bottom;
 
     // Bottom axis line
-    path.moveTo(padding.left, lineY);
-    path.lineTo(w - padding.right, lineY);
+    b.moveTo(padding.left, lineY);
+    b.lineTo(w - padding.right, lineY);
 
     // Tick marks
     const items = entries.get();
     for (let i = 0; i < items.length; i++) {
-      path.moveTo(items[i].x, lineY);
-      path.lineTo(items[i].x, lineY + TICK_HEIGHT);
+      b.moveTo(items[i].x, lineY);
+      b.lineTo(items[i].x, lineY + TICK_HEIGHT);
     }
-    return path;
+    return b.detach();
   });
 
   // Transform XAxisEntry[] into { x, y, label, alpha } for AnimatedLabel

package/src/components/YAxisOverlay.tsx

@@ -2,11 +2,8 @@ import {
   DashPathEffect,
   Group,
   Path,
-  Skia,
   type SkFont,
-  type SkPath,
 } from "@shopify/react-native-skia";
-import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { BADGE_METRICS_DEFAULTS } from "../constants";
 import type { ResolvedGridStyleConfig } from "../core/resolveConfig";
@@ -18,6 +15,7 @@ import {
   pillTextLeftX,
   type ChartPadding,
 } from "../draw/line";
+import { usePathBuilder } from "../hooks/usePathBuilder";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import type { BadgeMetrics, LiveChartPalette } from "../types";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
@@ -57,31 +55,17 @@ export function YAxisOverlay({
   const gridWidth = gridStyle?.strokeWidth ?? 1;
   const gridIntervals = gridStyle?.intervals ?? [];
   const gridOpacity = gridStyle?.opacity ?? 1;
-  const gridCacheRef = useRef<{
-    a: SkPath;
-    b: SkPath;
-    tick: boolean;
-  } | null>(null);
-  if (gridCacheRef.current === null) {
-    gridCacheRef.current = {
-      a: Skia.Path.Make(),
-      b: Skia.Path.Make(),
-      tick: false,
-    };
-  }
+  const gridBuilder = usePathBuilder();
 
   const gridLinesPath = useDerivedValue(() => {
-    const gridCache = gridCacheRef.current!;
-    gridCache.tick = !gridCache.tick;
-    const path = gridCache.tick ? gridCache.a : gridCache.b;
-    path.reset();
+    const b = gridBuilder.value;
     const items = entries.get();
     const w = engine.canvasWidth.get();
     for (let i = 0; i < items.length; i++) {
-      path.moveTo(padding.left, items[i].y);
-      path.lineTo(w - padding.right, items[i].y);
+      b.moveTo(padding.left, items[i].y);
+      b.lineTo(w - padding.right, items[i].y);
     }
-    return path;
+    return b.detach();
   });
 
   const leftInset =

package/src/core/resolveConfig.ts

@@ -1,4 +1,5 @@
 import type {
+  AxisLabelConfig,
   BadgeConfig,
   BadgeVariant,
   DegenOptions,
@@ -17,12 +18,16 @@ import type {
   PulseConfig,
   ReferenceLine,
   ScrubConfig,
+  SelectionDotConfig,
+  SelectionDotProps,
+  SelectionDotRingConfig,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,
   YAxisConfig,
 } from "../types";
 
+import type { ComponentType, ReactElement } from "react";
 import type { SharedValue } from "react-native-reanimated";
 import {
   BADGE_METRICS_DEFAULTS,
@@ -53,6 +58,16 @@ export interface ResolvedYAxisConfig {
   minGap: number;
 }
 
+export interface ResolvedAxisLabelConfig {
+  /** undefined → use the chart's `formatValue` at render time. */
+  format?: (v: number) => string;
+  /** undefined → use the muted default label color at render time. */
+  color?: string;
+  position: "left" | "right";
+  /** When set, the built-in value label is replaced by this custom element. */
+  render?: () => ReactElement | null;
+}
+
 export interface ResolvedXAxisConfig {
   minGap: number;
 }
@@ -80,6 +95,10 @@ export interface ResolvedGradientConfig {
   topOpacity: number | undefined;
   /** undefined → use palette.fillBottom (transparent) at render time */
   bottomOpacity: number | undefined;
+  /** Explicit color stops (top → bottom); overrides the opacity stops. */
+  colors: string[] | undefined;
+  /** Stop positions (0..1) matching `colors` length. */
+  positions: number[] | undefined;
 }
 
 export interface ResolvedPulseConfig {
@@ -217,6 +236,24 @@ export function resolveYAxis(
   return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
 }
 
+const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
+  format: undefined,
+  color: undefined,
+  position: "right",
+  render: undefined,
+};
+
+/**
+ * Resolves a `topLabel` / `bottomLabel` prop to a fully-typed config or null
+ * (no label). Opt-in, so `undefined`/`false` → null; `true` → the built-in
+ * value label with defaults; object → configured built-in (or a custom `render`).
+ */
+export function resolveAxisLabel(
+  prop: boolean | AxisLabelConfig | undefined,
+): ResolvedAxisLabelConfig | null {
+  return resolveToggle(prop, AXIS_LABEL_DEFAULTS, false);
+}
+
 const X_AXIS_DEFAULTS: ResolvedXAxisConfig = {
   minGap: 60,
 };
@@ -255,6 +292,8 @@ export function resolveScrub(
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
   topOpacity: undefined,
   bottomOpacity: undefined,
+  colors: undefined,
+  positions: undefined,
 };
 
 /**
@@ -574,6 +613,65 @@ export function resolveMultiSeriesDot(
   };
 }
 
+// ─── Selection dot ──────────────────────────────────────────────────────────
+
+/** Resolved selection-dot ring. `color: undefined` → use the dot color. */
+export interface ResolvedSelectionDotRingConfig {
+  color: string | undefined;
+  width: number;
+}
+
+const SELECTION_DOT_RING_DEFAULTS: ResolvedSelectionDotRingConfig = {
+  color: undefined,
+  width: 2,
+};
+
+/** `undefined`/`true` → ring defaults; `false` → null (no ring). */
+export function resolveSelectionDotRing(
+  prop: boolean | SelectionDotRingConfig | undefined,
+): ResolvedSelectionDotRingConfig | null {
+  return resolveToggle(prop, SELECTION_DOT_RING_DEFAULTS, true);
+}
+
+/** Fully-resolved selection-dot styling. */
+export interface ResolvedSelectionDotConfig {
+  size: number;
+  /** undefined → use the line / leading-series color at render time. */
+  color: string | undefined;
+  ring: ResolvedSelectionDotRingConfig | null;
+  /** When set, the built-in size/color/ring knobs are ignored. */
+  component?: ComponentType<SelectionDotProps>;
+}
+
+const SELECTION_DOT_SIZE_DEFAULT = 4;
+
+const SELECTION_DOT_DEFAULTS: ResolvedSelectionDotConfig = {
+  size: SELECTION_DOT_SIZE_DEFAULT,
+  color: undefined,
+  ring: SELECTION_DOT_RING_DEFAULTS,
+};
+
+/**
+ * Resolves the `selectionDot` prop to a fully-typed config or null (hidden).
+ * Defaults to ON, so `undefined`/`true` yield the built-in dot.
+ * - `false` → `null` (no dot)
+ * - `undefined`/`true` → built-in dot with defaults
+ * - object → configured built-in dot, or the custom `component` when set
+ *   (the size/color/ring knobs are still resolved but ignored by the slot)
+ */
+export function resolveSelectionDot(
+  prop: boolean | SelectionDotConfig | undefined,
+): ResolvedSelectionDotConfig | null {
+  if (prop === false) return null;
+  if (prop == null || prop === true) return SELECTION_DOT_DEFAULTS;
+  return {
+    size: prop.size ?? SELECTION_DOT_DEFAULTS.size,
+    color: prop.color,
+    ring: resolveSelectionDotRing(prop.ring),
+    component: prop.component,
+  };
+}
+
 // ─── Legend ───────────────────────────────────────────────────────────────────
 
 export interface ResolvedLegendConfig {

package/src/core/useLiveChartEngine.ts

@@ -7,6 +7,7 @@
  */
 import { useState } from "react";
 import {
+  useAnimatedReaction,
   useDerivedValue,
   useFrameCallback,
   useSharedValue,
@@ -31,6 +32,12 @@ export interface EngineConfig {
   nowOverride?: number;
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Loop-free render: settle the display state once (smoothing forced to 1, no
+   * per-frame frame callback) for many small charts in a list. See
+   * {@link LiveChartProps.static}.
+   */
+  static?: boolean;
   mode?: "line" | "candle";
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -143,7 +150,11 @@ export function applyLiveChartEngineFrame(
 export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   // Low-frequency config → UI thread via useDerivedValue
   const timeWindow = useDerivedValue(() => config.timeWindow);
-  const smoothing = useDerivedValue(() => config.smoothing);
+  // Static charts snap to their target in one tick (smoothing=1), so the single
+  // settle reaction below produces the final state with no per-frame easing.
+  const smoothing = useDerivedValue(() =>
+    config.static ? 1 : config.smoothing,
+  );
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
@@ -170,34 +181,74 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   // no useDerivedValue bridging, no closure serialization per tick.
   const { data, value, candles, liveCandle } = config;
 
+  // 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);
+
+  // Single refs object shared by the frame callback and the settle reaction so
+  // they can never drift out of sync.
+  const frameRefs: EngineFrameRefs = {
+    data,
+    value,
+    displayValue,
+    displayMin,
+    displayMax,
+    displayWindow,
+    timestamp,
+    canvasWidth,
+    canvasHeight,
+    timeWindow,
+    smoothing,
+    adaptiveSpeedBoostSV,
+    exaggerateSV,
+    referenceValue,
+    referenceValues,
+    nonNegativeSV,
+    maxValueSV,
+    nowOverrideSV,
+    windowBufferSV,
+    pausedSV,
+    modeSV,
+    candles,
+    liveCandle,
+  };
+
+  // `autostart=false` registers the frame callback without running it — the live
+  // loop is fully inert in static mode (the invariant that makes this worth it).
   useFrameCallback((frameInfo) => {
     "worklet";
-    applyLiveChartEngineFrame(frameInfo, {
-      data,
-      value,
-      displayValue,
-      displayMin,
-      displayMax,
-      displayWindow,
-      timestamp,
-      canvasWidth,
-      canvasHeight,
-      timeWindow,
-      smoothing,
-      adaptiveSpeedBoostSV,
-      exaggerateSV,
-      referenceValue,
-      referenceValues,
-      nonNegativeSV,
-      maxValueSV,
-      nowOverrideSV,
-      windowBufferSV,
-      pausedSV,
-      modeSV,
-      candles,
-      liveCandle,
-    });
-  });
+    applyLiveChartEngineFrame(frameInfo, frameRefs);
+  }, !config.static);
+
+  // One-shot settle for static charts: the fingerprint changes when the canvas
+  // lays out (width 0→real) or the framing inputs change, and the handler runs a
+  // single snap tick (smoothing=1). Inert when not static — `prepare` returns a
+  // constant so it never fires.
+  useAnimatedReaction(
+    () => {
+      if (!isStaticSV.get()) return 0; // inert when not static — never changes
+      const d = data.get();
+      const n = d.length;
+      return [
+        n,
+        n ? d[0].time : 0,
+        n ? d[0].value : 0,
+        n ? d[n - 1].time : 0,
+        n ? d[n - 1].value : 0,
+        value.get(),
+        canvasWidth.get(),
+        canvasHeight.get(),
+        timeWindow.get(),
+      ].join(",");
+    },
+    (curr, prev) => {
+      if (!isStaticSV.get() || curr === prev) return;
+      applyLiveChartEngineFrame(
+        { timeSincePreviousFrame: MS_PER_FRAME_60FPS },
+        frameRefs,
+      );
+    },
+  );
 
   return {
     data,

package/src/draw/markerAtlas.ts

@@ -207,17 +207,17 @@ function cellSpec(m: Marker, palette: LiveChartPalette, font: SkFont): CellSpec
       w: box,
       h: box,
       draw: (canvas, cx, cy) => {
-        const p = Skia.Path.Make();
+        const pb = Skia.PathBuilder.Make();
         for (let k = 0; k < 10; k++) {
           const ang = -Math.PI / 2 + (k * Math.PI) / 5;
           const rad = k % 2 === 0 ? outer : inner;
           const px = cx + rad * Math.cos(ang);
           const py = cy + rad * Math.sin(ang);
-          if (k === 0) p.moveTo(px, py);
-          else p.lineTo(px, py);
+          if (k === 0) pb.moveTo(px, py);
+          else pb.lineTo(px, py);
         }
-        p.close();
-        canvas.drawPath(p, fillPaint(color));
+        pb.close();
+        canvas.drawPath(pb.detach(), fillPaint(color));
       },
     };
   }
@@ -229,15 +229,15 @@ function cellSpec(m: Marker, palette: LiveChartPalette, font: SkFont): CellSpec
       w: box,
       h: box,
       draw: (canvas, cx, cy) => {
-        const p = Skia.Path.Make();
+        const pb = Skia.PathBuilder.Make();
         for (let k = 0; k < 4; k++) {
           const ang = (k * Math.PI) / 4;
           const dx = L * Math.cos(ang);
           const dy = L * Math.sin(ang);
-          p.moveTo(cx - dx, cy - dy);
-          p.lineTo(cx + dx, cy + dy);
+          pb.moveTo(cx - dx, cy - dy);
+          pb.lineTo(cx + dx, cy + dy);
         }
-        canvas.drawPath(p, strokePaint(color, 1.5, true));
+        canvas.drawPath(pb.detach(), strokePaint(color, 1.5, true));
       },
     };
   }

package/src/draw/particleAtlas.ts

@@ -0,0 +1,95 @@
+import {
+  Skia,
+  PaintStyle,
+  drawAsImageFromPicture,
+  type SkImage,
+} from "@shopify/react-native-skia";
+import { DEGEN_STRIDE } from "../constants";
+
+/** Reference radius of the rasterized white circle sprite (px). */
+const SPRITE_RADIUS = 16;
+/** Anti-alias breathing room baked around the circle so it never clips. */
+const SPRITE_MARGIN = 2;
+
+/** A rasterized white-circle sprite + its geometry. */
+export interface ParticleSprite {
+  image: SkImage | null;
+  /** Side length of the square sprite box (px). */
+  size: number;
+  /** Radius of the white circle inside the box (px). */
+  radius: number;
+}
+
+/**
+ * Rasterize ONE anti-aliased **white** filled circle into a square sprite, once
+ * (NOT per frame). Drawing it white lets each particle's per-sprite color
+ * modulate (multiply) the texture to its own tint + alpha via `drawAtlas`.
+ *
+ * Mirrors the PictureRecorder pattern in `markerAtlas.ts`.
+ */
+export function buildParticleSprite(): ParticleSprite {
+  const R = SPRITE_RADIUS;
+  const S = 2 * (R + SPRITE_MARGIN);
+  const paint = Skia.Paint();
+  paint.setAntiAlias(true);
+  paint.setColor(Skia.Color("#ffffff"));
+  paint.setStyle(PaintStyle.Fill);
+
+  const recorder = Skia.PictureRecorder();
+  const canvas = recorder.beginRecording(Skia.XYWHRect(0, 0, S, S));
+  canvas.drawCircle(S / 2, S / 2, R, paint);
+  const picture = recorder.finishRecordingAsPicture();
+  const image = drawAsImageFromPicture(picture, { width: S, height: S });
+  return { image, size: S, radius: R };
+}
+
+/** One particle ready to blit: world position + per-sprite scale/alpha/color. */
+export interface ParticleInstance {
+  x: number;
+  y: number;
+  scale: number;
+  alpha: number;
+  colorIndex: number;
+}
+
+/**
+ * Pure, worklet-safe projection of the packed particle ring buffer into render
+ * instances. No Skia — plain numbers only — so it's directly unit-testable.
+ *
+ * Preserves the exact size/opacity formulas the old per-slot `<Circle>` used:
+ *   life  = max(0, 1 - (now - t0) / burstDur)   (skip if dt = now - t0 < 0)
+ *   r     = size * (0.5 + life * 0.5),  size = buf[base+6] || 1
+ *   scale = r / spriteRadius
+ *   alpha = life * particleOpacity
+ * Inactive (active <= 0.5), pre-spawn (dt < 0) and fully-faded (life <= 0)
+ * slots are skipped.
+ */
+export function buildParticleInstances(
+  buf: Float64Array,
+  slots: number,
+  now: number,
+  burstDur: number,
+  particleOpacity: number,
+  spriteRadius: number,
+): ParticleInstance[] {
+  "worklet";
+  const out: ParticleInstance[] = [];
+  for (let i = 0; i < slots; i++) {
+    const base = i * DEGEN_STRIDE;
+    if (!(buf[base + 5] > 0.5)) continue;
+    const dt = now - buf[base + 4];
+    if (dt < 0) continue;
+    const life = Math.max(0, 1 - dt / burstDur);
+    if (life <= 0) continue;
+    const size = buf[base + 6] || 1;
+    const r = size * (0.5 + life * 0.5);
+    out.push({
+      x: buf[base + 0],
+      y: buf[base + 1],
+      scale: r / spriteRadius,
+      alpha: life * particleOpacity,
+      colorIndex: Math.max(0, Math.floor(buf[base + 7])),
+    });
+  }
+  return out;
+}

package/src/hooks/crosshairShared.ts

@@ -54,9 +54,35 @@ export interface CrosshairState {
   scrubValue: SharedValue<number | null>;
   crosshairOpacity: SharedValue<number>;
   tooltipLayout: SharedValue<TooltipLayout>;
+  /** Scrub intersection Y in canvas px; -1 when there's no dot to draw
+   *  (inactive / no value / degenerate range). See {@link computeScrubDotY}. */
+  scrubDotY: SharedValue<number>;
   gesture: ReturnType<typeof Gesture.Pan>;
 }
 
+/**
+ * Maps a scrub value to its Y pixel at the crosshair intersection — the same
+ * mapping the live dot and tooltip use. Returns -1 when there is no dot to draw
+ * (value is null or the canvas isn't laid out); a degenerate (zero) range pins
+ * the dot to the vertical center of the plot.
+ */
+export function computeScrubDotY(
+  value: number | null,
+  displayMin: number,
+  displayMax: number,
+  canvasHeight: number,
+  padTop: number,
+  padBottom: number,
+): number {
+  "worklet";
+  if (value === null) return -1;
+  const chartH = canvasHeight - padTop - padBottom;
+  if (chartH <= 0) return -1;
+  const valRange = displayMax - displayMin;
+  if (valRange === 0) return padTop + chartH / 2;
+  return padTop + ((displayMax - value) / valRange) * chartH;
+}
+
 /**
  * Maps a scrub X position to a window timestamp.
  * Returns -1 when inactive or when the canvas is not yet laid out.