react-native-vroom-chart 0.14.0 → 0.16.0

package/src/useChartCore.ts

@@ -3,22 +3,34 @@ import type { MutableRefObject } from 'react';
 
 import NativeVroomChart from './NativeVroomChart';
 import type { DataTransition } from './dataTransitions';
-import { classifyTransition, inferStepMs, timeframeWindow } from './dataTransitions';
+import {
+  classifyStream,
+  classifyTransition,
+  inferStepMs,
+  isPinnedToLatest,
+  timeframeWindow,
+} from './dataTransitions';
 import { ease } from './easing';
 import type { ChartFrame, ChartHandle } from './jsi.d';
 import { packCandles } from './packCandles';
 import { applyTheme, parseColor, FLOAT_LINE_TIP_PULSE } from './theme';
 import type {
   BollingerBandsConfig,
+  ATRConfig,
   Candle,
   ChartType,
+  FairValueGapsConfig,
+  IchimokuConfig,
   MACDConfig,
   MovingAverageOverlay,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintsStyle,
   RSIConfig,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   VisibleRange,
   VolumeConfig,
   VroomTheme,
@@ -36,6 +48,9 @@ const MA_SOURCES = [
   'ohlc4',
 ] as const;
 
+// Mirrors vroom::atr::Smoothing order in packages/core/src/atr.h.
+const ATR_SMOOTHINGS = ['rma', 'sma', 'ema'] as const;
+
 // An unset style color marshals as the core's transparent inherit sentinel.
 const inheritColor = (v: string | number | undefined): number =>
   (v != null ? parseColor(v) : null) ?? 0;
@@ -67,6 +82,7 @@ function rsiToSpec(cfg: RSIConfig | undefined) {
     maWidth: cfg?.maWidth ?? -1,
     bandColor: inheritColor(cfg?.bandColor),
     bandsVisible: cfg?.bandsVisible ?? true,
+    extremeFill: cfg?.extremeFill ?? true,
   };
 }
 
@@ -108,6 +124,89 @@ function bollingerToSpec(cfg: BollingerBandsConfig | undefined) {
   };
 }
 
+// Ichimoku defaults. Green and red do double duty: they color span A and kijun,
+// and tint the cloud for whichever span is on top.
+const DEFAULT_ICH_GREEN = 0xff26a69a;
+const DEFAULT_ICH_RED = 0xffef5350;
+const DEFAULT_ICH_BLUE = 0xff2962ff;
+const DEFAULT_ICH_ORANGE = 0xffff6d00;
+const DEFAULT_ICH_TEAL = 0xff00bcd4;
+
+function ichimokuToSpec(cfg: IchimokuConfig | undefined) {
+  const color = (v: string | number | undefined, fallback: number) =>
+    (v != null ? parseColor(v) : null) ?? fallback;
+  return {
+    enabled: cfg?.enabled ?? false,
+    tenkanPeriod: cfg?.tenkanPeriod ?? 9,
+    kijunPeriod: cfg?.kijunPeriod ?? 26,
+    senkouBPeriod: cfg?.senkouBPeriod ?? 52,
+    displacement: cfg?.displacement ?? 26,
+    tenkanColor: color(cfg?.tenkanColor, DEFAULT_ICH_BLUE),
+    tenkanWidth: cfg?.tenkanWidth ?? 1,
+    tenkanEnabled: cfg?.tenkanVisible ?? true,
+    kijunColor: color(cfg?.kijunColor, DEFAULT_ICH_RED),
+    kijunWidth: cfg?.kijunWidth ?? 1,
+    kijunEnabled: cfg?.kijunVisible ?? true,
+    senkouAColor: color(cfg?.senkouAColor, DEFAULT_ICH_GREEN),
+    senkouAWidth: cfg?.senkouAWidth ?? 1,
+    senkouAEnabled: cfg?.senkouAVisible ?? true,
+    senkouBColor: color(cfg?.senkouBColor, DEFAULT_ICH_ORANGE),
+    senkouBWidth: cfg?.senkouBWidth ?? 1,
+    senkouBEnabled: cfg?.senkouBVisible ?? true,
+    chikouColor: color(cfg?.chikouColor, DEFAULT_ICH_TEAL),
+    chikouWidth: cfg?.chikouWidth ?? 1,
+    chikouEnabled: cfg?.chikouVisible ?? true,
+    cloudEnabled: cfg?.cloudVisible ?? true,
+    bullishCloudColor: color(cfg?.bullishCloudColor, DEFAULT_ICH_GREEN),
+    bearishCloudColor: color(cfg?.bearishCloudColor, DEFAULT_ICH_RED),
+    cloudOpacity: cfg?.cloudOpacity ?? 0.15,
+  };
+}
+
+// Fair Value Gap defaults. The border colors fall back to the fill color, so a
+// config that only restyles the fill keeps its outline in the same hue.
+const DEFAULT_FVG_GREEN = 0xff26a69a;
+const DEFAULT_FVG_RED = 0xffef5350;
+const FVG_FILL_TYPES = ['close', 'wick'] as const;
+const FVG_BORDER_STYLES = ['solid', 'dotted', 'dashed'] as const;
+
+function fvgToSpec(cfg: FairValueGapsConfig | undefined) {
+  const color = (v: string | number | undefined, fallback: number) =>
+    (v != null ? parseColor(v) : null) ?? fallback;
+  const bullish = color(cfg?.bullishColor, DEFAULT_FVG_GREEN);
+  const bearish = color(cfg?.bearishColor, DEFAULT_FVG_RED);
+  return {
+    enabled: cfg?.enabled ?? false,
+    maxBarsBack: cfg?.maxBarsBack ?? 300,
+    waitForClose: cfg?.waitForClose ?? false,
+    fillType: Math.max(0, FVG_FILL_TYPES.indexOf(cfg?.fillType ?? 'close')),
+    deleteAfterFill: cfg?.deleteAfterFill ?? true,
+    extendBoxes: cfg?.extendBoxes ?? false,
+    boxLength: cfg?.boxLength ?? 20,
+    bullishColor: bullish,
+    bearishColor: bearish,
+    opacity: cfg?.opacity ?? 0.15,
+    borderEnabled: cfg?.borderVisible ?? true,
+    borderStyle: Math.max(
+      0,
+      FVG_BORDER_STYLES.indexOf(cfg?.borderStyle ?? 'solid'),
+    ),
+    borderWidth: cfg?.borderWidth ?? 1,
+    bullishBorderColor: color(cfg?.bullishBorderColor, bullish),
+    bearishBorderColor: color(cfg?.bearishBorderColor, bearish),
+    labelsEnabled: cfg?.showLabels ?? true,
+    label: cfg?.label ?? 'FVG',
+    labelDistance: cfg?.labelDistance ?? 10,
+    // Alpha 0 is the core's "inherit the border color" sentinel.
+    labelColor: color(cfg?.labelColor, 0),
+    labelFontSize: cfg?.labelFontSize ?? 0,
+    showInverse: cfg?.showInverse ?? false,
+    inverseBullishColor: color(cfg?.inverseBullishColor, bullish),
+    inverseBearishColor: color(cfg?.inverseBearishColor, bearish),
+    inverseLabel: cfg?.inverseLabel ?? 'iFVG',
+  };
+}
+
 function macdToSpec(cfg: MACDConfig | undefined) {
   const srcIdx = cfg?.source ? MA_SOURCES.indexOf(cfg.source) : 0;
   return {
@@ -134,6 +233,16 @@ function macdToSpec(cfg: MACDConfig | undefined) {
   };
 }
 
+function atrToSpec(cfg: ATRConfig | undefined) {
+  return {
+    enabled: cfg?.enabled ?? false,
+    period: cfg?.period ?? 14,
+    smoothing: Math.max(0, ATR_SMOOTHINGS.indexOf(cfg?.smoothing ?? 'rma')),
+    lineColor: inheritColor(cfg?.lineColor),
+    lineWidth: cfg?.lineWidth ?? -1,
+  };
+}
+
 // Unset style fields go down as the core's inherit sentinels (negative float,
 // transparent color) rather than as literal defaults, so the theme keys stay in
 // charge of anything the consumer didn't set.
@@ -203,6 +312,45 @@ function priceLinesToSpec(cfg: PriceLinesProp) {
 // requires them).
 const EMPTY_PRICE_LINES = priceLinesToSpec({ lines: [], hasCloseHandler: false });
 
+// Footprints share the price lines' hover weight so the two widgets light up
+// alike. Zeroed geometry defers to the core's own defaults.
+const DEFAULT_FOOTPRINT_HOVER_BOOST = 1.25;
+
+// Mirrors VroomFootprintSide in packages/core/include/vroom/vroom_chart.h.
+const FOOTPRINT_BUY = 0;
+const FOOTPRINT_SELL = 1;
+
+// A time no real series can contain (~273,000 BCE), still comfortably inside
+// int64. Parks a malformed footprint where the core will never bucket it.
+const UNBUCKETABLE_MS = -8.64e15;
+
+/** The footprints + their shared style, as the chart's props express them. */
+export type FootprintsProp = {
+  prints: Footprint[];
+  style?: FootprintsStyle;
+};
+
+function footprintsToSpec(cfg: FootprintsProp) {
+  return {
+    // Index alignment is load-bearing: the core reports hits as indices into this
+    // array and the gesture layer maps them straight back to the consumer's
+    // `footprints`. So a non-finite time — which can't be bucketed and would
+    // reach the native side as a garbage int64 — is neutralized *in place* rather
+    // than filtered out, which would shift every index after it onto the wrong
+    // trade.
+    prints: cfg.prints.map((f) => ({
+      timeMs: Number.isFinite(f.timeMs) ? f.timeMs : UNBUCKETABLE_MS,
+      side: f.side === 'sell' ? FOOTPRINT_SELL : FOOTPRINT_BUY,
+    })),
+    radiusPx: cfg.style?.radius ?? 0,
+    gapPx: cfg.style?.gap ?? 0,
+    marginPx: cfg.style?.margin ?? 0,
+    hoverBoost: cfg.style?.hoverBoost ?? DEFAULT_FOOTPRINT_HOVER_BOOST,
+  };
+}
+
+const EMPTY_FOOTPRINTS = footprintsToSpec({ prints: [] });
+
 let installed = false;
 function ensureInstalled(): void {
   if (installed) return;
@@ -232,6 +380,10 @@ export type TransitionOptions = {
   transitionEasing?: TransitionEasing;
   /** `'transform'` (default) slot-lerps; `'fade'` fades out then in. */
   intervalTransition?: IntervalTransition;
+  /** `'transform'` eases live updates; `'none'` (default) snaps them. */
+  streamTransition?: StreamTransition;
+  /** Duration of the stream animation in ms. 0 snaps. Default 150. */
+  streamTransitionMs?: number;
   /** OS reduced-motion preference: skips the capture and snaps. */
   reduceMotion?: boolean;
   /** Receives every morph frame. Without one, data swaps snap. */
@@ -263,11 +415,15 @@ export function useChartCore(
   theme?: VroomTheme,
   rsi?: RSIConfig,
   macd?: MACDConfig,
+  atr?: ATRConfig,
   movingAverages?: MovingAverageOverlay[],
   vwap?: VWAPConfig,
   bollingerBands?: BollingerBandsConfig,
+  ichimoku?: IchimokuConfig,
+  fairValueGaps?: FairValueGapsConfig,
   volume?: VolumeConfig,
   priceLines?: PriceLinesProp,
+  footprints?: FootprintsProp,
   transition?: TransitionOptions,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
@@ -284,6 +440,13 @@ export function useChartCore(
     seriesKey?: string;
   } | null>(null);
   const intervalMorphRaf = useRef<number | null>(null);
+  const streamRaf = useRef<number | null>(null);
+  // Where an in-flight stream shift is headed, so cancelling it can land there
+  // rather than stranding the view mid-slide.
+  const streamWindowRef = useRef<VisibleRange | null>(null);
+  // Whether that loop is the one driving the morph scalar, so settling it never
+  // cuts short a timeframe switch that happens to overlap.
+  const streamMorphRef = useRef(false);
   const [picture, setPicture] = useState<ChartFrame | null>(null);
 
   if (!handleRef.current && size.width > 0 && size.height > 0) {
@@ -299,12 +462,25 @@ export function useChartCore(
     easing: TransitionEasing | undefined;
     reduceMotion: boolean;
     interval: IntervalTransition;
-  }>({ ms: 300, easing: undefined, reduceMotion: false, interval: 'transform' });
+    stream: StreamTransition;
+    streamMs: number;
+  }>({
+    ms: 300,
+    easing: undefined,
+    reduceMotion: false,
+    interval: 'transform',
+    stream: 'none',
+    streamMs: 150,
+  });
   animRef.current = {
     ms: Math.max(0, transition?.transitionMs ?? 300),
     easing: transition?.transitionEasing,
     reduceMotion: transition?.reduceMotion ?? false,
     interval: transition?.intervalTransition === 'fade' ? 'fade' : 'transform',
+    stream: transition?.streamTransition === 'transform' ? 'transform' : 'none',
+    // Shorter than transitionMs by default: ticks can land faster than a 300ms
+    // curve, and every one that does interrupts the last.
+    streamMs: Math.max(0, transition?.streamTransitionMs ?? 150),
   };
   const onFrameRef = useRef(transition?.onFrame);
   onFrameRef.current = transition?.onFrame;
@@ -334,12 +510,91 @@ export function useChartCore(
     intervalMorphRaf.current = requestAnimationFrame(step);
   }, []);
 
+  // Stops an in-flight stream animation and puts the chart somewhere coherent.
+  //
+  // A pending window shift always lands on its target: abandoned mid-slide it
+  // would strand the view between two bars, half a candle off the grid.
+  //
+  // `keepMorph` is for a tick restarting on top of one already running —
+  // beginStreamMorph blends out of the geometry currently on screen, so landing
+  // that geometry first would throw away the very thing it resumes from.
+  const settleStream = useCallback((keepMorph = false) => {
+    if (streamRaf.current != null) {
+      cancelAnimationFrame(streamRaf.current);
+      streamRaf.current = null;
+    }
+    const h = handleRef.current;
+    const target = streamWindowRef.current;
+    streamWindowRef.current = null;
+    if (target) h?.setVisibleRange(target.startMs, target.endMs);
+    if (streamMorphRef.current && !keepMorph) {
+      streamMorphRef.current = false;
+      h?.setIntervalMorph(1);
+    }
+  }, []);
+
+  // Runs the clock for a live update. One loop drives both halves so they land
+  // on the same frame.
+  //
+  // `window` is null for a plain tick; for an append it is where the view has to
+  // end up. The slide is measured from wherever the window is *now*, so a shift
+  // interrupting another continues from the current position instead of
+  // snapping back to the start of the last one.
+  const startStreamAnim = useCallback(
+    (h: ChartHandle, morphing: boolean, window: VisibleRange | null) => {
+      const { streamMs, easing } = animRef.current;
+      let from = window ? h.getVisibleRange() : null;
+      // What the previous frame left the window at. Anything else — a pan, a
+      // pinch — lands somewhere different, which is how the slide notices it is
+      // no longer the only thing moving the view and gets out of the way.
+      // Cheaper than teaching every gesture to cancel it, and it can't miss one.
+      let applied: VisibleRange | null = null;
+      streamWindowRef.current = window;
+      streamMorphRef.current = morphing;
+      const start = performance.now();
+      const step = (now: number) => {
+        if (from && applied) {
+          const now_w = h.getVisibleRange();
+          if (now_w.startMs !== applied.startMs || now_w.endMs !== applied.endMs) {
+            from = null;
+            streamWindowRef.current = null;
+          }
+        }
+        const p = Math.min(1, (now - start) / streamMs);
+        const e = p < 1 ? ease(easing, p) : 1;
+        if (morphing) h.setIntervalMorph(e);
+        if (from && window) {
+          applied = {
+            startMs: Math.round(from.startMs + (window.startMs - from.startMs) * e),
+            endMs: Math.round(from.endMs + (window.endMs - from.endMs) * e),
+          };
+          h.setVisibleRange(applied.startMs, applied.endMs);
+        }
+        const pic = h.render();
+        if (pic) onFrameRef.current?.(pic);
+        if (p < 1) {
+          streamRaf.current = requestAnimationFrame(step);
+        } else {
+          streamRaf.current = null;
+          streamWindowRef.current = null;
+          streamMorphRef.current = false;
+        }
+      };
+      streamRaf.current = requestAnimationFrame(step);
+    },
+    [],
+  );
+
   useEffect(() => {
     return () => {
       if (intervalMorphRaf.current != null) {
         cancelAnimationFrame(intervalMorphRaf.current);
         intervalMorphRaf.current = null;
       }
+      if (streamRaf.current != null) {
+        cancelAnimationFrame(streamRaf.current);
+        streamRaf.current = null;
+      }
     };
   }, []);
 
@@ -356,16 +611,24 @@ export function useChartCore(
   const themeKey = theme ? JSON.stringify(theme) : '';
   const rsiKey = rsi ? JSON.stringify(rsi) : '';
   const macdKey = macd ? JSON.stringify(macd) : '';
+  const atrKey = atr ? JSON.stringify(atr) : '';
   const maKey = movingAverages ? JSON.stringify(movingAverages) : '';
   const vwapKey = vwap ? JSON.stringify(vwap) : '';
   const bollingerKey = bollingerBands ? JSON.stringify(bollingerBands) : '';
+  const ichimokuKey = ichimoku ? JSON.stringify(ichimoku) : '';
+  const fvgKey = fairValueGaps ? JSON.stringify(fairValueGaps) : '';
   const volumeKey = volume ? JSON.stringify(volume) : '';
   const priceLinesKey = priceLines ? JSON.stringify(priceLines) : '';
+  const footprintsKey = footprints ? JSON.stringify(footprints) : '';
 
   useEffect(() => {
     const h = handleRef.current;
     if (!h) return;
     h.setSize(size.width, size.height, size.pxRatio ?? 1);
+    // Ahead of setCandles, like setDefaultCandleWidth below: the default framing
+    // runs inside setCandles and reserves room past the newest candle for
+    // Ichimoku's leading spans, so it has to already know they're coming.
+    h.setIchimoku(ichimokuToSpec(ichimoku));
     // Drive the initial zoom from a target candle width. Pushed once, before the
     // first setCandles (while the core window is still 0/0), and only when the
     // caller isn't explicitly controlling the range.
@@ -404,6 +667,58 @@ export function useChartCore(
         } | null = null;
         // The pre-swap candle envelope, used to scale-lock the y-axis below.
         let prevEnvelope: { low: number; high: number } | null = null;
+        // Set for an animated live update: whether the last bar reshapes, and
+        // the window an appended bar should pull the view to.
+        let stream: { morph: boolean; window: VisibleRange | null } | null = null;
+        if (transitionKind === 'stream' && prev != null && !explicit) {
+          const { stream: mode, streamMs, reduceMotion } = animRef.current;
+          const stepMs = inferStepMs(candles);
+          if (
+            mode === 'transform' &&
+            streamMs > 0 &&
+            stepMs != null &&
+            !reduceMotion &&
+            onFrameRef.current != null
+          ) {
+            const lastMs = candles[candles.length - 1].timeMs;
+            const prevLastMs = prev.candles[prev.candles.length - 1].timeMs;
+            if (classifyStream(prev.candles, candles) === 'append') {
+              // Pull the window along by exactly what the data advanced, so the
+              // series translates a whole slot and the newest bar holds its
+              // place on screen. Only for a view still following the newest bar
+              // — someone reading history keeps their window.
+              //
+              // No capture here: slots pair from the right edge, so the new bar
+              // would take the previous one's geometry and drag every candle
+              // onto its neighbour. Translating the window moves them by their
+              // own timestamps instead.
+              const w = h.getVisibleRange();
+              const prevStepMs = inferStepMs(prev.candles) ?? stepMs;
+              if (isPinnedToLatest(w, prevLastMs, prevStepMs)) {
+                const by = lastMs - prevLastMs;
+                stream = {
+                  morph: false,
+                  window: { startMs: w.startMs + by, endMs: w.endMs + by },
+                };
+              }
+            } else {
+              stream = { morph: true, window: null };
+            }
+          }
+          if (stream?.morph) {
+            // Keep the geometry on screen for beginStreamMorph to resume from:
+            // at any real tick rate most ticks interrupt the previous one, and
+            // that continuity is what keeps the bar from stuttering.
+            settleStream(true);
+            h.beginStreamMorph();
+          } else {
+            // An append has no use for a capture — it would pair the new bar
+            // with the old one's geometry and drag the whole series along.
+            settleStream();
+          }
+        } else if (transitionKind === 'stream') {
+          settleStream();
+        }
         if (transitionKind === 'timeframe' && prev != null) {
           const oldWindow = h.getVisibleRange();
           const oldStepMs = inferStepMs(prev.candles);
@@ -456,6 +771,10 @@ export function useChartCore(
           // 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 (stream) {
+          // After setCandles, so the capture (and the window it slides from) is
+          // measured against the data the animation is heading toward.
+          startStreamAnim(h, stream.morph, stream.window);
         } else if (transitionKind === 'reset') {
           h.resetView();
         }
@@ -479,9 +798,11 @@ export function useChartCore(
     }
     h.setRSI(rsiToSpec(rsi));
     h.setMACD(macdToSpec(macd));
+    h.setATR(atrToSpec(atr));
     h.setOverlays((movingAverages ?? []).map(overlayToNumeric));
     h.setVWAP(vwapToSpec(vwap));
     h.setBollinger(bollingerToSpec(bollingerBands));
+    h.setFairValueGaps(fvgToSpec(fairValueGaps));
     h.setVolume(volumeToSpec(volume));
     // setVolume snaps the collapse scalar to its `enabled`, which would cut a
     // toggle animation short whenever this effect re-runs (a streaming candle, a
@@ -492,6 +813,9 @@ export function useChartCore(
     h.setPriceLines(
       priceLines?.lines.length ? priceLinesToSpec(priceLines) : EMPTY_PRICE_LINES,
     );
+    h.setFootprints(
+      footprints?.prints.length ? footprintsToSpec(footprints) : EMPTY_FOOTPRINTS,
+    );
     // TODO(rn-parity): mirror the web `liquidity` overlay here (setLiquidity +
     // the VroomBand structs in the JSI handle) — web-only for now.
     // A just-started morph is already pushing frames straight to the host sink;
@@ -499,10 +823,11 @@ export function useChartCore(
     // 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.
+    // theme/rsi/macd/atr/movingAverages/vwap/bollingerBands/ichimoku/
+    // fairValueGaps/volume/priceLines/footprints are represented by their *Key
+    // deps.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [candles, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey, startIntervalMorph, endIntervalMorph]);
+  }, [candles, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, atrKey, maKey, vwapKey, bollingerKey, ichimokuKey, fvgKey, volumeKey, priceLinesKey, footprintsKey, startIntervalMorph, endIntervalMorph, startStreamAnim, settleStream]);
 
   return { handle: handleRef.current, picture, volumeCollapseRef };
 }