react-native-vroom-chart 0.5.0 → 0.7.0

package/src/jsi.d.ts

@@ -102,22 +102,53 @@ export interface ChartHandle {
     } | null;
   } | null;
   /**
-   * Configures the RSI pane: enable, period (>=2), overbought/oversold band
-   * levels (0..100), and the RSI-based MA trendline (toggle + length >=1).
-   */
-  setRSI(
-    enabled: boolean,
-    period: number,
-    upperBand: number,
-    lowerBand: number,
-    maEnabled: boolean,
-    maPeriod: number,
-  ): void;
+   * Configures the RSI pane. maKind mirrors setOverlays' kind encoding; colors
+   * are packed 0xAARRGGBB where 0 means inherit, and a non-positive width
+   * inherits the default stroke.
+   */
+  setRSI(spec: {
+    enabled: boolean;
+    period: number;
+    upperBand: number;
+    lowerBand: number;
+    maPeriod: number;
+    maKind: number;
+    maVisible: boolean;
+    lineColor: number;
+    lineWidth: number;
+    lineVisible: boolean;
+    maColor: number;
+    maWidth: number;
+    bandColor: number;
+    bandsVisible: boolean;
+  }): void;
   /**
-   * Configures the MACD pane: enable, fast/slow EMA lengths (slow forced > fast)
-   * and the signal-line length. Defaults 12/26/9.
+   * Configures the MACD pane. source/maKind mirror setOverlays' encodings;
+   * colors are packed 0xAARRGGBB where 0 means inherit, and a non-positive
+   * width inherits the default stroke.
    */
-  setMACD(enabled: boolean, fast: number, slow: number, signal: number): void;
+  setMACD(spec: {
+    enabled: boolean;
+    fast: number;
+    slow: number;
+    signal: number;
+    source: number;
+    maKind: number;
+    signalMaKind: number;
+    lineColor: number;
+    lineWidth: number;
+    lineVisible: boolean;
+    signalColor: number;
+    signalWidth: number;
+    signalVisible: boolean;
+    histVisible: boolean;
+    histUpColor: number;
+    histUpFadingColor: number;
+    histDownColor: number;
+    histDownFadingColor: number;
+    zeroColor: number;
+    zeroVisible: boolean;
+  }): 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;
@@ -136,12 +167,12 @@ export interface ChartHandle {
    * Configures the session VWAP overlay. `resetOffsetMin` shifts the session
    * boundary from UTC midnight (minutes); `color` is packed 0xAARRGGBB.
    */
-  setVWAP(
-    enabled: boolean,
-    resetOffsetMin: number,
-    color: number,
-    width: number,
-  ): void;
+  setVWAP(spec: {
+    enabled: boolean;
+    resetOffsetMin: number;
+    color: number;
+    width: number;
+  }): void;
   /**
    * Configures the Bollinger Bands overlay (three price-pane lines + optional
    * fill between the bands). source/basisKind mirror setOverlays' encodings;
@@ -162,6 +193,79 @@ export interface ChartHandle {
     fillEnabled: boolean;
     fillOpacity: number;
   }): 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
+   * sentinel: a negative number or a transparent color falls back to the
+   * matching theme key.
+   */
+  setVolume(spec: {
+    enabled: boolean;
+    heightFrac: number;
+    opacity: number;
+    radiusPx: number;
+    upColor: number;
+    downColor: number;
+  }): void;
+  /**
+   * Staggered volume-bar collapse: 0 = full height, 1 = all bars flat. Bars fall
+   * tallest-first and land together; drive 1 → 0 to reveal them, which plays the
+   * cascade in reverse (shortest bar home first).
+   *
+   * Unlike setMorph, `t` must be **linear** progress — the core eases each bar
+   * over its own slice of the timeline, so the curve is applied there. `easing`
+   * indexes `linear | ease-in | ease-out | ease-in-out`. setVolume snaps this to
+   * match its `enabled`, so it's only needed while animating.
+   */
+  setVolumeCollapse(t: number, easing: number): void;
+  /**
+   * The continuous data coordinate at pixel (x, y) — not snapped to a candle
+   * slot. Null when there are no candles or the viewport is degenerate. Cheap to
+   * call at gesture rate (no rendering).
+   */
+  coordAt(x: number, y: number): { timeMs: number; price: number } | null;
+  /**
+   * Replaces the full set of price status lines (plus their shared style).
+   * lineStyle: 0=solid,1=dotted,2=dashed; color/bodyBg are packed 0xAARRGGBB;
+   * flags is a bitmask (1=draggable, 2=closable, 4=axis label, 8=extend left);
+   * align: 0=left,1=center,2=right. Pass an empty `lines` array to clear.
+   */
+  setPriceLines(spec: {
+    lines: {
+      price: number;
+      color: number;
+      width: number;
+      lineStyle: number;
+      text: string;
+      quantity: string;
+      flags: number;
+    }[];
+    bodyBg: number;
+    fontSizePx: number;
+    lineLengthFrac: number;
+    align: number;
+    hoverBoost: number;
+  }): void;
+  /**
+   * Hit-tests pixel (x, y) against the price lines. `part` is 0 for the line or
+   * its label body (the drag target) and 1 for the close button; close buttons
+   * win over lines and the nearest in y wins among several candidates. Only
+   * draggable lines report part 0 and only closable lines report part 1. Cheap
+   * to call at gesture rate (no rendering).
+   */
+  hitTestPriceLine(x: number, y: number): { index: number; part: number } | null;
+  /**
+   * Marks a price line's segment as hovered so it renders highlighted; -1 clears.
+   * `part` matches hitTestPriceLine. Touch has no hover state, so this is here
+   * for pointer devices and web parity.
+   */
+  setPriceLineHover(index: number, part: number): void;
+  /**
+   * Drives the live drag preview: the line, its label and its badge render at
+   * `price` with a ghost at the committed one. Pass -1 to end the preview. The
+   * committed price is untouched — restate setPriceLines to apply the move.
+   */
+  setPriceLineDrag(index: number, price: number): void;
   /** True while any axis-label fade is still in progress. Drives a RAF loop. */
   isAnimating(): boolean;
   render(): SkPicture | null;

package/src/theme.ts

@@ -27,6 +27,7 @@ export const FLOAT_KEYS: Partial<Record<keyof VroomTheme, number>> = {
   candleRadius: 8, // VROOM_FLOAT_CANDLE_RADIUS_PX
   volumeRadius: 10, // VROOM_FLOAT_VOLUME_RADIUS_PX
   lineWidth: 11, // VROOM_FLOAT_LINE_WIDTH_PX
+  lineGradientOpacity: 12, // VROOM_FLOAT_LINE_GRADIENT_OPACITY
 };
 
 // Maps each boolean VroomTheme field to its VroomFloatKey index (pushed as 0/1).

package/src/types.ts

@@ -12,11 +12,16 @@ export type {
   VisibleRange,
   RSIConfig,
   MASource,
+  MAKind,
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  VolumeConfig,
   MACDConfig,
   ChartType,
+  TransitionEasing,
+  PriceLine,
+  PriceLinesStyle,
 } from '@vroomchart/types';
 
 /**

package/src/useChartCore.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from 'react';
+import type { MutableRefObject } from 'react';
 import type { SkPicture } from '@shopify/react-native-skia';
 
 import NativeVroomChart from './NativeVroomChart';
@@ -11,8 +12,11 @@ import type {
   ChartType,
   MACDConfig,
   MovingAverageOverlay,
+  PriceLine,
+  PriceLinesStyle,
   RSIConfig,
   VisibleRange,
+  VolumeConfig,
   VroomTheme,
   VWAPConfig,
 } from './types';
@@ -28,17 +32,49 @@ const MA_SOURCES = [
   'ohlc4',
 ] 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;
+
 function overlayToNumeric(o: MovingAverageOverlay) {
   const srcIdx = o.source ? MA_SOURCES.indexOf(o.source) : 0;
   return {
-    kind: o.kind === 'ema' ? 1 : 0,
-    period: o.length,
+    kind: o.maType === 'ema' ? 1 : 0,
+    period: o.period,
     source: srcIdx < 0 ? 0 : srcIdx,
     color: (o.color != null ? parseColor(o.color) : null) ?? 0xff2962ff,
     width: o.width ?? 1.5,
   };
 }
 
+function rsiToSpec(cfg: RSIConfig | undefined) {
+  return {
+    enabled: cfg?.enabled ?? false,
+    period: cfg?.period ?? 14,
+    upperBand: cfg?.upperBand ?? 70,
+    lowerBand: cfg?.lowerBand ?? 30,
+    maPeriod: cfg?.maPeriod ?? 14,
+    maKind: cfg?.maType === 'ema' ? 1 : 0,
+    maVisible: cfg?.maVisible ?? true,
+    lineColor: inheritColor(cfg?.lineColor),
+    lineWidth: cfg?.lineWidth ?? -1,
+    lineVisible: cfg?.lineVisible ?? true,
+    maColor: inheritColor(cfg?.maColor),
+    maWidth: cfg?.maWidth ?? -1,
+    bandColor: inheritColor(cfg?.bandColor),
+    bandsVisible: cfg?.bandsVisible ?? true,
+  };
+}
+
+function vwapToSpec(cfg: VWAPConfig | undefined) {
+  return {
+    enabled: cfg?.enabled ?? false,
+    resetOffsetMin: cfg?.resetMinutes ?? 0,
+    color: inheritColor(cfg?.color),
+    width: cfg?.width ?? -1,
+  };
+}
+
 // Bollinger defaults: blue bands / orange basis, matching the repo palette.
 const DEFAULT_BB_BAND_COLOR = 0xff2962ff;
 const DEFAULT_BB_BASIS_COLOR = 0xffff6d00;
@@ -50,7 +86,7 @@ function bollingerToSpec(cfg: BollingerBandsConfig | undefined) {
     period: cfg?.period ?? 20,
     mult: cfg?.stdDev ?? 2,
     source: srcIdx < 0 ? 0 : srcIdx,
-    basisKind: cfg?.basis === 'ema' ? 1 : 0,
+    basisKind: cfg?.maType === 'ema' ? 1 : 0,
     upperColor:
       (cfg?.upperColor != null ? parseColor(cfg.upperColor) : null) ??
       DEFAULT_BB_BAND_COLOR,
@@ -63,11 +99,106 @@ function bollingerToSpec(cfg: BollingerBandsConfig | undefined) {
       (cfg?.lowerColor != null ? parseColor(cfg.lowerColor) : null) ??
       DEFAULT_BB_BAND_COLOR,
     lowerWidth: cfg?.lowerWidth ?? 1,
-    fillEnabled: cfg?.fill ?? true,
+    fillEnabled: cfg?.fillVisible ?? true,
     fillOpacity: cfg?.fillOpacity ?? 0.1,
   };
 }
 
+function macdToSpec(cfg: MACDConfig | undefined) {
+  const srcIdx = cfg?.source ? MA_SOURCES.indexOf(cfg.source) : 0;
+  return {
+    enabled: cfg?.enabled ?? false,
+    fast: cfg?.fast ?? 12,
+    slow: cfg?.slow ?? 26,
+    signal: cfg?.signal ?? 9,
+    source: srcIdx < 0 ? 0 : srcIdx,
+    maKind: cfg?.maType === 'sma' ? 0 : 1,
+    signalMaKind: cfg?.signalMaType === 'sma' ? 0 : 1,
+    lineColor: inheritColor(cfg?.lineColor),
+    lineWidth: cfg?.lineWidth ?? -1,
+    lineVisible: cfg?.lineVisible ?? true,
+    signalColor: inheritColor(cfg?.signalColor),
+    signalWidth: cfg?.signalWidth ?? -1,
+    signalVisible: cfg?.signalVisible ?? true,
+    histVisible: cfg?.histogramVisible ?? true,
+    histUpColor: inheritColor(cfg?.histogramUpColor),
+    histUpFadingColor: inheritColor(cfg?.histogramUpFadingColor),
+    histDownColor: inheritColor(cfg?.histogramDownColor),
+    histDownFadingColor: inheritColor(cfg?.histogramDownFadingColor),
+    zeroColor: inheritColor(cfg?.zeroLineColor),
+    zeroVisible: cfg?.zeroLineVisible ?? true,
+  };
+}
+
+// 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.
+function volumeToSpec(cfg: VolumeConfig | undefined) {
+  return {
+    enabled: cfg?.enabled ?? true,
+    heightFrac: cfg?.height ?? -1,
+    opacity: cfg?.opacity ?? -1,
+    radiusPx: cfg?.radius ?? -1,
+    upColor: (cfg?.upColor != null ? parseColor(cfg.upColor) : null) ?? 0,
+    downColor: (cfg?.downColor != null ? parseColor(cfg.downColor) : null) ?? 0,
+  };
+}
+
+// Price-line defaults: a soft red dotted rule with a dark translucent label,
+// close in weight to the current-price indicator it sits beside.
+const DEFAULT_PRICE_LINE_COLOR = 0xffef5350;
+const DEFAULT_PRICE_LINE_BODY_BG = 0xd91c2128;
+const DEFAULT_PRICE_LINE_HOVER_BOOST = 1.25;
+
+const LINE_STYLES = { solid: 0, dotted: 1, dashed: 2 } as const;
+
+// Mirrors VroomPriceLineFlags in packages/core/include/vroom/vroom_chart.h.
+const PRICE_LINE_DRAGGABLE = 1 << 0;
+const PRICE_LINE_CLOSABLE = 1 << 1;
+const PRICE_LINE_AXIS_LABEL = 1 << 2;
+const PRICE_LINE_EXTEND_LEFT = 1 << 3;
+
+/** The price lines + their shared style, as the chart's props express them. */
+export type PriceLinesProp = {
+  lines: PriceLine[];
+  style?: PriceLinesStyle;
+  /**
+   * Whether the host supplied a close handler. The close button is
+   * callback-gated, so with nothing for it to do it isn't drawn at all.
+   */
+  hasCloseHandler: boolean;
+};
+
+function priceLinesToSpec(cfg: PriceLinesProp) {
+  return {
+    lines: cfg.lines.map((l) => ({
+      price: l.price,
+      color:
+        (l.color != null ? parseColor(l.color) : null) ?? DEFAULT_PRICE_LINE_COLOR,
+      width: l.width ?? 1,
+      lineStyle: LINE_STYLES[l.lineStyle ?? 'dotted'],
+      text: l.text ?? '',
+      quantity: l.quantity ?? '',
+      flags:
+        (l.draggable ? PRICE_LINE_DRAGGABLE : 0) |
+        (cfg.hasCloseHandler && l.closable !== false ? PRICE_LINE_CLOSABLE : 0) |
+        (l.axisLabel !== false ? PRICE_LINE_AXIS_LABEL : 0) |
+        (l.extendLeft !== false ? PRICE_LINE_EXTEND_LEFT : 0),
+    })),
+    bodyBg:
+      (cfg.style?.bodyBackground != null ? parseColor(cfg.style.bodyBackground) : null) ??
+      DEFAULT_PRICE_LINE_BODY_BG,
+    fontSizePx: cfg.style?.fontSize ?? 0,
+    lineLengthFrac: cfg.style?.inset ?? 0,
+    align: cfg.style?.align === 'left' ? 0 : cfg.style?.align === 'center' ? 1 : 2,
+    hoverBoost: cfg.style?.hoverBoost ?? DEFAULT_PRICE_LINE_HOVER_BOOST,
+  };
+}
+
+// Cleared overlay: no lines (the style values are irrelevant, but the spec shape
+// requires them).
+const EMPTY_PRICE_LINES = priceLinesToSpec({ lines: [], hasCloseHandler: false });
+
 let installed = false;
 function ensureInstalled(): void {
   if (installed) return;
@@ -79,10 +210,19 @@ function ensureInstalled(): void {
   installed = true;
 }
 
+/** Progress + curve of the staggered volume-bar collapse. See setVolumeCollapse. */
+export type VolumeCollapse = { t: number; easing: number };
+
 export type ChartCoreState = {
   handle: ChartHandle | null;
   /** Picture freshly rendered after the latest data/size/range push. */
   picture: SkPicture | null;
+  /**
+   * The last volume collapse handed to the core, or null before the first push.
+   * VroomChart's animation loop owns this — it lives here only so the data effect
+   * can restore it, since setVolume snaps the scalar (see below).
+   */
+  volumeCollapseRef: MutableRefObject<VolumeCollapse | null>;
 };
 
 // Owns a ChartHandle and produces an "initial" picture whenever data, size,
@@ -101,12 +241,15 @@ export function useChartCore(
   movingAverages?: MovingAverageOverlay[],
   vwap?: VWAPConfig,
   bollingerBands?: BollingerBandsConfig,
+  volume?: VolumeConfig,
+  priceLines?: PriceLinesProp,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
   // Push setDefaultCandleWidth only once (first load): setCandles re-runs on
   // every data change, and the core setter re-frames when candles are present,
   // so re-pushing would snap the view away from the user's pan/zoom.
   const defaultWidthAppliedRef = useRef(false);
+  const volumeCollapseRef = useRef<VolumeCollapse | null>(null);
   const [picture, setPicture] = useState<SkPicture | null>(null);
 
   if (!handleRef.current && size.width > 0 && size.height > 0) {
@@ -130,6 +273,8 @@ export function useChartCore(
   const maKey = movingAverages ? JSON.stringify(movingAverages) : '';
   const vwapKey = vwap ? JSON.stringify(vwap) : '';
   const bollingerKey = bollingerBands ? JSON.stringify(bollingerBands) : '';
+  const volumeKey = volume ? JSON.stringify(volume) : '';
+  const priceLinesKey = priceLines ? JSON.stringify(priceLines) : '';
 
   useEffect(() => {
     const h = handleRef.current;
@@ -158,35 +303,28 @@ export function useChartCore(
     if (theme) {
       applyTheme(h, theme);
     }
-    h.setRSI(
-      rsi?.enabled ?? false,
-      rsi?.period ?? 14,
-      rsi?.upperBand ?? 70,
-      rsi?.lowerBand ?? 30,
-      rsi?.maEnabled ?? true,
-      rsi?.maPeriod ?? 14,
-    );
-    h.setMACD(
-      macd?.enabled ?? false,
-      macd?.fast ?? 12,
-      macd?.slow ?? 26,
-      macd?.signal ?? 9,
-    );
+    h.setRSI(rsiToSpec(rsi));
+    h.setMACD(macdToSpec(macd));
     h.setOverlays((movingAverages ?? []).map(overlayToNumeric));
-    h.setVWAP(
-      vwap?.enabled ?? false,
-      vwap?.resetMinutes ?? 0,
-      (vwap?.color != null ? parseColor(vwap.color) : null) ?? 0xff00bcd4,
-      vwap?.width ?? 1.5,
-    );
+    h.setVWAP(vwapToSpec(vwap));
     h.setBollinger(bollingerToSpec(bollingerBands));
+    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
+    // resize). Hand the in-flight value back; VroomChart's loop drives it from
+    // there.
+    const collapse = volumeCollapseRef.current;
+    if (collapse) h.setVolumeCollapse(collapse.t, collapse.easing);
+    h.setPriceLines(
+      priceLines?.lines.length ? priceLinesToSpec(priceLines) : EMPTY_PRICE_LINES,
+    );
     // TODO(rn-parity): mirror the web `liquidity` overlay here (setLiquidity +
     // the VroomBand structs in the JSI handle) — web-only for now.
     setPicture(h.render());
-    // theme/rsi/macd/movingAverages/vwap/bollingerBands are represented by
-    // their *Key deps.
+    // 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]);
+  }, [candles, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey, volumeKey, priceLinesKey]);
 
-  return { handle: handleRef.current, picture };
+  return { handle: handleRef.current, picture, volumeCollapseRef };
 }