react-native-vroom-chart 0.13.1 → 0.15.0

package/src/VroomChart.tsx

@@ -36,9 +36,12 @@ import { useReducedMotion, useSharedValue } from 'react-native-reanimated';
 import { useChartCore } from './useChartCore';
 import { ease, easingIndex } from './easing';
 import type { ChartFrame } from './jsi.d';
-import type { VroomChartProps } from './types';
+import type { Footprint, VroomChartProps } from './types';
 import './jsi.d';
 
+// Mirrors VroomFootprintSide in packages/core/include/vroom/vroom_chart.h.
+const FOOTPRINT_SELL = 1;
+
 function isSkImage(frame: ChartFrame): frame is SkImage {
   return typeof (frame as SkImage).getImageInfo === 'function';
 }
@@ -64,6 +67,7 @@ export function VroomChart(props: VroomChartProps) {
     chartType,
     transitionMs,
     transitionEasing,
+    intervalTransition,
     theme,
     rsi,
     macd,
@@ -79,6 +83,9 @@ export function VroomChart(props: VroomChartProps) {
     onPriceLineDrag,
     onPriceLineDragEnd,
     onPriceLineClose,
+    footprints,
+    footprintsStyle,
+    onFootprint,
   } = props;
 
   // Fill the parent by default: measure via onLayout. Explicit width/height
@@ -110,6 +117,11 @@ export function VroomChart(props: VroomChartProps) {
     [priceLines, priceLinesStyle, onPriceLineClose],
   );
 
+  const footprintsProp = useMemo(
+    () => (footprints ? { prints: footprints, style: footprintsStyle } : undefined),
+    [footprints, footprintsStyle],
+  );
+
   // RN-Skia's recorder reads these SharedValues on the UI/render runtime, a
   // beat behind JS-thread writes. If it ever reads null it throws ("Invalid
   // prop value for SkTextBlob received" — RN-Skia's mislabeled SkPicture
@@ -172,7 +184,8 @@ export function VroomChart(props: VroomChartProps) {
     bollingerBands,
     volume,
     priceLinesProp,
-    { seriesKey, transitionMs, transitionEasing, reduceMotion, onFrame },
+    footprintsProp,
+    { seriesKey, transitionMs, transitionEasing, intervalTransition, reduceMotion, onFrame },
   );
 
   // When the crosshair is showing, pan moves it (instead of scrolling) and
@@ -180,6 +193,11 @@ export function VroomChart(props: VroomChartProps) {
   // synchronously without re-subscribing. Tap dismisses it.
   const crosshairActive = useRef(false);
 
+  // Whether a footprint badge is currently open, so a tap that misses every badge
+  // knows whether it has a tooltip to dismiss. A ref for the same reason as
+  // crosshairActive: gesture callbacks read it synchronously.
+  const footprintActive = useRef(false);
+
   // timeMs of the candle last reported through onCrosshair, so a drag fires a
   // 'move' event only when it crosses into a *different* candle (one per
   // candle, not per frame). Null while the crosshair is hidden.
@@ -538,6 +556,31 @@ export function VroomChart(props: VroomChartProps) {
     'chart' | 'price-axis' | 'time-axis' | 'indicator' | 'price-line'
   >('chart');
 
+  // Closes an open footprint tooltip. Any viewport change slides the candles out
+  // from under it and the crosshair replaces it outright, so the host is told to
+  // take it down rather than left holding a position the badge has moved away
+  // from. `redraw` is false for callers that render a frame of their own right
+  // after — on Android that render rasterizes pixels, so the duplicate is worth
+  // skipping.
+  const dismissFootprint = (redraw = true) => {
+    if (!handle || !footprintActive.current) return;
+    footprintActive.current = false;
+    handle.setFootprintHover(0, -1);
+    if (redraw) {
+      const frame = handle.render();
+      if (frame) applyFrame(frame);
+    }
+    onFootprint?.({
+      active: false,
+      reason: 'hide',
+      side: null,
+      timeMs: null,
+      footprints: [],
+      badge: null,
+      pane: null,
+    });
+  };
+
   const pan = Gesture.Pan()
     .runOnJS(true)
     .maxPointers(1)  // don't fight Pinch's two-finger gesture
@@ -560,6 +603,10 @@ export function VroomChart(props: VroomChartProps) {
           if (p) applyFrame(p);
         }
       }
+      // Every mode but a price-line drag moves the viewport, and this one call
+      // covers the momentum fling too — decay only ever starts from a pan that
+      // already began here.
+      if (panMode.current !== 'price-line') dismissFootprint();
     })
     .onChange((e) => {
       if (!handle) return;
@@ -683,6 +730,7 @@ export function VroomChart(props: VroomChartProps) {
     .runOnJS(true)
     .onTouchesDown((e) => {
       if (e.numberOfTouches < 2) return;
+      dismissFootprint();
       const [a, b] = e.allTouches;
       const spanX = Math.abs(a.x - b.x);
       const spanY = Math.abs(a.y - b.y);
@@ -738,6 +786,10 @@ export function VroomChart(props: VroomChartProps) {
       // close button — so it must not raise the crosshair over the top.
       if (hitPriceLine(e.x, e.y)) return;
       cancelDecay();
+      // The crosshair takes the pane over, so it can't share it with a tooltip.
+      // No redraw: setCrosshair below returns a frame that already has the badge
+      // un-highlighted.
+      dismissFootprint(false);
       crosshairActive.current = true;
       const ch = handle.setCrosshair(e.x, e.y - crosshairOffset);
       if (ch) applyFrame(ch);
@@ -752,13 +804,45 @@ export function VroomChart(props: VroomChartProps) {
       });
     });
 
-  // A tap activates a price line's close button, and otherwise dismisses the
-  // crosshair while it's up. Any other tap is a no-op, so it never interferes
-  // with normal pan/pinch.
+  // A tap activates a price line's close button, selects or dismisses a footprint
+  // badge, and otherwise dismisses the crosshair while it's up. Any other tap is a
+  // no-op, so it never interferes with normal pan/pinch.
   const tap = Gesture.Tap()
     .runOnJS(true)
     .onStart((e) => {
       if (!handle) return;
+
+      // Badges get first refusal: one is a ~9px circle, while a price line's grab
+      // band spans the pane and would otherwise swallow any badge it crosses.
+      // Touch has no hover, so a tap is what opens a footprint here, and the next
+      // tap anywhere closes it.
+      const prints = footprints ?? [];
+      const fp = prints.length ? handle.hitTestFootprint(e.x, e.y) : null;
+      if (fp) {
+        handle.setFootprintHover(fp.candleTimeMs, fp.side);
+        const frame = handle.render();
+        if (frame) applyFrame(frame);
+        const wasActive = footprintActive.current;
+        footprintActive.current = true;
+        onFootprint?.({
+          active: true,
+          reason: wasActive ? 'move' : 'show',
+          side: fp.side === FOOTPRINT_SELL ? 'sell' : 'buy',
+          timeMs: fp.candleTimeMs,
+          // The core reports indices into the array we last pushed, which is this
+          // same prop — so this rejoins each badge to the consumer's own objects.
+          footprints: fp.indices
+            .map((i) => prints[i])
+            .filter((f): f is Footprint => f != null),
+          badge: { x: fp.x, y: fp.y, radius: fp.radius },
+          pane: fp.pane,
+        });
+        return;
+      }
+      // A tap that missed every badge dismisses the open one, so the host tooltip
+      // goes away the same way the crosshair does.
+      dismissFootprint();
+
       // The close button is a tap target whether or not the crosshair is up.
       const pl = hitPriceLine(e.x, e.y);
       if (pl && pl.part === 1) {

package/src/index.ts

@@ -22,6 +22,13 @@ export type {
   VolumeConfig,
   ChartType,
   TransitionEasing,
+  IntervalTransition,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintSide,
+  FootprintsStyle,
+  FootprintEvent,
+  PlotRect,
+  DefaultDrawingStyle,
 } from './types';

package/src/jsi.d.ts

@@ -1,6 +1,7 @@
 // Ambient declaration for the JSI HostObject installed by VroomChartModule.
 
 import type { SkImage, SkPicture } from '@shopify/react-native-skia';
+import type { IntervalTransition } from '@vroomchart/types';
 
 /** Frame the JSI handle returns: an SkPicture on iOS, an SkImage on Android. */
 export type ChartFrame = SkPicture | SkImage;
@@ -65,15 +66,12 @@ export interface ChartHandle {
    */
   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.
+   * Capture the visible candle geometry so the next data swap can animate.
+   * `'transform'` (default) lerps each slot into its counterpart; `'fade'`
+   * fades the capture out then the new scene in. Call before setCandles,
+   * then drive setIntervalMorph from 0 to 1.
    */
-  beginIntervalMorph(): void;
+  beginIntervalMorph(mode?: IntervalTransition): void;
   /**
    * Advance the interval morph started by beginIntervalMorph. `t` (clamped to
    * 0..1) is the eased progress: 0 renders the captured geometry pixel-
@@ -327,6 +325,45 @@ export interface ChartHandle {
    * committed price is untouched — restate setPriceLines to apply the move.
    */
   setPriceLineDrag(index: number, price: number): void;
+  /**
+   * Replaces the full set of footprints (plus their shared style). `side` is
+   * 0=buy, 1=sell; `timeMs` is the raw execution time — the core buckets each
+   * trade onto whichever candle's window contains it and regroups whenever the
+   * candles change. Geometry fields at 0 take the core's defaults. Pass an empty
+   * `prints` array to clear.
+   */
+  setFootprints(spec: {
+    prints: { timeMs: number; side: number }[];
+    radiusPx: number;
+    gapPx: number;
+    marginPx: number;
+    hoverBoost: number;
+  }): void;
+  /**
+   * Hit-tests pixel (x, y) against the footprint badges; null on a miss, nearest
+   * center wins when two overlap. `indices` addresses the array last passed to
+   * setFootprints and covers *both* sides of that candle, ascending by time, so
+   * one call is enough to fill a tooltip; `pane` is the plot rect, for deciding
+   * which side of the badge that tooltip fits on. Cheap to call at gesture rate.
+   */
+  hitTestFootprint(
+    x: number,
+    y: number,
+  ): {
+    side: number;
+    candleTimeMs: number;
+    x: number;
+    y: number;
+    radius: number;
+    pane: { left: number; top: number; right: number; bottom: number };
+    indices: number[];
+  } | null;
+  /**
+   * Marks a footprint badge as hovered so it renders highlighted; side -1 clears.
+   * The arguments match hitTestFootprint. Touch has no hover, so on RN this
+   * tracks the badge the user last tapped.
+   */
+  setFootprintHover(candleTimeMs: number, side: number): void;
   /** True while any axis-label fade is still in progress. Drives a RAF loop. */
   isAnimating(): boolean;
   render(): ChartFrame | null;

package/src/types.ts

@@ -20,8 +20,15 @@ export type {
   MACDConfig,
   ChartType,
   TransitionEasing,
+  IntervalTransition,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintSide,
+  FootprintsStyle,
+  FootprintEvent,
+  PlotRect,
+  DefaultDrawingStyle,
 } from '@vroomchart/types';
 
 /**

package/src/useChartCore.ts

@@ -16,8 +16,11 @@ import type {
   MovingAverageOverlay,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintsStyle,
   RSIConfig,
   TransitionEasing,
+  IntervalTransition,
   VisibleRange,
   VolumeConfig,
   VroomTheme,
@@ -202,6 +205,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;
@@ -229,6 +271,8 @@ export type TransitionOptions = {
   transitionMs?: number;
   /** Curve applied to the morph's progress. Default 'ease-in-out'. */
   transitionEasing?: TransitionEasing;
+  /** `'transform'` (default) slot-lerps; `'fade'` fades out then in. */
+  intervalTransition?: IntervalTransition;
   /** OS reduced-motion preference: skips the capture and snaps. */
   reduceMotion?: boolean;
   /** Receives every morph frame. Without one, data swaps snap. */
@@ -265,6 +309,7 @@ export function useChartCore(
   bollingerBands?: BollingerBandsConfig,
   volume?: VolumeConfig,
   priceLines?: PriceLinesProp,
+  footprints?: FootprintsProp,
   transition?: TransitionOptions,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
@@ -295,11 +340,13 @@ export function useChartCore(
     ms: number;
     easing: TransitionEasing | undefined;
     reduceMotion: boolean;
-  }>({ ms: 300, easing: undefined, reduceMotion: false });
+    interval: IntervalTransition;
+  }>({ ms: 300, easing: undefined, reduceMotion: false, interval: 'transform' });
   animRef.current = {
     ms: Math.max(0, transition?.transitionMs ?? 300),
     easing: transition?.transitionEasing,
     reduceMotion: transition?.reduceMotion ?? false,
+    interval: transition?.intervalTransition === 'fade' ? 'fade' : 'transform',
   };
   const onFrameRef = useRef(transition?.onFrame);
   onFrameRef.current = transition?.onFrame;
@@ -356,6 +403,7 @@ export function useChartCore(
   const bollingerKey = bollingerBands ? JSON.stringify(bollingerBands) : '';
   const volumeKey = volume ? JSON.stringify(volume) : '';
   const priceLinesKey = priceLines ? JSON.stringify(priceLines) : '';
+  const footprintsKey = footprints ? JSON.stringify(footprints) : '';
 
   useEffect(() => {
     const h = handleRef.current;
@@ -419,7 +467,7 @@ export function useChartCore(
             onFrameRef.current != null;
           if (morphing) {
             endIntervalMorph();
-            h.beginIntervalMorph();
+            h.beginIntervalMorph(animRef.current.interval);
           }
         } else if (transitionKind === 'initial' || transitionKind === 'reset') {
           // Wholesale reframing — the slot pairing no longer holds, so land any
@@ -487,6 +535,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;
@@ -494,10 +545,10 @@ 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/movingAverages/vwap/bollingerBands/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, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey, footprintsKey, startIntervalMorph, endIntervalMorph]);
 
   return { handle: handleRef.current, picture, volumeCollapseRef };
 }