react-native-vroom-chart 0.2.0 → 0.5.0

package/cpp/_core_src/ma_overlay.cpp

@@ -10,6 +10,7 @@
 #include "include/core/SkRect.h"
 #pragma clang diagnostic pop
 
+#include <algorithm>
 #include <cmath>
 
 #include "viewport.h"
@@ -29,11 +30,14 @@ void draw(SkCanvas* canvas,
           float candle_area_h,
           uint32_t color,
           float width,
-          const unsigned char* break_before) {
+          const unsigned char* break_before,
+          float opacity) {
     if (!canvas || !values_visible || n == 0 || candle_right <= 0.f ||
         candle_area_h <= 0.f) {
         return;
     }
+    opacity = std::clamp(opacity, 0.f, 1.f);
+    if (opacity <= 0.f) return;
 
     // SkPathBuilder (not SkPath's edit methods, removed in newer Skia tips).
     SkPathBuilder path;
@@ -59,6 +63,10 @@ void draw(SkCanvas* canvas,
     SkPaint line;
     line.setAntiAlias(true);
     line.setColor(static_cast<SkColor>(color));
+    // Fade the line in during the candle→line morph (multiplies the color alpha).
+    if (opacity < 1.f) {
+        line.setAlphaf(line.getAlphaf() * opacity);
+    }
     line.setStyle(SkPaint::kStroke_Style);
     line.setStrokeWidth(width > 0.f ? width : 1.5f);
 
@@ -70,4 +78,71 @@ void draw(SkCanvas* canvas,
     canvas->restore();
 }
 
+void fill_between(SkCanvas* canvas,
+                  const Layout& lay,
+                  const PriceBounds& bounds,
+                  const ::VroomCandle* visible,
+                  std::size_t n,
+                  const double* upper_visible,
+                  const double* lower_visible,
+                  int64_t window_ms,
+                  int64_t visible_start_ms,
+                  int64_t candle_duration_ms,
+                  float candle_right,
+                  float candle_area_h,
+                  uint32_t color,
+                  float opacity) {
+    if (!canvas || !upper_visible || !lower_visible || n == 0 ||
+        candle_right <= 0.f || candle_area_h <= 0.f) {
+        return;
+    }
+    opacity = std::clamp(opacity, 0.f, 1.f);
+    if (opacity <= 0.f) return;
+
+    // One closed contour per maximal run where both series are finite; a
+    // single-point run has no area. Multiple runs (e.g. around a data gap)
+    // become multiple contours in one path.
+    SkPathBuilder path;
+    std::size_t i = 0;
+    while (i < n) {
+        if (!std::isfinite(upper_visible[i]) ||
+            !std::isfinite(lower_visible[i])) {
+            ++i;
+            continue;
+        }
+        std::size_t e = i;
+        while (e + 1 < n && std::isfinite(upper_visible[e + 1]) &&
+               std::isfinite(lower_visible[e + 1])) {
+            ++e;
+        }
+        if (e > i) {
+            const auto x_at = [&](std::size_t k) {
+                return vroom::candle_center_x(lay, visible[k].time_ms,
+                                              candle_duration_ms,
+                                              visible_start_ms, window_ms);
+            };
+            path.moveTo(x_at(i), vroom::price_to_y(lay, bounds, upper_visible[i]));
+            for (std::size_t k = i + 1; k <= e; ++k) {
+                path.lineTo(x_at(k), vroom::price_to_y(lay, bounds, upper_visible[k]));
+            }
+            for (std::size_t k = e + 1; k-- > i;) {
+                path.lineTo(x_at(k), vroom::price_to_y(lay, bounds, lower_visible[k]));
+            }
+            path.close();
+        }
+        i = e + 1;
+    }
+
+    SkPaint fill;
+    fill.setAntiAlias(true);
+    fill.setColor(static_cast<SkColor>(color));
+    fill.setAlphaf(fill.getAlphaf() * opacity);
+    fill.setStyle(SkPaint::kFill_Style);
+
+    canvas->save();
+    canvas->clipRect(SkRect::MakeLTRB(0.f, 0.f, candle_right, candle_area_h));
+    canvas->drawPath(path.detach(), fill);
+    canvas->restore();
+}
+
 }  // namespace vroom::ma_overlay

package/cpp/_core_src/ma_overlay.h

@@ -37,6 +37,28 @@ void draw(SkCanvas* canvas,
           float candle_area_h,
           uint32_t color,
           float width,
-          const unsigned char* break_before = nullptr);
+          const unsigned char* break_before = nullptr,
+          float opacity = 1.f);
+
+// Fills the closed region between two aligned series (NaN where undefined)
+// with `color` at its alpha × `opacity` — used for the Bollinger Band fill.
+// Runs where either series is NaN are skipped, so the fill never bridges the
+// warmup gap. Plain-alpha SkPaint fill, no gradient shader (the Skia gradient
+// APIs diverge across our pinned versions; see liquidity.cpp). Clipped to the
+// candle area like draw().
+void fill_between(SkCanvas* canvas,
+                  const Layout& lay,
+                  const PriceBounds& bounds,
+                  const ::VroomCandle* visible,
+                  std::size_t n,
+                  const double* upper_visible,
+                  const double* lower_visible,
+                  int64_t window_ms,
+                  int64_t visible_start_ms,
+                  int64_t candle_duration_ms,
+                  float candle_right,
+                  float candle_area_h,
+                  uint32_t color,
+                  float opacity);
 
 }  // namespace vroom::ma_overlay

package/cpp/_core_src/theme.cpp

@@ -22,6 +22,7 @@ constexpr uint32_t kDefaultColors[VROOM_COLOR_COUNT_] = {
     0x00000000,  // WICK_BEAR   — transparent sentinel: inherit BEAR fill
     0xff26a69a,  // ACCENT_BULL — classic teal-green (price indicator, volume, MACD)
     0xffef5350,  // ACCENT_BEAR — classic red
+    0xffc9d1d9,  // LINE — line-chart close polyline; neutral foreground (AXIS_TEXT tone)
 };
 
 constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
@@ -36,6 +37,7 @@ constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
     0.f,    // CANDLE_RADIUS_PX — square by default
     0.f,    // WICK_ROUND_CAP — butt caps by default
     0.f,    // VOLUME_RADIUS_PX — square by default
+    1.5f,   // LINE_WIDTH_PX — line-chart polyline stroke width
 };
 
 }  // namespace

package/lib/index.d.mts

@@ -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 };