react-native-vroom-chart 0.4.0 → 0.6.0

package/lib/index.d.mts

@@ -201,6 +201,31 @@ type DrawingStore = {
      */
     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;
@@ -246,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
@@ -291,6 +352,78 @@ type LiquidityConfig = {
      * `widthPx` and `widthFrac * paneWidth` is used. */
     widthFrac?: number;
 };
+/**
+ * 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, 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
+ * 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. */
 type MACDConfig = {
     enabled?: boolean;
@@ -355,8 +488,41 @@ 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;
+    /**
+     * 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
@@ -417,6 +583,40 @@ type VroomChartCoreProps = {
      * 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;
 };
@@ -450,4 +650,4 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-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 };
+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 };

package/lib/index.d.ts

@@ -201,6 +201,31 @@ type DrawingStore = {
      */
     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;
@@ -246,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
@@ -291,6 +352,78 @@ type LiquidityConfig = {
      * `widthPx` and `widthFrac * paneWidth` is used. */
     widthFrac?: number;
 };
+/**
+ * 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, 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
+ * 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. */
 type MACDConfig = {
     enabled?: boolean;
@@ -355,8 +488,41 @@ 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;
+    /**
+     * 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
@@ -417,6 +583,40 @@ type VroomChartCoreProps = {
      * 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;
 };
@@ -450,4 +650,4 @@ declare global {
  */
 declare function VroomChart(props: VroomChartProps): React.JSX.Element;
 
-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 };
+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 };