react-native-vroom-chart 0.15.0 → 0.17.0

package/src/VroomChart.tsx

@@ -50,14 +50,16 @@ 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.
  */
 export function VroomChart(props: VroomChartProps) {
   const {
     candles,
+    loading,
     seriesKey,
     width: widthProp,
     height: heightProp,
@@ -68,12 +70,17 @@ export function VroomChart(props: VroomChartProps) {
     transitionMs,
     transitionEasing,
     intervalTransition,
+    streamTransition,
+    streamTransitionMs,
     theme,
     rsi,
     macd,
+    atr,
     movingAverages,
     vwap,
     bollingerBands,
+    ichimoku,
+    fairValueGaps,
     volume,
     crosshairOffset = 40,
     onCrosshair,
@@ -179,15 +186,34 @@ export function VroomChart(props: VroomChartProps) {
     theme,
     rsi,
     macd,
+    atr,
     movingAverages,
     vwap,
     bollingerBands,
+    ichimoku,
+    fairValueGaps,
     volume,
     priceLinesProp,
     footprintsProp,
-    { seriesKey, transitionMs, transitionEasing, intervalTransition, reduceMotion, onFrame },
+    {
+      seriesKey,
+      transitionMs,
+      transitionEasing,
+      intervalTransition,
+      streamTransition,
+      streamTransitionMs,
+      reduceMotion,
+      onFrame,
+    },
+    loading,
   );
 
+  // Same condition useChartCore draws the line on: a refresh that still has
+  // data keeps the chart interactive. Every gesture below is gated on this —
+  // there's nothing to pan, zoom or inspect while the line is up, and a
+  // crosshair reading prices off a placeholder walk would be actively wrong.
+  const showLoadingLine = loading === true && candles.length === 0;
+
   // When the crosshair is showing, pan moves it (instead of scrolling) and
   // pinch is disabled. A ref (not state) so gesture callbacks read it
   // synchronously without re-subscribing. Tap dismisses it.
@@ -582,6 +608,7 @@ export function VroomChart(props: VroomChartProps) {
   };
 
   const pan = Gesture.Pan()
+    .enabled(!showLoadingLine)
     .runOnJS(true)
     .maxPointers(1)  // don't fight Pinch's two-finger gesture
     .onStart((e) => {
@@ -727,6 +754,7 @@ export function VroomChart(props: VroomChartProps) {
     enableY: false,
   });
   const pinch = Gesture.Pinch()
+    .enabled(!showLoadingLine)
     .runOnJS(true)
     .onTouchesDown((e) => {
       if (e.numberOfTouches < 2) return;
@@ -777,6 +805,7 @@ export function VroomChart(props: VroomChartProps) {
   // activates `pan` (it needs movement first), so the chart won't scroll under
   // the hold. The dot/horizontal line are lifted above the fingertip.
   const longPress = Gesture.LongPress()
+    .enabled(!showLoadingLine)
     .runOnJS(true)
     .onStart((e) => {
       if (!handle) return;
@@ -808,6 +837,7 @@ export function VroomChart(props: VroomChartProps) {
   // 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()
+    .enabled(!showLoadingLine)
     .runOnJS(true)
     .onStart((e) => {
       if (!handle) return;

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,15 +14,20 @@ export type {
   VisibleRange,
   RSIConfig,
   MACDConfig,
+  ATRConfig,
+  ATRSmoothing,
   MASource,
   MAKind,
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  IchimokuConfig,
+  FairValueGapsConfig,
   VolumeConfig,
   ChartType,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   PriceLine,
   PriceLinesStyle,
   Footprint,

package/src/jsi.d.ts

@@ -73,12 +73,67 @@ 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.
    */
   setIntervalMorph(t: number): void;
+  /**
+   * Shows or hides the loading line: a single stroke drawn across the plot in a
+   * slow travelling sine, for a chart that is laid out but has no data yet.
+   * Suppresses the axis text, price badge, crosshair and indicator panes while
+   * it's up.
+   *
+   * `on` must mean "loading *and* holding no data" — the core takes it at face
+   * value rather than checking its candle buffer, since a host mid-asset-switch
+   * can still be holding the previous asset's bars. Pass `animate: false` for
+   * reduced motion: the line draws still and the chart may go idle.
+   *
+   * Passing `false` abandons any hand-off in flight, which is what a failed or
+   * superseded fetch wants. To hand off to data instead, use the two stages
+   * below.
+   */
+  setLoading(on: boolean, animate?: boolean): void;
+  /**
+   * Hand-off stage one: reshapes the loading line into the series. Freezes the
+   * sine where it is and aims each vertex at the vertical centre of the candle
+   * that will occupy its column, so the line resolves into the silhouette of
+   * the data.
+   *
+   * Call *after* setCandles — it reads them to know where to aim — then drive
+   * {@link setLoadingMorph} from 0 to 1. The axes and the candles stay
+   * suppressed throughout; stage two brings them in.
+   */
+  beginLoadingMorph(): void;
+  /**
+   * Advances stage one. `t` (clamped to 0..1) is the eased progress: 0 renders
+   * the frozen sine, 1 the polyline through the candle centres.
+   */
+  setLoadingMorph(t: number): void;
+  /**
+   * Hand-off stage two: the candles take over. Captures each one collapsed onto
+   * its own vertical centre at zero alpha and leaves the loading state, so the
+   * bars grow outward from the line and their color fades up as it fades out.
+   *
+   * Call once stage one has reached 1, then drive {@link setIntervalMorph} from
+   * 0 to 1 — the line's fade-out rides that same clock, so the two finish
+   * together.
+   */
+  beginLoadingReveal(): void;
   /** Shifts the visible range by `dx`/`dy` pixels and returns a fresh picture. */
   pan(dx: number, dy: number): ChartFrame | null;
   /**
@@ -173,6 +228,7 @@ export interface ChartHandle {
     maWidth: number;
     bandColor: number;
     bandsVisible: boolean;
+    extremeFill: boolean;
   }): void;
   /**
    * Configures the MACD pane. source/maKind mirror setOverlays' encodings;
@@ -201,6 +257,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 +313,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

package/src/theme.ts

@@ -20,6 +20,7 @@ export const COLOR_KEYS: Partial<Record<keyof VroomTheme, number>> = {
   accentBull: 14, // VROOM_COLOR_ACCENT_BULL
   accentBear: 15, // VROOM_COLOR_ACCENT_BEAR
   lineColor: 16, // VROOM_COLOR_LINE
+  skeleton: 17, // VROOM_COLOR_SKELETON
 };
 
 // Maps each numeric VroomTheme field to its VroomFloatKey index.

package/src/types.ts

@@ -16,11 +16,16 @@ export type {
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  IchimokuConfig,
+  FairValueGapsConfig,
   VolumeConfig,
   MACDConfig,
+  ATRConfig,
+  ATRSmoothing,
   ChartType,
   TransitionEasing,
   IntervalTransition,
+  StreamTransition,
   PriceLine,
   PriceLinesStyle,
   Footprint,