react-native-livechart 1.0.0

package/src/core/useLiveChartEngine.ts

@@ -0,0 +1,207 @@
+/**
+ * UI-thread chart engine: time window, Y-range smoothing, and tick cadence pursue
+ * the same “live chart” feel as liveline’s `requestAnimationFrame` loop; mechanism
+ * here is Reanimated frame callbacks and SharedValues, not DOM canvas.
+ *
+ * @see https://github.com/benjitaylor/liveline
+ */
+import { useState } from "react";
+import {
+  useDerivedValue,
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { MS_PER_FRAME_60FPS } from "../constants";
+import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
+import { tickLiveChartEngineFrame } from "./liveChartEngineTick";
+
+export interface EngineConfig {
+  data: SharedValue<LiveChartPoint[]>;
+  value: SharedValue<number>;
+  timeWindow: number;
+  smoothing: number;
+  exaggerate?: boolean;
+  referenceValue?: number;
+  referenceValues?: number[];
+  nonNegative?: boolean;
+  maxValue?: number;
+  nowOverride?: number;
+  windowBuffer?: number;
+  paused?: boolean;
+  mode?: "line" | "candle";
+  candles?: SharedValue<CandlePoint[]>;
+  liveCandle?: SharedValue<CandlePoint | null>;
+}
+
+/** Canvas, time window, and Y-range — shared by single- and multi-series engines. */
+export interface ChartEngineLayout {
+  displayMin: SharedValue<number>;
+  displayMax: SharedValue<number>;
+  displayWindow: SharedValue<number>;
+  canvasWidth: SharedValue<number>;
+  canvasHeight: SharedValue<number>;
+  timestamp: SharedValue<number>;
+}
+
+export interface SingleEngineState extends ChartEngineLayout {
+  data: SharedValue<LiveChartPoint[]>;
+  value: SharedValue<number>;
+  displayValue: SharedValue<number>;
+}
+
+export interface MultiEngineState extends ChartEngineLayout {
+  data: SharedValue<LiveChartPoint[]>;
+  value: SharedValue<number>;
+  displayValue: SharedValue<number>;
+  series: SharedValue<SeriesConfig[]>;
+  displaySeriesValues: SharedValue<number[]>;
+  seriesOpacities: SharedValue<number[]>;
+}
+
+export type EngineState = SingleEngineState | MultiEngineState;
+
+/** Canvas, range, and animated live value (badge / value line). */
+export type ChartEngineWithLiveValue = ChartEngineLayout & {
+  displayValue: SharedValue<number>;
+};
+
+export interface EngineFrameRefs {
+  data: SharedValue<LiveChartPoint[]>;
+  value: SharedValue<number>;
+  displayValue: SharedValue<number>;
+  displayMin: SharedValue<number>;
+  displayMax: SharedValue<number>;
+  displayWindow: SharedValue<number>;
+  canvasWidth: SharedValue<number>;
+  canvasHeight: SharedValue<number>;
+  timestamp: SharedValue<number>;
+  timeWindow: SharedValue<number>;
+  smoothing: SharedValue<number>;
+  exaggerateSV: SharedValue<boolean>;
+  referenceValue: SharedValue<number | undefined>;
+  referenceValues?: SharedValue<number[] | undefined>;
+  nonNegativeSV?: SharedValue<boolean>;
+  maxValueSV?: SharedValue<number | undefined>;
+  nowOverrideSV?: SharedValue<number | undefined>;
+  windowBufferSV?: SharedValue<number>;
+  pausedSV: SharedValue<boolean>;
+  modeSV: SharedValue<"line" | "candle">;
+  candles?: SharedValue<CandlePoint[]>;
+  liveCandle?: SharedValue<CandlePoint | null>;
+}
+
+/**
+ * Shared between the `useFrameCallback` worklet and unit tests.
+ * Mutates shared values from a snapshot tick (`tickLiveChartEngineFrame`).
+ */
+export function applyLiveChartEngineFrame(
+  frameInfo: { timeSincePreviousFrame?: number | null },
+  sv: EngineFrameRefs,
+): void {
+  "worklet";
+  const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
+  const state = {
+    displayValue: sv.displayValue.value,
+    displayMin: sv.displayMin.value,
+    displayMax: sv.displayMax.value,
+    displayWindow: sv.displayWindow.value,
+    timestamp: sv.timestamp.value,
+  };
+  tickLiveChartEngineFrame(state, {
+    dt,
+    canvasWidth: sv.canvasWidth.value,
+    canvasHeight: sv.canvasHeight.value,
+    timeWindow: sv.timeWindow.value,
+    smoothing: sv.smoothing.value,
+    exaggerate: sv.exaggerateSV.value,
+    referenceValue: sv.referenceValue.value,
+    referenceValues: sv.referenceValues?.value,
+    nonNegative: sv.nonNegativeSV?.value ?? false,
+    maxValue: sv.maxValueSV?.value,
+    nowOverride: sv.nowOverrideSV?.value,
+    windowBuffer: sv.windowBufferSV?.value ?? 0,
+    targetValue: sv.value.value,
+    points: sv.data.value,
+    nowSeconds: Date.now() / 1000,
+    paused: sv.pausedSV.value,
+    mode: sv.modeSV.value,
+    candles: sv.candles?.value,
+    liveCandle: sv.liveCandle?.value,
+  });
+  sv.displayValue.value = state.displayValue;
+  sv.displayMin.value = state.displayMin;
+  sv.displayMax.value = state.displayMax;
+  sv.displayWindow.value = state.displayWindow;
+  sv.timestamp.value = state.timestamp;
+}
+
+export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
+  // Low-frequency config → UI thread via useDerivedValue
+  const timeWindow = useDerivedValue(() => config.timeWindow);
+  const smoothing = useDerivedValue(() => config.smoothing);
+  const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
+  const referenceValue = useDerivedValue(() => config.referenceValue);
+  const referenceValues = useDerivedValue(() => config.referenceValues);
+  const nonNegativeSV = useDerivedValue(() => config.nonNegative ?? false);
+  const maxValueSV = useDerivedValue(() => config.maxValue);
+  const nowOverrideSV = useDerivedValue(() => config.nowOverride);
+  const windowBufferSV = useDerivedValue(() => config.windowBuffer ?? 0);
+  const pausedSV = useDerivedValue(() => config.paused ?? false);
+  const modeSV = useDerivedValue(() => config.mode ?? "line");
+
+  // Animation state (mutated on UI thread each frame)
+  const displayValue = useSharedValue(0);
+  const displayMin = useSharedValue(0);
+  const displayMax = useSharedValue(1);
+  const displayWindow = useSharedValue(config.timeWindow);
+  const canvasWidth = useSharedValue(0);
+  const canvasHeight = useSharedValue(0);
+  // Seed once; overwritten by the frame callback on the first tick.
+  const [initialTimestamp] = useState(() => Date.now() / 1000);
+  const timestamp = useSharedValue(initialTimestamp);
+
+  // High-frequency data reads directly from the caller's shared values —
+  // no useDerivedValue bridging, no closure serialization per tick.
+  const { data, value, candles, liveCandle } = config;
+
+  useFrameCallback((frameInfo) => {
+    "worklet";
+    applyLiveChartEngineFrame(frameInfo, {
+      data,
+      value,
+      displayValue,
+      displayMin,
+      displayMax,
+      displayWindow,
+      timestamp,
+      canvasWidth,
+      canvasHeight,
+      timeWindow,
+      smoothing,
+      exaggerateSV,
+      referenceValue,
+      referenceValues,
+      nonNegativeSV,
+      maxValueSV,
+      nowOverrideSV,
+      windowBufferSV,
+      pausedSV,
+      modeSV,
+      candles,
+      liveCandle,
+    });
+  });
+
+  return {
+    data,
+    value,
+    displayValue,
+    displayMin,
+    displayMax,
+    displayWindow,
+    canvasWidth,
+    canvasHeight,
+    timestamp,
+  };
+}

package/src/core/useLiveChartSeriesEngine.ts

@@ -0,0 +1,215 @@
+import { useRef, useState } from "react";
+import {
+  useDerivedValue,
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { MS_PER_FRAME_60FPS } from "../constants";
+import type { LiveChartPoint, SeriesConfig } from "../types";
+import { tickLiveChartSeriesEngineFrame } from "./liveChartSeriesEngineTick";
+import type { MultiEngineState } from "./useLiveChartEngine";
+
+export interface MultiSeriesEngineConfig {
+  series: SharedValue<SeriesConfig[]>;
+  timeWindow: number;
+  smoothing: number;
+  exaggerate?: boolean;
+  referenceValue?: number;
+  referenceValues?: number[];
+  nonNegative?: boolean;
+  maxValue?: number;
+  nowOverride?: number;
+  windowBuffer?: number;
+  paused?: boolean;
+}
+
+export interface MultiEngineFrameRefs {
+  series: SharedValue<SeriesConfig[]>;
+  displaySeriesValues: SharedValue<number[]>;
+  seriesOpacities: SharedValue<number[]>;
+  displayMin: SharedValue<number>;
+  displayMax: SharedValue<number>;
+  displayWindow: SharedValue<number>;
+  timestamp: SharedValue<number>;
+  canvasWidth: SharedValue<number>;
+  canvasHeight: SharedValue<number>;
+  timeWindow: SharedValue<number>;
+  smoothing: SharedValue<number>;
+  exaggerateSV: SharedValue<boolean>;
+  referenceValue: SharedValue<number | undefined>;
+  referenceValues?: SharedValue<number[] | undefined>;
+  nonNegativeSV?: SharedValue<boolean>;
+  maxValueSV?: SharedValue<number | undefined>;
+  nowOverrideSV?: SharedValue<number | undefined>;
+  windowBufferSV?: SharedValue<number>;
+  pausedSV: SharedValue<boolean>;
+}
+
+/**
+ * Reusable per-frame scratch for {@link applyLiveChartSeriesEngineFrame}. The two
+ * output arrays ping-pong so the assigned reference still changes each frame
+ * (Reanimated propagates on reference change) without allocating a fresh array
+ * per frame. Create one per engine (the React Compiler keeps it stable).
+ */
+export interface MultiSeriesEngineScratch {
+  dvA: number[];
+  dvB: number[];
+  opA: number[];
+  opB: number[];
+  tick: boolean;
+}
+
+/**
+ * One frame of the multi-series chart engine.
+ * Mirrors `applyLiveChartEngineFrame` but iterates over each series
+ * to lerp per-series display values and opacities. Extracted as a
+ * pure function so it can be called from both `useFrameCallback` and tests.
+ *
+ * Pass `scratch` to reuse the output arrays across frames instead of allocating
+ * two via `.slice()` each frame; omit it (tests) to fall back to allocation.
+ */
+export function applyLiveChartSeriesEngineFrame(
+  frameInfo: { timeSincePreviousFrame?: number | null },
+  sv: MultiEngineFrameRefs,
+  scratch?: MultiSeriesEngineScratch,
+): void {
+  "worklet";
+  const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
+  const seriesSnap = sv.series.value;
+  const curDv = sv.displaySeriesValues.value;
+  const curOp = sv.seriesOpacities.value;
+  let displayValues: number[];
+  let opacities: number[];
+  if (scratch) {
+    scratch.tick = !scratch.tick;
+    displayValues = scratch.tick ? scratch.dvA : scratch.dvB;
+    opacities = scratch.tick ? scratch.opA : scratch.opB;
+    displayValues.length = curDv.length;
+    for (let i = 0; i < curDv.length; i++) displayValues[i] = curDv[i];
+    opacities.length = curOp.length;
+    for (let i = 0; i < curOp.length; i++) opacities[i] = curOp[i];
+  } else {
+    displayValues = curDv.slice();
+    opacities = curOp.slice();
+  }
+  const state = {
+    displayMin: sv.displayMin.value,
+    displayMax: sv.displayMax.value,
+    displayWindow: sv.displayWindow.value,
+    timestamp: sv.timestamp.value,
+    displayValues,
+    opacities,
+  };
+  tickLiveChartSeriesEngineFrame(state, {
+    dt,
+    canvasWidth: sv.canvasWidth.value,
+    canvasHeight: sv.canvasHeight.value,
+    timeWindow: sv.timeWindow.value,
+    smoothing: sv.smoothing.value,
+    exaggerate: sv.exaggerateSV.value,
+    referenceValue: sv.referenceValue.value,
+    referenceValues: sv.referenceValues?.value,
+    nonNegative: sv.nonNegativeSV?.value ?? false,
+    maxValue: sv.maxValueSV?.value,
+    nowOverride: sv.nowOverrideSV?.value,
+    windowBuffer: sv.windowBufferSV?.value ?? 0,
+    series: seriesSnap,
+    nowSeconds: Date.now() / 1000,
+    paused: sv.pausedSV.value,
+  });
+  sv.displayMin.value = state.displayMin;
+  sv.displayMax.value = state.displayMax;
+  sv.displayWindow.value = state.displayWindow;
+  sv.timestamp.value = state.timestamp;
+  sv.displaySeriesValues.value = state.displayValues;
+  sv.seriesOpacities.value = state.opacities;
+}
+
+/**
+ * UI-thread engine for multi-series charts. Dummies `data` / `value` / `displayValue`
+ * mirror single-series fields for hooks that still read them.
+ */
+export function useLiveChartSeriesEngine(
+  config: MultiSeriesEngineConfig,
+): MultiEngineState {
+  const timeWindow = useDerivedValue(() => config.timeWindow);
+  const smoothing = useDerivedValue(() => config.smoothing);
+  const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
+  const referenceValue = useDerivedValue(() => config.referenceValue);
+  const referenceValues = useDerivedValue(() => config.referenceValues);
+  const nonNegativeSV = useDerivedValue(() => config.nonNegative ?? false);
+  const maxValueSV = useDerivedValue(() => config.maxValue);
+  const nowOverrideSV = useDerivedValue(() => config.nowOverride);
+  const windowBufferSV = useDerivedValue(() => config.windowBuffer ?? 0);
+  const pausedSV = useDerivedValue(() => config.paused ?? false);
+
+  const displayMin = useSharedValue(0);
+  const displayMax = useSharedValue(1);
+  const displayWindow = useSharedValue(config.timeWindow);
+  const canvasWidth = useSharedValue(0);
+  const canvasHeight = useSharedValue(0);
+  // Seed once; overwritten by the frame callback on the first tick.
+  const [initialTimestamp] = useState(() => Date.now() / 1000);
+  const timestamp = useSharedValue(initialTimestamp);
+
+  const displaySeriesValues = useSharedValue<number[]>([]);
+  const seriesOpacities = useSharedValue<number[]>([]);
+
+  const data = useSharedValue<LiveChartPoint[]>([]);
+  const value = useSharedValue(0);
+  const displayValue = useSharedValue(0);
+
+  const { series } = config;
+
+  // Reused per-frame output buffers (ping-ponged) — see applyLiveChartSeriesEngineFrame.
+  const scratchRef = useRef<MultiSeriesEngineScratch | null>(null);
+  if (scratchRef.current === null) {
+    scratchRef.current = { dvA: [], dvB: [], opA: [], opB: [], tick: false };
+  }
+
+  useFrameCallback((frameInfo) => {
+    "worklet";
+    const scratch = scratchRef.current!;
+    applyLiveChartSeriesEngineFrame(
+      frameInfo,
+      {
+        series,
+        displaySeriesValues,
+        seriesOpacities,
+        displayMin,
+        displayMax,
+        displayWindow,
+        timestamp,
+        canvasWidth,
+        canvasHeight,
+        timeWindow,
+        smoothing,
+        exaggerateSV,
+        referenceValue,
+        referenceValues,
+        nonNegativeSV,
+        maxValueSV,
+        nowOverrideSV,
+        windowBufferSV,
+        pausedSV,
+      },
+      scratch,
+    );
+  });
+
+  return {
+    data,
+    value,
+    displayValue,
+    displayMin,
+    displayMax,
+    displayWindow,
+    canvasWidth,
+    canvasHeight,
+    timestamp,
+    series,
+    displaySeriesValues,
+    seriesOpacities,
+  };
+}

package/src/draw/candle.ts

@@ -0,0 +1,210 @@
+import type { CandlePoint } from "../types";
+import type { ChartPadding } from "./line";
+
+export interface CandleRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  up: boolean;
+}
+
+export interface CandleWick {
+  x: number;
+  y1: number;
+  y2: number;
+  up: boolean;
+}
+
+export interface CandleGeometry {
+  bodies: CandleRect[];
+  wicks: CandleWick[];
+}
+
+const MIN_BODY_PX = 1;
+const MAX_BODY_PX = 40;
+
+function candleTimeToX(
+  t: number,
+  padLeft: number,
+  winStart: number,
+  windowSecs: number,
+  chartW: number,
+): number {
+  "worklet";
+  return padLeft + ((t - winStart) / windowSecs) * chartW;
+}
+
+function candleValueToY(
+  v: number,
+  padTop: number,
+  displayMax: number,
+  valRange: number,
+  chartH: number,
+): number {
+  "worklet";
+  return padTop + ((displayMax - v) / valRange) * chartH;
+}
+
+/** One candle → bodies/wicks; top-level worklet (no nested closures). */
+function appendCandleShapes(
+  c: CandlePoint,
+  winStart: number,
+  winEnd: number,
+  windowSecs: number,
+  chartW: number,
+  chartH: number,
+  chartLeft: number,
+  chartRight: number,
+  padTop: number,
+  padLeft: number,
+  displayMax: number,
+  valRange: number,
+  candleWidthSecs: number,
+  bodyW: number,
+  bodies: CandleRect[],
+  wicks: CandleWick[],
+): void {
+  "worklet";
+  if (c.time + candleWidthSecs < winStart || c.time > winEnd) return;
+
+  const up = c.close >= c.open;
+  const xCenter = candleTimeToX(
+    c.time + candleWidthSecs / 2,
+    padLeft,
+    winStart,
+    windowSecs,
+    chartW,
+  );
+
+  if (xCenter < chartLeft - bodyW / 2 || xCenter > chartRight + bodyW / 2)
+    return;
+
+  const bodyTop = candleValueToY(
+    up ? c.close : c.open,
+    padTop,
+    displayMax,
+    valRange,
+    chartH,
+  );
+  const bodyBot = candleValueToY(
+    up ? c.open : c.close,
+    padTop,
+    displayMax,
+    valRange,
+    chartH,
+  );
+  const bodyH = Math.max(MIN_BODY_PX, bodyBot - bodyTop);
+
+  let bx = xCenter - bodyW / 2;
+  let bw = bodyW;
+  if (bx < chartLeft) {
+    bw -= chartLeft - bx;
+    bx = chartLeft;
+  }
+  /* istanbul ignore next -- right-edge clip rare in tests */
+  if (bx + bw > chartRight) {
+    bw = chartRight - bx;
+  }
+  /* istanbul ignore next -- clipped to zero width */
+  if (bw <= 0) return;
+
+  bodies.push({ x: bx, y: bodyTop, w: bw, h: bodyH, up });
+
+  const wickX = Math.max(chartLeft, Math.min(xCenter, chartRight));
+  const wickTop = candleValueToY(c.high, padTop, displayMax, valRange, chartH);
+  const wickBot = candleValueToY(c.low, padTop, displayMax, valRange, chartH);
+  wicks.push({ x: wickX, y1: wickTop, y2: wickBot, up });
+}
+
+/**
+ * Build screen-space candle bodies and wicks for a visible window.
+ * Pure worklet — no Skia imports, consumed by useCandlePaths.
+ */
+export function buildCandleGeometry(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  padding: ChartPadding,
+  canvasW: number,
+  canvasH: number,
+  winStart: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  candleWidthSecs: number,
+): CandleGeometry {
+  "worklet";
+  const chartW = canvasW - padding.left - padding.right;
+  const chartH = canvasH - padding.top - padding.bottom;
+  const valRange = displayMax - displayMin;
+
+  if (valRange === 0 || chartW <= 0 || chartH <= 0)
+    return { bodies: [], wicks: [] };
+
+  const slotPx = (candleWidthSecs / windowSecs) * chartW;
+  const bodyW = Math.max(1, Math.min(slotPx * 0.8, slotPx - 2, MAX_BODY_PX));
+
+  const bodies: CandleRect[] = [];
+  const wicks: CandleWick[] = [];
+
+  const winEnd = winStart + windowSecs;
+  const chartLeft = padding.left;
+  const chartRight = canvasW - padding.right;
+  const padTop = padding.top;
+  const padLeft = padding.left;
+
+  // Binary search for first candle overlapping the window
+  let lo = 0;
+  let hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time + candleWidthSecs < winStart) lo = mid + 1;
+    else hi = mid;
+  }
+
+  for (let i = lo; i < candles.length; i++) {
+    /* istanbul ignore next -- past visible window */
+    if (candles[i].time > winEnd) break;
+    appendCandleShapes(
+      candles[i],
+      winStart,
+      winEnd,
+      windowSecs,
+      chartW,
+      chartH,
+      chartLeft,
+      chartRight,
+      padTop,
+      padLeft,
+      displayMax,
+      valRange,
+      candleWidthSecs,
+      bodyW,
+      bodies,
+      wicks,
+    );
+  }
+
+  if (liveCandle) {
+    appendCandleShapes(
+      liveCandle,
+      winStart,
+      winEnd,
+      windowSecs,
+      chartW,
+      chartH,
+      chartLeft,
+      chartRight,
+      padTop,
+      padLeft,
+      displayMax,
+      valRange,
+      candleWidthSecs,
+      bodyW,
+      bodies,
+      wicks,
+    );
+  }
+
+  return { bodies, wicks };
+}