react-native-vroom-chart 0.14.0 → 0.16.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';
 }
@@ -47,8 +50,9 @@ function isSkImage(frame: ChartFrame): frame is SkImage {
  * Skia-rendered candlestick chart. Pass OHLCV `candles` and size it via `style`
  * (it fills its parent by default). Pan to scroll, pinch to zoom, drag the
  * price/time axes to rescale, and long-press for the crosshair. Optional
- * indicators (`rsi`, `macd`, `movingAverages`, `vwap`), colors (`theme`), and
- * events (`onCrosshair`, `onViewportChange`) are configured through props.
+ * indicators (`rsi`, `macd`, `movingAverages`, `vwap`, `bollingerBands`,
+ * `ichimoku`, and more), colors (`theme`), and events (`onCrosshair`,
+ * `onViewportChange`) are configured through props.
  *
  * @see {@link VroomChartProps} for the full prop reference.
  */
@@ -65,12 +69,17 @@ export function VroomChart(props: VroomChartProps) {
     transitionMs,
     transitionEasing,
     intervalTransition,
+    streamTransition,
+    streamTransitionMs,
     theme,
     rsi,
     macd,
+    atr,
     movingAverages,
     vwap,
     bollingerBands,
+    ichimoku,
+    fairValueGaps,
     volume,
     crosshairOffset = 40,
     onCrosshair,
@@ -80,6 +89,9 @@ export function VroomChart(props: VroomChartProps) {
     onPriceLineDrag,
     onPriceLineDragEnd,
     onPriceLineClose,
+    footprints,
+    footprintsStyle,
+    onFootprint,
   } = props;
 
   // Fill the parent by default: measure via onLayout. Explicit width/height
@@ -111,6 +123,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
@@ -168,12 +185,25 @@ export function VroomChart(props: VroomChartProps) {
     theme,
     rsi,
     macd,
+    atr,
     movingAverages,
     vwap,
     bollingerBands,
+    ichimoku,
+    fairValueGaps,
     volume,
     priceLinesProp,
-    { seriesKey, transitionMs, transitionEasing, intervalTransition, reduceMotion, onFrame },
+    footprintsProp,
+    {
+      seriesKey,
+      transitionMs,
+      transitionEasing,
+      intervalTransition,
+      streamTransition,
+      streamTransitionMs,
+      reduceMotion,
+      onFrame,
+    },
   );
 
   // When the crosshair is showing, pan moves it (instead of scrolling) and
@@ -181,6 +211,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.
@@ -539,6 +574,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
@@ -561,6 +621,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;
@@ -684,6 +748,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);
@@ -739,6 +804,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);
@@ -753,13 +822,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/dataTransitions.ts

@@ -126,6 +126,53 @@ export function classifyTransition(
   return closeRatio <= MAX_SAME_ASSET_CLOSE_RATIO && endsTogether ? 'timeframe' : 'reset';
 }
 
+/**
+ * What a `'stream'` update did to the series: `'tick'` revised the bar already
+ * on screen, `'append'` brought at least one new one.
+ *
+ * The two animate by different means. A tick keeps the bar count, so the morph
+ * capture's slots still pair one-to-one and the last bar can reshape in place.
+ * An append can't use that capture at all — slots pair from the right edge, so
+ * a new bar shifts every candle onto its neighbour's geometry — and instead
+ * advances the visible window, which translates the series left and lets the
+ * new bar in at the right edge.
+ */
+export type StreamKind = 'tick' | 'append';
+
+/**
+ * Which of the two a `'stream'` transition is. Read from the newest timestamp
+ * rather than a length comparison, so a rolling buffer that drops a bar from
+ * the front as it adds one to the back still reads as an append.
+ *
+ * An update that both appends and revises the bar that just closed counts as an
+ * append: the translation is the dominant motion, and the revision is a final
+ * print that has nowhere to slot-pair to.
+ */
+export function classifyStream(prev: Candle[], next: Candle[]): StreamKind {
+  if (prev.length === 0 || next.length === 0) return 'tick';
+  return next[next.length - 1].timeMs > prev[prev.length - 1].timeMs
+    ? 'append'
+    : 'tick';
+}
+
+/**
+ * Whether the view is still following the newest bar, which is what decides if
+ * an appended bar should pull the window along with it.
+ *
+ * True when the right edge sits at or past the newest bar's slot *end* — where
+ * the default framing leaves it, plus whatever gap it reserved. Someone who has
+ * panned back into history falls below that and is left where they are: nothing
+ * is more disorienting than the chart walking out from under you while you read
+ * it.
+ */
+export function isPinnedToLatest(
+  window: VisibleRange,
+  lastMs: number,
+  stepMs: number,
+): boolean {
+  return window.endMs >= lastMs + stepMs;
+}
+
 /**
  * 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

package/src/index.ts

@@ -14,16 +14,26 @@ export type {
   VisibleRange,
   RSIConfig,
   MACDConfig,
+  ATRConfig,
+  ATRSmoothing,
   MASource,
   MAKind,
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  IchimokuConfig,
+  FairValueGapsConfig,
   VolumeConfig,
   ChartType,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintSide,
+  FootprintsStyle,
+  FootprintEvent,
+  PlotRect,
   DefaultDrawingStyle,
 } from './types';

package/src/jsi.d.ts

@@ -73,7 +73,20 @@ export interface ChartHandle {
    */
   beginIntervalMorph(mode?: IntervalTransition): void;
   /**
-   * Advance the interval morph started by beginIntervalMorph. `t` (clamped to
+   * Capture the visible geometry so the next setCandles can ease a live tick
+   * into place. Always a transform, and unlike beginIntervalMorph it leaves the
+   * axes alone — the interval hasn't changed, so its ticks must not fade.
+   * Restarting one still in flight continues from the shape on screen, so ticks
+   * arriving faster than the animation lands stay smooth. Call before
+   * setCandles, then drive setIntervalMorph from 0 to 1.
+   *
+   * Not for an update that appends a bar: slots pair from the right edge, so a
+   * new bar would shift every candle onto its neighbour's geometry. Advance the
+   * visible range instead and let the series translate.
+   */
+  beginStreamMorph(): void;
+  /**
+   * Advance the morph started by either begin method above. `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.
@@ -173,6 +186,7 @@ export interface ChartHandle {
     maWidth: number;
     bandColor: number;
     bandsVisible: boolean;
+    extremeFill: boolean;
   }): void;
   /**
    * Configures the MACD pane. source/maKind mirror setOverlays' encodings;
@@ -201,6 +215,18 @@ export interface ChartHandle {
     zeroColor: number;
     zeroVisible: boolean;
   }): void;
+  /**
+   * Configures the ATR pane. smoothing: 0=RMA (Wilder), 1=SMA, 2=EMA;
+   * lineColor is packed 0xAARRGGBB where 0 means inherit, and a non-positive
+   * width inherits the default stroke.
+   */
+  setATR(spec: {
+    enabled: boolean;
+    period: number;
+    smoothing: number;
+    lineColor: number;
+    lineWidth: number;
+  }): void;
   /**
    * Replaces the full set of MA/EMA overlay lines drawn on the price pane.
    * kind: 0=SMA, 1=EMA; source: 0=close,1=open,2=high,3=low,4=hl2,5=hlc3,6=ohlc4;
@@ -245,6 +271,76 @@ export interface ChartHandle {
     fillEnabled: boolean;
     fillOpacity: number;
   }): void;
+  /**
+   * Configures the Ichimoku overlay (five price-pane lines + the cloud between
+   * the leading spans). Colors are packed 0xAARRGGBB; cloudOpacity is 0..1.
+   *
+   * `displacement` is in candle slots and applies at draw time: the leading
+   * spans plot that many slots ahead of the bar they came from, past the newest
+   * candle, and chikou that many behind. Enabling the overlay also pulls the
+   * view forward far enough to show them.
+   */
+  setIchimoku(spec: {
+    enabled: boolean;
+    tenkanPeriod: number;
+    kijunPeriod: number;
+    senkouBPeriod: number;
+    displacement: number;
+    tenkanColor: number;
+    tenkanWidth: number;
+    tenkanEnabled: boolean;
+    kijunColor: number;
+    kijunWidth: number;
+    kijunEnabled: boolean;
+    senkouAColor: number;
+    senkouAWidth: number;
+    senkouAEnabled: boolean;
+    senkouBColor: number;
+    senkouBWidth: number;
+    senkouBEnabled: boolean;
+    chikouColor: number;
+    chikouWidth: number;
+    chikouEnabled: boolean;
+    cloudEnabled: boolean;
+    bullishCloudColor: number;
+    bearishCloudColor: number;
+    cloudOpacity: number;
+  }): void;
+  /**
+   * Configures the Fair Value Gap overlay (shaded imbalance boxes on the price
+   * pane). Colors are packed 0xAARRGGBB; opacity is 0..1.
+   *
+   * `maxBarsBack`, `boxLength` and `labelDistance` are all counted in candle
+   * slots. `fillType` is 0 for a close past the far edge or 1 for a wick
+   * reaching it, and `borderStyle` is 0 solid / 1 dotted / 2 dashed. Only
+   * enabled, maxBarsBack, waitForClose and fillType rescan for gaps.
+   */
+  setFairValueGaps(spec: {
+    enabled: boolean;
+    maxBarsBack: number;
+    waitForClose: boolean;
+    fillType: number;
+    deleteAfterFill: boolean;
+    extendBoxes: boolean;
+    boxLength: number;
+    bullishColor: number;
+    bearishColor: number;
+    opacity: number;
+    borderEnabled: boolean;
+    borderStyle: number;
+    borderWidth: number;
+    bullishBorderColor: number;
+    bearishBorderColor: number;
+    labelsEnabled: boolean;
+    label: string;
+    labelDistance: number;
+    labelColor: number;
+    labelFontSize: number;
+    showInverse: boolean;
+    inverseBullishColor: number;
+    inverseBearishColor: number;
+    inverseLabel: string;
+  }): void;
   /**
    * Configures the volume bars under the candles. `heightFrac` is the tallest
    * bar as a fraction of the price pane. The style fields carry an inherit
@@ -325,6 +421,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

@@ -16,13 +16,23 @@ export type {
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  IchimokuConfig,
+  FairValueGapsConfig,
   VolumeConfig,
   MACDConfig,
+  ATRConfig,
+  ATRSmoothing,
   ChartType,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   PriceLine,
   PriceLinesStyle,
+  Footprint,
+  FootprintSide,
+  FootprintsStyle,
+  FootprintEvent,
+  PlotRect,
   DefaultDrawingStyle,
 } from '@vroomchart/types';