react-native-livechart 1.0.0

package/src/hooks/useCrosshair.ts

@@ -0,0 +1,250 @@
+import { type SkFont } from "@shopify/react-native-skia";
+import { Platform } from "react-native";
+import { Gesture } from "react-native-gesture-handler";
+import {
+  useAnimatedReaction,
+  useDerivedValue,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import { type ChartPadding } from "../draw/line";
+import { interpolateAtTime } from "../math/interpolate";
+import { pickCandleAtTime } from "../math/pickCandle";
+import type { CandlePoint, LiveChartPalette, ScrubPoint } from "../types";
+import {
+  computeCandleTooltipLayout,
+  computeCrosshairOpacity,
+  computeScrubTime,
+  deriveCrosshairTooltipSingle,
+  type CrosshairState,
+} from "./crosshairShared";
+
+export type { CrosshairState, TooltipLayout } from "./crosshairShared";
+export type { ScrubPoint };
+
+  export {
+    computeCandleTooltipLayout,
+    computeCrosshairOpacity,
+    computeScrubTime,
+    computeTooltipLayout,
+    computeTooltipLayoutMulti,
+    deriveCrosshairTooltipSingle,
+    deriveScrubValueSingle,
+    HIDDEN_TOOLTIP
+  } from "./crosshairShared";
+
+export interface CrosshairCandleOpts {
+  mode: "line" | "candle";
+  candles?: SharedValue<CandlePoint[]>;
+  liveCandle?: SharedValue<CandlePoint | null>;
+  candleWidthSecs: number;
+}
+
+/**
+ * Single-series crosshair + scrub. Use `useCrosshairSeries` for `LiveChartSeries`.
+ */
+export function useCrosshair(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  _palette: LiveChartPalette,
+  formatValue: (v: number) => string,
+  formatTime: (t: number) => string,
+  font: SkFont,
+  enabled: boolean,
+  onScrub?: (point: ScrubPoint | null) => void,
+  candleOpts?: CrosshairCandleOpts,
+): CrosshairState {
+  const scrubX = useSharedValue(-1);
+  const scrubActive = useSharedValue(false);
+
+  const scrubTime = useDerivedValue(() =>
+    computeScrubTime(
+      scrubActive.get(),
+      scrubX.get(),
+      padding,
+      engine.canvasWidth.get(),
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+    ),
+  );
+
+  const isCandleMode = candleOpts?.mode === "candle";
+  const candlesSV = candleOpts?.candles;
+  const liveCandleSV = candleOpts?.liveCandle;
+  const candleWidthSecs = candleOpts?.candleWidthSecs ?? 60;
+
+  /* istanbul ignore next -- worklet */
+  const scrubCandle = useDerivedValue(() => {
+    if (
+      !isCandleMode ||
+      !candlesSV ||
+      !scrubActive.get() ||
+      scrubTime.get() < 0
+    )
+      return null;
+    return pickCandleAtTime(
+      candlesSV.get(),
+      liveCandleSV?.get() ?? null,
+      scrubTime.get(),
+      candleWidthSecs,
+    );
+  });
+
+  /* istanbul ignore next -- worklet */
+  const scrubValue = useDerivedValue(() => {
+    if (!scrubActive.get() || scrubTime.get() < 0) return null;
+    if (isCandleMode) {
+      return scrubCandle.get()?.close ?? null;
+    }
+    return interpolateAtTime(engine.data.get(), scrubTime.get());
+  });
+
+  const crosshairOpacity = useDerivedValue(() =>
+    computeCrosshairOpacity(
+      scrubActive.get(),
+      scrubX.get(),
+      engine.canvasWidth.get(),
+      padding.right,
+    ),
+  );
+
+  const tooltipLayout = useDerivedValue(() => {
+    if (isCandleMode) {
+      return computeCandleTooltipLayout(
+        scrubActive.get(),
+        scrubX.get(),
+        scrubCandle.get(),
+        scrubTime.get(),
+        padding,
+        engine.canvasWidth.get(),
+        formatValue,
+        formatTime,
+        font,
+      );
+    }
+    return deriveCrosshairTooltipSingle(
+      scrubActive.get(),
+      scrubX.get(),
+      scrubTime.get(),
+      scrubValue.get(),
+      padding,
+      engine.canvasWidth.get(),
+      formatValue,
+      formatTime,
+      font,
+    );
+  });
+
+  /* istanbul ignore next -- invoked only via scheduleOnRN from UI-thread gesture */
+  function handleScrub(
+    x: number,
+    y: number,
+    time: number,
+    value: number,
+    candleJson: string | null,
+  ) {
+    const candle: CandlePoint | undefined = candleJson
+      ? (JSON.parse(candleJson) as CandlePoint)
+      : undefined;
+    onScrub?.({ time, value, x, y, candle });
+  }
+
+  /* istanbul ignore next */
+  function handleScrubEnd() {
+    onScrub?.(null);
+  }
+
+  const hasOnScrub = onScrub != null;
+
+  useAnimatedReaction(
+    () => {
+      "worklet";
+      if (!hasOnScrub) return "__idle__";
+      if (!scrubActive.get()) return "__inactive__";
+      const time = scrubTime.get();
+      const val = scrubValue.get();
+      const x = scrubX.get();
+      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;
+      let candleJson: string | null = null;
+      if (isCandleMode) {
+        const c = scrubCandle.get();
+        if (c) candleJson = JSON.stringify(c);
+      }
+      return JSON.stringify([time, val, x, dotY, candleJson]);
+    },
+    (curr, prev) => {
+      "worklet";
+      if (!hasOnScrub) return;
+      if (
+        curr === "__idle__" ||
+        curr === "__inactive__" ||
+        curr === "__pending__"
+      ) {
+        return;
+      }
+      if (curr === prev) return;
+      const row = JSON.parse(curr) as [
+        number,
+        number,
+        number,
+        number,
+        string | null,
+      ];
+      scheduleOnRN(handleScrub, row[2], row[3], row[0], row[1], row[4]);
+    },
+  );
+
+  let gesture = Gesture.Pan()
+    .minDistance(Platform.OS === "android" ? 10 : 0)
+    .activateAfterLongPress(0)
+    .maxPointers(1)
+    .shouldCancelWhenOutside(false)
+    .onBegin(
+      /* istanbul ignore next */ (e) => {
+        "worklet";
+        if (!enabled) return;
+        scrubX.set(e.x);
+        scrubActive.set(true);
+      },
+    )
+    .onUpdate(
+      /* istanbul ignore next */ (e) => {
+        "worklet";
+        if (!enabled) return;
+        scrubX.set(e.x);
+      },
+    )
+    .onFinalize(
+      /* istanbul ignore next */ () => {
+        "worklet";
+        scrubActive.set(false);
+        if (hasOnScrub) scheduleOnRN(handleScrubEnd);
+      },
+    );
+
+  /* istanbul ignore next -- Android-only gesture axis config */
+  if (Platform.OS === "android") {
+    gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
+  }
+
+  return {
+    scrubX,
+    scrubActive,
+    scrubTime,
+    scrubValue,
+    crosshairOpacity,
+    tooltipLayout,
+    gesture,
+  };
+}

package/src/hooks/useCrosshairSeries.ts

@@ -0,0 +1,163 @@
+import { Platform } from "react-native";
+import { Gesture } from "react-native-gesture-handler";
+import {
+  useAnimatedReaction,
+  useDerivedValue,
+  useSharedValue,
+} from "react-native-reanimated";
+import type { MultiEngineState } from "../core/useLiveChartEngine";
+import { type ChartPadding } from "../draw/line";
+import type { ScrubPointMulti } from "../types";
+import {
+  deriveScrubValueSeries,
+  interpolateSeriesAtTime,
+} from "./crosshairSeries";
+import {
+  computeCrosshairOpacity,
+  computeScrubTime,
+  HIDDEN_TOOLTIP,
+  type CrosshairState,
+} from "./crosshairShared";
+
+/**
+ * LiveChartSeries crosshair + scrub. No tooltip — data is delivered via
+ * `onScrub` worklet callback on the UI thread.
+ */
+export function useCrosshairSeries(
+  engine: MultiEngineState,
+  padding: ChartPadding,
+  enabled: boolean,
+  onScrub?: (point: ScrubPointMulti | null) => void,
+): CrosshairState {
+  const scrubX = useSharedValue(-1);
+  const scrubActive = useSharedValue(false);
+
+  const scrubTime = useDerivedValue(() =>
+    computeScrubTime(
+      scrubActive.get(),
+      scrubX.get(),
+      padding,
+      engine.canvasWidth.get(),
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+    ),
+  );
+
+  const scrubValue = useDerivedValue(() =>
+    deriveScrubValueSeries(
+      scrubActive.get(),
+      scrubTime.get(),
+      engine.series.get(),
+    ),
+  );
+
+  const crosshairOpacity = useDerivedValue(() =>
+    computeCrosshairOpacity(
+      scrubActive.get(),
+      scrubX.get(),
+      engine.canvasWidth.get(),
+      padding.right,
+    ),
+  );
+
+  const tooltipLayout = useSharedValue(HIDDEN_TOOLTIP);
+
+  const hasOnScrub = onScrub != null;
+
+  useAnimatedReaction(
+    () => {
+      "worklet";
+      if (!hasOnScrub) return "__idle__";
+      if (!scrubActive.get()) return "__inactive__";
+      const time = scrubTime.get();
+      const x = scrubX.get();
+      const chartW = engine.canvasWidth.get() - padding.left - padding.right;
+      if (chartW <= 0) return "__pending__";
+      const r = interpolateSeriesAtTime(engine.series.get(), time);
+      if (r.primary === null) 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() - r.primary) / valRange) * chartH;
+      return JSON.stringify({
+        time,
+        x,
+        y: dotY,
+        primary: r.primary,
+        series: r.seriesValues,
+      });
+    },
+    (curr, prev) => {
+      "worklet";
+      if (!hasOnScrub) return;
+      if (curr === "__inactive__") {
+        onScrub!(null);
+        return;
+      }
+      if (curr === "__idle__" || curr === "__pending__") {
+        return;
+      }
+      if (curr === prev) return;
+      const p = JSON.parse(curr) as {
+        time: number;
+        x: number;
+        y: number;
+        primary: number;
+        series: ScrubPointMulti["seriesValues"];
+      };
+      onScrub!({
+        time: p.time,
+        value: p.primary,
+        x: p.x,
+        y: p.y,
+        seriesValues: p.series,
+      });
+    },
+  );
+
+  let gesture = Gesture.Pan()
+    .minDistance(Platform.OS === "android" ? 10 : 0)
+    .activateAfterLongPress(0)
+    .maxPointers(1)
+    .shouldCancelWhenOutside(false)
+    .onBegin(
+      /* istanbul ignore next */ (e) => {
+        "worklet";
+        if (!enabled) return;
+        scrubX.set(e.x);
+        scrubActive.set(true);
+      },
+    )
+    .onUpdate(
+      /* istanbul ignore next */ (e) => {
+        "worklet";
+        if (!enabled) return;
+        scrubX.set(e.x);
+      },
+    )
+    .onFinalize(
+      /* istanbul ignore next */ () => {
+        "worklet";
+        scrubActive.set(false);
+      },
+    );
+
+  /* istanbul ignore next */
+  if (Platform.OS === "android") {
+    gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
+  }
+
+  return {
+    scrubX,
+    scrubActive,
+    scrubTime,
+    scrubValue,
+    crosshairOpacity,
+    tooltipLayout,
+    gesture,
+  };
+}

package/src/hooks/useDegen.ts

@@ -0,0 +1,262 @@
+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 { SingleEngineState } from "../core/useLiveChartEngine";
+import { computeShake, spawnBurst, tickParticles } from "../math/degenTick";
+import type { DegenShakePayload, Momentum } from "../types";
+
+export function useDegen(
+  engine: SingleEngineState,
+  dotX: SharedValue<number>,
+  dotY: SharedValue<number>,
+  momentumSV: SharedValue<Momentum>,
+  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);
+  const prevM = useSharedValue<Momentum>("flat");
+  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 = (direction: "up" | "down") => {
+    onShakeRef.current?.({ direction });
+  };
+
+  const degenOff = cfg === null;
+  const resolvedScale = cfg?.scale ?? 1;
+  const resolvedDown = cfg?.downMomentum ?? false;
+  const resolvedShake = cfg?.shake ?? true;
+  const resolvedShakeIntensity = cfg?.shakeIntensity ?? 1;
+  const resolvedShakeDurationSec = cfg?.shakeDurationSec ?? 0.45;
+  const resolvedSlotCount = cfg?.particleSlotCount ?? 60;
+  const resolvedBurstParticleCount = cfg?.burstParticleCount ?? 20;
+  const resolvedParticleBurstDurationSec = cfg?.particleBurstDurationSec ?? 1.0;
+  const resolvedDrag = cfg?.drag ?? 0.95;
+  const resolvedSizeMin = cfg?.particleSizeMin ?? 1;
+  const resolvedSizeMax = cfg?.particleSizeMax ?? 2.2;
+  const resolvedSpreadAngle = cfg?.spreadAngle ?? Math.PI * 1.2;
+  const resolvedJitterX = cfg?.positionJitterX ?? 24;
+  const resolvedJitterY = cfg?.positionJitterY ?? 8;
+  const resolvedSpeedMin = cfg?.speedMin ?? 60;
+  const resolvedSpeedMax = cfg?.speedMax ?? 160;
+
+  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
+    // resolved* defaults already stand in for the null-config case.
+    enabledSV.set(degenOff ? 0 : 1);
+    shakeEnabledSV.set(!degenOff && resolvedShake ? 1 : 0);
+    hasOnShakeListenerSV.set(!degenOff && onShake != null ? 1 : 0);
+    scaleSV.set(resolvedScale);
+    downSV.set(resolvedDown ? 1 : 0);
+    shakeIntensitySV.set(resolvedShakeIntensity);
+    shakeDurationSecSV.set(resolvedShakeDurationSec);
+    slotCountSV.set(resolvedSlotCount);
+    burstParticleCountSV.set(resolvedBurstParticleCount);
+    particleBurstDurationSecSV.set(resolvedParticleBurstDurationSec);
+    dragSV.set(resolvedDrag);
+    sizeMinSV.set(resolvedSizeMin);
+    sizeMaxSV.set(resolvedSizeMax);
+    spreadAngleSV.set(resolvedSpreadAngle);
+    jitterXSV.set(resolvedJitterX);
+    jitterYSV.set(resolvedJitterY);
+    speedMinSV.set(resolvedSpeedMin);
+    speedMaxSV.set(resolvedSpeedMax);
+  }, [
+    degenOff,
+    onShake,
+    resolvedScale,
+    resolvedDown,
+    resolvedShake,
+    resolvedShakeIntensity,
+    resolvedShakeDurationSec,
+    resolvedSlotCount,
+    resolvedBurstParticleCount,
+    resolvedParticleBurstDurationSec,
+    resolvedDrag,
+    resolvedSizeMin,
+    resolvedSizeMax,
+    resolvedSpreadAngle,
+    resolvedJitterX,
+    resolvedJitterY,
+    resolvedSpeedMin,
+    resolvedSpeedMax,
+    // 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);
+
+      if (enabledSV.get() < 0.5) {
+        for (let i = 0; i < slots; i++) buf[i * DEGEN_STRIDE + 5] = 0;
+        prevM.set(momentumSV.get());
+        prevActiveCount.set(0);
+        shakeStart.set(0);
+        shakeX.set(0);
+        shakeY.set(0);
+        return;
+      }
+
+      const m = momentumSV.get();
+      const prev = prevM.get();
+
+      if (m !== prev && m !== "flat") {
+        const allowDown = downSV.get() > 0.5;
+        const ok = m === "up" || (m === "down" && allowDown);
+        if (ok) {
+          const cw = engine.canvasWidth.get();
+          const ch = engine.canvasHeight.get();
+          if (cw >= 1 && ch >= 1) {
+            const isUp = m === "up";
+            writeRot.set(
+              spawnBurst(buf, {
+                ox: dotX.get(),
+                oy: dotY.get(),
+                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: -1, // cycle the color list per particle
+              }),
+            );
+            if (shakeEnabledSV.get() > 0.5) {
+              shakeStart.set(now);
+              if (hasOnShakeListenerSV.get() > 0.5) {
+                runOnJS(emitShake)(isUp ? "up" : "down");
+              }
+            }
+          }
+        }
+      }
+      prevM.set(m);
+
+      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,
+      );
+
+      // Repaint only while particles are alive (or on the frame they all expire,
+      // so the overlay clears). When the field is empty the 4 derived values per
+      // slot stay subscribed to `packRevision` alone and freeze — no per-frame
+      // worklet churn for an idle particle system.
+      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/useLiveChartHasData.ts

@@ -0,0 +1,31 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { CandlePoint, LiveChartPoint } from "../types";
+
+/**
+ * Data presence for {@link LiveChart}: line mode needs ≥2 points;
+ * candle mode needs ≥2 committed candles (`liveCandle` alone does not count).
+ *
+ * {@link useChartReveal} seeds its first-paint state off `hasData` directly (in a
+ * layout effect), so no JS-thread snapshot is read during render here.
+ */
+export function useLiveChartHasData({
+  isCandle,
+  data,
+  candles,
+}: {
+  isCandle: boolean;
+  data: SharedValue<LiveChartPoint[]>;
+  candles: SharedValue<CandlePoint[]> | undefined;
+}): {
+  hasData: SharedValue<boolean>;
+} {
+  const hasData = useDerivedValue(() => {
+    "worklet";
+    if (isCandle) {
+      return (candles?.value.length ?? 0) >= 2;
+    }
+    return data.value.length >= 2;
+  });
+
+  return { hasData };
+}