react-native-vroom-chart 0.16.0 → 0.17.0

package/cpp/_core_src/price_indicator.h

@@ -10,6 +10,7 @@ class SkCanvas;
 struct VroomChart;
 
 namespace vroom {
+struct CandleSnapshot;
 struct Layout;
 struct PriceBounds;
 }  // namespace vroom
@@ -19,11 +20,20 @@ namespace vroom::price_indicator {
 // Draws the line across [0, candle_right] at the latest close's y, plus the
 // price box in the y-axis strip. `candle_area_h` is the y of the x-axis
 // separator; the indicator is skipped if the close maps outside [0, candle_area_h].
+//
+// `morph_from` is the newest candle's outgoing capture (slot 0 of
+// VroomChart::morph_from), or null to draw the settled close. When present the
+// level eases across `morph_t` on the same clock as the candle it marks, so the
+// badge tracks the bar instead of jumping ahead of it — see
+// price_indicator_anim.h. Callers must only pass a capture that pairs with the
+// newest candle (tip_anchor.h).
 void draw(SkCanvas* canvas,
           const VroomChart& chart,
           const Layout& lay,
           const PriceBounds& bounds,
           float candle_right,
-          float candle_area_h);
+          float candle_area_h,
+          const CandleSnapshot* morph_from = nullptr,
+          float morph_t = 1.f);
 
 }  // namespace vroom::price_indicator

package/cpp/_core_src/price_indicator_anim.h

@@ -0,0 +1,81 @@
+// Where the current-price indicator sits mid-morph (see price_indicator.cpp).
+//
+// The indicator marks the latest close, so every tick moves it. Drawing it
+// straight from that close makes it jump while the candle it belongs to eases
+// into place, which reads as the badge coming loose from the chart. Instead it
+// rides the same capture the candles do: morph_from[0] is the newest candle's
+// outgoing geometry and interval_morph_t is the host's eased clock, so the
+// indicator lands on the candle's close edge on every frame rather than only at
+// the two ends.
+//
+// The y is deliberately the same expression close_vertex uses for slot 0
+// (ma_overlay.cpp). Matching it by construction, rather than by giving the two
+// the same duration, is what keeps the badge glued to the line chart's tip.
+//
+// Skia-free and header-only so the unit tests can cover it; see
+// tests/test_price_indicator_anim.cpp.
+
+#pragma once
+
+#include <algorithm>
+
+#include "viewport.h"
+
+namespace vroom::price_indicator_anim {
+
+// One frame of the indicator.
+struct Level {
+    float y;       // pixels, on the candle's close edge
+    double price;  // what the badge should read
+    float bull_t;  // 0 = the captured direction's color, 1 = the new one
+};
+
+namespace detail {
+inline float lerp(float a, float b, float t) { return a + (b - a) * t; }
+
+// The price a captured band fraction stood for. The capture stores fractions so
+// it survives a resize or a rescale, so recovering the price it came from needs
+// the band it was measured against — which is why morph_from_bounds is kept.
+inline double price_at_fraction(const PriceBounds& b, double frac) {
+    return b.min + frac * (b.max - b.min);
+}
+}  // namespace detail
+
+// `from` is the newest candle's capture, or null when nothing is morphing or
+// the capture doesn't pair with the newest candle (panned into history — see
+// tip_anchor.h, which the caller shares the pairing rule with). A null capture
+// gives the settled values, which is what the indicator drew before it
+// animated at all.
+//
+// `from_bounds` is the price band `from` was captured against
+// (VroomChart::morph_from_bounds).
+inline Level level_at(const Layout& lay,
+                      const PriceBounds& bounds,
+                      double close_new,
+                      bool bull_new,
+                      const CandleSnapshot* from,
+                      const PriceBounds& from_bounds,
+                      float morph_t) {
+    const float to_y = vroom::price_to_y(lay, bounds, close_new);
+    if (!from) return Level{to_y, close_new, 1.f};
+
+    const float t = std::clamp(morph_t, 0.f, 1.f);
+
+    // Two different spaces on purpose. The y interpolates in band fractions,
+    // because that is the space the capture is in and the space the candles
+    // move through — anything else would start the indicator off the pixel the
+    // close occupied last frame. The price interpolates in price space, so both
+    // ends read exactly the close they belong to even when this tick set a new
+    // extreme and rescaled the band underneath. The two agree whenever the band
+    // holds still, which is the overwhelmingly common case: y_at_fraction is
+    // affine, so a fraction lerp and a price lerp are then the same function.
+    const float y =
+        detail::lerp(vroom::y_at_fraction(lay, from->close), to_y, t);
+    const double close_old =
+        detail::price_at_fraction(from_bounds, from->close);
+
+    return Level{y, close_old + (close_new - close_old) * static_cast<double>(t),
+                 from->bull == bull_new ? 1.f : t};
+}
+
+}  // namespace vroom::price_indicator_anim

package/cpp/_core_src/theme.cpp

@@ -23,6 +23,11 @@ constexpr uint32_t kDefaultColors[VROOM_COLOR_COUNT_] = {
     0xff26a69a,  // ACCENT_BULL — classic teal-green (price indicator, volume, MACD)
     0xffef5350,  // ACCENT_BEAR — classic red
     0xff8957e5,  // LINE — line-chart close polyline; violet, matching the RSI line
+    // SKELETON — transparent sentinel: inherit GRID, the way BORDER_BULL and
+    // the wick colors inherit their fills. The gridlines are already the
+    // chart's tone for structure rather than data, which is what the loading
+    // line is, so matching them keeps it from being read as a series.
+    0x00000000,
 };
 
 constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {

package/cpp/_core_src/tip_geometry.h

@@ -0,0 +1,55 @@
+// How big the line chart's tip marker is, and how much gutter it needs.
+//
+// The dot marks the newest close, which on a view pinned to the latest bar sits
+// half a slot from the right edge of the plot — a few pixels. The dot's own
+// radius is larger than that, so it can only be drawn in full if it is allowed
+// to spill into the gutter between the plot and the y-axis strip. That makes the
+// marker's size a layout input, not just a paint detail, so the renderer
+// (draw_close_tip in ma_overlay.cpp) and the layout (VroomChart::layout) read it
+// from here rather than each carrying its own copy.
+//
+// The pulse ring is deliberately not part of this. At its widest it is 3.5x the
+// border radius, and reserving that much gutter would eat the plot; it is
+// allowed to clip against the axis.
+//
+// Skia-free and header-only so the unit tests can cover it; see
+// tests/test_tip_geometry.cpp.
+
+#pragma once
+
+#include <algorithm>
+
+namespace vroom::tip_geometry {
+
+// Width of the background-colored ring that separates the tip dot from the line
+// and from the pulse expanding out behind it.
+constexpr float kBorderPx = 2.f;
+
+// Gap left between the dot's outer edge and the y-axis strip. The dot touching
+// the price labels reads as a rendering fault even when nothing is clipped.
+constexpr float kClearPx = 4.f;
+
+struct Geometry {
+    float dot_r;     // the filled dot in the line's color
+    float border_r;  // the dot plus its background-colored halo
+};
+
+// Scaling off the stroke keeps the marker proportionate at any line width; the
+// floor stops a hairline chart from getting an invisible dot.
+inline Geometry of(float line_width) {
+    const float w = line_width > 0.f ? line_width : 1.5f;
+    const float dot_r = std::max(2.f, w * 1.5f);
+    return Geometry{dot_r, dot_r + kBorderPx};
+}
+
+// Gutter width that lets the dot draw in full with `kClearPx` to spare.
+//
+// draw_close_tip drops the marker once its center passes the plot's right edge,
+// so the center is at worst flush with that edge and the dot overhangs it by
+// exactly `border_r`. A gutter of that plus the clearance therefore makes "the
+// dot never touches the axis strip" true by construction, whatever the window.
+inline float gutter_px(float line_width) {
+    return of(line_width).border_r + kClearPx;
+}
+
+}  // namespace vroom::tip_geometry

package/cpp/_core_src/viewport.h

@@ -92,6 +92,30 @@ struct CandleSnapshot {
     float x;
     float open, high, low, close;
     bool  bull;  // close >= open; selects the fill / wick / border color
+    // Set when the capture came from the loading skeleton. Such a slot starts
+    // out grey and semi-transparent rather than in its own bull/bear color, so
+    // the draw path has to blend from `skeleton_alpha`-scaled grey instead —
+    // that color blend is what makes the hand-off read as the placeholder
+    // *becoming* the data (see candles::draw).
+    bool  skeleton = false;
+    // The wave's alpha for this bar at capture time. Carried so the morph's
+    // first frame matches the skeleton frame it replaced; without it every bar
+    // would jump to full opacity the instant data landed.
+    float skeleton_alpha = 1.f;
+};
+
+// One vertex of the loading line's morph, holding both ends of the animation
+// so a frame is a plain lerp between them.
+//
+// The two y's are in different spaces on purpose. The sine knows nothing about
+// prices, so it's a fraction of the pane; the candle centre is a fraction of
+// the price band, the same space CandleSnapshot uses — which is what keeps the
+// line sitting exactly where the bars emerge from, since both resolve through
+// y_at_fraction.
+struct LinePoint {
+    float x;       // fraction of the candle-area width
+    float from_y;  // fraction of the pane height — the sine, frozen at capture
+    float to_y;    // fraction of the price band — the candle's vertical centre
 };
 
 // How many captured slots still contribute to a frame — 0 once the morph is
@@ -140,6 +164,15 @@ inline void blend_candle_snapshots(CandleSnapshot* dst, std::size_t dst_n,
         // `bull` stays the fresh one: the draw path colors a paired slot from
         // the live candle and only reads the capture's flag for a slot the next
         // update drops, where the newer direction is the better answer.
+        //
+        // The skeleton state, by contrast, carries over from the interrupted
+        // capture: a tick landing mid-hand-off must not abandon the grey blend
+        // partway, or the bar would snap to full color while its geometry is
+        // still moving. Its alpha follows the same lerp as the geometry.
+        if (from.skeleton) {
+            to.skeleton = true;
+            to.skeleton_alpha = mix(from.skeleton_alpha, 1.f);
+        }
     }
 }
 

package/lib/index.d.mts

@@ -106,6 +106,19 @@ type VroomTheme = {
     crosshairTarget?: VroomColor;
     /** Line-chart-mode close polyline color. Defaults to violet, matching the RSI line. */
     lineColor?: VroomColor;
+    /**
+     * The line drawn across the plot while loading (see the `loading` prop).
+     * Defaults to inheriting `grid`: the gridlines are already the chart's tone
+     * for structure rather than data, which is what the line is, so matching
+     * them keeps it from being read as a series.
+     *
+     * The line breathes between roughly 60% and 100% of whatever color it ends
+     * up with — a pulse, not a dimmer, so a recessive color stays legible. Any
+     * alpha given here multiplies into that, so an opaque color is the usual
+     * choice. Pass `lineColor` to make the line read as the chart's own series
+     * warming up instead.
+     */
+    skeleton?: VroomColor;
     /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
     lineWidth?: number;
     /**
@@ -1059,6 +1072,23 @@ type ATRConfig = {
 type VroomChartCoreProps = {
     /** OHLCV bars to render. The only required prop. */
     candles: Candle[];
+    /**
+     * Whether the series is still being fetched. While this is true *and*
+     * `candles` is empty, the chart draws a single grey line across the plot,
+     * drifting in a slow sine wave, in place of the scene. Gestures, the
+     * crosshair, the price badge, the axis labels and any indicator panes are all
+     * suppressed for the duration.
+     *
+     * When the data arrives the line doesn't cut away — it becomes the chart, in
+     * two steps that split `transitionMs`: it reshapes to pass through the
+     * vertical centre of every candle about to be drawn, then fades out while
+     * those candles grow outward from it and their color fades up.
+     *
+     * Passing `candles` alongside `loading` leaves the real chart up, so a
+     * background refresh of an already-loaded series won't blank out. Default
+     * false.
+     */
+    loading?: boolean;
     /**
      * Identity of the data series (e.g. "BTC-USD"). When it changes between
      * renders the chart resets to the default view (most recent candles + price

package/lib/index.d.ts

@@ -106,6 +106,19 @@ type VroomTheme = {
     crosshairTarget?: VroomColor;
     /** Line-chart-mode close polyline color. Defaults to violet, matching the RSI line. */
     lineColor?: VroomColor;
+    /**
+     * The line drawn across the plot while loading (see the `loading` prop).
+     * Defaults to inheriting `grid`: the gridlines are already the chart's tone
+     * for structure rather than data, which is what the line is, so matching
+     * them keeps it from being read as a series.
+     *
+     * The line breathes between roughly 60% and 100% of whatever color it ends
+     * up with — a pulse, not a dimmer, so a recessive color stays legible. Any
+     * alpha given here multiplies into that, so an opaque color is the usual
+     * choice. Pass `lineColor` to make the line read as the chart's own series
+     * warming up instead.
+     */
+    skeleton?: VroomColor;
     /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
     lineWidth?: number;
     /**
@@ -1059,6 +1072,23 @@ type ATRConfig = {
 type VroomChartCoreProps = {
     /** OHLCV bars to render. The only required prop. */
     candles: Candle[];
+    /**
+     * Whether the series is still being fetched. While this is true *and*
+     * `candles` is empty, the chart draws a single grey line across the plot,
+     * drifting in a slow sine wave, in place of the scene. Gestures, the
+     * crosshair, the price badge, the axis labels and any indicator panes are all
+     * suppressed for the duration.
+     *
+     * When the data arrives the line doesn't cut away — it becomes the chart, in
+     * two steps that split `transitionMs`: it reshapes to pass through the
+     * vertical centre of every candle about to be drawn, then fades out while
+     * those candles grow outward from it and their color fades up.
+     *
+     * Passing `candles` alongside `loading` leaves the real chart up, so a
+     * background refresh of an already-loaded series won't blank out. Default
+     * false.
+     */
+    loading?: boolean;
     /**
      * Identity of the data series (e.g. "BTC-USD"). When it changes between
      * renders the chart resets to the default view (most recent candles + price

package/lib/index.js

@@ -186,8 +186,10 @@ var COLOR_KEYS = {
   // VROOM_COLOR_ACCENT_BULL
   accentBear: 15,
   // VROOM_COLOR_ACCENT_BEAR
-  lineColor: 16
+  lineColor: 16,
   // VROOM_COLOR_LINE
+  skeleton: 17
+  // VROOM_COLOR_SKELETON
 };
 var FLOAT_KEYS = {
   wickWidth: 1,
@@ -487,7 +489,7 @@ function ensureInstalled() {
   }
   installed = true;
 }
-function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType, theme, rsi, macd, atr, movingAverages, vwap, bollingerBands, ichimoku, fairValueGaps, volume, priceLines, footprints, transition) {
+function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType, theme, rsi, macd, atr, movingAverages, vwap, bollingerBands, ichimoku, fairValueGaps, volume, priceLines, footprints, transition, loading) {
   const handleRef = (0, import_react.useRef)(null);
   const defaultWidthAppliedRef = (0, import_react.useRef)(false);
   const volumeCollapseRef = (0, import_react.useRef)(null);
@@ -522,18 +524,26 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
   const onFrameRef = (0, import_react.useRef)(transition?.onFrame);
   onFrameRef.current = transition?.onFrame;
   const seriesKey = transition?.seriesKey;
+  const loadingHandoffRef = (0, import_react.useRef)(false);
   const endIntervalMorph = (0, import_react.useCallback)(() => {
     if (intervalMorphRaf.current != null) {
       cancelAnimationFrame(intervalMorphRaf.current);
       intervalMorphRaf.current = null;
     }
-    handleRef.current?.setIntervalMorph(1);
+    const h = handleRef.current;
+    if (loadingHandoffRef.current) {
+      loadingHandoffRef.current = false;
+      h?.setLoadingMorph(1);
+      h?.beginLoadingReveal();
+    }
+    h?.setIntervalMorph(1);
   }, []);
-  const startIntervalMorph = (0, import_react.useCallback)((h) => {
+  const startIntervalMorph = (0, import_react.useCallback)((h, durationMs) => {
     const { ms, easing } = animRef.current;
+    const dur = durationMs ?? ms;
     const start = performance.now();
     const step = (now) => {
-      const p = Math.min(1, (now - start) / ms);
+      const p = Math.min(1, (now - start) / dur);
       h.setIntervalMorph(p < 1 ? ease(easing, p) : 1);
       const pic = h.render();
       if (pic) onFrameRef.current?.(pic);
@@ -541,6 +551,31 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
     };
     intervalMorphRaf.current = requestAnimationFrame(step);
   }, []);
+  const startLoadingHandoff = (0, import_react.useCallback)(
+    (h) => {
+      const { ms, easing } = animRef.current;
+      const half = ms / 2;
+      loadingHandoffRef.current = true;
+      h.beginLoadingMorph();
+      const start = performance.now();
+      const step = (now) => {
+        const p = Math.min(1, (now - start) / half);
+        h.setLoadingMorph(p < 1 ? ease(easing, p) : 1);
+        const pic = h.render();
+        if (pic) onFrameRef.current?.(pic);
+        if (p < 1) {
+          intervalMorphRaf.current = requestAnimationFrame(step);
+          return;
+        }
+        intervalMorphRaf.current = null;
+        loadingHandoffRef.current = false;
+        h.beginLoadingReveal();
+        startIntervalMorph(h, half);
+      };
+      intervalMorphRaf.current = requestAnimationFrame(step);
+    },
+    [startIntervalMorph]
+  );
   const settleStream = (0, import_react.useCallback)((keepMorph = false) => {
     if (streamRaf.current != null) {
       cancelAnimationFrame(streamRaf.current);
@@ -610,6 +645,8 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
   const explicit = visibleRange != null;
   const startMs = visibleRange?.startMs ?? 0;
   const endMs = visibleRange?.endMs ?? 0;
+  const showLoadingLine = loading === true && candles.length === 0;
+  const lineUpRef = (0, import_react.useRef)(false);
   const themeKey = theme ? JSON.stringify(theme) : "";
   const rsiKey = rsi ? JSON.stringify(rsi) : "";
   const macdKey = macd ? JSON.stringify(macd) : "";
@@ -632,6 +669,19 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
       defaultWidthAppliedRef.current = true;
     }
     let morphing = false;
+    if (showLoadingLine) {
+      if (!lineUpRef.current) {
+        endIntervalMorph();
+        settleStream();
+        h.setCandles(packCandles([]));
+        prevDataRef.current = null;
+      }
+      h.setLoading(true, !animRef.current.reduceMotion);
+      lineUpRef.current = true;
+    } else if (lineUpRef.current && candles.length === 0) {
+      h.setLoading(false, true);
+      lineUpRef.current = false;
+    }
     if (candles.length > 0) {
       const prev = prevDataRef.current;
       const freshHandle = prev == null || prev.handle !== h;
@@ -639,6 +689,7 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
         const transitionKind = freshHandle ? "initial" : explicit ? "stream" : classifyTransition(prev.candles, candles, seriesKey !== prev.seriesKey);
         let tfArgs = null;
         let prevEnvelope = null;
+        let handOff = false;
         let stream = null;
         if (transitionKind === "stream" && prev != null && !explicit) {
           const { stream: mode, streamMs, reduceMotion } = animRef.current;
@@ -688,6 +739,11 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
         } else if (transitionKind === "initial" || transitionKind === "reset") {
           endIntervalMorph();
         }
+        if (lineUpRef.current) {
+          lineUpRef.current = false;
+          handOff = animRef.current.ms > 0 && !animRef.current.reduceMotion && onFrameRef.current != null;
+          if (!handOff) h.setLoading(false, true);
+        }
         h.setCandles(packCandles(candles));
         if (transitionKind === "timeframe") {
           const newStepMs = inferStepMs(candles);
@@ -709,6 +765,7 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
         } else if (transitionKind === "reset") {
           h.resetView();
         }
+        if (handOff) startLoadingHandoff(h);
         prevDataRef.current = { handle: h, candles, seriesKey };
       }
     }
@@ -738,7 +795,7 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType
       footprints?.prints.length ? footprintsToSpec(footprints) : EMPTY_FOOTPRINTS
     );
     if (!morphing) setPicture(h.render());
-  }, [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]);
+  }, [candles, showLoadingLine, seriesKey, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, atrKey, maKey, vwapKey, bollingerKey, ichimokuKey, fvgKey, volumeKey, priceLinesKey, footprintsKey, startIntervalMorph, startLoadingHandoff, endIntervalMorph, startStreamAnim, settleStream]);
   return { handle: handleRef.current, picture, volumeCollapseRef };
 }
 
@@ -750,6 +807,7 @@ function isSkImage(frame) {
 function VroomChart(props) {
   const {
     candles,
+    loading,
     seriesKey,
     width: widthProp,
     height: heightProp,
@@ -867,8 +925,10 @@ function VroomChart(props) {
       streamTransitionMs,
       reduceMotion,
       onFrame
-    }
+    },
+    loading
   );
+  const showLoadingLine = loading === true && candles.length === 0;
   const crosshairActive = (0, import_react2.useRef)(false);
   const footprintActive = (0, import_react2.useRef)(false);
   const lastCrosshairTime = (0, import_react2.useRef)(null);
@@ -1148,7 +1208,7 @@ function VroomChart(props) {
       pane: null
     });
   };
-  const pan = import_react_native_gesture_handler.Gesture.Pan().runOnJS(true).maxPointers(1).onStart((e) => {
+  const pan = import_react_native_gesture_handler.Gesture.Pan().enabled(!showLoadingLine).runOnJS(true).maxPointers(1).onStart((e) => {
     cancelDecay();
     panMode.current = hitAxis(e.x, e.y);
     priceDrag.current = null;
@@ -1243,7 +1303,7 @@ function VroomChart(props) {
     enableX: false,
     enableY: false
   });
-  const pinch = import_react_native_gesture_handler.Gesture.Pinch().runOnJS(true).onTouchesDown((e) => {
+  const pinch = import_react_native_gesture_handler.Gesture.Pinch().enabled(!showLoadingLine).runOnJS(true).onTouchesDown((e) => {
     if (e.numberOfTouches < 2) return;
     dismissFootprint();
     const [a, b] = e.allTouches;
@@ -1281,7 +1341,7 @@ function VroomChart(props) {
     if (next) applyFrame(next);
     maybeStartAnim();
   });
-  const longPress = import_react_native_gesture_handler.Gesture.LongPress().runOnJS(true).onStart((e) => {
+  const longPress = import_react_native_gesture_handler.Gesture.LongPress().enabled(!showLoadingLine).runOnJS(true).onStart((e) => {
     if (!handle) return;
     if (hitAxis(e.x, e.y) !== "chart") return;
     if (hitPriceLine(e.x, e.y)) return;
@@ -1301,7 +1361,7 @@ function VroomChart(props) {
       reason: "show"
     });
   });
-  const tap = import_react_native_gesture_handler.Gesture.Tap().runOnJS(true).onStart((e) => {
+  const tap = import_react_native_gesture_handler.Gesture.Tap().enabled(!showLoadingLine).runOnJS(true).onStart((e) => {
     if (!handle) return;
     const prints = footprints ?? [];
     const fp = prints.length ? handle.hitTestFootprint(e.x, e.y) : null;