react-native-vroom-chart 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-vroom-chart",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Mobile-first Skia candlestick chart for React Native",
   "license": "MIT",
   "author": "Darion Welch",

package/src/VroomChart.tsx

@@ -59,6 +59,7 @@ function isSkImage(frame: ChartFrame): frame is SkImage {
 export function VroomChart(props: VroomChartProps) {
   const {
     candles,
+    loading,
     seriesKey,
     width: widthProp,
     height: heightProp,
@@ -204,8 +205,15 @@ export function VroomChart(props: VroomChartProps) {
       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.
@@ -600,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) => {
@@ -745,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;
@@ -795,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;
@@ -826,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/jsi.d.ts

@@ -92,6 +92,48 @@ export interface ChartHandle {
    * 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;
   /**

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/useChartCore.ts

@@ -425,6 +425,9 @@ export function useChartCore(
   priceLines?: PriceLinesProp,
   footprints?: FootprintsProp,
   transition?: TransitionOptions,
+  // Trails the config params because it's data state, not configuration: it
+  // pairs with `candles` above (see showLoadingLine below).
+  loading?: boolean,
 ): ChartCoreState {
   const handleRef = useRef<ChartHandle | null>(null);
   // Push setDefaultCandleWidth only once (first load): setCandles re-runs on
@@ -486,22 +489,39 @@ export function useChartCore(
   onFrameRef.current = transition?.onFrame;
   const seriesKey = transition?.seriesKey;
 
+  // Set only while the loading hand-off is in its *first* stage, which is the
+  // one an interruption can't simply land: stage one leaves `loading` set in
+  // the core, and only stage two releases it.
+  const loadingHandoffRef = useRef(false);
+
   // Stop an in-flight interval morph and land the core on the new candles.
   const endIntervalMorph = useCallback(() => {
     if (intervalMorphRaf.current != null) {
       cancelAnimationFrame(intervalMorphRaf.current);
       intervalMorphRaf.current = null;
     }
-    handleRef.current?.setIntervalMorph(1);
+    const h = handleRef.current;
+    // Walk a half-finished hand-off through the rest of its stages rather than
+    // just stopping the clock, or the core would be left drawing the loading
+    // line over the data it was supposed to hand off to.
+    if (loadingHandoffRef.current) {
+      loadingHandoffRef.current = false;
+      h?.setLoadingMorph(1);
+      h?.beginLoadingReveal();
+    }
+    h?.setIntervalMorph(1);
   }, []);
 
   // Runs the interval morph clock. The core holds the pre-swap geometry (see
   // beginIntervalMorph) and reshapes each candle slot toward its new counterpart.
-  const startIntervalMorph = useCallback((h: ChartHandle) => {
+  // `durationMs` overrides transitionMs for the loading hand-off, which splits
+  // it across two stages.
+  const startIntervalMorph = useCallback((h: ChartHandle, durationMs?: number) => {
     const { ms, easing } = animRef.current;
+    const dur = durationMs ?? ms;
     const start = performance.now();
     const step = (now: number) => {
-      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);
@@ -510,6 +530,44 @@ export function useChartCore(
     intervalMorphRaf.current = requestAnimationFrame(step);
   }, []);
 
+  // Hands the loading line over to the data that just landed, in two stages:
+  // the line reshapes into the series' silhouette, then the candles grow out of
+  // it while it fades.
+  //
+  // Sequential rather than overlapped — the shape has to read as the data
+  // before the bars start emerging from it — so the two split transitionMs and
+  // the whole hand-off costs what any other transition costs.
+  const startLoadingHandoff = useCallback(
+    (h: ChartHandle) => {
+      const { ms, easing } = animRef.current;
+      const half = ms / 2;
+      loadingHandoffRef.current = true;
+      h.beginLoadingMorph();
+      const start = performance.now();
+      const step = (now: number) => {
+        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;
+        // Past here an interruption is an ordinary interval morph again: the
+        // core has left the loading state, so landing the clock is enough.
+        loadingHandoffRef.current = false;
+        // Stage two rides the interval-morph clock, which also carries the
+        // line's fade-out — so the bars' growth and the line's exit finish
+        // together instead of one outlasting the other.
+        h.beginLoadingReveal();
+        startIntervalMorph(h, half);
+      };
+      intervalMorphRaf.current = requestAnimationFrame(step);
+    },
+    [startIntervalMorph],
+  );
+
   // Stops an in-flight stream animation and puts the chart somewhere coherent.
   //
   // A pending window shift always lands on its target: abandoned mid-slide it
@@ -606,6 +664,17 @@ export function useChartCore(
   const startMs = visibleRange?.startMs ?? 0;
   const endMs = visibleRange?.endMs ?? 0;
 
+  // The core trusts `setLoading` outright, so the "and no data yet" half of the
+  // condition is decided here. Both halves matter: without `loading` a chart
+  // that legitimately has no bars would wave a placeholder forever, and without
+  // the emptiness check a background refresh of a loaded series would blank the
+  // chart the user is already reading.
+  const showLoadingLine = loading === true && candles.length === 0;
+  // Tracks whether the *core* is currently showing the line, which is what
+  // decides if the next data push is a hand-off. Distinct from `showLoadingLine`:
+  // that is this render's intent, this is what's on screen.
+  const lineUpRef = useRef(false);
+
   // Stable deps so inline `theme={{...}}` / `rsi={{...}}` literals don't re-run
   // the effect every render — only when the actual values change.
   const themeKey = theme ? JSON.stringify(theme) : '';
@@ -645,6 +714,31 @@ export function useChartCore(
     // the viewport: a stream leaves it alone, a timeframe switch re-anchors and
     // morphs into it, a different asset resets it.
     let morphing = false;
+
+    if (showLoadingLine) {
+      // Clear the core's buffer, which the `candles.length > 0` gate below
+      // otherwise never does: pushing an empty array is treated as "hold the
+      // last frame" everywhere else, so a chart switching assets would still be
+      // holding the previous one's bars underneath the line — and would
+      // classify the incoming series as a timeframe switch rather than a fresh
+      // load. Scoped to the loading case so that hold-the-last-frame behavior
+      // is untouched for every other empty push.
+      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) {
+      // Loading resolved to nothing — an empty result, or an error the consumer
+      // handled. There's no geometry to morph into, so drop the line rather
+      // than leaving it waving at data that isn't coming.
+      h.setLoading(false, true);
+      lineUpRef.current = false;
+    }
+
     if (candles.length > 0) {
       const prev = prevDataRef.current;
       const freshHandle = prev == null || prev.handle !== h;
@@ -667,6 +761,8 @@ export function useChartCore(
         } | null = null;
         // The pre-swap candle envelope, used to scale-lock the y-axis below.
         let prevEnvelope: { low: number; high: number } | null = null;
+        // Set when this push is the loading line's hand-off to real data.
+        let handOff = false;
         // Set for an animated live update: whether the last bar reshapes, and
         // the window an appended bar should pull the view to.
         let stream: { morph: boolean; window: VisibleRange | null } | null = null;
@@ -747,6 +843,22 @@ export function useChartCore(
           endIntervalMorph();
         }
 
+        // The loading line's data has landed, so it hands over to the series
+        // instead of the chart cutting to it. Always classified 'initial' (the
+        // loading branch above cleared prevDataRef), so this runs after that
+        // branch's endIntervalMorph.
+        if (lineUpRef.current) {
+          lineUpRef.current = false;
+          handOff =
+            animRef.current.ms > 0 &&
+            !animRef.current.reduceMotion &&
+            onFrameRef.current != null;
+          // Snap path only. The hand-off itself starts after setCandles and the
+          // framing below: both its stages aim at where the candles will
+          // actually sit, so neither can be set up until they're there.
+          if (!handOff) h.setLoading(false, true);
+        }
+
         h.setCandles(packCandles(candles));
 
         if (transitionKind === 'timeframe') {
@@ -778,6 +890,9 @@ export function useChartCore(
         } else if (transitionKind === 'reset') {
           h.resetView();
         }
+        // After setCandles and the framing above, so the line aims at — and the
+        // candles grow from — the geometry each bar will actually occupy.
+        if (handOff) startLoadingHandoff(h);
         prevDataRef.current = { handle: h, candles, seriesKey };
       }
     }
@@ -827,7 +942,7 @@ export function useChartCore(
     // fairValueGaps/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, 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 };
 }