react-native-livechart 1.0.0

package/src/hooks/useReferenceLine.ts

@@ -0,0 +1,212 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { SkFont } from "@shopify/react-native-skia";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import {
+  classifyReferenceEdge,
+  referenceLineForm,
+} from "../math/referenceLines";
+import type { ReferenceLine } from "../types";
+
+/** Screen-space geometry for one reference line / band, recomputed each frame. */
+export interface ReferenceLineLayout {
+  visible: boolean;
+  /** Line y, or band top-edge y. */
+  y: number;
+  /** Band bottom-edge y (value/time band); equals `y` for a plain line. */
+  yBottom: number;
+  /** Left x extent. */
+  x1: number;
+  /** Right x extent. */
+  x2: number;
+  /** Resolved label text (with appended value when `showValue`). */
+  label: string;
+  labelX: number;
+  labelY: number;
+  /** True when a Form-A line is off-screen and its off-axis badge is showing. */
+  offAxis: boolean;
+  /** Off-axis chevron points up (target above range) vs down (below). */
+  chevronUp: boolean;
+}
+
+const INVISIBLE: ReferenceLineLayout = {
+  visible: false,
+  y: -1,
+  yBottom: -1,
+  x1: 0,
+  x2: 0,
+  label: "",
+  labelX: 0,
+  labelY: -1,
+  offAxis: false,
+  chevronUp: false,
+};
+
+/** Off-axis indicator inset from the nearest plot edge, in px. */
+const OFF_AXIS_EDGE_INSET = 12;
+
+/**
+ * Derives screen-space layout for a single reference line or band. Supports all
+ * three `ReferenceLine` forms (horizontal line, horizontal value band, vertical
+ * time band) plus the off-axis badge for an off-screen Form-A value.
+ */
+export function useReferenceLine(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  line: ReferenceLine | undefined,
+  formatValue: (v: number) => string,
+  font: SkFont,
+): SharedValue<ReferenceLineLayout> {
+  const form = line ? referenceLineForm(line) : "none";
+
+  return useDerivedValue<ReferenceLineLayout>(() => {
+    if (!line || form === "none") return INVISIBLE;
+
+    const w = engine.canvasWidth.value;
+    const h = engine.canvasHeight.value;
+    if (w === 0 || h === 0) return INVISIBLE;
+
+    const chartTop = padding.top;
+    const chartBottom = h - padding.bottom;
+    const chartH = chartBottom - chartTop;
+    const x1 = padding.left;
+    const x2 = w - padding.right;
+
+    const fm = font.getMetrics();
+    const baselineOffset = (fm.ascent + fm.descent) / 2;
+
+    // ── Form C — vertical time band (independent of the value range) ─────────
+    if (form === "time-band") {
+      if (line.from === undefined || line.to === undefined) return INVISIBLE;
+      const now = engine.timestamp.value;
+      const win = engine.displayWindow.value;
+      const winStart = now - win;
+      const chartW = x2 - x1;
+      if (win <= 0 || chartW <= 0) return INVISIBLE;
+
+      let bx1 = x1 + ((line.from - winStart) / win) * chartW;
+      let bx2 = x1 + ((line.to - winStart) / win) * chartW;
+      if (bx2 < bx1) {
+        const t = bx1;
+        bx1 = bx2;
+        bx2 = t;
+      }
+      if (bx2 < x1 || bx1 > x2) return INVISIBLE;
+      if (bx1 < x1) bx1 = x1;
+      if (bx2 > x2) bx2 = x2;
+
+      const label = line.label ?? "";
+      const labelX =
+        line.labelPosition === "right"
+          ? bx2 - 4 - measureFontTextWidth(font, label)
+          : bx1 + 4;
+      return {
+        visible: true,
+        y: chartTop,
+        yBottom: chartBottom,
+        x1: bx1,
+        x2: bx2,
+        label,
+        labelX,
+        labelY: chartTop - fm.ascent + 2,
+        offAxis: false,
+        chevronUp: false,
+      };
+    }
+
+    // Forms A / B project values onto y, so they need a non-degenerate range.
+    const dMin = engine.displayMin.value;
+    const dMax = engine.displayMax.value;
+    const valRange = dMax - dMin;
+    if (valRange <= 0) return INVISIBLE;
+    const toY = (v: number) => chartTop + ((dMax - v) / valRange) * chartH;
+
+    // ── Form B — horizontal value band ───────────────────────────────────────
+    if (form === "value-band") {
+      if (line.valueFrom === undefined || line.valueTo === undefined) {
+        return INVISIBLE;
+      }
+      let yTop = toY(line.valueTo);
+      let yBot = toY(line.valueFrom);
+      if (yBot < yTop) {
+        const t = yTop;
+        yTop = yBot;
+        yBot = t;
+      }
+      if (yBot < chartTop || yTop > chartBottom) return INVISIBLE;
+      if (yTop < chartTop) yTop = chartTop;
+      if (yBot > chartBottom) yBot = chartBottom;
+
+      const label = line.label ?? "";
+      const labelX =
+        line.labelPosition === "right"
+          ? x2 - 4 - measureFontTextWidth(font, label)
+          : x1 + 4;
+      return {
+        visible: true,
+        y: yTop,
+        yBottom: yBot,
+        x1,
+        x2,
+        label,
+        labelX,
+        labelY: yTop - fm.ascent + 2,
+        offAxis: false,
+        chevronUp: false,
+      };
+    }
+
+    // ── Form A — horizontal line (with optional off-axis badge) ──────────────
+    if (line.value === undefined) return INVISIBLE;
+    const v = line.value;
+    const edge = classifyReferenceEdge(v, dMin, dMax);
+
+    if (edge !== "in") {
+      if (!line.offAxisBadge) return INVISIBLE; // legacy: cull off-screen line
+      const above = edge === "above";
+      const clampedY = above
+        ? chartTop + OFF_AXIS_EDGE_INSET
+        : chartBottom - OFF_AXIS_EDGE_INSET;
+      const word = line.offAxisBadgeLabel ?? line.label;
+      const text = word ? `${word}: ${formatValue(v)}` : formatValue(v);
+      return {
+        visible: true,
+        y: clampedY,
+        yBottom: clampedY,
+        x1,
+        x2,
+        label: text,
+        labelX: x1 + 16,
+        labelY: clampedY - baselineOffset,
+        offAxis: true,
+        chevronUp: above,
+      };
+    }
+
+    const y = toY(v);
+    let label = line.label ?? formatValue(v);
+    if (line.showValue && line.label) label = `${line.label} ${formatValue(v)}`;
+
+    const pos = line.labelPosition ?? "right";
+    let labelX: number;
+    if (pos === "left") labelX = x1 + 4;
+    else if (pos === "center")
+      labelX = (x1 + x2) / 2 - measureFontTextWidth(font, label) / 2;
+    else labelX = x2 + 4; // "right" — legacy gutter position
+
+    return {
+      visible: true,
+      y,
+      yBottom: y,
+      x1,
+      x2,
+      label,
+      labelX,
+      labelY: y - baselineOffset,
+      offAxis: false,
+      chevronUp: false,
+    };
+  });
+}

package/src/hooks/useReverseMorphEngineInputs.ts

@@ -0,0 +1,154 @@
+import {
+  useAnimatedReaction,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
+
+const STASH_MORPH_EPS = 0.01;
+
+/**
+ * While `morphT` animates down after data clears, keep feeding the engine the
+ * last stashed line/candle snapshot.
+ */
+export function useSingleChartReverseMorphInputs({
+  isCandle,
+  data,
+  candles,
+  liveCandle,
+  hasData,
+  morphT,
+}: {
+  isCandle: boolean;
+  data: SharedValue<LiveChartPoint[]>;
+  candles: SharedValue<CandlePoint[]> | undefined;
+  liveCandle: SharedValue<CandlePoint | null> | undefined;
+  hasData: SharedValue<boolean>;
+  morphT: SharedValue<number>;
+}): {
+  lineEngineData: SharedValue<LiveChartPoint[]>;
+  candlesEngine: SharedValue<CandlePoint[]>;
+  liveEngine: SharedValue<CandlePoint | null>;
+} {
+  const lineStash = useSharedValue<LiveChartPoint[]>([]);
+  const candleStash = useSharedValue<CandlePoint[]>([]);
+  const lineEngineData = useSharedValue<LiveChartPoint[]>([]);
+  const candlesEngine = useSharedValue<CandlePoint[]>([]);
+  const liveEngine = useSharedValue<CandlePoint | null>(null);
+
+  useAnimatedReaction(
+    () => ({
+      candle: isCandle,
+      has: hasData.get(),
+      m: morphT.get(),
+      d: data.get(),
+      cLen: candles?.get().length ?? 0,
+      c: candles?.get(),
+      lc: liveCandle?.get() ?? null,
+    }),
+    (curr) => {
+      "worklet";
+      if (!curr.candle) {
+        if (curr.has && curr.d.length >= 2) {
+          lineStash.set(curr.d.slice());
+          lineEngineData.set(curr.d);
+        } else if (
+          !curr.has &&
+          curr.m > STASH_MORPH_EPS &&
+          lineStash.get().length >= 2
+        ) {
+          lineEngineData.set(lineStash.get());
+        } else {
+          lineEngineData.set(curr.d);
+        }
+        return;
+      }
+
+      const cArr = curr.c;
+      if (curr.has && curr.cLen >= 2 && cArr) {
+        candleStash.set(cArr.slice());
+        candlesEngine.set(cArr);
+        liveEngine.set(curr.lc);
+      } else if (
+        !curr.has &&
+        curr.m > STASH_MORPH_EPS &&
+        candleStash.get().length >= 2
+      ) {
+        candlesEngine.set(candleStash.get());
+        liveEngine.set(null);
+      } else {
+        candlesEngine.set(cArr ?? []);
+        liveEngine.set(curr.lc);
+      }
+    },
+    [isCandle, data, candles, liveCandle, hasData, morphT],
+  );
+
+  return { lineEngineData, candlesEngine, liveEngine };
+}
+
+function snapshotSeriesWorklet(s: SeriesConfig[]): SeriesConfig[] {
+  "worklet";
+  const out: SeriesConfig[] = [];
+  for (let i = 0; i < s.length; i++) {
+    const x = s[i];
+    out.push({ ...x, data: x.data.slice() });
+  }
+  return out;
+}
+
+export function useMultiSeriesReverseMorphInputs({
+  series,
+  hasData,
+  morphT,
+}: {
+  series: SharedValue<SeriesConfig[]>;
+  hasData: SharedValue<boolean>;
+  morphT: SharedValue<number>;
+}): SharedValue<SeriesConfig[]> {
+  const seriesStash = useSharedValue<SeriesConfig[]>([]);
+  const effectiveSeries = useSharedValue<SeriesConfig[]>([]);
+
+  useAnimatedReaction(
+    () => ({
+      has: hasData.get(),
+      m: morphT.get(),
+      live: series.get(),
+    }),
+    (curr) => {
+      "worklet";
+      const live = curr.live;
+
+      let anyReady = false;
+      for (let i = 0; i < live.length; i++) {
+        if (live[i].data.length >= 2) {
+          anyReady = true;
+          break;
+        }
+      }
+
+      if (curr.has && anyReady) {
+        seriesStash.set(snapshotSeriesWorklet(live));
+        effectiveSeries.set(live);
+      } else {
+        let stashReady = false;
+        const stash = seriesStash.get();
+        for (let i = 0; i < stash.length; i++) {
+          if (stash[i].data.length >= 2) {
+            stashReady = true;
+            break;
+          }
+        }
+
+        if (!curr.has && curr.m > STASH_MORPH_EPS && stashReady) {
+          effectiveSeries.set(seriesStash.get());
+        } else {
+          effectiveSeries.set(live);
+        }
+      }
+    },
+    [series, hasData, morphT],
+  );
+
+  return effectiveSeries;
+}

package/src/hooks/useTradeStream.ts

@@ -0,0 +1,64 @@
+import {
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { MS_PER_FRAME_60FPS } from "../constants";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import {
+  createTradeStreamState,
+  projectLabels,
+  tickTradeStream,
+  type TradeMarker,
+  type TradeStreamState,
+} from "../draw/trade";
+import type { TradeEvent } from "../types";
+
+/**
+ * Process live trade events into projected on-chart markers.
+ * Runs a frame callback that ticks the trade-stream state and produces
+ * `TradeMarker[]` positioned within the chart area.
+ */
+export function useTradeStream(
+  engine: SingleEngineState,
+  tradeStream: SharedValue<TradeEvent[]>,
+  padding: ChartPadding,
+  active: boolean,
+): SharedValue<TradeMarker[]> {
+  const markers = useSharedValue<TradeMarker[]>([]);
+  const state = useSharedValue<TradeStreamState>(createTradeStreamState());
+
+  useFrameCallback(
+    /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ (
+      frameInfo,
+    ) => {
+      "worklet";
+      if (!active) {
+        if (markers.get().length > 0) markers.set([]);
+        return;
+      }
+
+      const dt = frameInfo.timeSincePreviousFrame ?? MS_PER_FRAME_60FPS;
+      const h = engine.canvasHeight.get();
+      const chartTop = padding.top;
+      const LABEL_CLEARANCE = 6;
+      const chartBottom = h - padding.bottom - LABEL_CLEARANCE;
+
+      if (chartBottom <= chartTop) return;
+
+      const s = state.get();
+      tickTradeStream(s, tradeStream.get(), dt, chartTop, chartBottom);
+
+      // Idle tape: nothing to draw and nothing already drawn. Skip the projection
+      // and SharedValue write so the TapeLabel derived values don't re-run and we
+      // don't allocate a fresh marker array every frame.
+      if (s.labels.length === 0 && markers.get().length === 0) return;
+
+      const chartH = chartBottom - chartTop;
+      markers.set(projectLabels(s, chartTop, chartH));
+    },
+  );
+
+  return markers;
+}

package/src/hooks/useXAxis.ts

@@ -0,0 +1,200 @@
+import { useEffect } from "react";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
+
+import type { SkFont } from "@shopify/react-native-skia";
+import { MS_PER_FRAME_60FPS } from "../constants";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import { niceTimeInterval } from "../math/intervals";
+import { lerp } from "../math/lerp";
+
+export interface XAxisEntry {
+  x: number;
+  label: string;
+  alpha: number;
+}
+
+const FADE = 0.08;
+
+/**
+ * Build a fresh label cache that re-formats every tick's `text` with
+ * `formatTime`, preserving each entry's `alpha`. The cache (see {@link useXAxis})
+ * formats each tick once for allocation reasons; this refreshes it when the
+ * `formatTime` prop changes. Returns a NEW object (and new entry objects) rather
+ * than mutating `cache` in place — the cache is also read inside the derived
+ * value worklet, and mutating an already-serialized object from the JS thread
+ * is unsafe under Reanimated's worklet model. Replacing the SharedValue with a
+ * fresh object propagates cleanly to the UI thread.
+ */
+export function reformatXAxisLabels(
+  cache: Record<number, { alpha: number; text: string }>,
+  formatTime: (t: number) => string,
+): Record<number, { alpha: number; text: string }> {
+  const next: Record<number, { alpha: number; text: string }> = {};
+  for (const key in cache) {
+    next[key] = { alpha: cache[key].alpha, text: formatTime(Number(key) / 100) };
+  }
+  return next;
+}
+
+function xAxisKeyIsTarget(key: number, targetKeys: number[]): boolean {
+  "worklet";
+  for (let i = 0; i < targetKeys.length; i++) {
+    if (targetKeys[i] === key) return true;
+  }
+  return false;
+}
+
+/** Insertion sort — worklet-safe, no callback functions. */
+export function insertionSortByX(arr: XAxisEntry[]) {
+  "worklet";
+  for (let i = 1; i < arr.length; i++) {
+    const item = arr[i];
+    let j = i - 1;
+    while (j >= 0 && arr[j].x > item.x) {
+      /* istanbul ignore next -- worklet instrumentation under-counts swaps; insertionSort.test.ts covers behaviour */
+      arr[j + 1] = arr[j];
+      /* istanbul ignore next */
+      j--;
+    }
+    arr[j + 1] = item;
+  }
+}
+
+export function useXAxis(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  formatTime: (t: number) => string,
+  font: SkFont,
+) {
+  const labelAlphas = useSharedValue<
+    Record<number, { alpha: number; text: string }>
+  >({});
+
+  // A tick's key encodes its time, so its label is formatted once (below) and
+  // never re-formatted per frame — an allocation optimization. That assumes
+  // `formatTime` is stable; if the consumer swaps it at runtime, already-cached
+  // labels would otherwise keep their old text until they scroll off-window.
+  // Rebuild the cache with the new formatter (alphas preserved, so no fade
+  // restart) whenever the formatter identity changes.
+  useEffect(() => {
+    labelAlphas.set(reformatXAxisLabels(labelAlphas.get(), formatTime));
+  }, [formatTime, labelAlphas]);
+
+  const xAxisEntries = useDerivedValue(() => {
+    const w = engine.canvasWidth.get();
+    const h = engine.canvasHeight.get();
+    if (w === 0 || h === 0) return [] as XAxisEntry[];
+
+    const now = engine.timestamp.get();
+    const windowSecs = engine.displayWindow.get();
+    const winStart = now - windowSecs;
+
+    const chartLeft = padding.left;
+    const chartRight = w - padding.right;
+    const chartW = chartRight - chartLeft;
+    /* istanbul ignore next -- defensive; Reanimated test mock rarely executes this guard with non-zero w/h */
+    if (chartW <= 0) return [] as XAxisEntry[];
+
+    const fadeZone = 50;
+
+    // Pick interval from window duration
+    const targetPxPerSec = chartW / windowSecs;
+    let interval = niceTimeInterval(windowSecs);
+    while (interval * targetPxPerSec < 60 && interval < windowSecs) {
+      interval *= 2;
+    }
+
+    // Generate target label keys (plain array, no Set — worklet-safe)
+    const firstTime = Math.ceil((winStart - interval) / interval) * interval;
+    const targetKeys: number[] = [];
+    for (
+      let t = firstTime;
+      t <= now + interval && targetKeys.length < 30;
+      t += interval
+    ) {
+      targetKeys.push(Math.round(t * 100));
+    }
+
+    const alphas = labelAlphas.get();
+
+    // Create labels for new keys only. A key encodes its time, so the formatted
+    // text never changes — re-formatting (and re-allocating the entry) every
+    // frame just churns strings/objects for the GC.
+    for (let i = 0; i < targetKeys.length; i++) {
+      const key = targetKeys[i];
+      if (!alphas[key]) {
+        alphas[key] = { alpha: 0, text: formatTime(key / 100) };
+      }
+    }
+
+    // Update alphas
+    const allKeys = Object.keys(alphas);
+    for (let i = 0; i < allKeys.length; i++) {
+      const key = Number(allKeys[i]);
+      const label = alphas[key];
+      const x = chartLeft + ((key / 100 - winStart) / windowSecs) * chartW;
+
+      const fromLeft = x - chartLeft;
+      const fromRight = chartRight - x;
+      const fromEdge = Math.min(fromLeft, fromRight);
+      const edgeAlpha =
+        fromEdge >= fadeZone ? 1 : fromEdge <= 0 ? 0 : fromEdge / fadeZone;
+
+      const target = xAxisKeyIsTarget(key, targetKeys) ? edgeAlpha : 0;
+      let next = lerp(label.alpha, target, FADE, MS_PER_FRAME_60FPS);
+      if (Math.abs(next - target) < 0.02) next = target;
+
+      if (next < 0.01 && target === 0) {
+        delete alphas[key];
+      } else {
+        // Mutate in place — text is stable, so no need to reallocate the entry.
+        label.alpha = next;
+      }
+    }
+
+    labelAlphas.set(alphas);
+
+    // Collect visible labels
+    const raw: XAxisEntry[] = [];
+    const visibleKeys = Object.keys(alphas);
+    for (let i = 0; i < visibleKeys.length; i++) {
+      const key = Number(visibleKeys[i]);
+      const label = alphas[key];
+      /* istanbul ignore next -- alpha band skip is timing-sensitive under RTL + Reanimated mocks */
+      if (label.alpha < 0.02) continue;
+      const x = chartLeft + ((key / 100 - winStart) / windowSecs) * chartW;
+      /* istanbul ignore next -- horizontal clip; x stays in-band for consistent time keys */
+      if (x < chartLeft - 20 || x > chartRight) continue;
+      raw.push({ x, label: label.text, alpha: label.alpha });
+    }
+
+    // Worklet-safe sort (no callback)
+    insertionSortByX(raw);
+
+    // Overlap resolution: keep higher-alpha label when two collide
+    const drawn: XAxisEntry[] = [];
+    for (let i = 0; i < raw.length; i++) {
+      const entry = raw[i];
+      const textW = measureFontTextWidth(font, entry.label);
+      const left = entry.x - textW / 2;
+      if (drawn.length > 0) {
+        const prev = drawn[drawn.length - 1];
+        const prevW = measureFontTextWidth(font, prev.label);
+        const prevRight = prev.x + prevW / 2;
+        if (left < prevRight + 8) {
+          if (entry.alpha > prev.alpha) {
+            drawn[drawn.length - 1] = entry;
+          }
+          continue;
+        }
+      }
+      drawn.push(entry);
+    }
+
+    return drawn;
+  });
+
+  return { xAxisEntries, font };
+}

package/src/hooks/useYAxis.ts

@@ -0,0 +1,48 @@
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
+
+import type { SkFont } from "@shopify/react-native-skia";
+import { MS_PER_FRAME_60FPS } from "../constants";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { computeGridEntries } from "../draw/grid";
+import type { ChartPadding } from "../draw/line";
+
+/**
+ * Compute Y-axis grid entries (values + labels) with animated fade-in/out.
+ * Uses `computeGridEntries` to pick nice intervals and track label alpha for
+ * smooth transitions when the value range changes.
+ */
+export function useYAxis(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  formatValue: (v: number) => string,
+  font: SkFont,
+  minGap = 36,
+) {
+  const prevInterval = useSharedValue(0);
+  const labelAlphas = useSharedValue<Record<number, number>>({});
+
+  const yAxisEntries = useDerivedValue(() => {
+    const dt = MS_PER_FRAME_60FPS;
+
+    const alphas = labelAlphas.get();
+    const result = computeGridEntries(
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+      prevInterval.get(),
+      alphas,
+      formatValue,
+      dt,
+      minGap,
+    );
+
+    prevInterval.set(result.interval);
+    labelAlphas.set(alphas);
+
+    return result.entries;
+  });
+
+  return { yAxisEntries, font };
+}