react-native-vroom-chart 0.1.4 → 0.4.0

package/cpp/_core_src/liquidity.cpp

@@ -0,0 +1,112 @@
+#include "liquidity.h"
+
+#include <algorithm>
+#include <cstdint>
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#include "include/core/SkCanvas.h"
+#include "include/core/SkColor.h"
+#include "include/core/SkPaint.h"
+#include "include/core/SkPoint.h"
+#include "include/core/SkRect.h"
+#include "include/core/SkShader.h"
+#include "include/core/SkTileMode.h"
+// Skia's linear-gradient API differs across the Skia versions we build against:
+// the WASM build uses a newer Skia (SkGradient.h + SkShaders::LinearGradient),
+// while react-native-skia bundles an older one (SkGradientShader::MakeLinear).
+// Neither ships both headers, so select whichever is present.
+#if __has_include("include/effects/SkGradient.h")
+#  include "include/core/SkSpan.h"
+#  include "include/effects/SkGradient.h"
+#  define VROOM_SK_MODERN_GRADIENT 1
+#else
+#  include "include/effects/SkGradientShader.h"
+#  define VROOM_SK_MODERN_GRADIENT 0
+#endif
+#pragma clang diagnostic pop
+
+#include "chart.h"
+
+namespace vroom::liquidity {
+namespace {
+
+// A horizontal shader fading from transparent at the left of `pts` to `base` at
+// opacity `alpha` on the right, keeping RGB constant so the faded edge doesn't
+// darken toward black. Abstracts over the two Skia gradient APIs above.
+sk_sp<SkShader> left_fade_shader(const SkPoint pts[2], SkColor base, float alpha) {
+#if VROOM_SK_MODERN_GRADIENT
+    const float r = SkColorGetR(base) / 255.f;
+    const float g = SkColorGetG(base) / 255.f;
+    const float b = SkColorGetB(base) / 255.f;
+    const SkColor4f colors[2] = {SkColor4f{r, g, b, 0.f}, SkColor4f{r, g, b, alpha}};
+    const SkGradient::Colors grad_colors(
+        SkSpan<const SkColor4f>(colors, 2), SkTileMode::kClamp);
+    const SkGradient grad(grad_colors, SkGradient::Interpolation{});
+    return SkShaders::LinearGradient(pts, grad);
+#else
+    const auto a = static_cast<U8CPU>(alpha * 255.f + 0.5f);
+    const SkColor colors[2] = {SkColorSetA(base, 0), SkColorSetA(base, a)};
+    return SkGradientShader::MakeLinear(pts, colors, nullptr, 2, SkTileMode::kClamp);
+#endif
+}
+
+}  // namespace
+
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const Layout& lay,
+          const PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h) {
+    if (!canvas || candle_right <= 0.f || candle_area_h <= 0.f) return;
+    if (chart.bands.empty()) return;
+
+    const VroomLiquidityStyle& style = chart.liquidity_style;
+
+    // Leftward reach: the smaller of the px cap and the pane-fraction, clamped so
+    // the band never starts left of the pane.
+    const float frac_reach = style.width_frac > 0.f ? style.width_frac * candle_right
+                                                    : candle_right;
+    const float px_reach = style.width_px > 0.f ? style.width_px : candle_right;
+    const float reach = std::min(px_reach, frac_reach);
+    const float left_x = std::max(0.f, candle_right - reach);
+
+    // Volume that maps to peak opacity: explicit, or the largest band's volume.
+    double max_vol = style.max_volume;
+    if (max_vol <= 0.0) {
+        for (const VroomBand& b : chart.bands) max_vol = std::max(max_vol, b.volume);
+    }
+
+    const float min_op = std::clamp(style.min_opacity, 0.f, 1.f);
+    const float max_op = std::clamp(style.max_opacity, 0.f, 1.f);
+
+    canvas->save();
+    canvas->clipRect(SkRect::MakeLTRB(0.f, 0.f, candle_right, candle_area_h));
+
+    const SkPoint pts[2] = {SkPoint{left_x, 0.f}, SkPoint{candle_right, 0.f}};
+
+    for (const VroomBand& b : chart.bands) {
+        // Higher price -> smaller y, so max_price is the top edge.
+        const float y_top = vroom::price_to_y(lay, bounds, b.max_price);
+        const float y_bot = vroom::price_to_y(lay, bounds, b.min_price);
+        if (y_bot < 0.f || y_top > candle_area_h) continue;  // fully off-pane
+
+        const SkColor base =
+            static_cast<SkColor>(b.side == 0 ? style.buy_color : style.sell_color);
+
+        const double t = max_vol > 0.0
+            ? std::clamp(b.volume / max_vol, 0.0, 1.0)
+            : 0.0;
+        const float alpha = min_op + (max_op - min_op) * static_cast<float>(t);
+
+        SkPaint paint;
+        paint.setAntiAlias(true);
+        paint.setShader(left_fade_shader(pts, base, alpha));
+        canvas->drawRect(SkRect::MakeLTRB(left_x, y_top, candle_right, y_bot), paint);
+    }
+
+    canvas->restore();
+}
+
+}  // namespace vroom::liquidity

package/cpp/_core_src/liquidity.h

@@ -0,0 +1,35 @@
+// Liquidity bands — resting-order / order-book depth rendered on the price pane.
+//
+// Each band (chart.bands) is a price interval carrying a total size on one side
+// of the book. It is drawn as a horizontal rectangle anchored at the inner edge
+// of the price axis (`candle_right`), stretching left by the configured reach
+// and fading to transparent with a left->right gradient. Color comes from the
+// band's side (buy/sell); the band's alpha comes from its volume mapped into
+// [min_opacity, max_opacity]. Because the vertical extent is derived from price
+// via price_to_y, bands scale with the y-axis on zoom.
+//
+// Like ma_overlay / drawings this is its own module so the chart orchestrator
+// stays thin. Drawn BEHIND the candles (before candles::draw) so candle bodies
+// paint over the bands.
+
+#pragma once
+
+#include "viewport.h"
+#include "vroom/vroom_chart.h"
+
+class SkCanvas;
+struct VroomChart;
+
+namespace vroom::liquidity {
+
+// Draws the liquidity bands. `candle_right` is the x of the price-axis strip
+// (bands' right edge); `candle_area_h` is the price-pane bottom. Geometry is
+// clipped to that rectangle so bands never bleed into the axis strips.
+void draw(SkCanvas* canvas,
+          const VroomChart& chart,
+          const vroom::Layout& lay,
+          const vroom::PriceBounds& bounds,
+          float candle_right,
+          float candle_area_h);
+
+}  // namespace vroom::liquidity

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);
 

package/cpp/_core_src/ma_overlay.h

@@ -37,6 +37,7 @@ 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);
 
 }  // 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_] = {
@@ -33,6 +34,10 @@ constexpr float kDefaultFloats[VROOM_FLOAT_COUNT_] = {
     22.f,   // X_AXIS_HEIGHT_PX — bottom strip for time labels
     0.5f,   // VOLUME_OPACITY — candle color at 50% transparency
     0.20f,  // INDICATOR_HEIGHT_FRAC — below-chart indicator pane = 20% of height
+    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/cpp/_core_src/volume.cpp

@@ -4,6 +4,7 @@
 #pragma clang diagnostic ignored "-Wdocumentation"
 #include "include/core/SkCanvas.h"
 #include "include/core/SkPaint.h"
+#include "include/core/SkRRect.h"
 #include "include/core/SkRect.h"
 #pragma clang diagnostic pop
 
@@ -41,6 +42,7 @@ void draw(SkCanvas* canvas,
     const float half_body = body_w * 0.5f;
 
     const float opacity = theme.floats[VROOM_FLOAT_VOLUME_OPACITY];
+    const float vol_r = theme.floats[VROOM_FLOAT_VOLUME_RADIUS_PX];
     SkPaint bull_paint;
     bull_paint.setAntiAlias(true);
     bull_paint.setColor(theme.colors[VROOM_COLOR_ACCENT_BULL]);
@@ -61,9 +63,19 @@ void draw(SkCanvas* canvas,
             visible_start_ms, window_ms);
         const float h = std::max(
             1.f, static_cast<float>(c.volume / max_vol) * region_h);
-        canvas->drawRect(
-            SkRect::MakeXYWH(cx - half_body, candle_area_h - h, body_w, h),
-            bull ? bull_paint : bear_paint);
+        const SkRect rect =
+            SkRect::MakeXYWH(cx - half_body, candle_area_h - h, body_w, h);
+        const SkPaint& paint = bull ? bull_paint : bear_paint;
+        // Round only the top corners; clamp so short/narrow bars don't over-round.
+        const float r = std::min({vol_r, body_w * 0.5f, h});
+        if (r > 0.f) {
+            SkRRect rr;
+            const SkVector radii[4] = {{r, r}, {r, r}, {0, 0}, {0, 0}};  // TL, TR, BR, BL
+            rr.setRectRadii(rect, radii);
+            canvas->drawRRect(rr, paint);
+        } else {
+            canvas->drawRect(rect, paint);
+        }
     }
 }
 

package/lib/index.d.mts

@@ -68,14 +68,22 @@ type VroomTheme = {
     accentBull?: VroomColor;
     /** Generic down color for the price indicator, volume bars, and MACD histogram. Defaults to red; independent of `bear`. */
     accentBear?: VroomColor;
-    /** Up candle body 1px border. Defaults to the bull fill color. */
+    /** Up candle body border (1px, drawn *inside* the body so it never changes candle width). Omit or set to the bull fill color to hide it. */
     borderBull?: VroomColor;
-    /** Down candle body 1px border. Defaults to the bear fill color. */
+    /** Down candle body border (1px, drawn *inside* the body so it never changes candle width). Omit or set to the bear fill color to hide it. */
     borderBear?: VroomColor;
     /** Up candle wick color. Defaults to the bull fill color. */
     wickBull?: VroomColor;
     /** Down candle wick color. Defaults to the bear fill color. */
     wickBear?: VroomColor;
+    /** Wick stroke width in px (applies to both up and down wicks). Defaults to 1. */
+    wickWidth?: number;
+    /** Corner radius (px) of candle bodies. Defaults to 0 (square). */
+    candleRadius?: number;
+    /** Round the wick end caps. Defaults to false. */
+    wickRoundCap?: boolean;
+    /** Corner radius (px) of the *top* of volume bars. Defaults to 0 (square). */
+    volumeRadius?: number;
     /** Gridlines. */
     grid?: VroomColor;
     /** Axis label text (price + time). */
@@ -84,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 = {
@@ -98,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). */
@@ -107,23 +126,81 @@ 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>;
+};
 /** RSI indicator config. Rendered in a pane below the candles when enabled. */
 type RSIConfig = {
     enabled?: boolean;
@@ -169,6 +246,51 @@ type VWAPConfig = {
     /** Stroke width in px. Default 1.5. */
     width?: 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
+ * passing them. The vertical extent is defined in price space, so bands scale
+ * with the y-axis on zoom.
+ */
+type LiquidityBand = {
+    /** Bottom of the price interval. */
+    minPrice: number;
+    /** Top of the price interval. A per-level order uses a thin interval. */
+    maxPrice: number;
+    /** Which side of the book — selects the buy vs sell color. */
+    side: 'buy' | 'sell';
+    /** Total resting size in this band; drives the band's opacity. */
+    volume: number;
+};
+/**
+ * Resting-order / order-book liquidity overlay. Each band is drawn as a
+ * horizontal rectangle anchored at the inner edge of the price axis, stretching
+ * left (~`widthPx`/`widthFrac` of the pane) and fading out with a gradient,
+ * colored by side and made more opaque with volume. Rendered behind the candles.
+ * Omit the prop (or pass no bands) to hide the overlay.
+ */
+type LiquidityConfig = {
+    /** The bands to render. */
+    bands: LiquidityBand[];
+    /** Buy-side color (hex string or packed ARGB number). Default teal-green. */
+    buyColor?: VroomColor;
+    /** Sell-side color (hex string or packed ARGB number). Default red. */
+    sellColor?: VroomColor;
+    /**
+     * Volume mapped to the peak (`maxOpacity`) band. Omit to auto-scale to the
+     * largest band's volume each render.
+     */
+    maxVolume?: number;
+    /** Opacity floor for the smallest band. Default 0.05. */
+    minOpacity?: number;
+    /** Opacity at `maxVolume`. Default 0.8. */
+    maxOpacity?: number;
+    /** Leftward reach from the axis in px. Default 300. */
+    widthPx?: number;
+    /** Leftward reach as a fraction of pane width. Default 0.25. The smaller of
+     * `widthPx` and `widthFrac * paneWidth` is used. */
+    widthFrac?: number;
+};
 /** MACD indicator config. Rendered in its own pane below the candles. */
 type MACDConfig = {
     enabled?: boolean;
@@ -204,6 +326,26 @@ type VroomChartCoreProps = {
     height?: number;
     /** Time window to render. Omit (or both 0) to show every candle. */
     visibleRange?: VisibleRange;
+    /**
+     * Target candle *body* width in logical px for the INITIAL framing. Larger →
+     * more zoomed in (fewer candles); smaller → more zoomed out. Only affects
+     * first load / reset; an explicit `visibleRange` takes precedence. Omit for
+     * the default (~80 candles). Useful to keep candles a consistent size across
+     * 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;
@@ -213,6 +355,8 @@ type VroomChartCoreProps = {
     movingAverages?: MovingAverageOverlay[];
     /** VWAP overlay (session anchor, configurable reset). */
     vwap?: VWAPConfig;
+    /** Resting-order / order-book liquidity bands drawn behind the candles. */
+    liquidity?: LiquidityConfig;
     /**
      * Pixels the crosshair dot / horizontal line sit *above* the touch point so
      * they aren't hidden under the thumb. The vertical line stays centered on the
@@ -243,10 +387,30 @@ 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
@@ -286,4 +450,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 Candle, type ChartType, type CrosshairEvent, type MACDConfig, type MASource, type MovingAverageOverlay, type RSIConfig, type VWAPConfig, type VisibleRange, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };