react-native-vroom-chart 0.2.0 → 0.5.0

package/lib/index.d.ts

@@ -92,6 +92,10 @@ type VroomTheme = {
     crosshair?: VroomColor;
     /** Crosshair target — the hollow ring/dot at the intersection. */
     crosshairTarget?: VroomColor;
+    /** Line-chart-mode close polyline color. Defaults to a neutral foreground. */
+    lineColor?: VroomColor;
+    /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
+    lineWidth?: number;
 };
 /** A time window over the candle data, as Unix epoch milliseconds. */
 type VisibleRange = {
@@ -106,8 +110,15 @@ type VisibleRange = {
  *   'draw' — left-clicks place drawing points; panning/zooming are suppressed.
  */
 type ChartMode = 'pan' | 'draw';
+/**
+ * How the price series is drawn.
+ *   'candles' — default: candlestick bodies + wicks.
+ *   'line'    — a single polyline through each candle's close. Volume, indicators,
+ *               overlays, crosshair, and drawings still render.
+ */
+type ChartType = 'candles' | 'line';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
-type DrawTool = null | 'line';
+type DrawTool = null | 'line' | 'box' | 'pencil';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
 type DrawPoint = {
     /** Anchor time as Unix epoch milliseconds (not snapped to a candle slot). */
@@ -115,23 +126,106 @@ type DrawPoint = {
     /** Anchor price. */
     price: number;
 };
-/**
- * A committed drawing. Pass an array of these via the `drawings` prop to render
- * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
- * each time the user finishes drawing. For now only the `'line'` (two-point
- * trendline) type exists.
- */
-type Drawing = {
+/** Fields shared by every drawing type. */
+type DrawingBase = {
     /** Stable unique id (the chart generates one for drawings it creates). */
     id: string;
-    type: 'line';
-    /** The two endpoints, in data space. */
-    points: [DrawPoint, DrawPoint];
-    /** Line color (hex string or packed ARGB number). Default solid blue. */
+    /** Stroke color (hex string or packed ARGB number). Default solid blue. */
     color?: VroomColor;
     /** Stroke width in px. Default 2. */
     width?: number;
 };
+/** A two-point trendline from `points[0]` to `points[1]`. */
+type LineDrawing = DrawingBase & {
+    type: 'line';
+    /** The two endpoints, in data space. */
+    points: [DrawPoint, DrawPoint];
+};
+/**
+ * An axis-aligned rectangle whose two opposite corners are `points[0]` and
+ * `points[1]` (the other two corners are derived).
+ */
+type BoxDrawing = DrawingBase & {
+    type: 'box';
+    /** Two opposite corners, in data space. */
+    points: [DrawPoint, DrawPoint];
+};
+/**
+ * A freehand pencil stroke: an open path through `points`, in order. Unlike the
+ * other tools a stroke has a variable number of points, and once committed it
+ * can only be translated — never reshaped.
+ */
+type PencilDrawing = DrawingBase & {
+    type: 'pencil';
+    /** The path's points in draw order (at least 2), in data space. */
+    points: DrawPoint[];
+};
+/**
+ * A committed drawing. Pass an array of these via the `drawings` prop to render
+ * persisted annotations; the chart appends a new one (via `onDrawingComplete`)
+ * each time the user finishes drawing.
+ *
+ * This is a discriminated union on `type` — narrow on it before reading
+ * `points[1]`, since a `'pencil'` stroke has a variable-length array while
+ * `'line'` and `'box'` are always exactly two points.
+ */
+type Drawing = LineDrawing | BoxDrawing | PencilDrawing;
+/**
+ * Storage adapter for **managed** drawing persistence. Provide it via the
+ * `drawingStore` prop and the chart owns the drawings array itself — loading and
+ * saving through this adapter instead of you wiring the controlled `drawings`
+ * prop + `onDrawing*` callbacks.
+ *
+ * The adapter is an **opaque string key-value store** — the chart serializes
+ * drawings into a **versioned envelope** (`{ v, drawings }`) and hands you the
+ * string; you just persist bytes. Because the library owns the schema and
+ * migrates old payloads on load, adding drawing tools or persisted fields later
+ * never changes this interface — your adapter is written once.
+ *
+ * `marketId` is the chart's `seriesKey`, so drawings are bucketed per market:
+ * they persist across timeframe changes (same key) but not across markets. Both
+ * methods may be async (localStorage is sync; AsyncStorage / MMKV / a REST
+ * backend are async). The chart debounces `save`. Consumers that only handle a
+ * single market can ignore `marketId`.
+ */
+type DrawingStore = {
+    /**
+     * Return the raw string previously handed to `save` for `marketId`, or
+     * `null`/`undefined`/`''` if nothing is stored. Sync or async.
+     */
+    load: (marketId: string) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Persist the opaque `data` string for `marketId`. Sync or async; the chart
+     * debounces calls. The string is a versioned envelope owned by the library —
+     * store it verbatim, don't parse or reshape it.
+     */
+    save: (marketId: string, data: string) => void | Promise<void>;
+};
+/**
+ * Whether undo/redo are currently available for the chart's drawings — the
+ * payload of `onHistoryChange`, for binding toolbar button enabled-states.
+ */
+type UndoRedoState = {
+    canUndo: boolean;
+    canRedo: boolean;
+};
+/**
+ * Programmatic undo/redo controls, published through the `historyRef` prop in
+ * managed mode — for toolbar buttons and other UI outside the chart. The
+ * keyboard shortcuts (⌘Z / ⇧⌘Z / Ctrl+Y) work without this.
+ */
+type UndoRedoControls = {
+    /** Roll back the most recent committed drawing action. No-op when empty. */
+    undo: () => void;
+    /** Re-apply the most recently undone action. No-op when empty. */
+    redo: () => void;
+    /**
+     * Drop the undo/redo stacks without touching the drawings. Rarely needed —
+     * users find a cleared history surprising — but useful when reusing a mounted
+     * chart for what the user perceives as a brand-new context.
+     */
+    clearHistory: () => void;
+};
 /** RSI indicator config. Rendered in a pane below the candles when enabled. */
 type RSIConfig = {
     enabled?: boolean;
@@ -177,6 +271,42 @@ type VWAPConfig = {
     /** Stroke width in px. Default 1.5. */
     width?: number;
 };
+/**
+ * Bollinger Bands overlay config. A basis moving average of `source` over
+ * `period`, banded at ± `stdDev` × population standard deviation of the same
+ * window, drawn as three lines on the price pane with an optional translucent
+ * fill between the bands. No pane is reserved.
+ */
+type BollingerBandsConfig = {
+    enabled?: boolean;
+    /** Lookback in candles. Default 20, clamped to >= 1. */
+    period?: number;
+    /** Standard-deviation multiplier. Default 2. */
+    stdDev?: number;
+    /** Price source. Default 'close'. */
+    source?: MASource;
+    /**
+     * Basis (middle) line type. Default 'sma'. The stdev always uses the
+     * window's arithmetic mean, even with an EMA basis (TradingView semantics).
+     */
+    basis?: 'sma' | 'ema';
+    /** Upper band color (hex string or packed ARGB number). Default blue. */
+    upperColor?: string | number;
+    /** Upper band stroke width in px. Default 1. */
+    upperWidth?: number;
+    /** Basis (middle) line color. Default orange. */
+    middleColor?: string | number;
+    /** Basis line stroke width in px. Default 1. */
+    middleWidth?: number;
+    /** Lower band color. Default blue. */
+    lowerColor?: string | number;
+    /** Lower band stroke width in px. Default 1. */
+    lowerWidth?: number;
+    /** Translucent fill between the bands. Default true. */
+    fill?: boolean;
+    /** Fill opacity 0..1, applied to the upper band color. Default 0.1. */
+    fillOpacity?: number;
+};
 /**
  * A single resting-liquidity band: a price interval carrying a total order size
  * on one side of the book. Consolidate raw L2 levels into these buckets before
@@ -265,6 +395,18 @@ type VroomChartCoreProps = {
      * devices of different widths.
      */
     defaultCandleWidth?: number;
+    /**
+     * Price-series render style. `'candles'` (default) draws candlesticks;
+     * `'line'` draws a polyline through each candle's close (style it with
+     * `theme.lineColor` / `theme.lineWidth`). All other layers are unaffected.
+     */
+    chartType?: ChartType;
+    /**
+     * Duration (ms) of the animated candle↔line transition when `chartType`
+     * changes. Default ~300. `0` snaps instantly. Ignored (snaps) when the OS
+     * requests reduced motion, which instead uses a plain cross-fade.
+     */
+    transitionMs?: number;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
@@ -274,6 +416,8 @@ type VroomChartCoreProps = {
     movingAverages?: MovingAverageOverlay[];
     /** VWAP overlay (session anchor, configurable reset). */
     vwap?: VWAPConfig;
+    /** Bollinger Bands overlay (three lines + fill on the price pane). */
+    bollingerBands?: BollingerBandsConfig;
     /** Resting-order / order-book liquidity bands drawn behind the candles. */
     liquidity?: LiquidityConfig;
     /**
@@ -306,16 +450,70 @@ type VroomChartCoreProps = {
      * Committed drawings to render, anchored to data so they track the candles on
      * pan/zoom. This is a controlled prop: append the value the chart hands you in
      * `onDrawingComplete` to persist it.
+     *
+     * Ignored when `drawingStore` is set (the chart then owns the array itself).
      */
     drawings?: Drawing[];
+    /**
+     * Opt into **managed** drawing persistence: the chart owns the drawings array
+     * internally and loads/saves it through this adapter, keyed by `seriesKey`.
+     * When set, `drawings` and the `onDrawing*` callbacks are ignored. Web only.
+     * Requires `seriesKey` — without one, drawings work in-session but aren't saved.
+     */
+    drawingStore?: DrawingStore;
     /** Fired with the finished drawing when the user completes one. */
     onDrawingComplete?: (drawing: Drawing) => void;
+    /**
+     * Fired after the user drags a selected line's endpoint handle. The payload is
+     * the same drawing (same `id`) with updated `points`; apply it to your
+     * controlled `drawings` state (replace by id). Web only.
+     */
+    onDrawingChange?: (drawing: Drawing) => void;
+    /**
+     * Fired when the user deletes the selected line (Backspace/Delete). Remove the
+     * drawing with this `id` from your controlled `drawings` state. Web only.
+     */
+    onDrawingDelete?: (id: string) => void;
     /**
      * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
      * the user clicks away from a just-drawn line. Since `mode` is controlled, the
      * host should apply the requested mode.
      */
     onModeChange?: (mode: ChartMode) => void;
+    /**
+     * Max drawing undo depth in managed mode (one step = one committed drawing
+     * action). Oldest steps are evicted beyond this. Default 100. History is
+     * in-memory and per-`seriesKey`: it resets on market switch and is never
+     * persisted — only the drawings themselves are saved. Web only.
+     */
+    historyLimit?: number;
+    /**
+     * Fired when drawing undo/redo availability changes in managed mode — bind
+     * toolbar undo/redo buttons' enabled-state to it. (In controlled mode you own
+     * the history, so track availability yourself.) Web only.
+     */
+    onHistoryChange?: (state: UndoRedoState) => void;
+    /**
+     * Receives programmatic `undo`/`redo`/`clearHistory` controls in managed mode
+     * (e.g. `useRef<UndoRedoControls | null>(null)` passed here, then
+     * `historyRef.current?.undo()` from a toolbar button). Set to `null` while
+     * unmounted or when no `drawingStore` is present. Web only.
+     */
+    historyRef?: {
+        current: UndoRedoControls | null;
+    };
+    /**
+     * Fired when the user presses the undo shortcut (⌘Z / Ctrl+Z) in controlled
+     * mode — apply the undo to your own drawings state. Ignored when
+     * `drawingStore` is set (managed mode undoes internally). Web only.
+     */
+    onUndo?: () => void;
+    /**
+     * Fired when the user presses the redo shortcut (⇧⌘Z / Ctrl+Shift+Z /
+     * Ctrl+Y) in controlled mode — apply the redo to your own drawings state.
+     * Ignored when `drawingStore` is set. Web only.
+     */
+    onRedo?: () => void;
     onCrosshair?: (e: CrosshairEvent) => void;
     onViewportChange?: (startMs: number, endMs: number) => void;
 };
@@ -349,4 +547,4 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-export { type Candle, type CrosshairEvent, type MACDConfig, type MASource, type MovingAverageOverlay, type RSIConfig, type VWAPConfig, type VisibleRange, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type MACDConfig, type MASource, type MovingAverageOverlay, type RSIConfig, type VWAPConfig, type VisibleRange, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };

package/lib/index.js

@@ -92,16 +92,20 @@ var COLOR_KEYS = {
   // VROOM_COLOR_WICK_BEAR
   accentBull: 14,
   // VROOM_COLOR_ACCENT_BULL
-  accentBear: 15
+  accentBear: 15,
   // VROOM_COLOR_ACCENT_BEAR
+  lineColor: 16
+  // VROOM_COLOR_LINE
 };
 var FLOAT_KEYS = {
   wickWidth: 1,
   // VROOM_FLOAT_WICK_WIDTH_PX
   candleRadius: 8,
   // VROOM_FLOAT_CANDLE_RADIUS_PX
-  volumeRadius: 10
+  volumeRadius: 10,
   // VROOM_FLOAT_VOLUME_RADIUS_PX
+  lineWidth: 11
+  // VROOM_FLOAT_LINE_WIDTH_PX
 };
 var BOOL_KEYS = {
   wickRoundCap: 9
@@ -157,6 +161,26 @@ function overlayToNumeric(o) {
     width: o.width ?? 1.5
   };
 }
+var DEFAULT_BB_BAND_COLOR = 4280902399;
+var DEFAULT_BB_BASIS_COLOR = 4294929664;
+function bollingerToSpec(cfg) {
+  const srcIdx = cfg?.source ? MA_SOURCES.indexOf(cfg.source) : 0;
+  return {
+    enabled: cfg?.enabled ?? false,
+    period: cfg?.period ?? 20,
+    mult: cfg?.stdDev ?? 2,
+    source: srcIdx < 0 ? 0 : srcIdx,
+    basisKind: cfg?.basis === "ema" ? 1 : 0,
+    upperColor: (cfg?.upperColor != null ? parseColor(cfg.upperColor) : null) ?? DEFAULT_BB_BAND_COLOR,
+    upperWidth: cfg?.upperWidth ?? 1,
+    middleColor: (cfg?.middleColor != null ? parseColor(cfg.middleColor) : null) ?? DEFAULT_BB_BASIS_COLOR,
+    middleWidth: cfg?.middleWidth ?? 1,
+    lowerColor: (cfg?.lowerColor != null ? parseColor(cfg.lowerColor) : null) ?? DEFAULT_BB_BAND_COLOR,
+    lowerWidth: cfg?.lowerWidth ?? 1,
+    fillEnabled: cfg?.fill ?? true,
+    fillOpacity: cfg?.fillOpacity ?? 0.1
+  };
+}
 var installed = false;
 function ensureInstalled() {
   if (installed) return;
@@ -167,7 +191,7 @@ function ensureInstalled() {
   }
   installed = true;
 }
-function useChartCore(candles, size, visibleRange, defaultCandleWidth, theme, rsi, macd, movingAverages, vwap) {
+function useChartCore(candles, size, visibleRange, defaultCandleWidth, chartType, theme, rsi, macd, movingAverages, vwap, bollingerBands) {
   const handleRef = (0, import_react.useRef)(null);
   const defaultWidthAppliedRef = (0, import_react.useRef)(false);
   const [picture, setPicture] = (0, import_react.useState)(null);
@@ -183,6 +207,7 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, theme, rs
   const macdKey = macd ? JSON.stringify(macd) : "";
   const maKey = movingAverages ? JSON.stringify(movingAverages) : "";
   const vwapKey = vwap ? JSON.stringify(vwap) : "";
+  const bollingerKey = bollingerBands ? JSON.stringify(bollingerBands) : "";
   (0, import_react.useEffect)(() => {
     const h = handleRef.current;
     if (!h) return;
@@ -221,8 +246,9 @@ function useChartCore(candles, size, visibleRange, defaultCandleWidth, theme, rs
       (vwap?.color != null ? parseColor(vwap.color) : null) ?? 4278238420,
       vwap?.width ?? 1.5
     );
+    h.setBollinger(bollingerToSpec(bollingerBands));
     setPicture(h.render());
-  }, [candles, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey]);
+  }, [candles, size.width, size.height, size.pxRatio, explicit, startMs, endMs, defaultCandleWidth, themeKey, rsiKey, macdKey, maKey, vwapKey, bollingerKey]);
   return { handle: handleRef.current, picture };
 }
 
@@ -235,11 +261,14 @@ function VroomChart(props) {
     style,
     visibleRange,
     defaultCandleWidth,
+    chartType,
+    transitionMs,
     theme,
     rsi,
     macd,
     movingAverages,
     vwap,
+    bollingerBands,
     crosshairOffset = 40,
     onCrosshair,
     onViewportChange
@@ -259,11 +288,13 @@ function VroomChart(props) {
     { width, height },
     visibleRange,
     defaultCandleWidth,
+    chartType,
     theme,
     rsi,
     macd,
     movingAverages,
-    vwap
+    vwap,
+    bollingerBands
   );
   const emptyPicture = (0, import_react2.useMemo)(() => {
     const rec = import_react_native_skia.Skia.PictureRecorder();
@@ -307,6 +338,62 @@ function VroomChart(props) {
       }
     };
   }, []);
+  const morphRaf = (0, import_react2.useRef)(null);
+  const morphFade = (0, import_react2.useRef)(null);
+  const morphHandle = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    if (!handle) return void 0;
+    const target = chartType === "line" ? 1 : 0;
+    if (morphHandle.current !== handle || morphFade.current == null) {
+      morphHandle.current = handle;
+      morphFade.current = target;
+      handle.setChartType(target);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      return void 0;
+    }
+    if (morphFade.current === target) return void 0;
+    if (morphRaf.current != null) {
+      cancelAnimationFrame(morphRaf.current);
+      morphRaf.current = null;
+    }
+    const dur = Math.max(0, transitionMs ?? 300);
+    if (dur === 0) {
+      morphFade.current = target;
+      handle.setChartType(target);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      return void 0;
+    }
+    const from = morphFade.current;
+    let startTs = null;
+    const step = (now) => {
+      if (startTs == null) startTs = now;
+      const prog = Math.min(1, (now - startTs) / dur);
+      const e = prog * prog * (3 - 2 * prog);
+      const fade = from + (target - from) * e;
+      morphFade.current = fade;
+      handle.setMorph(fade, fade);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      if (prog < 1) {
+        morphRaf.current = requestAnimationFrame(step);
+      } else {
+        morphRaf.current = null;
+        morphFade.current = target;
+        handle.setChartType(target);
+        const q = handle.render();
+        if (q) pictureSV.value = q;
+      }
+    };
+    morphRaf.current = requestAnimationFrame(step);
+    return () => {
+      if (morphRaf.current != null) {
+        cancelAnimationFrame(morphRaf.current);
+        morphRaf.current = null;
+      }
+    };
+  }, [handle, chartType, transitionMs, pictureSV]);
   const hitAxis = (0, import_react2.useCallback)(
     (x, y) => {
       if (!handle) return "chart";