react-native-livechart 3.0.0 → 3.2.0

package/src/hooks/useCrosshair.ts

@@ -16,6 +16,7 @@ import type { CandlePoint, LiveChartPalette, ScrubPoint } from "../types";
 import {
   computeCandleTooltipLayout,
   computeCrosshairOpacity,
+  computeScrubDotY,
   computeScrubTime,
   deriveCrosshairTooltipSingle,
   type CrosshairState,
@@ -57,9 +58,14 @@ export function useCrosshair(
   candleOpts?: CrosshairCandleOpts,
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay = 0,
+  onGestureStart?: () => void,
+  onGestureEnd?: () => void,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
+  // Tracks whether the active scrub phase actually began, so a tap that never
+  // activates doesn't emit a spurious onGestureEnd.
+  const gestureStarted = useSharedValue(false);
 
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
@@ -112,6 +118,19 @@ export function useCrosshair(
     ),
   );
 
+  // Y pixel of the scrub intersection — used by the selection dot. -1 when
+  // there's no value to mark.
+  const scrubDotY = useDerivedValue(() =>
+    computeScrubDotY(
+      scrubValue.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
   // Monospace advance width, measured once per render (not per scrub frame) so
   // the tooltip layout worklet can size text by character count instead of a
   // per-frame Skia measureText.
@@ -165,7 +184,19 @@ export function useCrosshair(
     onScrub?.(null);
   }
 
+  /* istanbul ignore next */
+  function handleGestureStart() {
+    onGestureStart?.();
+  }
+
+  /* istanbul ignore next */
+  function handleGestureEnd() {
+    onGestureEnd?.();
+  }
+
   const hasOnScrub = onScrub != null;
+  const hasOnGestureStart = onGestureStart != null;
+  const hasOnGestureEnd = onGestureEnd != null;
 
   useAnimatedReaction(
     () => {
@@ -178,13 +209,14 @@ export function useCrosshair(
       if (val === null || time < 0) return "__pending__";
       const chartW = engine.canvasWidth.get() - padding.left - padding.right;
       if (chartW <= 0) return "__pending__";
-      const h = engine.canvasHeight.get();
-      const chartH = h - padding.top - padding.bottom;
-      const valRange = engine.displayMax.get() - engine.displayMin.get();
-      const dotY =
-        valRange === 0
-          ? padding.top + chartH / 2
-          : padding.top + ((engine.displayMax.get() - val) / valRange) * chartH;
+      const dotY = computeScrubDotY(
+        val,
+        engine.displayMin.get(),
+        engine.displayMax.get(),
+        engine.canvasHeight.get(),
+        padding.top,
+        padding.bottom,
+      );
       let candleJson: string | null = null;
       if (isCandleMode) {
         const c = scrubCandle.get();
@@ -229,6 +261,8 @@ export function useCrosshair(
         if (!enabled) return;
         scrubX.set(e.x);
         scrubActive.set(true);
+        gestureStarted.set(true);
+        if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
     .onUpdate(
@@ -243,6 +277,10 @@ export function useCrosshair(
         "worklet";
         scrubActive.set(false);
         if (hasOnScrub) scheduleOnRN(handleScrubEnd);
+        if (gestureStarted.get()) {
+          gestureStarted.set(false);
+          if (hasOnGestureEnd) scheduleOnRN(handleGestureEnd);
+        }
       },
     );
 
@@ -258,6 +296,7 @@ export function useCrosshair(
     scrubValue,
     crosshairOpacity,
     tooltipLayout,
+    scrubDotY,
     gesture,
   };
 }

package/src/hooks/useCrosshairSeries.ts

@@ -5,6 +5,7 @@ import {
   useDerivedValue,
   useSharedValue,
 } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
 import type { MultiEngineState } from "../core/useLiveChartEngine";
 import { type ChartPadding } from "../draw/line";
 import type { ScrubPointMulti } from "../types";
@@ -14,6 +15,7 @@ import {
 } from "./crosshairSeries";
 import {
   computeCrosshairOpacity,
+  computeScrubDotY,
   computeScrubTime,
   HIDDEN_TOOLTIP,
   type CrosshairState,
@@ -30,9 +32,14 @@ export function useCrosshairSeries(
   onScrub?: (point: ScrubPointMulti | null) => void,
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay = 0,
+  onGestureStart?: () => void,
+  onGestureEnd?: () => void,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
+  // Tracks whether the active scrub phase actually began, so a tap that never
+  // activates doesn't emit a spurious onGestureEnd.
+  const gestureStarted = useSharedValue(false);
 
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
@@ -62,9 +69,34 @@ export function useCrosshairSeries(
     ),
   );
 
+  // Y pixel of the scrub intersection (leading-series value) — used by the
+  // selection dot. -1 when there's no value to mark.
+  const scrubDotY = useDerivedValue(() =>
+    computeScrubDotY(
+      scrubValue.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
   const tooltipLayout = useSharedValue(HIDDEN_TOOLTIP);
 
+  /* istanbul ignore next */
+  function handleGestureStart() {
+    onGestureStart?.();
+  }
+
+  /* istanbul ignore next */
+  function handleGestureEnd() {
+    onGestureEnd?.();
+  }
+
   const hasOnScrub = onScrub != null;
+  const hasOnGestureStart = onGestureStart != null;
+  const hasOnGestureEnd = onGestureEnd != null;
 
   useAnimatedReaction(
     () => {
@@ -77,14 +109,14 @@ export function useCrosshairSeries(
       if (chartW <= 0) return "__pending__";
       const r = interpolateSeriesAtTime(engine.series.get(), time);
       if (r.primary === null) return "__pending__";
-      const h = engine.canvasHeight.get();
-      const chartH = h - padding.top - padding.bottom;
-      const valRange = engine.displayMax.get() - engine.displayMin.get();
-      const dotY =
-        valRange === 0
-          ? padding.top + chartH / 2
-          : padding.top +
-            ((engine.displayMax.get() - r.primary) / valRange) * chartH;
+      const dotY = computeScrubDotY(
+        r.primary,
+        engine.displayMin.get(),
+        engine.displayMax.get(),
+        engine.canvasHeight.get(),
+        padding.top,
+        padding.bottom,
+      );
       return JSON.stringify({
         time,
         x,
@@ -136,6 +168,8 @@ export function useCrosshairSeries(
         if (!enabled) return;
         scrubX.set(e.x);
         scrubActive.set(true);
+        gestureStarted.set(true);
+        if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
     .onUpdate(
@@ -149,6 +183,10 @@ export function useCrosshairSeries(
       /* istanbul ignore next */ () => {
         "worklet";
         scrubActive.set(false);
+        if (gestureStarted.get()) {
+          gestureStarted.set(false);
+          if (hasOnGestureEnd) scheduleOnRN(handleGestureEnd);
+        }
       },
     );
 
@@ -164,6 +202,7 @@ export function useCrosshairSeries(
     scrubValue,
     crosshairOpacity,
     tooltipLayout,
+    scrubDotY,
     gesture,
   };
 }

package/src/hooks/useDegen.ts

@@ -20,6 +20,8 @@ export function useDegen(
   momentumSV: SharedValue<Momentum>,
   cfg: ResolvedDegenConfig | null,
   onShake?: (payload: DegenShakePayload) => void,
+  /** Static charts run no loops: register the frame callback without starting it. */
+  isStatic = false,
 ): {
   pack: SharedValue<Float64Array<ArrayBuffer>>;
   packRevision: SharedValue<number>;
@@ -248,6 +250,10 @@ export function useDegen(
       }
       prevActiveCount.set(activeCount);
     },
+    // Static charts register the callback but never start it, so no degen frame
+    // loop runs. Live charts keep the default (autostart) loop unchanged. The
+    // controller also forces `cfg` to null in static, so degen is doubly off.
+    !isStatic,
   );
 
   const shakeTransform = useDerivedValue(() => {

package/src/hooks/useMarkers.ts

@@ -30,6 +30,8 @@ export function useMarkers(
   onMarkerHover?: (event: MarkerHoverEvent | null) => void,
   seriesSV?: SharedValue<SeriesConfig[]>,
   lineData?: SharedValue<LiveChartPoint[]>,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ): { projected: SharedValue<ProjectedMarker[]>; tapGesture: ReturnType<typeof Gesture.Tap> } {
   const projected = useSharedValue<ProjectedMarker[]>([]);
   const cacheRef = useRef<{
@@ -73,6 +75,7 @@ export function useMarkers(
       });
       projected.set(buf);
     },
+    autostart,
   );
 
   const tapGesture = Gesture.Tap().onEnd(

package/src/hooks/useTradeStream.ts

@@ -25,6 +25,8 @@ export function useTradeStream(
   tradeStream: SharedValue<TradeEvent[]>,
   padding: ChartPadding,
   active: boolean,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ): SharedValue<TradeMarker[]> {
   const markers = useSharedValue<TradeMarker[]>([]);
   const state = useSharedValue<TradeStreamState>(createTradeStreamState());
@@ -58,6 +60,7 @@ export function useTradeStream(
       const chartH = chartBottom - chartTop;
       markers.set(projectLabels(s, chartTop, chartH));
     },
+    autostart,
   );
 
   return markers;

package/src/index.ts

@@ -28,6 +28,7 @@ export { useTradeStream } from "./hooks/useTradeStream";
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export type {
+  AxisLabelConfig,
   BadgeConfig,
   BadgeMetrics,
   BadgeVariant,
@@ -67,6 +68,9 @@ export type {
   ScrubPointCore,
   ScrubPointMulti,
   ScrubSeriesValue,
+  SelectionDotConfig,
+  SelectionDotProps,
+  SelectionDotRingConfig,
   SeriesConfig,
   ThemeMode,
   TradeEvent,

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ComponentType, ReactElement } from "react";
 import type { ViewStyle } from "react-native";
 import type { SharedValue } from "react-native-reanimated";
 
@@ -142,6 +143,11 @@ export interface LineConfig {
   width?: number;
   /** Line color override. Defaults to palette-derived accent. */
   color?: string;
+  /**
+   * Two or more CSS color strings → horizontal gradient along the stroke
+   * (left → right). Takes precedence over `color` when set.
+   */
+  colors?: string[];
 }
 
 /** Area fill gradient beneath the chart line. */
@@ -150,6 +156,11 @@ export interface GradientConfig {
   topOpacity?: number;
   /** Opacity at the bottom of the gradient. Default `0`. */
   bottomOpacity?: number;
+  /** Explicit gradient color stops (top → bottom) for the area fill. Overrides
+   *  topOpacity/bottomOpacity when provided. Must have at least 2 entries. */
+  colors?: string[];
+  /** Optional stop positions (0..1, ascending) matching `colors` length. */
+  positions?: number[];
 }
 
 /** Value badge pill configuration. */
@@ -170,6 +181,24 @@ export interface YAxisConfig {
   minGap?: number;
 }
 
+/**
+ * Axis edge label — the value floated at the plot's top or bottom edge
+ * (Robinhood-style high/low). Pass `topLabel`/`bottomLabel` as `true` for the
+ * batteries-included value label (the chart's current top/bottom Y-axis bound,
+ * updated each frame), an object to configure it, or `{ render }` to float a
+ * fully custom element instead.
+ */
+export interface AxisLabelConfig {
+  /** Formatter for the built-in value. Defaults to the chart's `formatValue`. */
+  format?: (v: number) => string;
+  /** Text color. Defaults to a muted label color (`palette.gridLabel`). */
+  color?: string;
+  /** Horizontal alignment within the plot width. Default `"right"`. */
+  position?: "left" | "right";
+  /** Full custom element, floated at the edge. Overrides the built-in value label. */
+  render?: () => ReactElement | null;
+}
+
 /** X-axis (time) configuration. */
 export interface XAxisConfig {
   /** Minimum pixel gap between time labels. Default `60`. */
@@ -213,6 +242,55 @@ export interface ScrubConfig {
   panGestureDelay?: number;
 }
 
+/**
+ * Props passed to a custom {@link SelectionDotConfig.component} — the dot drawn
+ * at the scrub intersection while scrubbing. All positional inputs are
+ * SharedValues so the dot animates on the UI thread without re-renders.
+ */
+export interface SelectionDotProps {
+  /** Scrub X in canvas px. */
+  x: SharedValue<number>;
+  /** Scrub Y in canvas px (the line/value intersection). */
+  y: SharedValue<number>;
+  /** Whether scrubbing is active. */
+  active: SharedValue<boolean>;
+  /** Crosshair fade opacity (0..1), already ramped. */
+  opacity: SharedValue<number>;
+  /** Resolved dot color (accent/series color). */
+  color: string;
+  /** Suggested dot radius in px. */
+  size: number;
+}
+
+/** Outer ring drawn around the built-in selection dot (the subtle halo). */
+export interface SelectionDotRingConfig {
+  /** Ring color. Defaults to the dot color. */
+  color?: string;
+  /** Ring thickness in pixels — how far the halo extends past the dot. Default `2`. */
+  width?: number;
+}
+
+/**
+ * Selection-dot styling — the dot drawn at the scrub intersection while
+ * scrubbing. Pass `selectionDot={false}` to hide it, an object to configure the
+ * built-in dot, or `{ component }` to supply a fully custom Skia dot.
+ */
+export interface SelectionDotConfig {
+  /** Dot radius in px. Default `4`. */
+  size?: number;
+  /** Dot color. Defaults to the line / leading-series color. */
+  color?: string;
+  /**
+   * Outer ring around the dot. `true`/config = on, `false` = off. Default on.
+   */
+  ring?: boolean | SelectionDotRingConfig;
+  /**
+   * Fully custom Skia dot — receives the scrub position as SharedValues. When
+   * set, the `size` / `color` / `ring` knobs are ignored.
+   */
+  component?: ComponentType<SelectionDotProps>;
+}
+
 /** Left-edge fade — soft erase so the chart blends into the left gutter (web liveline parity). */
 export interface LeftEdgeFadeConfig {
   /**
@@ -695,6 +773,20 @@ export interface LiveChartCoreProps {
   yAxis?: boolean | YAxisConfig;
   /** X-axis time labels. `true` = defaults, `false` = hidden, or pass `XAxisConfig`. Default `true`. */
   xAxis?: boolean | XAxisConfig;
+  /**
+   * Label floated at the top edge of the plot area. `true` = the built-in value
+   * label showing the chart's current TOP Y-axis bound (updated each frame),
+   * `false`/omitted = none, or pass `AxisLabelConfig` to configure it (or supply
+   * a custom `render`). Default off.
+   */
+  topLabel?: boolean | AxisLabelConfig;
+  /**
+   * Label floated at the bottom edge of the plot area. `true` = the built-in
+   * value label showing the chart's current BOTTOM Y-axis bound (updated each
+   * frame), `false`/omitted = none, or pass `AxisLabelConfig` (or a custom
+   * `render`). Default off.
+   */
+  bottomLabel?: boolean | AxisLabelConfig;
   /** Reference lines / bands drawn into the chart. Supports all three `ReferenceLine` forms. */
   referenceLines?: ReferenceLine[];
   /** Per-instance grid-line styling. Pass an object to override color / width / dash / opacity. */
@@ -737,6 +829,16 @@ export interface LiveChartCoreProps {
   accessibilityRole?: "image" | "none" | "adjustable" | "summary";
   /** Crosshair scrubbing on hover/drag. `true` = defaults, `false` = disabled, or pass `ScrubConfig`. Default `true`. */
   scrub?: boolean | ScrubConfig;
+  /**
+   * Selection dot drawn at the scrub intersection while scrubbing. `true`/omitted
+   * = built-in dot, `false` = hidden, or pass `SelectionDotConfig` (`size`,
+   * `color`, `ring`, or a custom `component`). Default `true`.
+   */
+  selectionDot?: boolean | SelectionDotConfig;
+  /** Called once when the user starts scrubbing/panning the chart. */
+  onGestureStart?: () => void;
+  /** Called once when the user stops scrubbing/panning the chart. */
+  onGestureEnd?: () => void;
   /**
    * Fade out chart content on the left (destination-out style). `true` = defaults, `false` = off,
    * or pass `LeftEdgeFadeConfig`. Default `true`.
@@ -796,6 +898,10 @@ export interface LiveChartProps extends LiveChartCoreProps {
   data: SharedValue<LiveChartPoint[]>;
   /** Latest live value for smooth interpolation between data updates. */
   value: SharedValue<number>;
+  /** Render once with no per-frame animation loop — for many small charts (sparklines)
+   *  in a list. Pulse/scrub/degen and the entry animation are disabled. Frame the data
+   *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
+  static?: boolean;
   /** Called when the user scrubs the crosshair. `null` when scrub ends. */
   onScrub?: (point: ScrubPoint | null) => void;
   /**