react-native-vroom-chart 0.6.0 → 0.8.0

package/src/dataTransitions.ts

@@ -0,0 +1,148 @@
+// Mirror of packages/react/src/dataTransitions.ts — the platform packages don't
+// depend on each other, and @vroomchart/types carries types only.
+//
+// Classifies how a new `candles` prop relates to the previous one so the chart
+// can react appropriately: leave the viewport alone for streaming updates,
+// re-anchor the time window for a timeframe switch, or fully reset the view
+// for a different asset. Pure functions, no React — see useChartCore for the
+// orchestration.
+
+import type { Candle, VisibleRange } from '@vroomchart/types';
+
+/**
+ * How a new `candles` array relates to the one the chart already holds:
+ * `'initial'` is the first data, `'stream'` a live update to the same series,
+ * `'timeframe'` the same asset re-bucketed into a different interval, and
+ * `'reset'` a different series entirely.
+ */
+export type DataTransition = 'initial' | 'stream' | 'timeframe' | 'reset';
+
+// A step change below this ratio is treated as the same timeframe. Real steps
+// are exact integer ms; the tolerance only absorbs rounding/DST quirks (the
+// smallest real timeframe jump, 1m -> 2m, is 100% apart).
+const STEP_TOLERANCE = 0.01;
+
+// Same-asset check for a timeframe switch: both series end "now", so their
+// last closes must be close. No asset moves 25% between two consecutive prop
+// pushes; distinct assets within 25% of each other are what `seriesKey` is for.
+const MAX_SAME_ASSET_CLOSE_RATIO = 1.25;
+
+// A coarser bucketing can shift the final bar's open by up to one coarse bar;
+// allow that plus an in-flight bar when checking the two series end together.
+const MAX_END_DRIFT_STEPS = 3;
+
+// Streaming pushes may batch a few bars (e.g. a throttled background tab), but
+// a jump of more than this many steps means the data was re-fetched elsewhere.
+const MAX_STREAM_ADVANCE_STEPS = 5;
+
+/**
+ * The candle period in ms, inferred as the median of the first few intervals
+ * (robust to a single gap). Null when there are fewer than two candles.
+ */
+export function inferStepMs(candles: Candle[]): number | null {
+  if (candles.length < 2) return null;
+  const k = Math.min(candles.length - 1, 8);
+  const diffs: number[] = [];
+  for (let i = 0; i < k; i++) diffs.push(candles[i + 1].timeMs - candles[i].timeMs);
+  diffs.sort((a, b) => a - b);
+  const median = diffs[Math.floor(diffs.length / 2)];
+  return median > 0 ? median : null;
+}
+
+// Index of the candle whose timeMs exactly equals `t`, or -1. Binary search over
+// the ascending-by-time series, so it tolerates interior gaps (missing bars from
+// downtime / illiquid periods) — unlike a uniform-grid index computed from the
+// step, which assumes a hole-free grid.
+function indexByTime(candles: Candle[], t: number): number {
+  let lo = 0;
+  let hi = candles.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const v = candles[mid].timeMs;
+    if (v === t) return mid;
+    if (v < t) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+
+/**
+ * Classify a candles-prop change. `prev` is the previously rendered array
+ * (null on first render); `seriesKeyChanged` forces `reset` regardless of the
+ * data (the explicit escape hatch).
+ *
+ * Constraint: detection compares two immutable snapshots. An array mutated in
+ * place (same reference) never reaches this code — React props must change
+ * identity to re-render.
+ */
+export function classifyTransition(
+  prev: Candle[] | null,
+  next: Candle[],
+  seriesKeyChanged: boolean,
+): DataTransition {
+  if (!prev || prev.length === 0) return 'initial';
+  if (next.length === 0) return 'stream'; // nothing to reframe against
+  if (seriesKeyChanged) return 'reset';
+
+  const prevStep = inferStepMs(prev);
+  const nextStep = inferStepMs(next);
+  if (prevStep == null || nextStep == null) return 'reset'; // too little data to reason
+
+  const prevLast = prev[prev.length - 1];
+  const nextLast = next[next.length - 1];
+
+  if (Math.abs(nextStep - prevStep) <= prevStep * STEP_TOLERANCE) {
+    // Same step: streaming iff prev's last bar still appears in next (covers
+    // append, update-last, and rolling buffers that drop old bars from the
+    // front) and the series only advanced by a few bars. Locate that bar by
+    // timestamp, not by a step-derived index — real series have interior gaps
+    // (downtime / illiquid periods), so a uniform-grid index would miss it and
+    // misread a harmless in-place tick as a reset.
+    // Time alignment alone isn't enough: two assets on the same exchange share
+    // the bar grid, so the bar at the shared timestamp must also be (nearly) the
+    // same bar — update-last moves the close, but never by the same-asset ratio.
+    const idx = indexByTime(next, prevLast.timeMs);
+    const aligned = idx >= 0;
+    const sharedBarRatio =
+      aligned && next[idx].close > 0 && prevLast.close > 0
+        ? Math.max(next[idx].close / prevLast.close, prevLast.close / next[idx].close)
+        : Infinity;
+    const advanced =
+      nextLast.timeMs >= prevLast.timeMs &&
+      nextLast.timeMs - prevLast.timeMs <= MAX_STREAM_ADVANCE_STEPS * nextStep;
+    return sharedBarRatio <= MAX_SAME_ASSET_CLOSE_RATIO && advanced ? 'stream' : 'reset';
+  }
+
+  // Step changed: a timeframe switch iff it still looks like the same asset —
+  // last closes near each other and both series ending around the same time.
+  const closeRatio =
+    prevLast.close > 0 && nextLast.close > 0
+      ? Math.max(nextLast.close / prevLast.close, prevLast.close / nextLast.close)
+      : Infinity;
+  const prevEnd = prevLast.timeMs + prevStep;
+  const nextEnd = nextLast.timeMs + nextStep;
+  const endsTogether =
+    Math.abs(nextEnd - prevEnd) <= MAX_END_DRIFT_STEPS * Math.max(prevStep, nextStep);
+  return closeRatio <= MAX_SAME_ASSET_CLOSE_RATIO && endsTogether ? 'timeframe' : 'reset';
+}
+
+/**
+ * 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
+ * the right edge re-anchors on the newest candle (any future-gap overshoot is
+ * carried over in slots, clamped to the core's 3/4-window cap). The new start
+ * may precede the first candle — that gap is intentional, width wins.
+ */
+export function timeframeWindow(
+  oldWindow: VisibleRange,
+  oldStepMs: number,
+  oldLastMs: number,
+  newStepMs: number,
+  newLastMs: number,
+): VisibleRange {
+  const slots = (oldWindow.endMs - oldWindow.startMs) / oldStepMs;
+  const offsetRaw = (oldWindow.endMs - oldLastMs) / oldStepMs;
+  const offsetSlots = Math.min(Math.max(offsetRaw, 0), slots * 0.75);
+  const endMs = Math.round(newLastMs + offsetSlots * newStepMs);
+  return { startMs: Math.round(endMs - slots * newStepMs), endMs };
+}

package/src/easing.ts

@@ -0,0 +1,40 @@
+// Mirror of packages/react/src/easing.ts — the platform packages don't depend on
+// each other, and @vroomchart/types carries types only.
+
+import type { TransitionEasing } from '@vroomchart/types';
+
+/**
+ * Maps linear animation progress (0..1) to eased progress (0..1) for the chart's
+ * transitions. Unknown values fall back to `'ease-in-out'`, which is a
+ * smoothstep — the curve the candle↔line transition has always used.
+ */
+export function ease(kind: TransitionEasing | undefined, p: number): number {
+  switch (kind) {
+    case 'linear':
+      return p;
+    case 'ease-in':
+      return p * p;
+    case 'ease-out':
+      return p * (2 - p);
+    default:
+      return p * p * (3 - 2 * p);
+  }
+}
+
+// Index order matches VroomEasing in vroom_chart.h.
+const EASINGS: readonly TransitionEasing[] = [
+  'linear',
+  'ease-in',
+  'ease-out',
+  'ease-in-out',
+];
+
+/**
+ * The curve as a `VroomEasing` index, for the animations the core paces itself
+ * (see `setVolumeCollapse`) rather than taking pre-eased progress. Falls back to
+ * `'ease-in-out'`, matching {@link ease}.
+ */
+export function easingIndex(kind: TransitionEasing | undefined): number {
+  const i = kind ? EASINGS.indexOf(kind) : -1;
+  return i < 0 ? EASINGS.indexOf('ease-in-out') : i;
+}

package/src/index.ts

@@ -1,4 +1,10 @@
 export { VroomChart } from './VroomChart';
+export {
+  classifyTransition,
+  inferStepMs,
+  timeframeWindow,
+  type DataTransition,
+} from './dataTransitions';
 export type {
   VroomChartProps,
   Candle,
@@ -9,10 +15,13 @@ export type {
   RSIConfig,
   MACDConfig,
   MASource,
+  MAKind,
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  VolumeConfig,
   ChartType,
+  TransitionEasing,
   PriceLine,
   PriceLinesStyle,
 } from './types';

package/src/jsi.d.ts

@@ -27,6 +27,57 @@ export interface ChartHandle {
   setChartType(mode: number): void;
   /** Candle↔line morph blend: collapse folds candles to close, fade crossfades. */
   setMorph(collapse: number, fade: number): void;
+  /** The current visible time window. {startMs: 0, endMs: 0} = uninitialized. */
+  getVisibleRange(): { startMs: number; endMs: number };
+  /**
+   * Reset to the fresh-mount view: frame the most recent ~80 candles and
+   * re-enable continuous y auto-fit (the price range follows the visible
+   * candles until the next manual y gesture). Use when the data series is
+   * wholesale replaced — e.g. switching assets.
+   */
+  resetView(): void;
+  /**
+   * Re-enable continuous y auto-fit only; the time window is untouched. Use
+   * after repositioning the window for a same-asset data swap (e.g. a
+   * timeframe switch) so the price scale re-fits the newly visible candles.
+   */
+  resetPriceScale(): void;
+  /**
+   * The visible price *envelope* — the min low / max high across the currently
+   * visible candles, i.e. the extent the candles occupy rather than the (wider)
+   * axis range. Null when no candles are visible.
+   */
+  getVisiblePriceEnvelope(): { low: number; high: number } | null;
+  /**
+   * Scale lock for a same-asset data swap that re-buckets the same price action
+   * into a different high-low span (a timeframe switch). Rescales a *manual*
+   * price range so the visible envelope keeps the exact pixel height and
+   * position the given pre-swap envelope had — so candles don't suddenly shrink
+   * or grow when the interval changes.
+   *
+   * Call after setCandles + setVisibleRange, passing the envelope read by
+   * getVisiblePriceEnvelope before the swap. A no-op in auto-y mode (auto-fit is
+   * already span-invariant); falls back to resetPriceScale when either envelope
+   * is degenerate.
+   */
+  preservePriceEnvelope(prevLow: number, prevHigh: number): void;
+  /**
+   * Capture the visible candle geometry so the next data swap can animate as a
+   * reshape rather than a jump: each candle's wick and body slide and stretch
+   * into the shape of its counterpart in the new data.
+   *
+   * Candles are paired by *slot* — position counting back from the right edge of
+   * the visible window, which a timeframe switch preserves. Call before
+   * setCandles, then drive setIntervalMorph from 0 to 1.
+   */
+  beginIntervalMorph(): void;
+  /**
+   * Advance the interval morph started by beginIntervalMorph. `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;
   /** Shifts the visible range by `dx`/`dy` pixels and returns a fresh picture. */
   pan(dx: number, dy: number): SkPicture | null;
   /**
@@ -102,22 +153,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).
+   * 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(
-    enabled: boolean,
-    period: number,
-    upperBand: number,
-    lowerBand: number,
-    maEnabled: boolean,
-    maPeriod: number,
-  ): void;
+  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 +218,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 +244,31 @@ 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

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,14 @@ export type {
   VisibleRange,
   RSIConfig,
   MASource,
+  MAKind,
   MovingAverageOverlay,
   VWAPConfig,
   BollingerBandsConfig,
+  VolumeConfig,
   MACDConfig,
   ChartType,
+  TransitionEasing,
   PriceLine,
   PriceLinesStyle,
 } from '@vroomchart/types';