react-native-vroom-chart 0.6.0 → 0.7.0

package/cpp/_core_src/volume.cpp

@@ -12,11 +12,13 @@
 
 #include "theme.h"
 #include "viewport.h"
+#include "volume_anim.h"
 
 namespace vroom::volume {
 
 namespace {
-constexpr float kVolumeFrac = 0.20f;  // tallest bar = this fraction of the area
+// Ceiling for the tallest bar when the config inherits it.
+constexpr float kDefaultHeightFrac = 0.20f;
 }  // namespace
 
 void draw(SkCanvas* canvas,
@@ -24,6 +26,9 @@ void draw(SkCanvas* canvas,
           std::size_t n,
           const Layout& lay,
           const Theme& theme,
+          const ::VroomVolume& cfg,
+          float collapse_t,
+          int32_t collapse_easing,
           int64_t window_ms,
           int64_t visible_start_ms,
           int64_t candle_duration_ms) {
@@ -34,23 +39,38 @@ void draw(SkCanvas* canvas,
     for (std::size_t i = 0; i < n; ++i) max_vol = std::max(max_vol, visible[i].volume);
     if (max_vol <= 0.0) return;
 
+    // Resolve every inherit sentinel up front so the loop reads plain values.
+    const float height_frac =
+        cfg.height_frac >= 0.f ? cfg.height_frac : kDefaultHeightFrac;
+    const float opacity = cfg.opacity >= 0.f
+        ? cfg.opacity
+        : theme.floats[VROOM_FLOAT_VOLUME_OPACITY];
+    const float vol_r = cfg.radius_px >= 0.f
+        ? cfg.radius_px
+        : theme.floats[VROOM_FLOAT_VOLUME_RADIUS_PX];
+    const SkColor up_color = cfg.up_color != 0
+        ? static_cast<SkColor>(cfg.up_color)
+        : theme.colors[VROOM_COLOR_ACCENT_BULL];
+    const SkColor down_color = cfg.down_color != 0
+        ? static_cast<SkColor>(cfg.down_color)
+        : theme.colors[VROOM_COLOR_ACCENT_BEAR];
+
     const float candle_area_h = vroom::price_pane_bottom(lay);
-    const float region_h = candle_area_h * kVolumeFrac;
+    const float region_h = candle_area_h * height_frac;
+    if (region_h <= 0.f) return;
 
     const float body_w = vroom::candle_body_width(
         lay, window_ms, candle_duration_ms);
     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]);
+    bull_paint.setColor(up_color);
     bull_paint.setAlphaf(opacity);
 
     SkPaint bear_paint;
     bear_paint.setAntiAlias(true);
-    bear_paint.setColor(theme.colors[VROOM_COLOR_ACCENT_BEAR]);
+    bear_paint.setColor(down_color);
     bear_paint.setAlphaf(opacity);
 
     for (std::size_t i = 0; i < n; ++i) {
@@ -61,8 +81,13 @@ void draw(SkCanvas* canvas,
         const float cx = vroom::candle_center_x(
             lay, c.time_ms, candle_duration_ms,
             visible_start_ms, window_ms);
-        const float h = std::max(
-            1.f, static_cast<float>(c.volume / max_vol) * region_h);
+        // The 1px floor applies to the settled height, not the animated one, so
+        // a collapsing bar can still reach zero.
+        const float frac = static_cast<float>(c.volume / max_vol);
+        const float full_h = std::max(1.f, frac * region_h);
+        const float h = full_h * (1.f - vroom::volume_anim::bar_collapse(
+                                            frac, collapse_t, collapse_easing));
+        if (h < 0.5f) continue;  // collapsed past the point of drawing anything
         const SkRect rect =
             SkRect::MakeXYWH(cx - half_body, candle_area_h - h, body_w, h);
         const SkPaint& paint = bull ? bull_paint : bear_paint;

package/cpp/_core_src/volume.h

@@ -21,12 +21,23 @@ namespace vroom::volume {
 
 // Draws a volume bar for each candle in [visible, visible + n). Bars share the
 // candles' x/width (via candle_center_x / candle_body_width) so they scroll and
-// resize with the candles. Heights auto-fit to the max volume in the slice.
+// resize with the candles. Heights auto-fit to the max volume in the slice, so
+// the loudest bar lands on cfg.height_frac of the pane.
+//
+// `cfg` supplies height/opacity/radius/colors; each of its style fields falls
+// back to `theme` when left on its inherit sentinel.
+//
+// `collapse_t` (0 = full height, 1 = flat) staggers the bars down out of view,
+// tallest first, all landing together — see volume_anim.h. It's also the
+// visibility gate: callers skip this entirely at 1, since nothing would draw.
 void draw(SkCanvas* canvas,
           const ::VroomCandle* visible,
           std::size_t n,
           const Layout& lay,
           const Theme& theme,
+          const ::VroomVolume& cfg,
+          float collapse_t,
+          int32_t collapse_easing,
           int64_t window_ms,
           int64_t visible_start_ms,
           int64_t candle_duration_ms);

package/cpp/_core_src/volume_anim.cpp

@@ -0,0 +1,32 @@
+#include "volume_anim.h"
+
+#include <algorithm>
+
+#include "vroom/vroom_chart.h"
+
+namespace vroom::volume_anim {
+
+float ease(int32_t kind, float p) {
+    const float t = std::clamp(p, 0.f, 1.f);
+    switch (kind) {
+        case VROOM_EASING_LINEAR:
+            return t;
+        case VROOM_EASING_IN:
+            return t * t;
+        case VROOM_EASING_OUT:
+            return t * (2.f - t);
+        default:
+            return t * t * (3.f - 2.f * t);  // smoothstep
+    }
+}
+
+float bar_collapse(float frac, float t, int32_t easing) {
+    const float progress = std::clamp(t, 0.f, 1.f);
+    const float window = std::clamp(frac, kMinWindow, 1.f);
+    // The window occupies the tail of the timeline, so a taller bar (bigger
+    // window) opens earlier. Every window ends at 1.
+    const float start = 1.f - window;
+    return ease(easing, (progress - start) / window);
+}
+
+}  // namespace vroom::volume_anim

package/cpp/_core_src/volume_anim.h

@@ -0,0 +1,41 @@
+// Volume-bar collapse timing — pure functions, no Skia, no state.
+//
+// Split out from volume.cpp so the stagger arithmetic unit-tests without a Skia
+// checkout, and so the one piece of easing the core owns lives somewhere
+// obvious.
+//
+// Unlike the candle↔line and interval morphs, the host can't pre-ease this
+// animation: every bar runs on its own window, so easing has to be applied per
+// bar, after the window split. Feed bar_collapse the raw linear progress.
+
+#pragma once
+
+#include <cstdint>
+
+namespace vroom::volume_anim {
+
+// Shortest window any bar gets, as a fraction of the timeline. Without a floor a
+// near-zero bar would collapse inside a single frame and read as a pop rather
+// than a fall. Clamping only moves a start earlier, so every bar still lands
+// together.
+constexpr float kMinWindow = 0.2f;
+
+// Linear progress (0..1) mapped through a VroomEasing curve. Mirrors ease() in
+// packages/react/src/easing.ts; unknown kinds fall back to smoothstep, matching
+// it. Progress outside 0..1 is clamped.
+float ease(int32_t kind, float p);
+
+// How far a single bar has collapsed at global linear progress `t`, from 0
+// (untouched, full height) to 1 (flat).
+//
+// `frac` is the bar's height as a fraction of the tallest bar in view, and
+// doubles as the length of its window: a bar falls over the last `frac` of the
+// timeline. So the tallest bar starts immediately and takes the whole
+// transition, shorter bars start progressively later, and everything reaches
+// zero at t = 1 — the "tallest first, all land together" cascade.
+//
+// Symmetric in `t`, so driving it backwards (1 -> 0) plays the reveal: the
+// shortest bar rises first and the tallest arrives last.
+float bar_collapse(float frac, float t, int32_t easing);
+
+}  // namespace vroom::volume_anim

package/lib/index.d.mts

@@ -82,7 +82,12 @@ type VroomTheme = {
     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). */
+    /**
+     * Corner radius (px) of the *top* of volume bars. Defaults to 0 (square).
+     *
+     * @deprecated Use `volume.radius`, which sits with the rest of the volume
+     * styling. This still applies when `volume.radius` is omitted.
+     */
     volumeRadius?: number;
     /** Gridlines. */
     grid?: VroomColor;
@@ -92,10 +97,16 @@ 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. */
+    /** Line-chart-mode close polyline color. Defaults to violet, matching the RSI line. */
     lineColor?: VroomColor;
     /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
     lineWidth?: number;
+    /**
+     * Opacity of the gradient filled beneath the line-chart polyline, at its
+     * strongest point. The fill uses `lineColor` and ramps to fully transparent at
+     * the bottom of the price pane. Defaults to 0.28; set to 0 to disable the fill.
+     */
+    lineGradientOpacity?: number;
 };
 /** A time window over the candle data, as Unix epoch milliseconds. */
 type VisibleRange = {
@@ -117,6 +128,11 @@ type ChartMode = 'pan' | 'draw';
  *               overlays, crosshair, and drawings still render.
  */
 type ChartType = 'candles' | 'line';
+/**
+ * Easing curve for animated transitions (candle↔line and interval switches).
+ * Defaults to `'ease-in-out'`.
+ */
+type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
 type DrawTool = null | 'line' | 'box' | 'pencil';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
@@ -226,8 +242,21 @@ type UndoRedoControls = {
      */
     clearHistory: () => void;
 };
-/** RSI indicator config. Rendered in a pane below the candles when enabled. */
+/** Price source for a moving average. */
+type MASource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4';
+/** Averaging used by a moving average: simple or exponential. */
+type MAKind = 'sma' | 'ema';
+/**
+ * RSI indicator config. Rendered in a pane below the candles when enabled: the
+ * RSI line, an optional moving-average trendline over it, and two dashed rules
+ * at the overbought and oversold levels.
+ *
+ * RSI reads closes only — Wilder's definition is built on close-to-close
+ * change — so unlike the moving-average, Bollinger, and MACD configs it takes
+ * no {@link MASource}.
+ */
 type RSIConfig = {
+    /** Draw the pane. Default false. */
     enabled?: boolean;
     /** Lookback period in candle counts. Default 14, clamped to >= 2. */
     period?: number;
@@ -235,23 +264,37 @@ type RSIConfig = {
     upperBand?: number;
     /** Oversold band level (0..100). Default 30. */
     lowerBand?: number;
-    /** Show the RSI-based moving-average trendline. Default true. */
-    maEnabled?: boolean;
     /** Trendline (MA of RSI) length. Default 14, clamped to >= 1. */
     maPeriod?: number;
+    /** Averaging used for the trendline ({@link MAKind}). Default 'sma'. */
+    maType?: MAKind;
+    /** Draw the moving-average trendline. Default true. */
+    maVisible?: boolean;
+    /** RSI line color (hex string or packed ARGB number). Default violet. */
+    lineColor?: string | number;
+    /** RSI line stroke width in px. Default 1.5. */
+    lineWidth?: number;
+    /** Draw the RSI line. Default true. */
+    lineVisible?: boolean;
+    /** Trendline color. Default amber. */
+    maColor?: string | number;
+    /** Trendline stroke width in px. Default 1.5. */
+    maWidth?: number;
+    /** Color of both dashed band rules. Default gray. */
+    bandColor?: string | number;
+    /** Draw the overbought/oversold rules. Default true. */
+    bandsVisible?: boolean;
 };
-/** Price source for a moving average. */
-type MASource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4';
 /**
  * A moving-average overlay line drawn on the price pane. Provide an array of
  * these via `movingAverages` to render a ribbon of SMA/EMA lines.
  */
 type MovingAverageOverlay = {
-    /** 'sma' (simple) or 'ema' (exponential). */
-    kind: 'sma' | 'ema';
+    /** Averaging for this line ({@link MAKind}). */
+    maType: MAKind;
     /** Lookback in candles. */
-    length: number;
-    /** Price source. Default 'close'. */
+    period: number;
+    /** Price source ({@link MASource}). Default 'close'. */
     source?: MASource;
     /** Line color (hex string or packed ARGB number). */
     color?: string | number;
@@ -263,6 +306,7 @@ type MovingAverageOverlay = {
  * pane, resetting each session.
  */
 type VWAPConfig = {
+    /** Draw the line. Default false. */
     enabled?: boolean;
     /** Session reset offset from UTC midnight, in minutes (default 0). */
     resetMinutes?: number;
@@ -278,18 +322,20 @@ type VWAPConfig = {
  * fill between the bands. No pane is reserved.
  */
 type BollingerBandsConfig = {
+    /** Draw the bands. Default false. */
     enabled?: boolean;
     /** Lookback in candles. Default 20, clamped to >= 1. */
     period?: number;
     /** Standard-deviation multiplier. Default 2. */
     stdDev?: number;
-    /** Price source. Default 'close'. */
+    /** Price source ({@link MASource}). 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).
+     * Averaging for the basis (middle) line ({@link MAKind}). Default 'sma'. The
+     * stdev always uses the window's arithmetic mean, even with an EMA basis
+     * (the standard semantics).
      */
-    basis?: 'sma' | 'ema';
+    maType?: MAKind;
     /** Upper band color (hex string or packed ARGB number). Default blue. */
     upperColor?: string | number;
     /** Upper band stroke width in px. Default 1. */
@@ -302,11 +348,40 @@ type BollingerBandsConfig = {
     lowerColor?: string | number;
     /** Lower band stroke width in px. Default 1. */
     lowerWidth?: number;
-    /** Translucent fill between the bands. Default true. */
-    fill?: boolean;
+    /** Draw the translucent fill between the bands. Default true. */
+    fillVisible?: boolean;
     /** Fill opacity 0..1, applied to the upper band color. Default 0.1. */
     fillOpacity?: number;
 };
+/**
+ * Volume bar config. One bottom-anchored bar per candle on the price pane,
+ * drawn under the candles and sharing their x position and body width.
+ *
+ * Unlike the other indicator configs the bars are on by default, so omitting
+ * this prop leaves the chart looking as it always has.
+ */
+type VolumeConfig = {
+    /** Draw the bars. Default true. */
+    enabled?: boolean;
+    /** Bar opacity 0..1 (1 = opaque). Default 0.5, so bars read quieter than the candles. */
+    opacity?: number;
+    /**
+     * Height of the tallest bar as a fraction of the price pane, 0..1.
+     * Default 0.2.
+     *
+     * This is a ceiling rather than a reserved strip: raising it lets the bars
+     * reach further up over the candles rather than compressing them, matching
+     * the conventional volume overlay. Heights always auto-fit the loudest volume
+     * in view, so the tallest bar sits exactly at the ceiling.
+     */
+    height?: number;
+    /** Corner radius (px) of the *top* of each bar. Defaults to `theme.volumeRadius`, else 0 (square). */
+    radius?: number;
+    /** Up-bar color (hex string or packed ARGB number). Defaults to `theme.accentBull`. */
+    upColor?: string | number;
+    /** Down-bar color (hex string or packed ARGB number). Defaults to `theme.accentBear`. */
+    downColor?: string | 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
@@ -360,9 +435,9 @@ type LiquidityConfig = {
  * plus an optional solid-filled `quantity` pill and an optional close button),
  * with a price badge in the y-axis strip.
  *
- * Interaction is opt-in and callback-gated, mirroring TradingView: the line is
- * only draggable when `draggable` is set, and the close button only renders when
- * you pass `onPriceLineClose`. Dragging is a *preview* — the chart never mutates
+ * Interaction is opt-in and callback-gated: the line is only draggable when
+ * `draggable` is set, and the close button only renders when you pass
+ * `onPriceLineClose`. Dragging is a *preview* — the chart never mutates
  * the price you gave it, so a move your backend rejects reverts on its own
  * simply by leaving your `priceLines` state unchanged.
  */
@@ -424,15 +499,65 @@ type PriceLinesStyle = {
      */
     hoverBoost?: number;
 };
-/** MACD indicator config. Rendered in its own pane below the candles. */
+/**
+ * MACD indicator config. Rendered in its own pane below the candles: the gap
+ * between a fast and a slow moving average, a signal line smoothing that gap,
+ * and a histogram of the distance between the two.
+ *
+ * Every style field is optional and falls back to the stock look, so an
+ * untouched config renders exactly as it always has.
+ */
 type MACDConfig = {
+    /** Draw the pane. Default false. */
     enabled?: boolean;
-    /** Fast EMA length. Default 12. */
+    /** Fast moving-average length. Default 12. */
     fast?: number;
-    /** Slow EMA length (forced > fast). Default 26. */
+    /** Slow moving-average length (forced > fast). Default 26. */
     slow?: number;
-    /** Signal-line EMA length. Default 9. */
+    /** Signal-line length. Default 9. */
     signal?: number;
+    /** Price source for the fast/slow legs ({@link MASource}). Default 'close'. */
+    source?: MASource;
+    /** Averaging used for the fast and slow legs ({@link MAKind}). Default 'ema'. */
+    maType?: MAKind;
+    /** Averaging applied to the MACD series for the signal line. Default 'ema'. */
+    signalMaType?: MAKind;
+    /** MACD line color (hex string or packed ARGB number). Default blue. */
+    lineColor?: string | number;
+    /** MACD line stroke width in px. Default 1.5. */
+    lineWidth?: number;
+    /** Draw the MACD line. Default true. */
+    lineVisible?: boolean;
+    /** Signal line color. Default orange. */
+    signalColor?: string | number;
+    /** Signal line stroke width in px. Default 1.5. */
+    signalWidth?: number;
+    /** Draw the signal line. Default true. */
+    signalVisible?: boolean;
+    /** Draw the histogram bars. Default true. */
+    histogramVisible?: boolean;
+    /**
+     * Bars above zero that are still growing away from it. Defaults to
+     * `theme.accentBull`. Set all four histogram colors alike for a flat,
+     * single-color histogram.
+     */
+    histogramUpColor?: string | number;
+    /**
+     * Bars above zero that are falling back toward it, i.e. momentum easing.
+     * Defaults to `histogramUpColor` at half opacity.
+     */
+    histogramUpFadingColor?: string | number;
+    /** Bars below zero still growing away from it. Defaults to `theme.accentBear`. */
+    histogramDownColor?: string | number;
+    /**
+     * Bars below zero rising back toward it. Defaults to `histogramDownColor` at
+     * half opacity.
+     */
+    histogramDownFadingColor?: string | number;
+    /** Zero-reference line color. Default gray. */
+    zeroLineColor?: string | number;
+    /** Draw the zero-reference line. Default true. */
+    zeroLineVisible?: boolean;
 };
 /**
  * Platform-agnostic props shared by every vroom chart component. Each platform
@@ -474,11 +599,17 @@ type VroomChartCoreProps = {
      */
     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.
+     * Duration (ms) of the animated transitions: the candle↔line switch when
+     * `chartType` changes, and the candle reshape when the `candles` array is
+     * swapped for a different interval of the same asset. Default ~300. `0` snaps
+     * instantly. Ignored (snaps) when the OS requests reduced motion, which
+     * instead uses a plain cross-fade.
      */
     transitionMs?: number;
+    /**
+     * Easing curve applied to those transitions. Default `'ease-in-out'`.
+     */
+    transitionEasing?: TransitionEasing;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
@@ -490,6 +621,8 @@ type VroomChartCoreProps = {
     vwap?: VWAPConfig;
     /** Bollinger Bands overlay (three lines + fill on the price pane). */
     bollingerBands?: BollingerBandsConfig;
+    /** Volume bars under the candles. On by default; disable or restyle them here. */
+    volume?: VolumeConfig;
     /** Resting-order / order-book liquidity bands drawn behind the candles. */
     liquidity?: LiquidityConfig;
     /**
@@ -650,4 +783,4 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type MACDConfig, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, 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 MAKind, type MASource, type MovingAverageOverlay, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme };