react-native-livechart 1.0.0

package/src/hooks/useLiveDot.ts

@@ -0,0 +1,31 @@
+import { useDerivedValue } from "react-native-reanimated";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+
+/**
+ * Derive the live dot position (right edge of the chart, mapped to current value).
+ * Returns `{ dotX, dotY }` as shared values. Coordinates are set to `-100`
+ * (off-screen sentinel) when canvas dimensions are unavailable.
+ */
+export function useLiveDot(engine: SingleEngineState, padding: ChartPadding) {
+  const dotX = useDerivedValue(() => {
+    const w = engine.canvasWidth.value;
+    if (w === 0) return -100;
+    return w - padding.right;
+  });
+
+  const dotY = useDerivedValue(() => {
+    const h = engine.canvasHeight.value;
+    if (h === 0) return -100;
+    const chartH = h - padding.top - padding.bottom;
+    const dMin = engine.displayMin.value;
+    const dMax = engine.displayMax.value;
+    const valRange = dMax - dMin;
+    if (valRange === 0) return padding.top + chartH / 2;
+    return (
+      padding.top + ((dMax - engine.displayValue.value) / valRange) * chartH
+    );
+  });
+
+  return { dotX, dotY } as const;
+}

package/src/hooks/useMarkers.ts

@@ -0,0 +1,95 @@
+import { useRef } from "react";
+import { Gesture } from "react-native-gesture-handler";
+import {
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { runOnJS } from "react-native-worklets";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { projectMarkers, type ProjectedMarker } from "../math/markers";
+import { nearestMarkerIndex } from "../math/markers";
+import type {
+  LiveChartPoint,
+  Marker,
+  MarkerHoverEvent,
+  SeriesConfig,
+} from "../types";
+
+/**
+ * Projects markers to screen positions each frame and builds a tap gesture that
+ * hit-tests against them, firing `onMarkerHover` (or `null` on a miss).
+ */
+export function useMarkers(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  markers: SharedValue<Marker[]>,
+  active: boolean,
+  hitRadius: number,
+  onMarkerHover?: (event: MarkerHoverEvent | null) => void,
+  seriesSV?: SharedValue<SeriesConfig[]>,
+  lineData?: SharedValue<LiveChartPoint[]>,
+): { projected: SharedValue<ProjectedMarker[]>; tapGesture: ReturnType<typeof Gesture.Tap> } {
+  const projected = useSharedValue<ProjectedMarker[]>([]);
+  const cacheRef = useRef<{
+    a: ProjectedMarker[];
+    b: ProjectedMarker[];
+    tick: boolean;
+  } | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = { a: [] as ProjectedMarker[], b: [] as ProjectedMarker[], tick: false };
+  }
+
+  const emitHover =
+    /* istanbul ignore next -- invoked only from the UI-thread tap worklet */
+    (event: MarkerHoverEvent | null) => {
+      onMarkerHover?.(event);
+    };
+
+  useFrameCallback(
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
+      "worklet";
+      const cache = cacheRef.current!;
+      if (!active) {
+        if (projected.get().length > 0) projected.set([]);
+        return;
+      }
+      cache.tick = !cache.tick;
+      const buf = cache.tick ? cache.a : cache.b;
+      projectMarkers(markers.get(), buf, {
+        canvasWidth: engine.canvasWidth.get(),
+        canvasHeight: engine.canvasHeight.get(),
+        padTop: padding.top,
+        padBottom: padding.bottom,
+        padLeft: padding.left,
+        padRight: padding.right,
+        timestamp: engine.timestamp.get(),
+        displayWindow: engine.displayWindow.get(),
+        displayMin: engine.displayMin.get(),
+        displayMax: engine.displayMax.get(),
+        series: seriesSV?.get(),
+        lineData: lineData?.get(),
+      });
+      projected.set(buf);
+    },
+  );
+
+  const tapGesture = Gesture.Tap().onEnd(
+    /* istanbul ignore next -- gesture worklet runs on UI thread, not in Jest */ (
+      e,
+    ) => {
+      "worklet";
+      const idx = nearestMarkerIndex(projected.get(), e.x, e.y, hitRadius);
+      if (idx < 0) {
+        runOnJS(emitHover)(null);
+        return;
+      }
+      const m = markers.get()[idx];
+      const p = projected.get()[idx];
+      runOnJS(emitHover)({ marker: m, point: { x: p.x, y: p.y } });
+    },
+  );
+
+  return { projected, tapGesture };
+}

package/src/hooks/useModeBlend.ts

@@ -0,0 +1,52 @@
+import { useEffect } from "react";
+import {
+  Easing,
+  useDerivedValue,
+  useSharedValue,
+  withTiming,
+  type SharedValue,
+} from "react-native-reanimated";
+
+const MODE_BLEND_DURATION_MS = 300;
+
+export interface ModeBlendState {
+  /** 0 = fully line, 1 = fully candle */
+  modeBlend: SharedValue<number>;
+  /** line opacity = reveal.lineOpacity * (1 - modeBlend) */
+  lineGroupOpacity: SharedValue<number>;
+  /** candle opacity = reveal.lineOpacity * modeBlend */
+  candleGroupOpacity: SharedValue<number>;
+}
+
+/**
+ * Animated crossfade between line and candle chart layers.
+ *
+ * `modeBlend` animates 0→1 when `isCandle` becomes true, 1→0 when false.
+ * The derived opacities multiply by `lineOpacity` from `useChartReveal`
+ * so the reveal and mode-switch animations compose correctly.
+ */
+export function useModeBlend(
+  isCandle: boolean,
+  lineOpacity: SharedValue<number>,
+): ModeBlendState {
+  const modeBlend = useSharedValue(isCandle ? 1 : 0);
+
+  useEffect(() => {
+    modeBlend.set(
+      withTiming(isCandle ? 1 : 0, {
+        duration: MODE_BLEND_DURATION_MS,
+        easing: Easing.inOut(Easing.ease),
+      }),
+    );
+  }, [isCandle, modeBlend]);
+
+  const lineGroupOpacity = useDerivedValue(
+    () => lineOpacity.get() * (1 - modeBlend.get()),
+  );
+
+  const candleGroupOpacity = useDerivedValue(
+    () => lineOpacity.get() * modeBlend.get(),
+  );
+
+  return { modeBlend, lineGroupOpacity, candleGroupOpacity };
+}

package/src/hooks/useMomentum.ts

@@ -0,0 +1,37 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import { detectMomentum } from "../math/momentum";
+import type { Momentum, MomentumConfig } from "../types";
+
+/**
+ * Resolve the momentum prop to a detected or forced momentum value.
+ * - `true` = auto-detect from data with defaults
+ * - `false` = disabled, always 'flat'
+ * - `'up'` / `'down'` / `'flat'` = forced value
+ * - `MomentumConfig` = auto-detect with custom threshold/lookback
+ */
+export function resolveMomentumProp(
+  prop: boolean | Momentum | MomentumConfig,
+  data: readonly { time: number; value: number }[],
+): Momentum {
+  "worklet";
+  if (prop === false) return "flat";
+  if (prop === true)
+    return detectMomentum(data as { time: number; value: number }[]);
+  if (typeof prop === "object")
+    return detectMomentum(
+      data as { time: number; value: number }[],
+      prop.lookback,
+      prop.threshold,
+    );
+  return prop;
+}
+
+export function useMomentum(
+  engine: SingleEngineState,
+  momentumProp: boolean | Momentum | MomentumConfig = true,
+): SharedValue<Momentum> {
+  return useDerivedValue(() =>
+    resolveMomentumProp(momentumProp, engine.data.value),
+  );
+}

package/src/hooks/useMultiSeriesDegen.ts

@@ -0,0 +1,260 @@
+import { useEffect, useRef } from "react";
+import {
+  useDerivedValue,
+  useFrameCallback,
+  useSharedValue,
+  type DerivedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { runOnJS } from "react-native-worklets";
+import { DEGEN_STRIDE } from "../constants";
+import type { ResolvedDegenConfig } from "../core/resolveConfig";
+import type { MultiEngineState } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { computeShake, spawnBurst, tickParticles } from "../math/degenTick";
+import { detectMomentum } from "../math/momentum";
+import type { DegenShakePayload } from "../types";
+
+/**
+ * Multi-series degen: **every** visible series sparks a burst off its own
+ * endpoint dot on an up-momentum swing — in that series' color (its particles
+ * carry the series index as their `colorIndex`) — plus one shared chart shake
+ * re-armed from the strongest swing each frame. Reuses the single-series
+ * particle/shake math (`math/degenTick`).
+ */
+export function useMultiSeriesDegen(
+  engine: MultiEngineState,
+  padding: ChartPadding,
+  cfg: ResolvedDegenConfig | null,
+  onShake?: (payload: DegenShakePayload) => void,
+): {
+  pack: SharedValue<Float64Array<ArrayBuffer>>;
+  packRevision: SharedValue<number>;
+  shakeTransform: DerivedValue<
+    [{ translateX: number }, { translateY: number }]
+  >;
+} {
+  const MAX_SLOTS = 80;
+  const pack = useSharedValue(new Float64Array(MAX_SLOTS * DEGEN_STRIDE));
+  const packRevision = useSharedValue(0);
+  // Per-series previous momentum (0 = flat, 1 = up, 2 = down), index-aligned to series.
+  const prevMoms = useSharedValue<number[]>([]);
+  const writeRot = useSharedValue(0);
+  const enabledSV = useSharedValue(0);
+  const scaleSV = useSharedValue(1);
+  const downSV = useSharedValue(0);
+  const shakeEnabledSV = useSharedValue(0);
+  const shakeIntensitySV = useSharedValue(1);
+  const shakeDurationSecSV = useSharedValue(0.45);
+  const slotCountSV = useSharedValue(60);
+  const burstParticleCountSV = useSharedValue(20);
+  const particleBurstDurationSecSV = useSharedValue(1.0);
+  const dragSV = useSharedValue(0.95);
+  const sizeMinSV = useSharedValue(1);
+  const sizeMaxSV = useSharedValue(2.2);
+  const spreadAngleSV = useSharedValue(Math.PI * 1.2);
+  const jitterXSV = useSharedValue(24);
+  const jitterYSV = useSharedValue(8);
+  const speedMinSV = useSharedValue(60);
+  const speedMaxSV = useSharedValue(160);
+  const shakeX = useSharedValue(0);
+  const shakeY = useSharedValue(0);
+  const shakeStart = useSharedValue(0);
+  const prevTimestamp = useSharedValue(0);
+  const prevActiveCount = useSharedValue(0);
+  const hasOnShakeListenerSV = useSharedValue(0);
+
+  const onShakeRef = useRef(onShake);
+  useEffect(() => {
+    onShakeRef.current = onShake;
+  });
+  const emitShake =
+    /* istanbul ignore next -- invoked only from the UI-thread frame worklet */
+    (direction: "up" | "down") => {
+      onShakeRef.current?.({ direction });
+    };
+
+  const degenOff = cfg === null;
+
+  useEffect(() => {
+    // Mirror the resolved config into SharedValues for the UI-thread worklet.
+    // Everything is set unconditionally — no prop-derived `if` branch — so this
+    // is a plain external-store sync, not a disguised event handler. When degen
+    // is off, enabledSV is 0 and the frame worklet early-returns (zeroing the
+    // particle buffer and shake itself), so the remaining values are inert; the
+    // `?? default` fallbacks stand in for the null-config case.
+    enabledSV.set(degenOff ? 0 : 1);
+    shakeEnabledSV.set(cfg?.shake ? 1 : 0);
+    hasOnShakeListenerSV.set(!degenOff && onShake != null ? 1 : 0);
+    scaleSV.set(cfg?.scale ?? 1);
+    downSV.set(cfg?.downMomentum ? 1 : 0);
+    shakeIntensitySV.set(cfg?.shakeIntensity ?? 1);
+    shakeDurationSecSV.set(cfg?.shakeDurationSec ?? 0.45);
+    slotCountSV.set(cfg?.particleSlotCount ?? 60);
+    burstParticleCountSV.set(cfg?.burstParticleCount ?? 20);
+    particleBurstDurationSecSV.set(cfg?.particleBurstDurationSec ?? 1.0);
+    dragSV.set(cfg?.drag ?? 0.95);
+    sizeMinSV.set(cfg?.particleSizeMin ?? 1);
+    sizeMaxSV.set(cfg?.particleSizeMax ?? 2.2);
+    spreadAngleSV.set(cfg?.spreadAngle ?? Math.PI * 1.2);
+    jitterXSV.set(cfg?.positionJitterX ?? 24);
+    jitterYSV.set(cfg?.positionJitterY ?? 8);
+    speedMinSV.set(cfg?.speedMin ?? 60);
+    speedMaxSV.set(cfg?.speedMax ?? 160);
+  }, [
+    degenOff,
+    onShake,
+    cfg,
+    // SharedValue refs are stable (useSharedValue), so listing them satisfies
+    // exhaustive-deps without ever re-running the effect.
+    enabledSV,
+    shakeEnabledSV,
+    hasOnShakeListenerSV,
+    shakeStart,
+    shakeX,
+    shakeY,
+    scaleSV,
+    downSV,
+    shakeIntensitySV,
+    shakeDurationSecSV,
+    slotCountSV,
+    burstParticleCountSV,
+    particleBurstDurationSecSV,
+    dragSV,
+    sizeMinSV,
+    sizeMaxSV,
+    spreadAngleSV,
+    jitterXSV,
+    jitterYSV,
+    speedMinSV,
+    speedMaxSV,
+  ]);
+
+  useFrameCallback(
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
+      "worklet";
+      const now = engine.timestamp.get();
+      const buf = pack.get();
+      const slots = slotCountSV.get();
+
+      const dtSec = prevTimestamp.get() > 0 ? now - prevTimestamp.get() : 0.016;
+      prevTimestamp.set(now);
+
+      const moms = prevMoms.get();
+
+      if (enabledSV.get() < 0.5) {
+        for (let i = 0; i < slots; i++) buf[i * DEGEN_STRIDE + 5] = 0;
+        moms.length = 0;
+        prevActiveCount.set(0);
+        shakeStart.set(0);
+        shakeX.set(0);
+        shakeY.set(0);
+        return;
+      }
+
+      const s = engine.series.get();
+      const displays = engine.displaySeriesValues.get();
+      const ops = engine.seriesOpacities.get();
+      const n = s.length;
+      while (moms.length < n) moms.push(0);
+      if (moms.length > n) moms.length = n;
+
+      const cw = engine.canvasWidth.get();
+      const ch = engine.canvasHeight.get();
+      const canSpawn = cw >= 1 && ch >= 1;
+      const dMin = engine.displayMin.get();
+      const dMax = engine.displayMax.get();
+      const valRange = dMax - dMin;
+      const chartH = ch - padding.top - padding.bottom;
+      const ox = cw - padding.right;
+      const allowDown = downSV.get() > 0.5;
+
+      // Each visible series fires a burst off its own dot on a fresh swing.
+      let firedDir = 0; // 0 none, 1 up, 2 down
+      for (let i = 0; i < n; i++) {
+        const visible = (ops[i] ?? 0) >= 0.5;
+        const m = visible ? detectMomentum(s[i].data) : "flat";
+        const code = m === "up" ? 1 : m === "down" ? 2 : 0;
+        const prev = moms[i];
+        moms[i] = code;
+        if (!canSpawn || code === 0 || code === prev) continue;
+        const isUp = code === 1;
+        if (!isUp && !allowDown) continue;
+        const v = displays[i] ?? s[i].value;
+        const oy =
+          valRange === 0
+            ? padding.top + chartH / 2
+            : padding.top + ((dMax - v) / valRange) * chartH;
+        writeRot.set(
+          spawnBurst(buf, {
+            ox,
+            oy,
+            sc: scaleSV.get(),
+            burst: burstParticleCountSV.get(),
+            baseAngle: isUp ? -Math.PI / 2 : Math.PI / 2,
+            spread: spreadAngleSV.get(),
+            jx: jitterXSV.get(),
+            jy: jitterYSV.get(),
+            sMin: speedMinSV.get(),
+            sMax: speedMaxSV.get(),
+            szMin: sizeMinSV.get(),
+            szMax: sizeMaxSV.get(),
+            now,
+            baseRot: writeRot.get(),
+            slots,
+            colorIndex: i, // color this burst with series i's color
+          }),
+        );
+        // Up swings win the shared shake; otherwise a down swing arms it.
+        if (firedDir !== 1) firedDir = isUp ? 1 : 2;
+      }
+
+      if (firedDir !== 0 && shakeEnabledSV.get() > 0.5) {
+        shakeStart.set(now);
+        if (hasOnShakeListenerSV.get() > 0.5) {
+          runOnJS(emitShake)(firedDir === 1 ? "up" : "down");
+        }
+      }
+
+      if (shakeStart.get() > 0 && shakeEnabledSV.get() > 0.5) {
+        const r = computeShake(
+          now - shakeStart.get(),
+          shakeDurationSecSV.get(),
+          scaleSV.get(),
+          shakeIntensitySV.get(),
+        );
+        shakeX.set(r.x);
+        shakeY.set(r.y);
+        if (!r.active) shakeStart.set(0);
+      } else if (shakeEnabledSV.get() < 0.5) {
+        shakeStart.set(0);
+        shakeX.set(0);
+        shakeY.set(0);
+      }
+
+      const activeCount = tickParticles(
+        buf,
+        slots,
+        now,
+        particleBurstDurationSecSV.get(),
+        dragSV.get(),
+        dtSec,
+      );
+
+      if (activeCount > 0 || prevActiveCount.get() > 0) {
+        packRevision.set(packRevision.get() + 1);
+      }
+      prevActiveCount.set(activeCount);
+    },
+  );
+
+  const shakeTransform = useDerivedValue(() => {
+    "worklet";
+    return [{ translateX: shakeX.get() }, { translateY: shakeY.get() }] as [
+      { translateX: number },
+      { translateY: number },
+    ];
+  });
+
+  return { pack, packRevision, shakeTransform };
+}

package/src/hooks/useMultiSeriesLinePaths.ts

@@ -0,0 +1,76 @@
+import { Skia, type SkPath } from "@shopify/react-native-skia";
+import { useRef } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+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";
+
+/**
+ * One derived shared value holding up to `MAX_MULTI_SERIES` Skia paths (unused slots are empty paths).
+ *
+ * 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.
+ */
+export function useMultiSeriesLinePaths(
+  engine: MultiEngineState,
+  padding: ChartPadding,
+): SharedValue<ReturnType<typeof Skia.Path.Make>[]> {
+  const poolRef = useRef<{
+    a: SkPath[];
+    b: SkPath[];
+    tick: boolean;
+    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() };
+  }
+
+  return useDerivedValue(() => {
+    const pool = poolRef.current!;
+    pool.tick = !pool.tick;
+    const slots = pool.tick ? pool.a : pool.b;
+    const s = engine.series.get();
+    const displays = engine.displaySeriesValues.get();
+    const out: ReturnType<typeof Skia.Path.Make>[] = [];
+    for (let i = 0; i < MAX_MULTI_SERIES; i++) {
+      const path = slots[i];
+      path.reset();
+      if (i >= s.length) {
+        out.push(path);
+        continue;
+      }
+      const pts = buildLinePoints(
+        s[i].data,
+        displays[i] ?? s[i].value,
+        engine.timestamp.get(),
+        engine.displayWindow.get(),
+        engine.displayMin.get(),
+        engine.displayMax.get(),
+        engine.canvasWidth.get(),
+        engine.canvasHeight.get(),
+        padding,
+        pool.ptsBuf,
+      );
+      const n = pts.length >> 1;
+      if (n >= 2) {
+        path.moveTo(pts[0], pts[1]);
+        drawSpline(path, pts, pool.scratch);
+      }
+      out.push(path);
+    }
+    return out;
+  });
+}