react-native-vroom-chart 0.14.0 → 0.16.0

package/cpp/_core_src/viewport.h

@@ -108,6 +108,41 @@ inline std::size_t morph_from_count(const CandleSnapshot* from,
 // anything else = fade the outgoing snapshot out then the new scene in.
 inline bool interval_morph_is_fade(int32_t mode) { return mode != 0; }
 
+// Rewrites a fresh capture so it starts from the shape currently on screen
+// rather than from the data underneath it. Live ticks arrive faster than a
+// morph lands, so every restart interrupts one; without this the bar would jump
+// back to its un-morphed position on each tick, which is the snap the animation
+// exists to remove.
+//
+// `interrupted` is the capture being replaced and `morph_t` the progress it had
+// reached, so `dst` becomes exactly the frame that was being painted: the draw
+// path interpolates in this same fraction space (see candles::draw), which is
+// what makes a plain lerp here land pixel-exact.
+//
+// Slot 0 is the newest in both, so a differing visible count only drops the
+// oldest slots — those keep the fresh capture, which is where they already are.
+inline void blend_candle_snapshots(CandleSnapshot* dst, std::size_t dst_n,
+                                   const CandleSnapshot* interrupted,
+                                   std::size_t interrupted_n, float morph_t) {
+    if (!dst || !interrupted) return;
+    const std::size_t n = dst_n < interrupted_n ? dst_n : interrupted_n;
+    for (std::size_t k = 0; k < n; ++k) {
+        const CandleSnapshot& from = interrupted[k];
+        CandleSnapshot& to = dst[k];
+        const auto mix = [morph_t](float a, float b) {
+            return a + (b - a) * morph_t;
+        };
+        to.open = mix(from.open, to.open);
+        to.high = mix(from.high, to.high);
+        to.low = mix(from.low, to.low);
+        to.close = mix(from.close, to.close);
+        to.x = mix(from.x, to.x);
+        // `bull` stays the fresh one: the draw path colors a paired slot from
+        // the live candle and only reads the capture's flag for a slot the next
+        // update drops, where the newer direction is the better answer.
+    }
+}
+
 // Returns the indices of candles whose time_ms falls in [start_ms, end_ms].
 // When both are 0, returns the full range (Phase 1 default-everything behavior).
 // Candles must be sorted ascending by time_ms (invariant of the public API).

package/lib/index.d.mts

@@ -194,6 +194,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 +444,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 +523,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.
@@ -651,6 +843,123 @@ type PriceLinesStyle = {
      */
     hoverBoost?: number;
 };
+/** Which side of a position a footprint marks. */
+type FootprintSide = 'buy' | 'sell';
+/**
+ * A single filled trade, drawn as a circular badge above the candle it fell in —
+ * the "footprint" a trader leaves on the chart: `buy` marks an entry (a `+`
+ * badge in the bull color), `sell` marks an exit (a `−` badge in the bear color).
+ *
+ * `timeMs` is the raw execution time, *not* a bar-open time. The chart buckets
+ * each footprint into whichever candle's window contains it, so the same array
+ * renders correctly at every interval — switch from 1m to 1h and the badges
+ * re-group onto the wider bars on their own.
+ *
+ * At most two badges render per candle: one for that bar's buys and one for its
+ * sells, however many trades went into each. Hovering (or tapping) a badge hands
+ * every footprint on that candle back through `onFootprint`, so a bar holding
+ * twenty fills still shows one badge and still reports all twenty.
+ */
+type Footprint = {
+    /** Stable unique id, echoed back in `onFootprint`. */
+    id: string;
+    /** Execution time as Unix epoch milliseconds, unsnapped. */
+    timeMs: number;
+    /** Entry (`'buy'`) or exit (`'sell'`) — picks the badge color and glyph. */
+    side: FootprintSide;
+    /**
+     * Execution price. Ignored by the renderer (badges sit above the bar, not at
+     * the fill), and carried through to `onFootprint` for your own UI.
+     */
+    price?: number;
+};
+/** Shared layout/style for every footprint badge, passed via `footprintsStyle`. */
+type FootprintsStyle = {
+    /** Badge radius in px. Default 9. */
+    radius?: number;
+    /**
+     * Vertical gap between the two stacked badges on a candle that has both a buy
+     * and a sell. Default 4 — wide enough that each stays independently hoverable.
+     */
+    gap?: number;
+    /** Gap between the candle's high and the first badge, in px. Default 8. */
+    margin?: number;
+    /**
+     * How much the hovered badge brightens, as a channel multiplier. 1 disables
+     * the highlight (the halo ring still draws). Default 1.25.
+     */
+    hoverBoost?: number;
+};
+/**
+ * The chart's plot area in logical px relative to the chart element's top-left:
+ * the candles and everything drawn over them, with the price and time axis
+ * strips excluded.
+ *
+ * This is the rect to test a floating UI against, and it is deliberately *not*
+ * the element's own box — the element includes the axis strips, so measuring it
+ * overstates the room beside anything near an edge.
+ */
+type PlotRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * Fired when the pointer enters, moves between, or leaves footprint badges (on
+ * touch platforms, when one is tapped or dismissed).
+ *
+ * The chart draws no tooltip of its own — this event is the hook for yours.
+ * Position your UI off `badge` and `pane`, both in the same coordinate space as
+ * the chart element, and fill it from `footprints`.
+ *
+ * Panning or zooming fires a `'hide'`, since the bar the badge belongs to has
+ * moved: you don't need your own gesture listener to take the tooltip down.
+ */
+type FootprintEvent = {
+    /** True while a badge is hovered/tapped; false when it's dismissed. */
+    active: boolean;
+    /**
+     * Why this event fired:
+     *   'show' — a badge became hovered/tapped from nothing
+     *   'move' — the pointer moved to a *different* badge without leaving in between
+     *   'hide' — the badge was dismissed: the pointer left (or a tap missed), the
+     *            chart was panned or zoomed out from under it, or the crosshair
+     *            took the pane over
+     */
+    reason: 'show' | 'move' | 'hide';
+    /** Which badge — its buys or its sells. Null when inactive. */
+    side: FootprintSide | null;
+    /** Bar-open time (epoch ms) of the candle the badge sits on. Null when inactive. */
+    timeMs: number | null;
+    /**
+     * Every footprint bucketed into that candle, *both* sides, ascending by
+     * `timeMs`. Empty when inactive. Filter on `side` to show only the hovered
+     * badge's trades, or render the whole bar's activity at once.
+     */
+    footprints: Footprint[];
+    /**
+     * The badge's center and radius in logical px relative to the chart element's
+     * top-left — anchor your tooltip to it. Null when inactive.
+     */
+    badge: {
+        x: number;
+        y: number;
+        radius: number;
+    } | null;
+    /**
+     * The plot area the badge sits in, for choosing which side of it your tooltip
+     * fits on. Null when inactive (there is nothing to place).
+     *
+     * Only you know how big your tooltip is, so the chart reports the rect rather
+     * than picking a side:
+     *
+     * ```ts
+     * const fitsRight = badge.x + badge.radius + 8 + width <= pane.right;
+     * ```
+     */
+    pane: PlotRect | null;
+};
 /**
  * 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,
@@ -711,6 +1020,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
@@ -770,17 +1110,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. */
@@ -797,6 +1161,23 @@ type VroomChartCoreProps = {
     priceLines?: PriceLine[];
     /** Shared layout/style for every entry in `priceLines`. */
     priceLinesStyle?: PriceLinesStyle;
+    /**
+     * Executed trades to mark on the chart as circular badges above the bar they
+     * fell in — where a position was entered and exited.
+     *
+     * Pass raw fills with their real execution times; the chart groups them onto
+     * candles itself and re-groups on interval changes, so one array serves every
+     * timeframe. Order doesn't matter.
+     */
+    footprints?: Footprint[];
+    /** Shared layout/style for every entry in `footprints`. */
+    footprintsStyle?: FootprintsStyle;
+    /**
+     * Fired when a footprint badge is hovered (tapped on touch platforms) or
+     * dismissed. The chart renders no tooltip itself — use this to place your own,
+     * anchored to `e.badge`, kept inside `e.pane`, and filled from `e.footprints`.
+     */
+    onFootprint?: (e: FootprintEvent) => void;
     /**
      * 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);
@@ -953,8 +1334,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.
  */
@@ -991,4 +1373,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 IntervalTransition, 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 };
+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 };