react-native-vroom-chart 0.7.0 → 0.9.0

package/src/dataTransitions.ts

@@ -0,0 +1,148 @@
+// Mirror of packages/react/src/dataTransitions.ts — the platform packages don't
+// depend on each other, and @vroomchart/types carries types only.
+//
+// Classifies how a new `candles` prop relates to the previous one so the chart
+// can react appropriately: leave the viewport alone for streaming updates,
+// re-anchor the time window for a timeframe switch, or fully reset the view
+// for a different asset. Pure functions, no React — see useChartCore for the
+// orchestration.
+
+import type { Candle, VisibleRange } from '@vroomchart/types';
+
+/**
+ * How a new `candles` array relates to the one the chart already holds:
+ * `'initial'` is the first data, `'stream'` a live update to the same series,
+ * `'timeframe'` the same asset re-bucketed into a different interval, and
+ * `'reset'` a different series entirely.
+ */
+export type DataTransition = 'initial' | 'stream' | 'timeframe' | 'reset';
+
+// A step change below this ratio is treated as the same timeframe. Real steps
+// are exact integer ms; the tolerance only absorbs rounding/DST quirks (the
+// smallest real timeframe jump, 1m -> 2m, is 100% apart).
+const STEP_TOLERANCE = 0.01;
+
+// Same-asset check for a timeframe switch: both series end "now", so their
+// last closes must be close. No asset moves 25% between two consecutive prop
+// pushes; distinct assets within 25% of each other are what `seriesKey` is for.
+const MAX_SAME_ASSET_CLOSE_RATIO = 1.25;
+
+// A coarser bucketing can shift the final bar's open by up to one coarse bar;
+// allow that plus an in-flight bar when checking the two series end together.
+const MAX_END_DRIFT_STEPS = 3;
+
+// Streaming pushes may batch a few bars (e.g. a throttled background tab), but
+// a jump of more than this many steps means the data was re-fetched elsewhere.
+const MAX_STREAM_ADVANCE_STEPS = 5;
+
+/**
+ * The candle period in ms, inferred as the median of the first few intervals
+ * (robust to a single gap). Null when there are fewer than two candles.
+ */
+export function inferStepMs(candles: Candle[]): number | null {
+  if (candles.length < 2) return null;
+  const k = Math.min(candles.length - 1, 8);
+  const diffs: number[] = [];
+  for (let i = 0; i < k; i++) diffs.push(candles[i + 1].timeMs - candles[i].timeMs);
+  diffs.sort((a, b) => a - b);
+  const median = diffs[Math.floor(diffs.length / 2)];
+  return median > 0 ? median : null;
+}
+
+// Index of the candle whose timeMs exactly equals `t`, or -1. Binary search over
+// the ascending-by-time series, so it tolerates interior gaps (missing bars from
+// downtime / illiquid periods) — unlike a uniform-grid index computed from the
+// step, which assumes a hole-free grid.
+function indexByTime(candles: Candle[], t: number): number {
+  let lo = 0;
+  let hi = candles.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const v = candles[mid].timeMs;
+    if (v === t) return mid;
+    if (v < t) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+
+/**
+ * Classify a candles-prop change. `prev` is the previously rendered array
+ * (null on first render); `seriesKeyChanged` forces `reset` regardless of the
+ * data (the explicit escape hatch).
+ *
+ * Constraint: detection compares two immutable snapshots. An array mutated in
+ * place (same reference) never reaches this code — React props must change
+ * identity to re-render.
+ */
+export function classifyTransition(
+  prev: Candle[] | null,
+  next: Candle[],
+  seriesKeyChanged: boolean,
+): DataTransition {
+  if (!prev || prev.length === 0) return 'initial';
+  if (next.length === 0) return 'stream'; // nothing to reframe against
+  if (seriesKeyChanged) return 'reset';
+
+  const prevStep = inferStepMs(prev);
+  const nextStep = inferStepMs(next);
+  if (prevStep == null || nextStep == null) return 'reset'; // too little data to reason
+
+  const prevLast = prev[prev.length - 1];
+  const nextLast = next[next.length - 1];
+
+  if (Math.abs(nextStep - prevStep) <= prevStep * STEP_TOLERANCE) {
+    // Same step: streaming iff prev's last bar still appears in next (covers
+    // append, update-last, and rolling buffers that drop old bars from the
+    // front) and the series only advanced by a few bars. Locate that bar by
+    // timestamp, not by a step-derived index — real series have interior gaps
+    // (downtime / illiquid periods), so a uniform-grid index would miss it and
+    // misread a harmless in-place tick as a reset.
+    // Time alignment alone isn't enough: two assets on the same exchange share
+    // the bar grid, so the bar at the shared timestamp must also be (nearly) the
+    // same bar — update-last moves the close, but never by the same-asset ratio.
+    const idx = indexByTime(next, prevLast.timeMs);
+    const aligned = idx >= 0;
+    const sharedBarRatio =
+      aligned && next[idx].close > 0 && prevLast.close > 0
+        ? Math.max(next[idx].close / prevLast.close, prevLast.close / next[idx].close)
+        : Infinity;
+    const advanced =
+      nextLast.timeMs >= prevLast.timeMs &&
+      nextLast.timeMs - prevLast.timeMs <= MAX_STREAM_ADVANCE_STEPS * nextStep;
+    return sharedBarRatio <= MAX_SAME_ASSET_CLOSE_RATIO && advanced ? 'stream' : 'reset';
+  }
+
+  // Step changed: a timeframe switch iff it still looks like the same asset —
+  // last closes near each other and both series ending around the same time.
+  const closeRatio =
+    prevLast.close > 0 && nextLast.close > 0
+      ? Math.max(nextLast.close / prevLast.close, prevLast.close / nextLast.close)
+      : Infinity;
+  const prevEnd = prevLast.timeMs + prevStep;
+  const nextEnd = nextLast.timeMs + nextStep;
+  const endsTogether =
+    Math.abs(nextEnd - prevEnd) <= MAX_END_DRIFT_STEPS * Math.max(prevStep, nextStep);
+  return closeRatio <= MAX_SAME_ASSET_CLOSE_RATIO && endsTogether ? 'timeframe' : 'reset';
+}
+
+/**
+ * The visible window to apply after a timeframe switch so each candle keeps
+ * the exact pixel width it had before: the visible slot count is preserved and
+ * the right edge re-anchors on the newest candle (any future-gap overshoot is
+ * carried over in slots, clamped to the core's 3/4-window cap). The new start
+ * may precede the first candle — that gap is intentional, width wins.
+ */
+export function timeframeWindow(
+  oldWindow: VisibleRange,
+  oldStepMs: number,
+  oldLastMs: number,
+  newStepMs: number,
+  newLastMs: number,
+): VisibleRange {
+  const slots = (oldWindow.endMs - oldWindow.startMs) / oldStepMs;
+  const offsetRaw = (oldWindow.endMs - oldLastMs) / oldStepMs;
+  const offsetSlots = Math.min(Math.max(offsetRaw, 0), slots * 0.75);
+  const endMs = Math.round(newLastMs + offsetSlots * newStepMs);
+  return { startMs: Math.round(endMs - slots * newStepMs), endMs };
+}

package/src/index.ts

@@ -1,4 +1,10 @@
 export { VroomChart } from './VroomChart';
+export {
+  classifyTransition,
+  inferStepMs,
+  timeframeWindow,
+  type DataTransition,
+} from './dataTransitions';
 export type {
   VroomChartProps,
   Candle,

package/src/jsi.d.ts

@@ -27,6 +27,57 @@ export interface ChartHandle {
   setChartType(mode: number): void;
   /** Candle↔line morph blend: collapse folds candles to close, fade crossfades. */
   setMorph(collapse: number, fade: number): void;
+  /** The current visible time window. {startMs: 0, endMs: 0} = uninitialized. */
+  getVisibleRange(): { startMs: number; endMs: number };
+  /**
+   * Reset to the fresh-mount view: frame the most recent ~80 candles and
+   * re-enable continuous y auto-fit (the price range follows the visible
+   * candles until the next manual y gesture). Use when the data series is
+   * wholesale replaced — e.g. switching assets.
+   */
+  resetView(): void;
+  /**
+   * Re-enable continuous y auto-fit only; the time window is untouched. Use
+   * after repositioning the window for a same-asset data swap (e.g. a
+   * timeframe switch) so the price scale re-fits the newly visible candles.
+   */
+  resetPriceScale(): void;
+  /**
+   * The visible price *envelope* — the min low / max high across the currently
+   * visible candles, i.e. the extent the candles occupy rather than the (wider)
+   * axis range. Null when no candles are visible.
+   */
+  getVisiblePriceEnvelope(): { low: number; high: number } | null;
+  /**
+   * Scale lock for a same-asset data swap that re-buckets the same price action
+   * into a different high-low span (a timeframe switch). Rescales a *manual*
+   * price range so the visible envelope keeps the exact pixel height and
+   * position the given pre-swap envelope had — so candles don't suddenly shrink
+   * or grow when the interval changes.
+   *
+   * Call after setCandles + setVisibleRange, passing the envelope read by
+   * getVisiblePriceEnvelope before the swap. A no-op in auto-y mode (auto-fit is
+   * already span-invariant); falls back to resetPriceScale when either envelope
+   * is degenerate.
+   */
+  preservePriceEnvelope(prevLow: number, prevHigh: number): void;
+  /**
+   * Capture the visible candle geometry so the next data swap can animate as a
+   * reshape rather than a jump: each candle's wick and body slide and stretch
+   * into the shape of its counterpart in the new data.
+   *
+   * Candles are paired by *slot* — position counting back from the right edge of
+   * the visible window, which a timeframe switch preserves. Call before
+   * setCandles, then drive setIntervalMorph from 0 to 1.
+   */
+  beginIntervalMorph(): void;
+  /**
+   * Advance the interval morph started by beginIntervalMorph. `t` (clamped to
+   * 0..1) is the eased progress: 0 renders the captured geometry pixel-
+   * identically to the pre-swap frame, 1 renders the new candles and releases
+   * the capture. Driven per-frame by the host animation loop.
+   */
+  setIntervalMorph(t: number): void;
   /** Shifts the visible range by `dx`/`dy` pixels and returns a fresh picture. */
   pan(dx: number, dy: number): SkPicture | null;
   /**

package/src/theme.ts

@@ -28,11 +28,18 @@ export const FLOAT_KEYS: Partial<Record<keyof VroomTheme, number>> = {
   volumeRadius: 10, // VROOM_FLOAT_VOLUME_RADIUS_PX
   lineWidth: 11, // VROOM_FLOAT_LINE_WIDTH_PX
   lineGradientOpacity: 12, // VROOM_FLOAT_LINE_GRADIENT_OPACITY
+  lineTension: 13, // VROOM_FLOAT_LINE_TENSION
 };
 
+// Named because useChartCore clears it directly under reduced motion, outside
+// the theme sweep below.
+export const FLOAT_LINE_TIP_PULSE = 15; // VROOM_FLOAT_LINE_TIP_PULSE
+
 // Maps each boolean VroomTheme field to its VroomFloatKey index (pushed as 0/1).
 export const BOOL_KEYS: Partial<Record<keyof VroomTheme, number>> = {
   wickRoundCap: 9, // VROOM_FLOAT_WICK_ROUND_CAP
+  lineTipDot: 14, // VROOM_FLOAT_LINE_TIP_DOT
+  lineTipPulse: FLOAT_LINE_TIP_PULSE,
 };
 
 // Parses a color into a packed 0xAARRGGBB integer (Skia's ARGB order).

package/src/useChartCore.ts

@@ -1,11 +1,14 @@
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
 import type { SkPicture } from '@shopify/react-native-skia';
 
 import NativeVroomChart from './NativeVroomChart';
+import type { DataTransition } from './dataTransitions';
+import { classifyTransition, inferStepMs, timeframeWindow } from './dataTransitions';
+import { ease } from './easing';
 import type { ChartHandle } from './jsi.d';
 import { packCandles } from './packCandles';
-import { applyTheme, parseColor } from './theme';
+import { applyTheme, parseColor, FLOAT_LINE_TIP_PULSE } from './theme';
 import type {
   BollingerBandsConfig,
   Candle,
@@ -15,6 +18,7 @@ import type {
   PriceLine,
   PriceLinesStyle,
   RSIConfig,
+  TransitionEasing,
   VisibleRange,
   VolumeConfig,
   VroomTheme,
@@ -213,6 +217,25 @@ function ensureInstalled(): void {
 /** Progress + curve of the staggered volume-bar collapse. See setVolumeCollapse. */
 export type VolumeCollapse = { t: number; easing: number };
 
+/**
+ * How a data swap should animate, plus where its frames go. The interval morph
+ * has to be started from inside the data effect (it needs the pre-swap capture),
+ * but it repaints at 60fps — far too often for React state — so the host passes
+ * a sink that writes straight into the picture SharedValue.
+ */
+export type TransitionOptions = {
+  /** Identity of the series; a change forces a full view reset. */
+  seriesKey?: string;
+  /** Duration of the interval morph in ms. 0 snaps. Default 300. */
+  transitionMs?: number;
+  /** Curve applied to the morph's progress. Default 'ease-in-out'. */
+  transitionEasing?: TransitionEasing;
+  /** OS reduced-motion preference: skips the capture and snaps. */
+  reduceMotion?: boolean;
+  /** Receives every morph frame. Without one, data swaps snap. */
+  onFrame?: (picture: SkPicture) => void;
+};
+
 export type ChartCoreState = {
   handle: ChartHandle | null;
   /** Picture freshly rendered after the latest data/size/range push. */
@@ -243,6 +266,7 @@ export function useChartCore(
   bollingerBands?: BollingerBandsConfig,
   volume?: VolumeConfig,
   priceLines?: PriceLinesProp,
+  transition?: TransitionOptions,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
   // Push setDefaultCandleWidth only once (first load): setCandles re-runs on
@@ -250,6 +274,14 @@ export function useChartCore(
   // so re-pushing would snap the view away from the user's pan/zoom.
   const defaultWidthAppliedRef = useRef(false);
   const volumeCollapseRef = useRef<VolumeCollapse | null>(null);
+  // What the core currently holds, for classifying the next data change. Keyed
+  // by handle so a recreated core is treated as a fresh initial load.
+  const prevDataRef = useRef<{
+    handle: ChartHandle;
+    candles: Candle[];
+    seriesKey?: string;
+  } | null>(null);
+  const intervalMorphRaf = useRef<number | null>(null);
   const [picture, setPicture] = useState<SkPicture | null>(null);
 
   if (!handleRef.current && size.width > 0 && size.height > 0) {
@@ -257,6 +289,56 @@ export function useChartCore(
     handleRef.current = globalThis.VroomChartJSI!.create();
   }
 
+  // Animation config and frame sink in refs, refreshed each render, so changing
+  // the duration, curve or callback identity doesn't re-run the data effect
+  // below (which would re-push every candle).
+  const animRef = useRef<{
+    ms: number;
+    easing: TransitionEasing | undefined;
+    reduceMotion: boolean;
+  }>({ ms: 300, easing: undefined, reduceMotion: false });
+  animRef.current = {
+    ms: Math.max(0, transition?.transitionMs ?? 300),
+    easing: transition?.transitionEasing,
+    reduceMotion: transition?.reduceMotion ?? false,
+  };
+  const onFrameRef = useRef(transition?.onFrame);
+  onFrameRef.current = transition?.onFrame;
+  const seriesKey = transition?.seriesKey;
+
+  // Stop an in-flight interval morph and land the core on the new candles.
+  const endIntervalMorph = useCallback(() => {
+    if (intervalMorphRaf.current != null) {
+      cancelAnimationFrame(intervalMorphRaf.current);
+      intervalMorphRaf.current = null;
+    }
+    handleRef.current?.setIntervalMorph(1);
+  }, []);
+
+  // Runs the interval morph clock. The core holds the pre-swap geometry (see
+  // beginIntervalMorph) and reshapes each candle slot toward its new counterpart.
+  const startIntervalMorph = useCallback((h: ChartHandle) => {
+    const { ms, easing } = animRef.current;
+    const start = performance.now();
+    const step = (now: number) => {
+      const p = Math.min(1, (now - start) / ms);
+      h.setIntervalMorph(p < 1 ? ease(easing, p) : 1);
+      const pic = h.render();
+      if (pic) onFrameRef.current?.(pic);
+      intervalMorphRaf.current = p < 1 ? requestAnimationFrame(step) : null;
+    };
+    intervalMorphRaf.current = requestAnimationFrame(step);
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (intervalMorphRaf.current != null) {
+        cancelAnimationFrame(intervalMorphRaf.current);
+        intervalMorphRaf.current = null;
+      }
+    };
+  }, []);
+
   // When no visibleRange is provided, leave the range entirely to the C++
   // side (which defaults to a sensible recent window on first setCandles).
   // Only push setVisibleRange when the caller is actively controlling it,
@@ -292,8 +374,89 @@ export function useChartCore(
       h.setDefaultCandleWidth(defaultCandleWidth);
       defaultWidthAppliedRef.current = true;
     }
+    // How the new candles relate to what the core holds decides what happens to
+    // the viewport: a stream leaves it alone, a timeframe switch re-anchors and
+    // morphs into it, a different asset resets it.
+    let morphing = false;
     if (candles.length > 0) {
-      h.setCandles(packCandles(candles));
+      const prev = prevDataRef.current;
+      const freshHandle = prev == null || prev.handle !== h;
+      if (freshHandle || prev.candles !== candles || prev.seriesKey !== seriesKey) {
+        // A fresh core frames itself (its window starts at 0/0); an explicit
+        // visibleRange prop overrides any auto behavior, so treat the change
+        // like a stream and let the range application below win.
+        const transitionKind: DataTransition = freshHandle
+          ? 'initial'
+          : explicit
+            ? 'stream'
+            : classifyTransition(prev.candles, candles, seriesKey !== prev.seriesKey);
+
+        // Capture the outgoing view before setCandles re-infers the candle
+        // period from the new data.
+        let tfArgs: {
+          oldWindow: VisibleRange;
+          oldStepMs: number;
+          oldLastMs: number;
+        } | null = null;
+        // The pre-swap candle envelope, used to scale-lock the y-axis below.
+        let prevEnvelope: { low: number; high: number } | null = null;
+        if (transitionKind === 'timeframe' && prev != null) {
+          const oldWindow = h.getVisibleRange();
+          const oldStepMs = inferStepMs(prev.candles);
+          if (oldWindow.endMs > oldWindow.startMs && oldStepMs != null) {
+            tfArgs = {
+              oldWindow,
+              oldStepMs,
+              oldLastMs: prev.candles[prev.candles.length - 1].timeMs,
+            };
+          }
+          prevEnvelope = h.getVisiblePriceEnvelope();
+          // Capture the outgoing candle geometry, but only when it will actually
+          // be animated so a disabled animation costs no snapshot. A switch
+          // during a morph restarts from the data the core currently holds.
+          morphing =
+            animRef.current.ms > 0 &&
+            !animRef.current.reduceMotion &&
+            onFrameRef.current != null;
+          if (morphing) {
+            endIntervalMorph();
+            h.beginIntervalMorph();
+          }
+        } else if (transitionKind === 'initial' || transitionKind === 'reset') {
+          // Wholesale reframing — the slot pairing no longer holds, so land any
+          // in-flight morph rather than reshaping into unrelated data.
+          endIntervalMorph();
+        }
+
+        h.setCandles(packCandles(candles));
+
+        if (transitionKind === 'timeframe') {
+          const newStepMs = inferStepMs(candles);
+          if (tfArgs && newStepMs != null) {
+            const w = timeframeWindow(
+              tfArgs.oldWindow,
+              tfArgs.oldStepMs,
+              tfArgs.oldLastMs,
+              newStepMs,
+              candles[candles.length - 1].timeMs,
+            );
+            h.setVisibleRange(w.startMs, w.endMs);
+          }
+          // Scale-lock the y-axis: the same price action re-buckets into a
+          // smaller/larger high-low span, so a manual price range is rescaled to
+          // keep the candle envelope at the pixel height it just had instead of
+          // snapping back to auto-fit. A no-op in auto-y mode, which is already
+          // span-invariant.
+          if (prevEnvelope) h.preservePriceEnvelope(prevEnvelope.low, prevEnvelope.high);
+          else h.resetPriceScale();
+          // Started after the new bounds are in place: the snapshot is in band
+          // fractions, so frame 0 still matches the pre-switch pixels exactly.
+          if (morphing) startIntervalMorph(h);
+        } else if (transitionKind === 'reset') {
+          h.resetView();
+        }
+        prevDataRef.current = { handle: h, candles, seriesKey };
+      }
     }
     if (explicit) {
       h.setVisibleRange(startMs, endMs);
@@ -303,6 +466,13 @@ export function useChartCore(
     if (theme) {
       applyTheme(h, theme);
     }
+    // The tip dot stays, only its animation drops — the same bargain the
+    // candle↔line morph strikes when it keeps the crossfade but skips the
+    // collapse. Also stops the pulse from pinning a RAF loop for a user who
+    // asked for less motion.
+    if (animRef.current.reduceMotion) {
+      h.setFloat(FLOAT_LINE_TIP_PULSE, 0);
+    }
     h.setRSI(rsiToSpec(rsi));
     h.setMACD(macdToSpec(macd));
     h.setOverlays((movingAverages ?? []).map(overlayToNumeric));
@@ -320,11 +490,15 @@ export function useChartCore(
     );
     // TODO(rn-parity): mirror the web `liquidity` overlay here (setLiquidity +
     // the VroomBand structs in the JSI handle) — web-only for now.
-    setPicture(h.render());
+    // A just-started morph is already pushing frames straight to the host sink;
+    // this snapshot would land on top of them a frame or two later. The morph's
+    // frame 0 is pixel-identical to what's on screen, so there's nothing to show
+    // in the meantime anyway.
+    if (!morphing) setPicture(h.render());
     // theme/rsi/macd/movingAverages/vwap/bollingerBands/volume/priceLines are
     // represented by their *Key deps.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [candles, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey]);
+  }, [candles, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey, startIntervalMorph, endIntervalMorph]);
 
   return { handle: handleRef.current, picture, volumeCollapseRef };
 }