react-native-vroom-chart 0.11.0 → 0.12.0

package/cpp/_core_src/theme.cpp

@@ -13,8 +13,8 @@ constexpr uint32_t kDefaultColors[VROOM_COLOR_COUNT_] = {
     0xff1a1e24,  // GRID — ~20% darker than the crosshair so it recedes
     0xffc9d1d9,  // AXIS_TEXT
     0xff303741,  // CROSSHAIR — grid tone lightened ~44%; reads above GRID
-    0xff161b22,  // TOOLTIP_BG
-    0xffc9d1d9,  // TOOLTIP_TEXT
+    0x00000000,  // RESERVED_7_ — retired slot, never read
+    0xffffffff,  // BADGE_TEXT — text on filled badges/pills
     0xff3e4855,  // CROSSHAIR_TARGET — CROSSHAIR lightened 30% (prior derived ring)
     0x00000000,  // BORDER_BULL — transparent sentinel: inherit BULL fill
     0x00000000,  // BORDER_BEAR — transparent sentinel: inherit BEAR fill

package/cpp/_core_src/viewport.h

@@ -20,8 +20,40 @@ struct Layout {
     float top_padding_frac;     // fraction of candle area; keeps prices off edges
     float bottom_padding_frac;
     float indicator_area_h;     // height reserved for below-chart indicator panes
+    // Opacity of everything drawn *inside* an axis strip, 1 = shown, 0 = hidden.
+    // Separate from the strip's extent because the two ramp at different rates
+    // while an axis is being hidden or revealed (see axis_opacity).
+    float y_axis_opacity;
+    float x_axis_opacity;
 };
 
+// --- Axis show/hide ---------------------------------------------------------
+// An axis is hidden by collapsing its strip to nothing rather than by zeroing
+// the underlying dimension: the y-axis width is *measured* from the widest price
+// label (labels::recompute_axis_width) and gets recomputed constantly, so a zero
+// written there would not survive. `t` is the collapse progress the host eases,
+// 0 = fully shown, 1 = fully hidden.
+
+inline float clamp_collapse(float t) {
+    return t < 0.f ? 0.f : (t > 1.f ? 1.f : t);
+}
+
+// The strip's on-screen extent. Everything downstream (candle_area_width,
+// price_pane_bottom) is derived from this, so the plot reclaims the space as
+// the strip shrinks.
+inline float axis_extent(float base, float t) {
+    return base * (1.f - clamp_collapse(t));
+}
+
+// Opacity of the strip's contents. Deliberately front-loaded: the labels are
+// fully gone by the time the strip is halfway collapsed, so text never sits in
+// a strip too narrow to hold it.
+inline float axis_opacity(float t) {
+    constexpr float kFadeBy = 0.5f;  // fraction of the collapse spent fading
+    const float p = clamp_collapse(t) / kFadeBy;
+    return p >= 1.f ? 0.f : 1.f - p;
+}
+
 // Bottom of the price (candle) pane = top of the indicator band. Shrinks when
 // an indicator pane is present so candles, volume, and price labels reflow.
 inline float price_pane_bottom(const Layout& l) {

package/lib/index.d.mts

@@ -93,6 +93,13 @@ type VroomTheme = {
     grid?: VroomColor;
     /** Axis label text (price + time). */
     axisText?: VroomColor;
+    /**
+     * Text drawn on a filled badge — the current-price indicator, the crosshair's
+     * price and time badges, and price-line pills. Defaults to white, which reads
+     * against the saturated fills those badges use on a dark theme; light themes
+     * generally want a dark value here.
+     */
+    badgeText?: VroomColor;
     /** Crosshair dashed lines. */
     crosshair?: VroomColor;
     /** Crosshair target — the hollow ring/dot at the intersection. */
@@ -134,6 +141,26 @@ type VroomTheme = {
      * continuously — leave it off for charts that should be able to go idle.
      */
     lineTipPulse?: boolean;
+    /**
+     * Show the price (y) axis strip down the right edge. Defaults to `true`.
+     *
+     * Hiding it collapses the strip and hands the reclaimed width to the plot, so
+     * the candles widen to fill it. Its contents — price labels, the current-price
+     * badge, the crosshair price badge, price-line axis badges — fade out ahead of
+     * the collapse; gridlines and the price indicator's dotted line stay. Animated
+     * over `transitionMs` unless the OS asks for reduced motion.
+     *
+     * The axis drag-to-scale region goes with the strip, so a hidden axis can't be
+     * scaled by dragging it.
+     */
+    showYAxis?: boolean;
+    /**
+     * Show the time (x) axis strip along the bottom. Defaults to `true`.
+     *
+     * Behaves like {@link VroomTheme.showYAxis}: the strip collapses, the plot
+     * grows into it, and the time labels and crosshair time badge fade first.
+     */
+    showXAxis?: boolean;
 };
 /** A time window over the candle data, as Unix epoch milliseconds. */
 type VisibleRange = {
@@ -177,6 +204,12 @@ type DrawingBase = {
     color?: VroomColor;
     /** Stroke width in px. Default 2. */
     width?: number;
+    /**
+     * Protect the drawing from editing. A locked drawing still renders and can
+     * still be selected — so a toolbar can offer to unlock it — but it can't be
+     * dragged, reshaped or deleted, and its grab handles aren't drawn. Web only.
+     */
+    locked?: boolean;
 };
 /** A two-point trendline from `points[0]` to `points[1]`. */
 type LineDrawing = DrawingBase & {
@@ -192,6 +225,15 @@ type BoxDrawing = DrawingBase & {
     type: 'box';
     /** Two opposite corners, in data space. */
     points: [DrawPoint, DrawPoint];
+    /**
+     * Interior fill, painted beneath the stroke. Omitted, the interior keeps its
+     * default tint of the stroke color at 10% alpha.
+     *
+     * A solid fill hides the candles the box was drawn around, so this usually
+     * wants an alpha — as the high byte of an 8-digit hex (`'#5400ce2c'` is a
+     * green at 33%), since vroom reads hex as `#aarrggbb`, not CSS `#rrggbbaa`.
+     */
+    fill?: VroomColor;
 };
 /**
  * A freehand pencil stroke: an open path through `points`, in order. Unlike the
@@ -224,6 +266,35 @@ type PathDrawing = DrawingBase & {
  * `'line'` and `'box'` are always exactly two points.
  */
 type Drawing = LineDrawing | BoxDrawing | PencilDrawing | PathDrawing;
+/** An axis-aligned rectangle in CSS px, relative to the chart container. */
+type DrawingRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The currently selected drawing and where it sits on screen. */
+type DrawingSelection = {
+    /**
+     * The selected drawing. While a drag or reshape is in flight this holds the
+     * last committed geometry — the edit reaches you through `onDrawingChange`
+     * on release — whereas `rect` tracks the shape live.
+     */
+    drawing: Drawing;
+    /** The drawing's bounds in CSS px, relative to the chart container. */
+    rect: DrawingRect;
+};
+/**
+ * The subset of a drawing's appearance a host can change after the fact,
+ * through `restyle`. Fields left out are kept as they were.
+ */
+type DrawingStyle = {
+    color?: VroomColor;
+    width?: number;
+    /** Box interior fill; ignored by the other drawing types. */
+    fill?: VroomColor;
+    locked?: boolean;
+};
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -264,11 +335,11 @@ type UndoRedoState = {
     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.
+ * Programmatic controls over the chart's drawings, 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 = {
+type DrawingControls = {
     /** 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. */
@@ -279,6 +350,16 @@ type UndoRedoControls = {
      * chart for what the user perceives as a brand-new context.
      */
     clearHistory: () => void;
+    /**
+     * Restyle the drawing with this `id`, merging `patch` over its current
+     * appearance. No-op for an unknown id.
+     *
+     * In managed mode the chart owns the drawings array, so this is the only way
+     * to say "this drawing's color is now X" — the array is otherwise mutated by
+     * user gestures alone. The change records an undo step and persists like any
+     * other edit.
+     */
+    restyle: (id: string, patch: DrawingStyle) => void;
 };
 /** Price source for a moving average. */
 type MASource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4';
@@ -749,6 +830,17 @@ type VroomChartCoreProps = {
      * drawing with this `id` from your controlled `drawings` state. Web only.
      */
     onDrawingDelete?: (id: string) => void;
+    /**
+     * Fired when the selected drawing changes, and again whenever its position on
+     * screen moves — panning, zooming, resizing, or dragging the shape itself.
+     * `null` on deselect.
+     *
+     * Anchor a floating toolbar to `selection.rect` and it will stay attached to
+     * the drawing: the rect is recomputed from live chart state once per painted
+     * frame, so it tracks 1:1 rather than settling after the gesture. Works in
+     * both controlled and managed mode. Web only.
+     */
+    onSelectionChange?: (selection: DrawingSelection | null) => void;
     /**
      * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
      * the user clicks away from a just-drawn line. Since `mode` is controlled, the
@@ -769,13 +861,13 @@ type VroomChartCoreProps = {
      */
     onHistoryChange?: (state: UndoRedoState) => void;
     /**
-     * Receives programmatic `undo`/`redo`/`clearHistory` controls in managed mode
-     * (e.g. `useRef<UndoRedoControls | null>(null)` passed here, then
+     * Receives programmatic `undo`/`redo`/`clearHistory`/`restyle` controls in
+     * managed mode (e.g. `useRef<DrawingControls | 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;
+        current: DrawingControls | null;
     };
     /**
      * Fired when the user presses the undo shortcut (⌘Z / Ctrl+Z) in controlled

package/lib/index.d.ts

@@ -93,6 +93,13 @@ type VroomTheme = {
     grid?: VroomColor;
     /** Axis label text (price + time). */
     axisText?: VroomColor;
+    /**
+     * Text drawn on a filled badge — the current-price indicator, the crosshair's
+     * price and time badges, and price-line pills. Defaults to white, which reads
+     * against the saturated fills those badges use on a dark theme; light themes
+     * generally want a dark value here.
+     */
+    badgeText?: VroomColor;
     /** Crosshair dashed lines. */
     crosshair?: VroomColor;
     /** Crosshair target — the hollow ring/dot at the intersection. */
@@ -134,6 +141,26 @@ type VroomTheme = {
      * continuously — leave it off for charts that should be able to go idle.
      */
     lineTipPulse?: boolean;
+    /**
+     * Show the price (y) axis strip down the right edge. Defaults to `true`.
+     *
+     * Hiding it collapses the strip and hands the reclaimed width to the plot, so
+     * the candles widen to fill it. Its contents — price labels, the current-price
+     * badge, the crosshair price badge, price-line axis badges — fade out ahead of
+     * the collapse; gridlines and the price indicator's dotted line stay. Animated
+     * over `transitionMs` unless the OS asks for reduced motion.
+     *
+     * The axis drag-to-scale region goes with the strip, so a hidden axis can't be
+     * scaled by dragging it.
+     */
+    showYAxis?: boolean;
+    /**
+     * Show the time (x) axis strip along the bottom. Defaults to `true`.
+     *
+     * Behaves like {@link VroomTheme.showYAxis}: the strip collapses, the plot
+     * grows into it, and the time labels and crosshair time badge fade first.
+     */
+    showXAxis?: boolean;
 };
 /** A time window over the candle data, as Unix epoch milliseconds. */
 type VisibleRange = {
@@ -177,6 +204,12 @@ type DrawingBase = {
     color?: VroomColor;
     /** Stroke width in px. Default 2. */
     width?: number;
+    /**
+     * Protect the drawing from editing. A locked drawing still renders and can
+     * still be selected — so a toolbar can offer to unlock it — but it can't be
+     * dragged, reshaped or deleted, and its grab handles aren't drawn. Web only.
+     */
+    locked?: boolean;
 };
 /** A two-point trendline from `points[0]` to `points[1]`. */
 type LineDrawing = DrawingBase & {
@@ -192,6 +225,15 @@ type BoxDrawing = DrawingBase & {
     type: 'box';
     /** Two opposite corners, in data space. */
     points: [DrawPoint, DrawPoint];
+    /**
+     * Interior fill, painted beneath the stroke. Omitted, the interior keeps its
+     * default tint of the stroke color at 10% alpha.
+     *
+     * A solid fill hides the candles the box was drawn around, so this usually
+     * wants an alpha — as the high byte of an 8-digit hex (`'#5400ce2c'` is a
+     * green at 33%), since vroom reads hex as `#aarrggbb`, not CSS `#rrggbbaa`.
+     */
+    fill?: VroomColor;
 };
 /**
  * A freehand pencil stroke: an open path through `points`, in order. Unlike the
@@ -224,6 +266,35 @@ type PathDrawing = DrawingBase & {
  * `'line'` and `'box'` are always exactly two points.
  */
 type Drawing = LineDrawing | BoxDrawing | PencilDrawing | PathDrawing;
+/** An axis-aligned rectangle in CSS px, relative to the chart container. */
+type DrawingRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The currently selected drawing and where it sits on screen. */
+type DrawingSelection = {
+    /**
+     * The selected drawing. While a drag or reshape is in flight this holds the
+     * last committed geometry — the edit reaches you through `onDrawingChange`
+     * on release — whereas `rect` tracks the shape live.
+     */
+    drawing: Drawing;
+    /** The drawing's bounds in CSS px, relative to the chart container. */
+    rect: DrawingRect;
+};
+/**
+ * The subset of a drawing's appearance a host can change after the fact,
+ * through `restyle`. Fields left out are kept as they were.
+ */
+type DrawingStyle = {
+    color?: VroomColor;
+    width?: number;
+    /** Box interior fill; ignored by the other drawing types. */
+    fill?: VroomColor;
+    locked?: boolean;
+};
 /**
  * Storage adapter for **managed** drawing persistence. Provide it via the
  * `drawingStore` prop and the chart owns the drawings array itself — loading and
@@ -264,11 +335,11 @@ type UndoRedoState = {
     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.
+ * Programmatic controls over the chart's drawings, 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 = {
+type DrawingControls = {
     /** 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. */
@@ -279,6 +350,16 @@ type UndoRedoControls = {
      * chart for what the user perceives as a brand-new context.
      */
     clearHistory: () => void;
+    /**
+     * Restyle the drawing with this `id`, merging `patch` over its current
+     * appearance. No-op for an unknown id.
+     *
+     * In managed mode the chart owns the drawings array, so this is the only way
+     * to say "this drawing's color is now X" — the array is otherwise mutated by
+     * user gestures alone. The change records an undo step and persists like any
+     * other edit.
+     */
+    restyle: (id: string, patch: DrawingStyle) => void;
 };
 /** Price source for a moving average. */
 type MASource = 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4';
@@ -749,6 +830,17 @@ type VroomChartCoreProps = {
      * drawing with this `id` from your controlled `drawings` state. Web only.
      */
     onDrawingDelete?: (id: string) => void;
+    /**
+     * Fired when the selected drawing changes, and again whenever its position on
+     * screen moves — panning, zooming, resizing, or dragging the shape itself.
+     * `null` on deselect.
+     *
+     * Anchor a floating toolbar to `selection.rect` and it will stay attached to
+     * the drawing: the rect is recomputed from live chart state once per painted
+     * frame, so it tracks 1:1 rather than settling after the gesture. Works in
+     * both controlled and managed mode. Web only.
+     */
+    onSelectionChange?: (selection: DrawingSelection | null) => void;
     /**
      * Fired when the chart wants the mode changed — e.g. it requests `'pan'` after
      * the user clicks away from a just-drawn line. Since `mode` is controlled, the
@@ -769,13 +861,13 @@ type VroomChartCoreProps = {
      */
     onHistoryChange?: (state: UndoRedoState) => void;
     /**
-     * Receives programmatic `undo`/`redo`/`clearHistory` controls in managed mode
-     * (e.g. `useRef<UndoRedoControls | null>(null)` passed here, then
+     * Receives programmatic `undo`/`redo`/`clearHistory`/`restyle` controls in
+     * managed mode (e.g. `useRef<DrawingControls | 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;
+        current: DrawingControls | null;
     };
     /**
      * Fired when the user presses the undo shortcut (⌘Z / Ctrl+Z) in controlled

package/lib/index.js

@@ -163,6 +163,8 @@ var COLOR_KEYS = {
   // VROOM_COLOR_AXIS_TEXT
   crosshair: 6,
   // VROOM_COLOR_CROSSHAIR
+  badgeText: 8,
+  // VROOM_COLOR_BADGE_TEXT (7 is a retired slot)
   crosshairTarget: 9,
   // VROOM_COLOR_CROSSHAIR_TARGET
   borderBull: 10,
@@ -638,9 +640,13 @@ function VroomChart(props) {
       handle.setChartType(target);
       const p = handle.render();
       if (p) pictureSV.value = p;
+      maybeStartAnim();
+      return void 0;
+    }
+    if (morphFade.current === target) {
+      maybeStartAnim();
       return void 0;
     }
-    if (morphFade.current === target) return void 0;
     if (morphRaf.current != null) {
       cancelAnimationFrame(morphRaf.current);
       morphRaf.current = null;
@@ -651,6 +657,7 @@ function VroomChart(props) {
       handle.setChartType(target);
       const p = handle.render();
       if (p) pictureSV.value = p;
+      maybeStartAnim();
       return void 0;
     }
     const from = morphFade.current;
@@ -671,6 +678,7 @@ function VroomChart(props) {
         handle.setChartType(target);
         const q = handle.render();
         if (q) pictureSV.value = q;
+        maybeStartAnim();
       }
     };
     morphRaf.current = requestAnimationFrame(step);
@@ -680,7 +688,7 @@ function VroomChart(props) {
         morphRaf.current = null;
       }
     };
-  }, [handle, chartType, transitionMs, reduceMotion, pictureSV]);
+  }, [handle, chartType, transitionMs, reduceMotion, pictureSV, maybeStartAnim]);
   const volumeRaf = (0, import_react2.useRef)(null);
   const volumeHandle = (0, import_react2.useRef)(null);
   (0, import_react2.useEffect)(() => {
@@ -690,9 +698,13 @@ function VroomChart(props) {
     if (volumeHandle.current !== handle || volumeCollapseRef.current == null) {
       volumeHandle.current = handle;
       volumeCollapseRef.current = { t: target, easing };
+      maybeStartAnim();
+      return void 0;
+    }
+    if (volumeCollapseRef.current.t === target) {
+      maybeStartAnim();
       return void 0;
     }
-    if (volumeCollapseRef.current.t === target) return void 0;
     if (volumeRaf.current != null) {
       cancelAnimationFrame(volumeRaf.current);
       volumeRaf.current = null;
@@ -703,6 +715,7 @@ function VroomChart(props) {
       handle.setVolumeCollapse(target, easing);
       const p = handle.render();
       if (p) pictureSV.value = p;
+      maybeStartAnim();
       return void 0;
     }
     const from = volumeCollapseRef.current.t;
@@ -716,7 +729,12 @@ function VroomChart(props) {
       handle.setVolumeCollapse(t, kind);
       const p = handle.render();
       if (p) pictureSV.value = p;
-      volumeRaf.current = prog < 1 ? requestAnimationFrame(step) : null;
+      if (prog < 1) {
+        volumeRaf.current = requestAnimationFrame(step);
+      } else {
+        volumeRaf.current = null;
+        maybeStartAnim();
+      }
     };
     volumeRaf.current = requestAnimationFrame(step);
     return () => {
@@ -725,7 +743,86 @@ function VroomChart(props) {
         volumeRaf.current = null;
       }
     };
-  }, [handle, volume?.enabled, transitionMs, reduceMotion, pictureSV, volumeCollapseRef]);
+  }, [
+    handle,
+    volume?.enabled,
+    transitionMs,
+    reduceMotion,
+    pictureSV,
+    volumeCollapseRef,
+    maybeStartAnim
+  ]);
+  const axisRaf = (0, import_react2.useRef)(null);
+  const axisHandle = (0, import_react2.useRef)(null);
+  const axisCollapse = (0, import_react2.useRef)(null);
+  const showYAxis = theme?.showYAxis ?? true;
+  const showXAxis = theme?.showXAxis ?? true;
+  (0, import_react2.useEffect)(() => {
+    if (!handle) return void 0;
+    const targetY = showYAxis ? 0 : 1;
+    const targetX = showXAxis ? 0 : 1;
+    if (axisHandle.current !== handle || axisCollapse.current == null) {
+      axisHandle.current = handle;
+      axisCollapse.current = { y: targetY, x: targetX };
+      handle.setAxisCollapse(targetY, targetX);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      maybeStartAnim();
+      return void 0;
+    }
+    const fromY = axisCollapse.current.y;
+    const fromX = axisCollapse.current.x;
+    if (fromY === targetY && fromX === targetX) {
+      maybeStartAnim();
+      return void 0;
+    }
+    if (axisRaf.current != null) {
+      cancelAnimationFrame(axisRaf.current);
+      axisRaf.current = null;
+    }
+    const dur = Math.max(0, transitionMs ?? 300);
+    if (dur === 0 || reduceMotion) {
+      axisCollapse.current = { y: targetY, x: targetX };
+      handle.setAxisCollapse(targetY, targetX);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      maybeStartAnim();
+      return void 0;
+    }
+    let startTs = null;
+    const step = (now) => {
+      if (startTs == null) startTs = now;
+      const prog = Math.min(1, (now - startTs) / dur);
+      const e = ease(easingRef.current, prog);
+      const y = prog < 1 ? fromY + (targetY - fromY) * e : targetY;
+      const x = prog < 1 ? fromX + (targetX - fromX) * e : targetX;
+      axisCollapse.current = { y, x };
+      handle.setAxisCollapse(y, x);
+      const p = handle.render();
+      if (p) pictureSV.value = p;
+      if (prog < 1) {
+        axisRaf.current = requestAnimationFrame(step);
+      } else {
+        axisRaf.current = null;
+        maybeStartAnim();
+      }
+    };
+    axisRaf.current = requestAnimationFrame(step);
+    return () => {
+      if (axisRaf.current != null) {
+        cancelAnimationFrame(axisRaf.current);
+        axisRaf.current = null;
+      }
+    };
+  }, [
+    handle,
+    showYAxis,
+    showXAxis,
+    transitionMs,
+    reduceMotion,
+    pictureSV,
+    maybeStartAnim
+  ]);
   const hitAxis = (0, import_react2.useCallback)(
     (x, y) => {
       if (!handle) return "chart";