react-native-vroom-chart 0.7.0 → 0.8.0

package/lib/index.d.mts

@@ -134,7 +134,7 @@ type ChartType = 'candles' | 'line';
  */
 type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
-type DrawTool = null | 'line' | 'box' | 'pencil';
+type DrawTool = null | 'line' | 'box' | 'pencil' | 'path';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
 type DrawPoint = {
     /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
@@ -176,16 +176,27 @@ type PencilDrawing = DrawingBase & {
     /** The path's points in draw order (at least 2), in data space. */
     points: DrawPoint[];
 };
+/**
+ * A multi-segment path: straight segments through `points`, in order, ending in
+ * an arrowhead on the last vertex. Like a pencil stroke it holds a variable
+ * number of points, but every one was placed deliberately (one click each), so
+ * each is an individually draggable handle once the path is committed.
+ */
+type PathDrawing = DrawingBase & {
+    type: 'path';
+    /** The path's vertices in draw order (at least 2), in data space. */
+    points: DrawPoint[];
+};
 /**
  * A committed drawing. Pass an array of these via the `drawings` prop to render
  * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
  * each time the user finishes drawing.
  *
  * This is a discriminated union on `type` — narrow on it before reading
- * `points[1]`, since a `'pencil'` stroke has a variable-length array while
+ * `points[1]`, since `'pencil'` and `'path'` have variable-length arrays while
  * `'line'` and `'box'` are always exactly two points.
  */
-type Drawing = LineDrawing | BoxDrawing | PencilDrawing;
+type Drawing = LineDrawing | BoxDrawing | PencilDrawing | PathDrawing;
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -783,4 +794,35 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };
+/**
+ * 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.
+ */
+type DataTransition = 'initial' | 'stream' | 'timeframe' | 'reset';
+/**
+ * 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.
+ */
+declare function inferStepMs(candles: Candle[]): number | null;
+/**
+ * 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.
+ */
+declare function classifyTransition(prev: Candle[] | null, next: Candle[], seriesKeyChanged: boolean): DataTransition;
+/**
+ * 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.
+ */
+declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
+
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };

package/lib/index.d.ts

@@ -134,7 +134,7 @@ type ChartType = 'candles' | 'line';
  */
 type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
-type DrawTool = null | 'line' | 'box' | 'pencil';
+type DrawTool = null | 'line' | 'box' | 'pencil' | 'path';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
 type DrawPoint = {
     /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
@@ -176,16 +176,27 @@ type PencilDrawing = DrawingBase & {
     /** The path's points in draw order (at least 2), in data space. */
     points: DrawPoint[];
 };
+/**
+ * A multi-segment path: straight segments through `points`, in order, ending in
+ * an arrowhead on the last vertex. Like a pencil stroke it holds a variable
+ * number of points, but every one was placed deliberately (one click each), so
+ * each is an individually draggable handle once the path is committed.
+ */
+type PathDrawing = DrawingBase & {
+    type: 'path';
+    /** The path's vertices in draw order (at least 2), in data space. */
+    points: DrawPoint[];
+};
 /**
  * A committed drawing. Pass an array of these via the `drawings` prop to render
  * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
  * each time the user finishes drawing.
  *
  * This is a discriminated union on `type` — narrow on it before reading
- * `points[1]`, since a `'pencil'` stroke has a variable-length array while
+ * `points[1]`, since `'pencil'` and `'path'` have variable-length arrays while
  * `'line'` and `'box'` are always exactly two points.
  */
-type Drawing = LineDrawing | BoxDrawing | PencilDrawing;
+type Drawing = LineDrawing | BoxDrawing | PencilDrawing | PathDrawing;
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -783,4 +794,35 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };
+/**
+ * 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.
+ */
+type DataTransition = 'initial' | 'stream' | 'timeframe' | 'reset';
+/**
+ * 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.
+ */
+declare function inferStepMs(candles: Candle[]): number | null;
+/**
+ * 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.
+ */
+declare function classifyTransition(prev: Candle[] | null, next: Candle[], seriesKeyChanged: boolean): DataTransition;
+/**
+ * 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.
+ */
+declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
+
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };

package/lib/index.js

@@ -30,7 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  VroomChart: () => VroomChart
+  VroomChart: () => VroomChart,
+  classifyTransition: () => classifyTransition,
+  inferStepMs: () => inferStepMs,
+  timeframeWindow: () => timeframeWindow
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -48,6 +51,86 @@ var import_react = require("react");
 var import_react_native = require("react-native");
 var NativeVroomChart_default = import_react_native.TurboModuleRegistry.getEnforcing("VroomChartModule");
 
+// src/dataTransitions.ts
+var STEP_TOLERANCE = 0.01;
+var MAX_SAME_ASSET_CLOSE_RATIO = 1.25;
+var MAX_END_DRIFT_STEPS = 3;
+var MAX_STREAM_ADVANCE_STEPS = 5;
+function inferStepMs(candles) {
+  if (candles.length < 2) return null;
+  const k = Math.min(candles.length - 1, 8);
+  const diffs = [];
+  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;
+}
+function indexByTime(candles, t) {
+  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;
+}
+function classifyTransition(prev, next, seriesKeyChanged) {
+  if (!prev || prev.length === 0) return "initial";
+  if (next.length === 0) return "stream";
+  if (seriesKeyChanged) return "reset";
+  const prevStep = inferStepMs(prev);
+  const nextStep = inferStepMs(next);
+  if (prevStep == null || nextStep == null) return "reset";
+  const prevLast = prev[prev.length - 1];
+  const nextLast = next[next.length - 1];
+  if (Math.abs(nextStep - prevStep) <= prevStep * STEP_TOLERANCE) {
+    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";
+  }
+  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";
+}
+function timeframeWindow(oldWindow, oldStepMs, oldLastMs, newStepMs, newLastMs) {
+  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 };
+}
+
+// src/easing.ts
+function ease(kind, p) {
+  switch (kind) {
+    case "linear":
+      return p;
+    case "ease-in":
+      return p * p;
+    case "ease-out":
+      return p * (2 - p);
+    default:
+      return p * p * (3 - 2 * p);
+  }
+}
+var EASINGS = [
+  "linear",
+  "ease-in",
+  "ease-out",
+  "ease-in-out"
+];
+function easingIndex(kind) {
+  const i = kind ? EASINGS.indexOf(kind) : -1;
+  return i < 0 ? EASINGS.indexOf("ease-in-out") : i;
+}
+
 // src/packCandles.ts
 var BYTES_PER_CANDLE = 48;
 function packCandles(candles) {
@@ -282,15 +365,53 @@ function ensureInstalled() {
   }
   installed = true;
 }
-function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType, theme, rsi, macd, movingAverages, vwap, bollingerBands, volume, priceLines) {
+function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType, theme, rsi, macd, movingAverages, vwap, bollingerBands, volume, priceLines, transition) {
   const handleRef = (0, import_react.useRef)(null);
   const defaultWidthAppliedRef = (0, import_react.useRef)(false);
   const volumeCollapseRef = (0, import_react.useRef)(null);
+  const prevDataRef = (0, import_react.useRef)(null);
+  const intervalMorphRaf = (0, import_react.useRef)(null);
   const [picture, setPicture] = (0, import_react.useState)(null);
   if (!handleRef.current && size.width > 0 && size.height > 0) {
     ensureInstalled();
     handleRef.current = globalThis.VroomChartJSI.create();
   }
+  const animRef = (0, import_react.useRef)({ ms: 300, easing: void 0, reduceMotion: false });
+  animRef.current = {
+    ms: Math.max(0, transition?.transitionMs ?? 300),
+    easing: transition?.transitionEasing,
+    reduceMotion: transition?.reduceMotion ?? false
+  };
+  const onFrameRef = (0, import_react.useRef)(transition?.onFrame);
+  onFrameRef.current = transition?.onFrame;
+  const seriesKey = transition?.seriesKey;
+  const endIntervalMorph = (0, import_react.useCallback)(() => {
+    if (intervalMorphRaf.current != null) {
+      cancelAnimationFrame(intervalMorphRaf.current);
+      intervalMorphRaf.current = null;
+    }
+    handleRef.current?.setIntervalMorph(1);
+  }, []);
+  const startIntervalMorph = (0, import_react.useCallback)((h) => {
+    const { ms, easing } = animRef.current;
+    const start = performance.now();
+    const step = (now) => {
+      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);
+  }, []);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      if (intervalMorphRaf.current != null) {
+        cancelAnimationFrame(intervalMorphRaf.current);
+        intervalMorphRaf.current = null;
+      }
+    };
+  }, []);
   const explicit = visibleRange != null;
   const startMs = visibleRange?.startMs ?? 0;
   const endMs = visibleRange?.endMs ?? 0;
@@ -310,8 +431,54 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
       h.setDefaultCandleWidth(defaultCandleWidth);
       defaultWidthAppliedRef.current = true;
     }
+    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) {
+        const transitionKind = freshHandle ? "initial" : explicit ? "stream" : classifyTransition(prev.candles, candles, seriesKey !== prev.seriesKey);
+        let tfArgs = null;
+        let prevEnvelope = 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();
+          morphing = animRef.current.ms > 0 && !animRef.current.reduceMotion && onFrameRef.current != null;
+          if (morphing) {
+            endIntervalMorph();
+            h.beginIntervalMorph();
+          }
+        } else if (transitionKind === "initial" || transitionKind === "reset") {
+          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);
+          }
+          if (prevEnvelope) h.preservePriceEnvelope(prevEnvelope.low, prevEnvelope.high);
+          else h.resetPriceScale();
+          if (morphing) startIntervalMorph(h);
+        } else if (transitionKind === "reset") {
+          h.resetView();
+        }
+        prevDataRef.current = { handle: h, candles, seriesKey };
+      }
     }
     if (explicit) {
       h.setVisibleRange(startMs, endMs);
@@ -330,39 +497,16 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
     h.setPriceLines(
       priceLines?.lines.length ? priceLinesToSpec(priceLines) : EMPTY_PRICE_LINES
     );
-    setPicture(h.render());
-  }, [candles, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey]);
+    if (!morphing) setPicture(h.render());
+  }, [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 };
 }
 
-// src/easing.ts
-function ease(kind, p) {
-  switch (kind) {
-    case "linear":
-      return p;
-    case "ease-in":
-      return p * p;
-    case "ease-out":
-      return p * (2 - p);
-    default:
-      return p * p * (3 - 2 * p);
-  }
-}
-var EASINGS = [
-  "linear",
-  "ease-in",
-  "ease-out",
-  "ease-in-out"
-];
-function easingIndex(kind) {
-  const i = kind ? EASINGS.indexOf(kind) : -1;
-  return i < 0 ? EASINGS.indexOf("ease-in-out") : i;
-}
-
 // src/VroomChart.tsx
 function VroomChart(props) {
   const {
     candles,
+    seriesKey,
     width: widthProp,
     height: heightProp,
     style,
@@ -405,6 +549,19 @@ function VroomChart(props) {
     } : void 0,
     [priceLines, priceLinesStyle, onPriceLineClose]
   );
+  const emptyPicture = (0, import_react2.useMemo)(() => {
+    const rec = import_react_native_skia.Skia.PictureRecorder();
+    rec.beginRecording(import_react_native_skia.Skia.XYWHRect(0, 0, 1, 1));
+    return rec.finishRecordingAsPicture();
+  }, []);
+  const pictureSV = (0, import_react_native_reanimated.useSharedValue)(emptyPicture);
+  const reduceMotion = (0, import_react_native_reanimated.useReducedMotion)();
+  const onFrame = (0, import_react2.useCallback)(
+    (p) => {
+      pictureSV.value = p;
+    },
+    [pictureSV]
+  );
   const { handle, picture, volumeCollapseRef } = useChartCore(
     candles,
     { width, height },
@@ -418,14 +575,9 @@ function VroomChart(props) {
     vwap,
     bollingerBands,
     volume,
-    priceLinesProp
+    priceLinesProp,
+    { seriesKey, transitionMs, transitionEasing, reduceMotion, onFrame }
   );
-  const emptyPicture = (0, import_react2.useMemo)(() => {
-    const rec = import_react_native_skia.Skia.PictureRecorder();
-    rec.beginRecording(import_react_native_skia.Skia.XYWHRect(0, 0, 1, 1));
-    return rec.finishRecordingAsPicture();
-  }, []);
-  const pictureSV = (0, import_react_native_reanimated.useSharedValue)(emptyPicture);
   const crosshairActive = (0, import_react2.useRef)(false);
   const lastCrosshairTime = (0, import_react2.useRef)(null);
   (0, import_react2.useEffect)(() => {
@@ -498,7 +650,7 @@ function VroomChart(props) {
       const prog = Math.min(1, (now - startTs) / dur);
       const fade = from + (target - from) * ease(easingRef.current, prog);
       morphFade.current = fade;
-      handle.setMorph(fade, fade);
+      handle.setMorph(reduceMotion ? 0 : fade, fade);
       const p = handle.render();
       if (p) pictureSV.value = p;
       if (prog < 1) {
@@ -518,7 +670,7 @@ function VroomChart(props) {
         morphRaf.current = null;
       }
     };
-  }, [handle, chartType, transitionMs, pictureSV]);
+  }, [handle, chartType, transitionMs, reduceMotion, pictureSV]);
   const volumeRaf = (0, import_react2.useRef)(null);
   const volumeHandle = (0, import_react2.useRef)(null);
   (0, import_react2.useEffect)(() => {
@@ -536,7 +688,7 @@ function VroomChart(props) {
       volumeRaf.current = null;
     }
     const dur = Math.max(0, transitionMs ?? 300);
-    if (dur === 0) {
+    if (dur === 0 || reduceMotion) {
       volumeCollapseRef.current = { t: target, easing };
       handle.setVolumeCollapse(target, easing);
       const p = handle.render();
@@ -563,7 +715,7 @@ function VroomChart(props) {
         volumeRaf.current = null;
       }
     };
-  }, [handle, volume?.enabled, transitionMs, pictureSV, volumeCollapseRef]);
+  }, [handle, volume?.enabled, transitionMs, reduceMotion, pictureSV, volumeCollapseRef]);
   const hitAxis = (0, import_react2.useCallback)(
     (x, y) => {
       if (!handle) return "chart";
@@ -775,6 +927,9 @@ function VroomChart(props) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  VroomChart
+  VroomChart,
+  classifyTransition,
+  inferStepMs,
+  timeframeWindow
 });
 //# sourceMappingURL=index.js.map