react-native-livechart 4.18.0 → 4.19.0

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/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;
+}

package/src/types.ts

@@ -422,6 +422,15 @@ export interface LineConfig {
    * pair with `join: "miter"` + `cap: "butt"` for true sharp corners (no rounding).
    */
   curve?: "monotone" | "linear";
+  /**
+   * Screen-space path simplification tolerance in pixels. Values above `0`
+   * remove intermediate points that deviate by no more than this amount while
+   * retaining endpoints and larger peaks/valleys. This changes only the drawn
+   * line/fill; axis fitting, live values, markers, and scrubbing still use the
+   * original data. Default `0` (off). Start around `0.75`–`1.5` for sub-pixel
+   * noise reduction.
+   */
+  simplify?: number;
   /** Line color override. Defaults to palette-derived accent. */
   color?: string;
   /**
@@ -854,13 +863,36 @@ export interface ScrubConfig {
    */
   seriesTooltip?: boolean | PerSeriesTooltipConfig;
   /**
-   * Opacity of the chart content to the *right* of the crosshair (the "future")
-   * while scrubbing — `0` fully fades it out, `1` disables the dim. Implemented
-   * by erasing the content's alpha (`dstOut`), so it reveals the real background
-   * and works on any background color. Default `0.3`. Ignored when
-   * `crosshairDimColor` is set (that uses the legacy colored mask instead).
+   * Which content {@link dimOpacity} fades while scrubbing.
+   *
+   * - `"future"` fades all chart content to the right of the crosshair.
+   * - `"otherCandles"` keeps the candle under the finger at full strength and
+   *   fades every other candle body and wick. Outside candle mode it falls back
+   *   to the standard `"future"` behavior. When the finger is in a gap between
+   *   candle buckets no candle is selected. Volume bars are unchanged. The
+   *   vertical crosshair and scrub selection dot are hidden so the focused
+   *   candle is the sole position indicator.
+   *
+   * Default `"future"`.
+   */
+  dimTarget?: "future" | "otherCandles";
+  /**
+   * Opacity of the content selected by {@link dimTarget} while scrubbing — `0`
+   * fully fades it out, `1` disables the dim. Values are clamped to `[0, 1]`.
+   *
+   * With the default `dimTarget: "future"`, the fade is implemented by erasing
+   * the trailing content's alpha (`dstOut`), so it reveals the real background
+   * and works on any background color. Default `0.3`. `crosshairDimColor`
+   * overrides this opacity only for the `"future"` target.
    */
   dimOpacity?: number;
+  /**
+   * Duration in milliseconds for other candles to ease toward
+   * {@link dimOpacity} when a focused-candle scrub starts, and back to full
+   * strength on release. Used only with `dimTarget: "otherCandles"`.
+   * Set `0` for an instant change. Negative values clamp to `0`. Default `60`.
+   */
+  dimFadeMs?: number;
   /** Vertical crosshair line stroke. Omit to use theme `crosshairLine`. */
   crosshairLineColor?: string;
   /** Vertical crosshair line width in px. Default `1`. */
@@ -1522,11 +1554,23 @@ export interface DegenShakePayload {
   direction: "up" | "down";
 }
 
-/** Contrasting outer ring drawn behind each series dot — the "haloed" look the
- *  single-series live dot has, so dots stand out against the lines and one
- *  another. */
+/** Optional soft, static color glow drawn behind a live dot. */
+export interface DotGlowConfig {
+  /** Glow color. Defaults to the dot's resolved fill color. */
+  color?: string;
+  /** Radius of the glow's source circle in pixels. Default `7`. */
+  radius?: number;
+  /** Skia blur radius in pixels. Default `5`. */
+  blur?: number;
+  /** Glow opacity (0–1). Default `0.18`. */
+  opacity?: number;
+}
+
+/** Contrasting outer ring drawn behind each series dot — the crisp backing
+ *  circle the single-series live dot has, so dots stand out against the lines
+ *  and one another. */
 export interface DotRingConfig {
-  /** Ring color. Default: theme `badgeOuterBg` (a near-background halo). */
+  /** Ring color. Default: theme `badgeOuterBg` (a near-background backing). */
   color?: string;
   /** Ring thickness in pixels — how far the halo extends past the dot. Default `2.5`. */
   width?: number;
@@ -1535,7 +1579,8 @@ export interface DotRingConfig {
 /**
  * Shared live-dot styling, used by both `LiveChart` (`dot`) and
  * `LiveChartSeries` (`dot`, which extends this). A dot is a color-filled circle
- * of `radius` with an optional contrasting outer `ring` (halo).
+ * of `radius` with an optional contrasting outer `ring` and opt-in soft
+ * `glow`. The glow is static; use `pulse` for an animated heartbeat.
  */
 export interface DotConfig {
   /** Radius of the (color-filled) dot in pixels. Default `3.5`. */
@@ -1546,6 +1591,12 @@ export interface DotConfig {
    * `DotRingConfig`. Default `true`.
    */
   ring?: boolean | DotRingConfig;
+  /**
+   * Soft static glow behind the dot. `true` = restrained defaults, `false` =
+   * off, or pass `DotGlowConfig` to tune its color, radius, blur, and opacity.
+   * Default `false`.
+   */
+  glow?: boolean | DotGlowConfig;
   /**
    * Show the dot. `false` hides it (line, badge, and labels still render). Default `true`.
    *
@@ -1637,6 +1688,13 @@ export interface SeriesConfig {
    *   anchored to this series snap to the straight chord to match.
    */
   curve?: "monotone" | "linear";
+  /**
+   * Per-series screen-space path simplification tolerance in pixels. Overrides
+   * `LiveChartSeries.line.simplify`; `0` disables simplification for this series.
+   * Only rendered geometry is simplified — values, range fitting, and scrubbing
+   * continue to use the original points.
+   */
+  simplify?: number;
   /** Per-series stroke width override (px). Falls back to the chart line width. */
   strokeWidth?: number;
   /** Render a soft glow behind this series' line. Default `false`. */
@@ -1986,9 +2044,11 @@ export interface LiveChartCoreProps {
   /**
    * UI-thread opacity multiplier for the plotted data. Set a value from `0`
    * (hidden) to `1` (fully visible), such as `0.5` while replacement data loads.
-   * Applies to every plotted series — line/fill/candles, live dots, value lines,
-   * and inline values — without affecting axes, reference lines, legends, or
-   * scrub UI. Default `1`.
+   * Applies to every plotted series — line/fill/candles, value lines, and inline
+   * values — without affecting axes, reference lines, legends, or scrub UI.
+   * While the multiplier is below `1`, live dots and pulse rings fade completely
+   * out so the dimmed stroke cannot show through them; they fade back in when it
+   * returns to `1`. Default `1`.
    */
   seriesOpacity?: SharedValue<number>;
   /**
@@ -2326,7 +2386,8 @@ export interface LiveChartProps extends LiveChartCoreProps {
   pulse?: boolean | PulseConfig;
   /**
    * Live dot styling. `true`/omitted = shown defaults, `false` = hidden, or pass
-   * `DotConfig` (`radius`, `ring` halo, `color`). See {@link DotConfig}. Default `true`.
+   * `DotConfig` (`radius`, `ring`, opt-in `glow`, `color`). See
+   * {@link DotConfig}. Default `true`.
    */
   dot?: boolean | DotConfig;
   /** Horizontal dashed line at the current live value. `true` = defaults, or pass `ValueLineConfig`. */
@@ -2374,8 +2435,9 @@ export interface LiveChartProps extends LiveChartCoreProps {
   /** Render once with no per-frame animation loop — for many small charts (sparklines)
    *  in a list. The continuous animations (pulse, degen, the entry reveal) are disabled,
    *  but `scrub` / `scrubAction` stay available — they're on-demand touch gestures with
-   *  no per-frame cost, so a still chart is still scrubbable. Frame the data with
-   *  `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
+   *  no per-frame cost, so a still chart is still scrubbable. May be toggled at runtime:
+   *  switching back to live restarts the suspended loops and catches up. Frame the data
+   *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
   static?: boolean;
   /**
    * Render a custom overlay floated over the chart canvas, handed a price↔pixel /