react-native-livechart 3.0.0 → 3.1.0

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/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.

package/src/hooks/useCandlePaths.ts

@@ -29,6 +29,8 @@ export function useCandlePaths(
   candleWidthSecs: number,
   active: boolean,
   candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ) {
   const targetCandleWidth = useDerivedValue(() => candleWidthSecs);
   const displayCandleWidth = useSharedValue(candleWidthSecs);
@@ -50,7 +52,7 @@ export function useCandlePaths(
         dt,
       ),
     );
-  });
+  }, autostart);
 
   /* istanbul ignore next -- worklet */
   const geometry = useDerivedValue(() => {

package/src/hooks/useChartColors.ts

@@ -12,6 +12,11 @@ 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[];
+  /** Stop positions matching `gradientColors`, or undefined for even spacing. */
+  gradientPositions: number[] | undefined;
 }
 
 /**
@@ -39,10 +44,24 @@ export function useChartColors(
       ? `rgba(${r}, ${g}, ${b}, ${gradientCfg.bottomOpacity})`
       : 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;
+
   return {
     backgroundColor,
     gradientEnd,
     gradientTopColor,
     gradientBottomColor,
+    gradientColors,
+    gradientPositions,
   };
 }

package/src/hooks/useChartReveal.ts

@@ -58,6 +58,8 @@ export interface ChartRevealState {
 export function useChartReveal(
   loading: boolean,
   hasData: SharedValue<boolean>,
+  /** Static charts skip the entry ramp: morphT snaps to its target, no `withTiming`. */
+  isStatic = false,
 ): 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
@@ -71,13 +73,14 @@ export function useChartReveal(
 
   // The reaction reads presence/loading on the UI thread (a worklet, never during
   // render — so no Reanimated "reading `value` during render" warning), seeds the
-  // exact reveal state on its first run, then animates on later changes.
+  // exact reveal state on its first run, then animates on later changes. Static
+  // charts always snap (no `withTiming` ramp) so no entry animation ever runs.
   useAnimatedReaction(
     () => !isLoading.get() && hasData.get(),
     (chartVisible, prev) => {
       "worklet";
-      if (prev === null || prev === undefined) {
-        // First run: snap to the correct initial reveal state (no animation).
+      if (isStatic || prev === null || prev === undefined) {
+        // Static, or first run: snap to the correct reveal state (no animation).
         morphT.set(chartVisible ? 1 : 0);
         return;
       }
@@ -90,7 +93,7 @@ export function useChartReveal(
         );
       }
     },
-    [hasData],
+    [hasData, isStatic],
   );
 
   const isEmpty = useDerivedValue(() => !isLoading.get() && !hasData.get());

package/src/hooks/useCrosshair.ts

@@ -16,6 +16,7 @@ import type { CandlePoint, LiveChartPalette, ScrubPoint } from "../types";
 import {
   computeCandleTooltipLayout,
   computeCrosshairOpacity,
+  computeScrubDotY,
   computeScrubTime,
   deriveCrosshairTooltipSingle,
   type CrosshairState,
@@ -57,9 +58,14 @@ export function useCrosshair(
   candleOpts?: CrosshairCandleOpts,
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay = 0,
+  onGestureStart?: () => void,
+  onGestureEnd?: () => void,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
+  // Tracks whether the active scrub phase actually began, so a tap that never
+  // activates doesn't emit a spurious onGestureEnd.
+  const gestureStarted = useSharedValue(false);
 
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
@@ -112,6 +118,19 @@ export function useCrosshair(
     ),
   );
 
+  // Y pixel of the scrub intersection — used by the selection dot. -1 when
+  // there's no value to mark.
+  const scrubDotY = useDerivedValue(() =>
+    computeScrubDotY(
+      scrubValue.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
   // Monospace advance width, measured once per render (not per scrub frame) so
   // the tooltip layout worklet can size text by character count instead of a
   // per-frame Skia measureText.
@@ -165,7 +184,19 @@ export function useCrosshair(
     onScrub?.(null);
   }
 
+  /* istanbul ignore next */
+  function handleGestureStart() {
+    onGestureStart?.();
+  }
+
+  /* istanbul ignore next */
+  function handleGestureEnd() {
+    onGestureEnd?.();
+  }
+
   const hasOnScrub = onScrub != null;
+  const hasOnGestureStart = onGestureStart != null;
+  const hasOnGestureEnd = onGestureEnd != null;
 
   useAnimatedReaction(
     () => {
@@ -178,13 +209,14 @@ export function useCrosshair(
       if (val === null || time < 0) return "__pending__";
       const chartW = engine.canvasWidth.get() - padding.left - padding.right;
       if (chartW <= 0) return "__pending__";
-      const h = engine.canvasHeight.get();
-      const chartH = h - padding.top - padding.bottom;
-      const valRange = engine.displayMax.get() - engine.displayMin.get();
-      const dotY =
-        valRange === 0
-          ? padding.top + chartH / 2
-          : padding.top + ((engine.displayMax.get() - val) / valRange) * chartH;
+      const dotY = computeScrubDotY(
+        val,
+        engine.displayMin.get(),
+        engine.displayMax.get(),
+        engine.canvasHeight.get(),
+        padding.top,
+        padding.bottom,
+      );
       let candleJson: string | null = null;
       if (isCandleMode) {
         const c = scrubCandle.get();
@@ -229,6 +261,8 @@ export function useCrosshair(
         if (!enabled) return;
         scrubX.set(e.x);
         scrubActive.set(true);
+        gestureStarted.set(true);
+        if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
     .onUpdate(
@@ -243,6 +277,10 @@ export function useCrosshair(
         "worklet";
         scrubActive.set(false);
         if (hasOnScrub) scheduleOnRN(handleScrubEnd);
+        if (gestureStarted.get()) {
+          gestureStarted.set(false);
+          if (hasOnGestureEnd) scheduleOnRN(handleGestureEnd);
+        }
       },
     );
 
@@ -258,6 +296,7 @@ export function useCrosshair(
     scrubValue,
     crosshairOpacity,
     tooltipLayout,
+    scrubDotY,
     gesture,
   };
 }