react-native-livechart 4.17.0 → 4.19.0

package/src/hooks/useCrosshair.ts

@@ -37,6 +37,7 @@ import {
   SCRUB_ACTIVATE_X_PX,
   SCRUB_FAIL_Y_PX,
   snapPrice,
+  snapScrubXToCandleCenter,
   startPlainScrub,
   type CrosshairState,
   updatePlainScrub,
@@ -157,6 +158,12 @@ export function useCrosshair(
    * Default `false`.
    */
   clampToPlot = false,
+  /**
+   * Candle mode: quantize the plain-scrub X to the hovered candle's center
+   * before it enters `scrubX` (`scrub.snapToCandles`). No-op in line mode.
+   * Default `false`.
+   */
+  snapToCandles = false,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -519,6 +526,26 @@ export function useCrosshair(
       ? SCRUB_ACTION_PRESS_HOLD_MS
       : panGestureDelay;
 
+  // `scrub.snapToCandles`: quantize the scrub X to the hovered candle's center
+  // before it enters `scrubX`, so the crosshair — and everything derived from
+  // it (time, tooltip, dim edge) — jumps candle-to-candle instead of gliding.
+  // Line mode and gaps between candles pass the raw X through.
+  /* istanbul ignore next -- worklet, called only from UI-thread gesture handlers */
+  const snapCandleX = (x: number): number => {
+    "worklet";
+    if (!snapToCandles || !isCandleMode || !candlesSV) return x;
+    return snapScrubXToCandleCenter(
+      x,
+      candlesSV.get(),
+      liveCandleSV?.get() ?? null,
+      candleWidthSecs,
+      padding,
+      engine.canvasWidth.get(),
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+    );
+  };
+
   let gesture = Gesture.Pan()
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
@@ -618,7 +645,7 @@ export function useCrosshair(
         // guard needed. (Plain-scrub counterpart of the scrub-action tap defer.)
         if (deferTapHit !== undefined && deferTapHit(e.x, e.y)) return;
         startPlainScrub(
-          e.x,
+          snapCandleX(e.x),
           padding,
           engine.canvasWidth.get(),
           clampPlainScrubToPlot,
@@ -653,7 +680,7 @@ export function useCrosshair(
           return;
         }
         updatePlainScrub(
-          e.x,
+          snapCandleX(e.x),
           padding,
           engine.canvasWidth.get(),
           clampPlainScrubToPlot,

package/src/hooks/useDegen.ts

@@ -20,8 +20,6 @@ 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>;
@@ -154,6 +152,8 @@ export function useDegen(
     speedMaxSV,
   ]);
 
+  // ChartWithDegen only mounts while the resolved effect is enabled; static
+  // charts force that config to null and unmount this callback entirely.
   useFrameCallback(
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
@@ -250,10 +250,6 @@ 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/useLiveDot.ts

@@ -1,5 +1,8 @@
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type {
+  ChartEngineScroll,
+  SingleEngineState,
+} from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 
 /**
@@ -10,17 +13,39 @@ import type { ChartPadding } from "../draw/line";
  * With `followViewEdge` + `edgeValue`, the dot (and the value line that shares
  * `dotY`) tracks the visible window's right-edge price while scrolled back, so it
  * stays aligned with a `followViewEdge` badge instead of marking the live value.
+ *
+ * With `trackWhileParked` (`dot.trackWhileParked`), the dot instead tracks the
+ * **true live point's x** while scrolled back / overscrolled (`viewEnd`
+ * frozen), and hides once the live point leaves the visible window.
+ * `followViewEdge` wins when both are set — an edge-pinned dot must stay
+ * aligned with its badge.
  */
 export function useLiveDot(
-  engine: SingleEngineState,
+  engine: SingleEngineState & ChartEngineScroll,
   padding: ChartPadding,
   edgeValue?: SharedValue<number>,
   followViewEdge = false,
+  trackWhileParked = false,
 ) {
   const dotX = useDerivedValue(() => {
     const w = engine.canvasWidth.value;
     if (w === 0) return -100;
-    return w - padding.right;
+    const right = w - padding.right;
+    // While parked (scrolled back / overscrolled) the live point is not at the
+    // plot edge — track its real x so a pan doesn't lose the dot, and hide it
+    // only once the point leaves the window.
+    if (trackWhileParked && !followViewEdge && engine.viewEnd.value != null) {
+      const data = engine.data.value;
+      const last = data[data.length - 1];
+      const win = engine.displayWindow.value;
+      const chartW = w - padding.left - padding.right;
+      if (!last || win <= 0 || chartW <= 0) return -100;
+      const x =
+        padding.left +
+        ((last.time - (engine.timestamp.value - win)) / win) * chartW;
+      return x < padding.left || x > right ? -100 : x;
+    }
+    return right;
   });
 
   const dotY = useDerivedValue(() => {

package/src/hooks/useMarkers.ts

@@ -1,4 +1,4 @@
-import { useRef } from "react";
+import { useEffect, useRef } from "react";
 import { Gesture } from "react-native-gesture-handler";
 import {
   useFrameCallback,
@@ -77,7 +77,7 @@ export function useMarkers(
       onMarkerPress?.(event);
     };
 
-  useFrameCallback(
+  const markerFrameCallback = useFrameCallback(
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ () => {
       "worklet";
       const cache = cacheRef.current!;
@@ -102,11 +102,19 @@ export function useMarkers(
         lineData: lineData?.get(),
         lineLinear,
       });
-      clusterMarkers(markers.get(), buf, { config: cluster });
+      clusterMarkers(markers.get(), buf, {
+        config: cluster,
+        minY: 0,
+        maxY: engine.canvasHeight.get(),
+      });
       projected.set(buf);
     },
     autostart,
   );
+  useEffect(() => {
+    // Reanimated does not reactively apply later `autostart` values.
+    markerFrameCallback.setActive(autostart);
+  }, [autostart, markerFrameCallback]);
 
   const tapGesture = Gesture.Tap().onEnd(
     /* istanbul ignore next -- gesture worklet runs on UI thread, not in Jest */ (

package/src/hooks/useMultiSeriesLinePaths.ts

@@ -4,6 +4,10 @@ import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { MAX_MULTI_SERIES } from "../constants";
 import type { MultiEngineState } from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
+import {
+  makeLineSimplifyScratch,
+  simplifyLinePoints,
+} from "../math/simplify";
 import { drawSpline, makeSplineScratch } from "../math/spline";
 import { usePathBuilders } from "./usePathBuilder";
 
@@ -21,25 +25,31 @@ export function useMultiSeriesLinePaths(
   engine: MultiEngineState,
   padding: ChartPadding,
   activeSeriesCount = MAX_MULTI_SERIES,
+  /** Shared screen-space simplification tolerance; a series can override it. */
+  simplifyTolerance = 0,
 ): SharedValue<SkPath[]> {
   const builders = usePathBuilders(MAX_MULTI_SERIES);
 
   const poolRef = useRef<{
     empty: SkPath;
     ptsBuf: number[];
+    simplifiedPts: number[];
     pathsA: SkPath[];
     pathsB: SkPath[];
     pathsTick: boolean;
     scratch: ReturnType<typeof makeSplineScratch>;
+    simplifyScratch: ReturnType<typeof makeLineSimplifyScratch>;
   } | null>(null);
   if (poolRef.current === null) {
     poolRef.current = {
       empty: Skia.Path.Make(),
       ptsBuf: [] as number[],
+      simplifiedPts: [] as number[],
       pathsA: [] as SkPath[],
       pathsB: [] as SkPath[],
       pathsTick: false,
       scratch: makeSplineScratch(),
+      simplifyScratch: makeLineSimplifyScratch(),
     };
   }
 
@@ -52,19 +62,36 @@ export function useMultiSeriesLinePaths(
     const out = pool.pathsTick ? pool.pathsA : pool.pathsB;
     out.length = 0;
     const count = Math.min(activeSeriesCount, s.length, MAX_MULTI_SERIES);
+    const now = engine.timestamp.get();
+    const windowSecs = engine.displayWindow.get();
+    const canvasWidth = engine.canvasWidth.get();
+    const chartWidth = canvasWidth - padding.left - padding.right;
+    const absoluteXOffset =
+      windowSecs > 0 ? (now - windowSecs) * (chartWidth / windowSecs) : 0;
     for (let i = 0; i < count; i++) {
-      const pts = buildLinePoints(
+      const rawPts = buildLinePoints(
         s[i].data,
         displays[i] ?? s[i].value,
-        engine.timestamp.get(),
-        engine.displayWindow.get(),
+        now,
+        windowSecs,
         engine.displayMin.get(),
         engine.displayMax.get(),
-        engine.canvasWidth.get(),
+        canvasWidth,
         engine.canvasHeight.get(),
         padding,
         pool.ptsBuf,
       );
+      const seriesTolerance = s[i].simplify ?? simplifyTolerance;
+      const pts =
+        Number.isFinite(seriesTolerance) && seriesTolerance > 0
+          ? simplifyLinePoints(
+              rawPts,
+              seriesTolerance,
+              pool.simplifiedPts,
+              pool.simplifyScratch,
+              absoluteXOffset,
+            )
+          : rawPts;
       const n = pts.length >> 1;
       if (n >= 2) {
         const b = slots[i];

package/src/hooks/useSeriesIndicatorOpacity.ts

@@ -0,0 +1,56 @@
+import {
+  Easing,
+  useAnimatedReaction,
+  useSharedValue,
+  withTiming,
+  type SharedValue,
+} from "react-native-reanimated";
+
+/** Short independent fade used when replacement data dims the plotted series. */
+export const SERIES_INDICATOR_FADE_MS = 180;
+
+/** Treat tiny animation residue at the top end as fully restored. */
+const SERIES_OPACITY_VISIBLE_EPSILON = 0.001;
+
+/** Worklet-safe target for live dots and their pulse rings. */
+export function seriesIndicatorOpacityTarget(seriesOpacity: number): 0 | 1 {
+  "worklet";
+  return seriesOpacity >= 1 - SERIES_OPACITY_VISIBLE_EPSILON ? 1 : 0;
+}
+
+/**
+ * Fades live dots and pulse rings away while `seriesOpacity` dims replacement
+ * data, then restores them once the plotted series is fully opaque again.
+ * Keeping this as a separate opacity avoids compositing a translucent dot over
+ * its own line, where the stroke would otherwise shine through.
+ */
+export function useSeriesIndicatorOpacity(
+  seriesOpacity: SharedValue<number>,
+  duration: number = SERIES_INDICATOR_FADE_MS,
+): SharedValue<number> {
+  // Fully visible is the common mount state. The reaction snaps an initially
+  // dimmed series to 0 on its first UI-thread run so it never flashes a dot.
+  const opacity = useSharedValue(1);
+
+  useAnimatedReaction(
+    () => seriesIndicatorOpacityTarget(seriesOpacity.get()),
+    (target, previous) => {
+      "worklet";
+      if (previous === null || previous === undefined || duration === 0) {
+        opacity.set(target);
+        return;
+      }
+      if (target !== previous) {
+        opacity.set(
+          withTiming(target, {
+            duration,
+            easing: Easing.inOut(Easing.ease),
+          }),
+        );
+      }
+    },
+    [seriesOpacity, duration],
+  );
+
+  return opacity;
+}

package/src/hooks/useTradeStream.ts

@@ -1,3 +1,4 @@
+import { useEffect } from "react";
 import {
   useFrameCallback,
   useSharedValue,
@@ -31,7 +32,7 @@ export function useTradeStream(
   const markers = useSharedValue<TradeMarker[]>([]);
   const state = useSharedValue<TradeStreamState>(createTradeStreamState());
 
-  useFrameCallback(
+  const tradeFrameCallback = useFrameCallback(
     /* istanbul ignore next -- worklet runs on UI thread, not in Jest */ (
       frameInfo,
     ) => {
@@ -62,6 +63,10 @@ export function useTradeStream(
     },
     autostart,
   );
+  useEffect(() => {
+    // Reanimated treats `autostart` as mount-time state; synchronize changes.
+    tradeFrameCallback.setActive(autostart);
+  }, [autostart, tradeFrameCallback]);
 
   return markers;
 }

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
   ChartSegment,
   DegenOptions,
   DegenShakePayload,
+  DotGlowConfig,
   EmptyStateMetrics,
   FontConfig,
   FontWeight,

package/src/math/markerCluster.ts

@@ -34,6 +34,12 @@ export interface ResolvedMarkerCluster {
 
 export interface ClusterMarkersOpts {
   config: ResolvedMarkerCluster;
+  /** Canvas-space y bounds (typically `0` / canvas height). When set, a
+   *  `"vertical"` column is additionally capped where the next glyph would
+   *  cross a bound, so a tall stack can't climb off the chart when its anchor
+   *  is already near the edge. The base slot always draws. */
+  minY?: number;
+  maxY?: number;
 }
 
 /** Glyph box used when `marker.size` is unset — mirrors `markerAtlas.DEFAULT_ICON_SIZE`. */
@@ -138,7 +144,15 @@ function layoutBucket(
     // `maxVisible` caps the column: the oldest glyphs keep their slots and the
     // newest overflow is simply hidden.
     const dir = side === "below" ? 1 : -1;
-    const cap = opts.config.maxVisible;
+    let cap = opts.config.maxVisible;
+    // Bounds clamp: slot j sits at `base + dir * j * step`; keep only slots
+    // whose glyph box stays inside [minY, maxY].
+    if (opts.minY !== undefined && opts.maxY !== undefined && step > 0) {
+      const base = anchorY + sideDy;
+      const room = dir === -1 ? base - h / 2 - opts.minY : opts.maxY - h / 2 - base;
+      const fit = 1 + Math.floor(room / step);
+      if (fit < cap) cap = Math.max(1, fit);
+    }
     for (let j = 0; j < count; j++) {
       const p = proj[idx[s + j]];
       if (j >= cap) {

package/src/math/simplify.ts

@@ -0,0 +1,197 @@
+/** Reusable buffers for {@link simplifyLinePoints}. */
+export interface LineSimplifyScratch {
+  keep: number[];
+  stack: number[];
+}
+
+/** Allocate simplification scratch once, outside the per-frame worklet. */
+export function makeLineSimplifyScratch(): LineSimplifyScratch {
+  return { keep: [], stack: [] };
+}
+
+/**
+ * Maximum number of points simplified as one Ramer-Douglas-Peucker range.
+ *
+ * The visible line is already bounded to roughly two points per horizontal
+ * pixel. Splitting that bounded input into overlapping ranges also bounds the
+ * simplifier's worst-case work: a pathological zig-zag cannot turn a frame into
+ * an O(n²) scan. Range endpoints are retained, so chunking can only keep a few
+ * extra points; it cannot erase additional structure.
+ */
+const MAX_RDP_RANGE_POINTS = 64;
+
+/**
+ * Width of each RDP range on the stable, absolute screen-pixel grid.
+ *
+ * Dense line input contains at most two representatives per pixel bucket. A
+ * 30 px range therefore stays within the 64-point work bound even when the
+ * decimator and simplifier grids have different phases. Fixed-width ranges
+ * also keep their membership stable as the viewport advances.
+ */
+const RDP_RANGE_WIDTH_PX = 30;
+
+function pointSegmentDistanceSq(
+  px: number,
+  py: number,
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+): number {
+  "worklet";
+  const dx = bx - ax;
+  const dy = by - ay;
+  const lengthSq = dx * dx + dy * dy;
+  if (lengthSq === 0) {
+    const ex = px - ax;
+    const ey = py - ay;
+    return ex * ex + ey * ey;
+  }
+
+  let t = ((px - ax) * dx + (py - ay) * dy) / lengthSq;
+  if (t < 0) t = 0;
+  else if (t > 1) t = 1;
+  const ex = px - (ax + t * dx);
+  const ey = py - (ay + t * dy);
+  return ex * ex + ey * ey;
+}
+
+function simplifyRdpGroup(
+  points: number[],
+  keep: number[],
+  stack: number[],
+  toleranceSq: number,
+  rangeStart: number,
+  rangeEnd: number,
+): void {
+  "worklet";
+  if (rangeStart === rangeEnd) {
+    keep[rangeStart] = 1;
+    return;
+  }
+
+  // Oversized fixed-X groups are split into overlapping subranges. The group
+  // contents are themselves stable, so this point-count guard cannot move
+  // until that absolute group reaches a viewport edge.
+  for (let chunkStart = rangeStart; chunkStart < rangeEnd; ) {
+    const chunkEnd = Math.min(
+      chunkStart + MAX_RDP_RANGE_POINTS - 1,
+      rangeEnd,
+    );
+    keep[chunkStart] = 1;
+    keep[chunkEnd] = 1;
+    stack.push(chunkStart, chunkEnd);
+
+    while (stack.length >= 2) {
+      const end = stack.pop()!;
+      const start = stack.pop()!;
+      if (end <= start + 1) continue;
+
+      const ax = points[start * 2];
+      const ay = points[start * 2 + 1];
+      const bx = points[end * 2];
+      const by = points[end * 2 + 1];
+      let furthest = -1;
+      let maxDistanceSq = toleranceSq;
+
+      for (let i = start + 1; i < end; i++) {
+        const distanceSq = pointSegmentDistanceSq(
+          points[i * 2],
+          points[i * 2 + 1],
+          ax,
+          ay,
+          bx,
+          by,
+        );
+        if (distanceSq > maxDistanceSq) {
+          maxDistanceSq = distanceSq;
+          furthest = i;
+        }
+      }
+
+      if (furthest >= 0) {
+        keep[furthest] = 1;
+        stack.push(start, furthest, furthest, end);
+      }
+    }
+
+    chunkStart = chunkEnd;
+  }
+}
+
+/**
+ * Simplify flat screen-space points (`[x0, y0, x1, y1, ...]`) with a bounded
+ * Ramer-Douglas-Peucker pass.
+ *
+ * `tolerance` is the maximum removable deviation in pixels. The first and last
+ * point, larger peaks/valleys, and the original point order are retained. Pass
+ * distinct reusable `out` and `scratch` buffers to avoid per-frame allocation.
+ * `absoluteXOffset` maps the viewport-relative X coordinates back onto a fixed
+ * screen-pixel grid; live chart callers should pass `winStart * xScale` so
+ * historical range membership does not change as the window advances.
+ */
+export function simplifyLinePoints(
+  points: number[],
+  tolerance: number,
+  out: number[],
+  scratch: LineSimplifyScratch,
+  absoluteXOffset = 0,
+): number[] {
+  "worklet";
+  if (out === points) return points;
+
+  out.length = 0;
+  const count = points.length >> 1;
+  if (!(tolerance > 0) || !Number.isFinite(tolerance) || count <= 2) {
+    for (let i = 0; i < count * 2; i++) out.push(points[i]);
+    return out;
+  }
+
+  const keep = scratch.keep;
+  keep.length = count;
+  for (let i = 0; i < count; i++) keep[i] = 0;
+
+  const stack = scratch.stack;
+  stack.length = 0;
+  const toleranceSq = tolerance * tolerance;
+  const stableXOffset = Number.isFinite(absoluteXOffset) ? absoluteXOffset : 0;
+
+  // Partition on a fixed absolute-X grid rather than by the first visible
+  // point's array index. Dropping a point from the left edge then affects only
+  // that edge range; fully visible historical ranges keep identical endpoints
+  // and RDP choices while translating across the viewport.
+  let groupStart = 0;
+  let groupKey = Math.floor(
+    (points[0] + stableXOffset) / RDP_RANGE_WIDTH_PX,
+  );
+  for (let i = 1; i < count; i++) {
+    const nextKey = Math.floor(
+      (points[i * 2] + stableXOffset) / RDP_RANGE_WIDTH_PX,
+    );
+    if (nextKey !== groupKey) {
+      simplifyRdpGroup(
+        points,
+        keep,
+        stack,
+        toleranceSq,
+        groupStart,
+        i - 1,
+      );
+      groupStart = i;
+      groupKey = nextKey;
+    }
+  }
+  simplifyRdpGroup(
+    points,
+    keep,
+    stack,
+    toleranceSq,
+    groupStart,
+    count - 1,
+  );
+
+  for (let i = 0; i < count; i++) {
+    if (keep[i] === 1) out.push(points[i * 2], points[i * 2 + 1]);
+  }
+  return out;
+}