react-native-vroom-chart 0.5.0 → 0.7.0

package/lib/index.d.ts

@@ -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
@@ -352,15 +427,137 @@ type LiquidityConfig = {
      * `widthPx` and `widthFrac * paneWidth` is used. */
     widthFrac?: number;
 };
-/** MACD indicator config. Rendered in its own pane below the candles. */
+/**
+ * A consumer-supplied horizontal status line at a fixed price — the primitive
+ * behind resting limit orders, take-profits, stop-losses and liquidation levels.
+ *
+ * Renders as a line across the price pane ending in a label group (a `text` pill
+ * 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: 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.
+ */
+type PriceLine = {
+    /** Stable unique id, echoed back by every callback. */
+    id: string;
+    /** Where the line sits on the price scale. */
+    price: number;
+    /** Body label — render whatever you like (e.g. `'Limit Buy @ 13.79'`). */
+    text?: string;
+    /**
+     * Trailing segment, drawn as a solid-filled pill with white text so size reads
+     * at a glance (e.g. `'x 5.206'`). Omit to hide it.
+     */
+    quantity?: string;
+    /** Line, border, body text and close-icon color. Defaults to a soft red. */
+    color?: VroomColor;
+    /** Stroke width in px. Default 1. */
+    width?: number;
+    /** Line style. Default `'dotted'`, matching the current-price indicator. */
+    lineStyle?: 'solid' | 'dotted' | 'dashed';
+    /**
+     * Let the user drag this line vertically to a new price. Default false.
+     * Pair with `onPriceLineDragEnd` to commit the move.
+     */
+    draggable?: boolean;
+    /**
+     * Show the close button on this line. Defaults to true, but the button only
+     * ever renders if you also pass `onPriceLineClose` — set this to false to opt a
+     * single line out (e.g. a liquidation level the user can't dismiss).
+     */
+    closable?: boolean;
+    /** Extend the line to the pane's left edge. Default true. */
+    extendLeft?: boolean;
+    /** Show the price badge in the y-axis strip. Default true. */
+    axisLabel?: boolean;
+};
+/** Shared layout/style for every price line, passed via `priceLinesStyle`. */
+type PriceLinesStyle = {
+    /**
+     * Translucent fill behind the body and close-button pills, so the label reads
+     * over candles without hiding them. Defaults to a dark translucent grey.
+     */
+    bodyBackground?: VroomColor;
+    /** Label font size in px. Defaults to the axis font size. */
+    fontSize?: number;
+    /**
+     * How far in from the price axis the label group sits, as a fraction of pane
+     * width (0 = flush against the axis, 0.5 = at the pane's midpoint). Only
+     * applies when `align` is `'right'`. Default 0.
+     */
+    inset?: number;
+    /** Where the label group sits horizontally. Default `'right'`. */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * How much the hovered line or close button brightens, as a channel
+     * multiplier. 1 disables the highlight. Default 1.25. Web only — touch
+     * platforms have no hover state.
+     */
+    hoverBoost?: number;
+};
+/**
+ * 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
@@ -402,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;
@@ -418,8 +621,41 @@ 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;
+    /**
+     * Horizontal status lines at consumer-supplied prices (resting orders, TP/SL,
+     * liquidation levels), each with a text label and an optional close button.
+     *
+     * This is a controlled prop: the chart renders exactly what you pass and never
+     * mutates it. A drag paints a live preview and reports the new price through
+     * `onPriceLineDragEnd`; the line only actually moves once you update this
+     * array, so a rejected move needs no explicit rollback.
+     */
+    priceLines?: PriceLine[];
+    /** Shared layout/style for every entry in `priceLines`. */
+    priceLinesStyle?: PriceLinesStyle;
+    /**
+     * Fired continuously while a draggable price line is being dragged, with the
+     * price under the pointer. Use it for a live readout (e.g. an order ticket);
+     * wait for `onPriceLineDragEnd` to commit.
+     */
+    onPriceLineDrag?: (id: string, price: number) => void;
+    /**
+     * Fired once when the user drops a dragged price line. Submit the new price to
+     * your backend here, then update `priceLines` on success — the line snaps back
+     * on its own if you don't. Dragging is cancelled (and this never fires) if the
+     * user presses Escape.
+     */
+    onPriceLineDragEnd?: (id: string, price: number) => void;
+    /**
+     * Fired when the user activates a price line's close button. Passing this
+     * handler is what makes the button render at all; individual lines opt out with
+     * `closable: false`.
+     */
+    onPriceLineClose?: (id: string) => void;
     /**
      * 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
@@ -547,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 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 };