react-native-vroom-chart 0.6.0 → 0.8.0

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,8 +128,13 @@ 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';
+type DrawTool = null | 'line' | 'box' | 'pencil' | 'path';
 /** 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). */
@@ -160,16 +176,27 @@ type PencilDrawing = DrawingBase & {
     /** The path's points in draw order (at least 2), in data space. */
     points: DrawPoint[];
 };
+/**
+ * A multi-segment path: straight segments through `points`, in order, ending in
+ * an arrowhead on the last vertex. Like a pencil stroke it holds a variable
+ * number of points, but every one was placed deliberately (one click each), so
+ * each is an individually draggable handle once the path is committed.
+ */
+type PathDrawing = DrawingBase & {
+    type: 'path';
+    /** The path's vertices 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
+ * `points[1]`, since `'pencil'` and `'path'` have variable-length arrays while
  * `'line'` and `'box'` are always exactly two points.
  */
-type Drawing = LineDrawing | BoxDrawing | PencilDrawing;
+type Drawing = LineDrawing | BoxDrawing | PencilDrawing | PathDrawing;
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -226,8 +253,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 +275,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 +317,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 +333,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 +359,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 +446,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 +510,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 +610,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 +632,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 +794,35 @@ 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 };
+/**
+ * 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.
+ */
+type DataTransition = 'initial' | 'stream' | 'timeframe' | 'reset';
+/**
+ * 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.
+ */
+declare function inferStepMs(candles: Candle[]): number | null;
+/**
+ * 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.
+ */
+declare function classifyTransition(prev: Candle[] | null, next: Candle[], seriesKeyChanged: boolean): DataTransition;
+/**
+ * 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.
+ */
+declare function timeframeWindow(oldWindow: VisibleRange, oldStepMs: number, oldLastMs: number, newStepMs: number, newLastMs: number): VisibleRange;
+
+export { type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, 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, classifyTransition, inferStepMs, timeframeWindow };