react-native-vroom-chart 0.13.1 → 0.15.0

package/cpp/_core_src/viewport.h

@@ -104,6 +104,10 @@ inline std::size_t morph_from_count(const CandleSnapshot* from,
     return (from && morph_t < 1.f) ? from_n : 0;
 }
 
+// C facade `vroom_chart_begin_interval_morph` mode: 0 = slot-lerp transform,
+// anything else = fade the outgoing snapshot out then the new scene in.
+inline bool interval_morph_is_fade(int32_t mode) { return mode != 0; }
+
 // 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

@@ -187,6 +187,13 @@ type ChartType = 'candles' | 'line';
  * Defaults to `'ease-in-out'`.
  */
 type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/**
+ * How a same-asset interval switch animates. `'transform'` (default) lerps
+ * each visible column into its counterpart. `'fade'` fades the old scene out
+ * then the new one in — use when the two windows don’t share a 1:1 pairing
+ * (e.g. a fixed lookback).
+ */
+type IntervalTransition = 'transform' | 'fade';
 /** 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. */
@@ -200,9 +207,12 @@ type DrawPoint = {
 type DrawingBase = {
     /** Stable unique id (the chart generates one for drawings it creates). */
     id: string;
-    /** Stroke color (hex string or packed ARGB number). Default solid blue. */
+    /**
+     * Stroke color (hex string or packed ARGB number). New drawings take
+     * `drawingStyle.color` when set; otherwise `#ff2962ff`.
+     */
     color?: VroomColor;
-    /** Stroke width in px. Default 2. */
+    /** Stroke width in px. New drawings take `drawingStyle.width` when set; otherwise 2. */
     width?: number;
     /**
      * Protect the drawing from editing. A locked drawing still renders and can
@@ -295,6 +305,29 @@ type DrawingStyle = {
     fill?: VroomColor;
     locked?: boolean;
 };
+/**
+ * Default appearance for drawings the user creates — the live draft and the
+ * object handed to `onDrawingComplete`. Paste copies the source drawing's
+ * style instead of this default.
+ *
+ * Omitted fields keep the library defaults: a 2px `#ff2962ff` stroke, and for
+ * boxes a 10% tint of the stroke as fill.
+ *
+ * Prefer 6-digit hex for `color` (`'#00FFFF'`). vroom treats that as opaque,
+ * and CSS swatches preview it correctly. 8-digit hex is `#aarrggbb`, not CSS
+ * `#rrggbbaa`.
+ */
+type DefaultDrawingStyle = {
+    /** Stroke color, used for the live draft and stamped onto the committed drawing. */
+    color?: VroomColor;
+    /** Stroke width in px. Default 2. */
+    width?: number;
+    /**
+     * Box interior fill. Omitted, new boxes keep the default 10% stroke tint.
+     * Ignored by line, pencil, and path.
+     */
+    fill?: VroomColor;
+};
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -618,6 +651,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,
@@ -720,16 +870,23 @@ type VroomChartCoreProps = {
     chartType?: ChartType;
     /**
      * Duration (ms) of the animated transitions: the candle↔line switch when
-     * `chartType` changes, and the candle reshape when the `candles` array is
+     * `chartType` changes, and the interval switch 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.
+     * instantly. Ignored (snaps) when the OS requests reduced motion.
      */
     transitionMs?: number;
     /**
      * Easing curve applied to those transitions. Default `'ease-in-out'`.
      */
     transitionEasing?: TransitionEasing;
+    /**
+     * How a same-asset interval switch animates. `'transform'` (default) lerps
+     * each visible column into its counterpart. `'fade'` fades the old scene out
+     * then the new one in — use when the two windows don’t share a 1:1 pairing
+     * (e.g. a fixed lookback). Same duration/easing as `transitionMs`. Reduced
+     * motion still snaps.
+     */
+    intervalTransition?: IntervalTransition;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
@@ -757,6 +914,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);
@@ -802,6 +976,12 @@ type VroomChartCoreProps = {
     mode?: ChartMode;
     /** Active drawing tool while in `draw` mode. Default `null` (draws nothing). */
     tool?: DrawTool;
+    /**
+     * Default appearance for drawings the user creates (live draft + the object
+     * handed to `onDrawingComplete`). Paste copies the source drawing's style
+     * instead of this. Omitted fields keep the library defaults.
+     */
+    drawingStyle?: DefaultDrawingStyle;
     /**
      * Committed drawings to render, anchored to data so they track the candles on
      * pan/zoom. This is a controlled prop: append the value the chart hands you in
@@ -945,4 +1125,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 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 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 };

package/lib/index.d.ts

@@ -187,6 +187,13 @@ type ChartType = 'candles' | 'line';
  * Defaults to `'ease-in-out'`.
  */
 type TransitionEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/**
+ * How a same-asset interval switch animates. `'transform'` (default) lerps
+ * each visible column into its counterpart. `'fade'` fades the old scene out
+ * then the new one in — use when the two windows don’t share a 1:1 pairing
+ * (e.g. a fixed lookback).
+ */
+type IntervalTransition = 'transform' | 'fade';
 /** 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. */
@@ -200,9 +207,12 @@ type DrawPoint = {
 type DrawingBase = {
     /** Stable unique id (the chart generates one for drawings it creates). */
     id: string;
-    /** Stroke color (hex string or packed ARGB number). Default solid blue. */
+    /**
+     * Stroke color (hex string or packed ARGB number). New drawings take
+     * `drawingStyle.color` when set; otherwise `#ff2962ff`.
+     */
     color?: VroomColor;
-    /** Stroke width in px. Default 2. */
+    /** Stroke width in px. New drawings take `drawingStyle.width` when set; otherwise 2. */
     width?: number;
     /**
      * Protect the drawing from editing. A locked drawing still renders and can
@@ -295,6 +305,29 @@ type DrawingStyle = {
     fill?: VroomColor;
     locked?: boolean;
 };
+/**
+ * Default appearance for drawings the user creates — the live draft and the
+ * object handed to `onDrawingComplete`. Paste copies the source drawing's
+ * style instead of this default.
+ *
+ * Omitted fields keep the library defaults: a 2px `#ff2962ff` stroke, and for
+ * boxes a 10% tint of the stroke as fill.
+ *
+ * Prefer 6-digit hex for `color` (`'#00FFFF'`). vroom treats that as opaque,
+ * and CSS swatches preview it correctly. 8-digit hex is `#aarrggbb`, not CSS
+ * `#rrggbbaa`.
+ */
+type DefaultDrawingStyle = {
+    /** Stroke color, used for the live draft and stamped onto the committed drawing. */
+    color?: VroomColor;
+    /** Stroke width in px. Default 2. */
+    width?: number;
+    /**
+     * Box interior fill. Omitted, new boxes keep the default 10% stroke tint.
+     * Ignored by line, pencil, and path.
+     */
+    fill?: VroomColor;
+};
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -618,6 +651,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,
@@ -720,16 +870,23 @@ type VroomChartCoreProps = {
     chartType?: ChartType;
     /**
      * Duration (ms) of the animated transitions: the candle↔line switch when
-     * `chartType` changes, and the candle reshape when the `candles` array is
+     * `chartType` changes, and the interval switch 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.
+     * instantly. Ignored (snaps) when the OS requests reduced motion.
      */
     transitionMs?: number;
     /**
      * Easing curve applied to those transitions. Default `'ease-in-out'`.
      */
     transitionEasing?: TransitionEasing;
+    /**
+     * How a same-asset interval switch animates. `'transform'` (default) lerps
+     * each visible column into its counterpart. `'fade'` fades the old scene out
+     * then the new one in — use when the two windows don’t share a 1:1 pairing
+     * (e.g. a fixed lookback). Same duration/easing as `transitionMs`. Reduced
+     * motion still snaps.
+     */
+    intervalTransition?: IntervalTransition;
     theme?: VroomTheme;
     /** RSI indicator (pane below the candles). Omit/disable to hide it. */
     rsi?: RSIConfig;
@@ -757,6 +914,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);
@@ -802,6 +976,12 @@ type VroomChartCoreProps = {
     mode?: ChartMode;
     /** Active drawing tool while in `draw` mode. Default `null` (draws nothing). */
     tool?: DrawTool;
+    /**
+     * Default appearance for drawings the user creates (live draft + the object
+     * handed to `onDrawingComplete`). Paste copies the source drawing's style
+     * instead of this. Omitted fields keep the library defaults.
+     */
+    drawingStyle?: DefaultDrawingStyle;
     /**
      * Committed drawings to render, anchored to data so they track the candles on
      * pan/zoom. This is a controlled prop: append the value the chart hands you in
@@ -945,4 +1125,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 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 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 };