react-native-vroom-chart 0.15.0 → 0.17.0

package/lib/index.d.mts

@@ -106,6 +106,19 @@ type VroomTheme = {
     crosshairTarget?: VroomColor;
     /** Line-chart-mode close polyline color. Defaults to violet, matching the RSI line. */
     lineColor?: VroomColor;
+    /**
+     * The line drawn across the plot while loading (see the `loading` prop).
+     * Defaults to inheriting `grid`: the gridlines are already the chart's tone
+     * for structure rather than data, which is what the line is, so matching
+     * them keeps it from being read as a series.
+     *
+     * The line breathes between roughly 60% and 100% of whatever color it ends
+     * up with — a pulse, not a dimmer, so a recessive color stays legible. Any
+     * alpha given here multiplies into that, so an opaque color is the usual
+     * choice. Pass `lineColor` to make the line read as the chart's own series
+     * warming up instead.
+     */
+    skeleton?: VroomColor;
     /** Line-chart-mode polyline stroke width in px. Defaults to 1.5. */
     lineWidth?: number;
     /**
@@ -194,6 +207,14 @@ type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
  * (e.g. a fixed lookback).
  */
 type IntervalTransition = 'transform' | 'fade';
+/**
+ * How a live update to the series being displayed animates. `'none'` (default)
+ * applies it on the next frame with no animation and leaves the viewport where
+ * it is. `'transform'` eases the in-progress bar into its new values and, when
+ * the view is already pinned to the newest bar, slides the series left as each
+ * new bar arrives.
+ */
+type StreamTransition = 'none' | 'transform';
 /** Active drawing tool while in `draw` mode. `null` draws nothing. */
 type DrawTool = null | 'line' | 'box' | 'pencil' | 'path';
 /** A drawing anchor in data space, so it stays glued to the candles on pan/zoom. */
@@ -436,6 +457,16 @@ type RSIConfig = {
     bandColor?: string | number;
     /** Draw the overbought/oversold rules. Default true. */
     bandsVisible?: boolean;
+    /**
+     * Shade the stretches where the RSI line sits past a band, fading out at the
+     * rule and deepening toward the end of the scale, so how far a reading went
+     * past the threshold reads at a glance. Default true.
+     *
+     * Colored from the theme's `accentBull` (overbought) and `accentBear`
+     * (oversold), the same pair the volume bars and MACD histogram use. Never
+     * reaches full opacity — the line and its rule stay legible through it.
+     */
+    extremeFill?: boolean;
 };
 /**
  * A moving-average overlay line drawn on the price pane. Provide an array of
@@ -505,6 +536,180 @@ type BollingerBandsConfig = {
     /** Fill opacity 0..1, applied to the upper band color. Default 0.1. */
     fillOpacity?: number;
 };
+/**
+ * Ichimoku Kinko Hyo overlay config. Five lines on the price pane plus the
+ * cloud (kumo) shaded between the two leading spans. No pane is reserved.
+ *
+ * Unlike the other overlays, three of the lines are drawn away from the bar
+ * they were computed on:
+ *
+ * - Senkou A and B lead by `displacement` bars, so the cloud extends past the
+ *   newest candle into empty time. The chart reserves that space when it frames
+ *   itself, so the forward cloud is on screen without panning.
+ * - Chikou lags by `displacement` bars.
+ *
+ * Ichimoku is built on highs and lows rather than a single price series, so it
+ * takes no {@link MASource} or {@link MAKind}.
+ *
+ * Like the other price-pane overlays, its values don't feed the automatic
+ * y-axis fit — the cloud can run off the top or bottom of the pane on a chart
+ * scaled to the candles alone.
+ */
+type IchimokuConfig = {
+    /** Draw the indicator. Default false. */
+    enabled?: boolean;
+    /** Tenkan-sen (conversion) lookback. Default 9, clamped to >= 1. */
+    tenkanPeriod?: number;
+    /** Kijun-sen (base) lookback. Default 26, clamped to >= 1. */
+    kijunPeriod?: number;
+    /** Senkou Span B lookback. Default 52, clamped to >= 1. */
+    senkouBPeriod?: number;
+    /**
+     * Bars the cloud leads by and Chikou lags by. Default 26, clamped to >= 0.
+     * Changing it only moves what's already drawn — the lines themselves don't
+     * recompute.
+     */
+    displacement?: number;
+    /** Tenkan-sen color (hex string or packed ARGB number). Default blue. */
+    tenkanColor?: string | number;
+    /** Tenkan-sen stroke width in px. Default 1. */
+    tenkanWidth?: number;
+    /** Draw the Tenkan-sen. Default true. */
+    tenkanVisible?: boolean;
+    /** Kijun-sen color. Default red. */
+    kijunColor?: string | number;
+    /** Kijun-sen stroke width in px. Default 1. */
+    kijunWidth?: number;
+    /** Draw the Kijun-sen. Default true. */
+    kijunVisible?: boolean;
+    /** Senkou Span A color. Default green. */
+    senkouAColor?: string | number;
+    /** Senkou Span A stroke width in px. Default 1. */
+    senkouAWidth?: number;
+    /** Draw the Senkou Span A edge. Default true. */
+    senkouAVisible?: boolean;
+    /** Senkou Span B color. Default orange. */
+    senkouBColor?: string | number;
+    /** Senkou Span B stroke width in px. Default 1. */
+    senkouBWidth?: number;
+    /** Draw the Senkou Span B edge. Default true. */
+    senkouBVisible?: boolean;
+    /** Chikou span color. Default teal. */
+    chikouColor?: string | number;
+    /** Chikou span stroke width in px. Default 1. */
+    chikouWidth?: number;
+    /** Draw the Chikou span. Default true. */
+    chikouVisible?: boolean;
+    /** Draw the cloud between the two leading spans. Default true. */
+    cloudVisible?: boolean;
+    /** Cloud fill where Senkou A is above Senkou B. Default green. */
+    bullishCloudColor?: string | number;
+    /** Cloud fill where Senkou A is below Senkou B. Default red. */
+    bearishCloudColor?: string | number;
+    /** Cloud opacity 0..1, applied to whichever cloud color is in play. Default 0.15. */
+    cloudOpacity?: number;
+};
+/**
+ * Fair Value Gap overlay config. Shaded boxes on the price pane marking
+ * three-candle imbalances — a run so fast the first and third candles' wicks
+ * never overlap, leaving a band of price that was skipped.
+ *
+ * A gap is bullish when `candles[i - 1].high < candles[i + 1].low` and bearish
+ * when `candles[i - 1].low > candles[i + 1].high`, and spans the untouched
+ * range between those two wicks. Each box is anchored to the middle bar's open
+ * and runs `boxLength` bars to the right, or to the pane's edge under
+ * `extendBoxes`.
+ *
+ * Gaps are tracked until price trades back through them — see `fillType` for
+ * which price settles that, and `deleteAfterFill` for what happens once it
+ * does. With `showInverse`, a filled gap carries on as a zone of the opposite
+ * polarity. Unlike the line overlays, the boxes are pure geometry: they don't
+ * feed the automatic y-axis fit.
+ */
+type FairValueGapsConfig = {
+    /** Draw the indicator. Default false. */
+    enabled?: boolean;
+    /** How many bars back to scan for gaps. Default 300, clamped to >= 0. */
+    maxBarsBack?: number;
+    /**
+     * Withhold a gap until its third candle closes. Default false, so a gap
+     * formed by the still-forming bar appears immediately and disappears again
+     * if that bar fills back in.
+     */
+    waitForClose?: boolean;
+    /**
+     * Which price counts as trading back through the gap. `'close'` (default)
+     * needs a candle to close past the far edge; `'wick'` settles it the moment
+     * a high or low reaches through.
+     */
+    fillType?: 'close' | 'wick';
+    /**
+     * Hide a gap once it's been filled. Default true. When false the box stays
+     * but stops at the bar that filled it, leaving a record of the rebalance.
+     */
+    deleteAfterFill?: boolean;
+    /**
+     * Run every box to the right edge of the pane instead of ending it after
+     * `boxLength` bars. Default false. A filled box still stops at its fill bar.
+     */
+    extendBoxes?: boolean;
+    /** Box width in bars when `extendBoxes` is off. Default 20, clamped to >= 1. */
+    boxLength?: number;
+    /** Fill color for bullish gaps (hex string or packed ARGB). Default green. */
+    bullishColor?: VroomColor;
+    /** Fill color for bearish gaps. Default red. */
+    bearishColor?: VroomColor;
+    /** Fill opacity 0..1, applied to whichever fill color is in play. Default 0.15. */
+    opacity?: number;
+    /** Draw the box outline. Default true. */
+    borderVisible?: boolean;
+    /** Outline style. Default `'solid'`. */
+    borderStyle?: 'solid' | 'dotted' | 'dashed';
+    /** Outline stroke width in px. Default 1. */
+    borderWidth?: number;
+    /** Outline color for bullish gaps. Defaults to `bullishColor` at full alpha. */
+    bullishBorderColor?: VroomColor;
+    /** Outline color for bearish gaps. Defaults to `bearishColor` at full alpha. */
+    bearishBorderColor?: VroomColor;
+    /** Draw a text label on each box. Default true. */
+    showLabels?: boolean;
+    /** Label text. Default `'FVG'`. */
+    label?: string;
+    /**
+     * Bars of clearance between the box and its label, used only under
+     * `extendBoxes` — a fixed-length box places the label inside its right end.
+     * Default 10, clamped to >= 0.
+     */
+    labelDistance?: number;
+    /** Label color. Defaults to the box's border color. */
+    labelColor?: VroomColor;
+    /** Label font size in px. Defaults to the axis font size. */
+    labelFontSize?: number;
+    /**
+     * Keep drawing a gap after it's been filled, with its polarity flipped — the
+     * band price rejected on the way through becomes a zone of the opposite
+     * kind. Default false.
+     *
+     * The inverse box starts where the original one stops, at the close of the
+     * bar that filled the gap, and lasts until price reclaims the band the other
+     * way (by the same rule `fillType` sets). This pairs with the default
+     * `deleteAfterFill: true`: the original box vanishes at the fill and the
+     * inverse takes over from there.
+     */
+    showInverse?: boolean;
+    /**
+     * Fill color for inverted zones that are bullish — that is, for *bearish*
+     * gaps price has broken above. Defaults to `bullishColor`.
+     */
+    inverseBullishColor?: VroomColor;
+    /**
+     * Fill color for inverted zones that are bearish — that is, for *bullish*
+     * gaps price has broken below. Defaults to `bearishColor`.
+     */
+    inverseBearishColor?: VroomColor;
+    /** Label text on inverted boxes. Default `'iFVG'`. */
+    inverseLabel?: string;
+};
 /**
  * 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.
@@ -828,6 +1033,37 @@ type MACDConfig = {
     /** Draw the zero-reference line. Default true. */
     zeroLineVisible?: boolean;
 };
+/**
+ * How the true-range series is smoothed into ATR. `'rma'` is Wilder's original
+ * (alpha = 1/period) and the conventional default; the other two are the
+ * ordinary moving averages applied to the same series.
+ *
+ * Distinct from {@link MAKind}, which the other indicators use — RMA is
+ * specific to Wilder's indicators and isn't offered elsewhere.
+ */
+type ATRSmoothing = 'rma' | 'sma' | 'ema';
+/**
+ * ATR (Average True Range) indicator config. Rendered in its own pane below the
+ * candles: a single line measuring volatility in price units.
+ *
+ * True Range is the widest of the bar's own high-low span and the two gaps from
+ * its extremes to the previous close, so an overnight jump the bar's range
+ * misses still counts. ATR smooths that series over `period` bars. It is
+ * strictly positive and unbounded, so the pane fits 0..peak from its bottom
+ * edge rather than centering on a reference level.
+ */
+type ATRConfig = {
+    /** Draw the pane. Default false. */
+    enabled?: boolean;
+    /** Lookback in candles. Default 14. */
+    period?: number;
+    /** Smoothing applied to the true-range series. Default `'rma'`. */
+    smoothing?: ATRSmoothing;
+    /** Line color (hex string or packed ARGB number). Default teal. */
+    lineColor?: string | number;
+    /** Line stroke width in px. Default 1.5. */
+    lineWidth?: number;
+};
 /**
  * Platform-agnostic props shared by every vroom chart component. Each platform
  * extends this with its own `style` typing (and any platform-only props) to
@@ -836,6 +1072,23 @@ type MACDConfig = {
 type VroomChartCoreProps = {
     /** OHLCV bars to render. The only required prop. */
     candles: Candle[];
+    /**
+     * Whether the series is still being fetched. While this is true *and*
+     * `candles` is empty, the chart draws a single grey line across the plot,
+     * drifting in a slow sine wave, in place of the scene. Gestures, the
+     * crosshair, the price badge, the axis labels and any indicator panes are all
+     * suppressed for the duration.
+     *
+     * When the data arrives the line doesn't cut away — it becomes the chart, in
+     * two steps that split `transitionMs`: it reshapes to pass through the
+     * vertical centre of every candle about to be drawn, then fades out while
+     * those candles grow outward from it and their color fades up.
+     *
+     * Passing `candles` alongside `loading` leaves the real chart up, so a
+     * background refresh of an already-loaded series won't blank out. Default
+     * false.
+     */
+    loading?: boolean;
     /**
      * Identity of the data series (e.g. "BTC-USD"). When it changes between
      * renders the chart resets to the default view (most recent candles + price
@@ -887,17 +1140,41 @@ type VroomChartCoreProps = {
      * motion still snaps.
      */
     intervalTransition?: IntervalTransition;
+    /**
+     * How a live update to the series already on screen animates — a tick to the
+     * in-progress bar, or a newly closed bar arriving. `'none'` (default) snaps,
+     * matching a chart with no streaming at all.
+     *
+     * `'transform'` eases the last bar (and every indicator reading from it) from
+     * its old shape into its new one. When a new bar arrives *and* the view is
+     * still pinned to the newest bar, the window advances with it so the series
+     * translates left. A view panned back into history is never moved.
+     */
+    streamTransition?: StreamTransition;
+    /**
+     * Duration (ms) of the `streamTransition` animation. Default ~150 — shorter
+     * than `transitionMs`, since ticks can arrive faster than a 300ms curve can
+     * land. `0` snaps. Follows `transitionEasing`. Ignored (snaps) when the OS
+     * requests reduced motion.
+     */
+    streamTransitionMs?: number;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
     /** MACD indicator (its own pane below the candles). Omit/disable to hide it. */
     macd?: MACDConfig;
+    /** ATR indicator (its own pane below the candles). Omit/disable to hide it. */
+    atr?: ATRConfig;
     /** Moving-average overlay lines (SMA/EMA) drawn on the price pane. */
     movingAverages?: MovingAverageOverlay[];
     /** VWAP overlay (session anchor, configurable reset). */
     vwap?: VWAPConfig;
     /** Bollinger Bands overlay (three lines + fill on the price pane). */
     bollingerBands?: BollingerBandsConfig;
+    /** Ichimoku Kinko Hyo overlay (five lines + the cloud on the price pane). */
+    ichimoku?: IchimokuConfig;
+    /** Fair Value Gap overlay (shaded imbalance boxes on the price pane). */
+    fairValueGaps?: FairValueGapsConfig;
     /** 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. */
@@ -1087,8 +1364,9 @@ declare global {
  * Skia-rendered candlestick chart. Pass OHLCV `candles` and size it via `style`
  * (it fills its parent by default). Pan to scroll, pinch to zoom, drag the
  * price/time axes to rescale, and long-press for the crosshair. Optional
- * indicators (`rsi`, `macd`, `movingAverages`, `vwap`), colors (`theme`), and
- * events (`onCrosshair`, `onViewportChange`) are configured through props.
+ * indicators (`rsi`, `macd`, `movingAverages`, `vwap`, `bollingerBands`,
+ * `ichimoku`, and more), colors (`theme`), and events (`onCrosshair`,
+ * `onViewportChange`) are configured through props.
  *
  * @see {@link VroomChartProps} for the full prop reference.
  */
@@ -1125,4 +1403,4 @@ declare function classifyTransition(prev: Candle[] | null, next: Candle[], serie
  */
 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 DefaultDrawingStyle, type Footprint, type FootprintEvent, type FootprintSide, type FootprintsStyle, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PlotRect, type PriceLine, type PriceLinesStyle, type RSIConfig, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };
+export { type ATRConfig, type ATRSmoothing, type BollingerBandsConfig, type Candle, type ChartType, type CrosshairEvent, type DataTransition, type DefaultDrawingStyle, type FairValueGapsConfig, type Footprint, type FootprintEvent, type FootprintSide, type FootprintsStyle, type IchimokuConfig, type IntervalTransition, type MACDConfig, type MAKind, type MASource, type MovingAverageOverlay, type PlotRect, type PriceLine, type PriceLinesStyle, type RSIConfig, type StreamTransition, type TransitionEasing, type VWAPConfig, type VisibleRange, type VolumeConfig, VroomChart, type VroomChartProps, type VroomColor, type VroomTheme, classifyTransition, inferStepMs, timeframeWindow };