react-native-livechart 4.13.0 → 4.14.0

package/src/hooks/usePanScroll.ts

@@ -1,6 +1,8 @@
 import { Gesture } from "react-native-gesture-handler";
 import {
   cancelAnimation,
+  useAnimatedReaction,
+  useDerivedValue,
   useSharedValue,
   withDecay,
   type SharedValue,
@@ -71,26 +73,85 @@ export interface UsePanScrollOptions {
    * price indicator. Cleared when the finger lifts (the scrub pan's finalize).
    */
   scrubActive?: SharedValue<boolean>;
+  /**
+   * Fraction of the visible window (0–1) the pan may travel past the data
+   * bounds — into blank future space beyond the live edge and blank history
+   * before the oldest point (TradingView-style free dragging). `0` (default)
+   * keeps the classic hard stops at the data. Resolved from
+   * `timeScroll.overscroll` (see `resolveOverscroll`).
+   */
+  overscroll?: number;
 }
 
+/**
+ * Snap-to-follow zone around the live edge, as a fraction of the window. With
+ * overscroll a released drag/fling that settles within this zone re-attaches to
+ * live; anything further out stays parked where it stopped.
+ */
+export const FOLLOW_SNAP = 0.02;
+
 /**
  * Smallest valid right-edge time: keeps the window's left edge
  * (`rightEdge - window`) from passing `minTime`, and never exceeds the live edge
- * so the `[lo, liveEdge]` clamp range stays valid when history is short.
+ * so the `[lo, liveEdge]` clamp range stays valid when history is short. With
+ * `overscroll` the left edge may pass `minTime` by that fraction of the window,
+ * exposing blank space before the oldest data.
  */
 export function panLowerBound(
   minTime: number,
   windowSecs: number,
   liveEdge: number,
+  overscroll: number = 0,
+): number {
+  "worklet";
+  return Math.min(minTime + windowSecs * (1 - overscroll), liveEdge);
+}
+
+/**
+ * Largest valid right-edge time: the live edge, pushed past it by `overscroll`
+ * (a fraction of the window) so the latest data can be dragged toward the middle
+ * of the plot, leaving blank future space on the right. `0` = the live edge.
+ */
+export function panUpperBound(
+  windowSecs: number,
+  liveEdge: number,
+  overscroll: number,
 ): number {
   "worklet";
-  return Math.min(minTime + windowSecs, liveEdge);
+  return liveEdge + windowSecs * overscroll;
+}
+
+/**
+ * Re-clamp a parked right edge after the overscroll setting changes. Reducing
+ * the allowance must not leave a stale future/history position outside the new
+ * bounds; at the classic live-edge hard stop, `null` resumes following live.
+ */
+export function clampViewEndForOverscroll(
+  viewEnd: number,
+  minTime: number,
+  windowSecs: number,
+  liveEdge: number,
+  overscroll: number,
+): number | null {
+  "worklet";
+  const lo = panLowerBound(minTime, windowSecs, liveEdge, overscroll);
+  if (viewEnd < lo) return lo;
+  const hi = panUpperBound(windowSecs, liveEdge, overscroll);
+  if (viewEnd >= hi) return overscroll > 0 ? hi : null;
+  return viewEnd;
 }
 
 /**
  * Next right-edge time after dragging `changeX` px (drag right ⇒ reveal earlier
- * time ⇒ smaller right edge), clamped to `[lo, liveEdge]`. Returns `null` once
- * the drag reaches the live edge — the signal to resume following.
+ * time ⇒ smaller right edge), clamped to `[lo, panUpperBound]`. Without
+ * overscroll, returns `null` once the drag reaches the live edge — the signal to
+ * resume following.
+ *
+ * With overscroll it must NOT return `null` mid-drag: the pan's `onChange`
+ * re-derives `cur` from `viewEnd ?? liveEdge` each frame, so snapping to follow
+ * re-anchors every per-frame delta at the live edge and the drag can't escape it
+ * in either direction. Re-attaching to live happens only in the release decay
+ * callback (see `usePanScroll`), inside the {@link FOLLOW_SNAP} zone.
  */
 export function nextViewEnd(
   cur: number,
@@ -99,10 +160,16 @@ export function nextViewEnd(
   windowSecs: number,
   liveEdge: number,
   lo: number,
+  overscroll: number = 0,
 ): number | null {
   "worklet";
   let next = cur - (changeX / chartW) * windowSecs;
   if (next < lo) next = lo;
+  if (overscroll > 0) {
+    const hi = panUpperBound(windowSecs, liveEdge, overscroll);
+    if (next > hi) next = hi;
+    return next;
+  }
   if (next > liveEdge) next = liveEdge;
   return next >= liveEdge ? null : next;
 }
@@ -150,6 +217,7 @@ export function usePanScroll({
   onScrollStart,
   scrollActive,
   scrubActive,
+  overscroll = 0,
 }: UsePanScrollOptions): ReturnType<typeof Gesture.Pan> {
   const { viewEnd, liveEdge, displayWindow, canvasWidth, canvasHeight } = engine;
   const padLeft = padding.left;
@@ -161,6 +229,31 @@ export function usePanScroll({
   const startX = useSharedValue(0);
   const startY = useSharedValue(0);
   const armed = useSharedValue(false);
+  const overscrollSV = useDerivedValue(() => overscroll);
+
+  // A runtime config change (the demo exposes Off / 50% / 90%) applies to an
+  // already parked window immediately. Without this, disabling overscroll while
+  // parked in the future leaves a numeric `viewEnd`; re-enabling it later revives
+  // that stale future position and makes the chart jump without a gesture.
+  useAnimatedReaction(
+    () => overscrollSV.value,
+    /* istanbul ignore next -- UI-thread config reaction; pure clamp is unit-tested */
+    (nextOverscroll) => {
+      const cur = viewEnd.get();
+      if (cur == null) return;
+      const next = clampViewEndForOverscroll(
+        cur,
+        minTime.get(),
+        displayWindow.get(),
+        liveEdge.get(),
+        nextOverscroll,
+      );
+      if (next !== cur) {
+        cancelAnimation(viewEnd);
+        viewEnd.set(next);
+      }
+    },
+  );
 
   const onStart =
     /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
@@ -194,8 +287,8 @@ export function usePanScroll({
       if (chartW <= 0) return;
       const edge = liveEdge.get();
       const cur = viewEnd.get() ?? edge;
-      const lo = panLowerBound(minTime.get(), win, edge);
-      viewEnd.set(nextViewEnd(cur, e.changeX, chartW, win, edge, lo));
+      const lo = panLowerBound(minTime.get(), win, edge, overscroll);
+      viewEnd.set(nextViewEnd(cur, e.changeX, chartW, win, edge, lo, overscroll));
     };
 
   const onEnd =
@@ -208,15 +301,20 @@ export function usePanScroll({
       const chartW = canvasWidth.get() - padLeft - padRight;
       if (chartW <= 0) return;
       const edge = liveEdge.get();
-      const lo = panLowerBound(minTime.get(), win, edge);
+      const lo = panLowerBound(minTime.get(), win, edge, overscroll);
+      const hi = overscroll > 0 ? panUpperBound(win, edge, overscroll) : edge;
+      // With overscroll the snap-to-follow zone widens from the exact live edge
+      // to FOLLOW_SNAP of the window around it — this release callback is the
+      // ONLY place that re-attaches to live (never mid-drag, see nextViewEnd).
+      const snapZone = overscroll > 0 ? win * FOLLOW_SNAP : 1e-3;
       const velocity = flingVelocity(e.velocityX, chartW, win);
       cancelAnimation(viewEnd);
       viewEnd.set(
-        withDecay({ velocity, clamp: [lo, edge] }, (finished) => {
+        withDecay({ velocity, clamp: [lo, hi] }, (finished) => {
           "worklet";
-          // Landed on the live-edge clamp → resume following; stopped short →
-          // stay frozen where inertia died.
-          if (finished && (viewEnd.get() ?? edge) >= edge - 1e-3) {
+          // Landed near the live edge → resume following; stopped short (or
+          // past, with overscroll) → stay frozen where inertia died.
+          if (finished && Math.abs((viewEnd.get() ?? edge) - edge) <= snapZone) {
             viewEnd.set(null);
           }
         }),

package/src/hooks/usePinchZoom.ts

@@ -6,7 +6,7 @@ import {
 } from "react-native-reanimated";
 
 import type { ChartPadding } from "../draw/line";
-import { panLowerBound } from "./usePanScroll";
+import { FOLLOW_SNAP, panLowerBound, panUpperBound } from "./usePanScroll";
 
 /** Engine SharedValues the pinch-zoom gesture reads/writes. */
 export interface PinchZoomEngineRefs {
@@ -44,6 +44,13 @@ export interface UsePinchZoomOptions {
   maxTimeWindow?: number;
   /** Worklet fired when a pinch activates — e.g. to clear a lingering crosshair. */
   onZoomStart?: () => void;
+  /**
+   * Fraction of the visible window (0–1) the zoomed window may travel past the
+   * data bounds — blank future space beyond the live edge, blank history before
+   * the oldest point. `0` (default) keeps the classic hard stops. Shared with
+   * {@link usePanScroll} (resolved from `timeScroll.overscroll`).
+   */
+  overscroll?: number;
 }
 
 /** Clamp a window width to `[minWin, maxWin]`. */
@@ -131,6 +138,7 @@ export function usePinchZoom({
   minTimeWindow,
   maxTimeWindow,
   onZoomStart,
+  overscroll = 0,
 }: UsePinchZoomOptions): ReturnType<typeof Gesture.Pinch> {
   const { viewWindow, viewEnd, liveEdge, displayWindow, canvasWidth } = engine;
   const padLeft = padding.left;
@@ -175,14 +183,27 @@ export function usePinchZoom({
       // doesn't compound; the right edge then keeps it under the (live) focal.
       const focalT = focalTime(e.focalX, padLeft, chartW, sEnd - sWin, sWin);
       let newEnd = zoomViewEnd(focalT, e.focalX, padLeft, chartW, newWin);
-      const lo = panLowerBound(minTime.get(), newWin, edge);
+      const lo = panLowerBound(minTime.get(), newWin, edge, overscroll);
       if (newEnd < lo) newEnd = lo;
-      if (newEnd > edge) newEnd = edge;
+      const hi = overscroll > 0 ? panUpperBound(newWin, edge, overscroll) : edge;
+      if (newEnd > hi) newEnd = hi;
       viewWindow.set(newWin);
       // Track the displayed window 1:1 (bypass the frame-loop lerp lag) so the
       // focal anchor is pixel-accurate during the gesture.
       displayWindow.set(newWin);
-      viewEnd.set(newEnd >= edge ? null : newEnd);
+      // Unlike the pan (see nextViewEnd), snapping to `null` mid-gesture is safe
+      // here: the pinch maps cumulative scale/focal from a gesture-START snapshot
+      // (`startViewEnd`), not per-frame deltas, so a snap can't re-anchor it.
+      // With overscroll, snap within the FOLLOW_SNAP zone; without, at the edge.
+      viewEnd.set(
+        overscroll > 0
+          ? Math.abs(newEnd - edge) <= newWin * FOLLOW_SNAP
+            ? null
+            : newEnd
+          : newEnd >= edge
+            ? null
+            : newEnd,
+      );
     };
 
   return Gesture.Pinch().enabled(enabled).onStart(onStart).onChange(onChange);

package/src/hooks/useSegmentLineGradient.ts

@@ -4,7 +4,11 @@ import { vec } from "@shopify/react-native-skia";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ResolvedSegment } from "../core/resolveSegment";
 import type { ChartPadding } from "../draw/line";
-import { segmentLineGradient } from "../math/segments";
+import {
+  padGradientStops,
+  segmentGradientStopCount,
+  segmentLineGradient,
+} from "../math/segments";
 
 const FALLBACK_POSITIONS = [0, 1];
 
@@ -43,11 +47,15 @@ export function useSegmentLineGradient(
     );
   });
 
-  const colors = useDerivedValue(
-    () => data.value?.colors ?? [baseColor, baseColor],
+  // Fixed stop count: `colors`/`positions` tear independently and Skia treats a
+  // length mismatch as a fatal UI-thread throw.
+  const stopCount = segmentGradientStopCount(segments);
+
+  const colors = useDerivedValue(() =>
+    padGradientStops(data.value?.colors ?? [baseColor, baseColor], stopCount),
   );
-  const positions = useDerivedValue(
-    () => data.value?.positions ?? FALLBACK_POSITIONS,
+  const positions = useDerivedValue(() =>
+    padGradientStops(data.value?.positions ?? FALLBACK_POSITIONS, stopCount),
   );
   const gradientEnd = useDerivedValue(() =>
     vec(Math.max(1, engine.canvasWidth.value), 0),

package/src/math/segments.ts

@@ -171,3 +171,29 @@ export function segmentLineGradient(
 
   return { colors, positions };
 }
+
+/** Stops {@link segmentLineGradient} can emit for `segments` — no per-frame state. */
+export function segmentGradientStopCount(segments: ResolvedSegment[]): number {
+  "worklet";
+  let n = 2;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (!seg.recolorLine) continue;
+    const cols =
+      seg.mutedColors && seg.mutedColors.length >= 2
+        ? seg.mutedColors.length
+        : 2;
+    n += cols + 2;
+  }
+  return n;
+}
+
+/** Resize `stops` to `count` by repeating its last entry. */
+export function padGradientStops<T>(stops: T[], count: number): T[] {
+  "worklet";
+  if (stops.length === count || stops.length === 0) return stops;
+  const out = stops.slice(0, count);
+  const last = stops[stops.length - 1];
+  while (out.length < count) out.push(last);
+  return out;
+}

package/src/types.ts

@@ -1700,6 +1700,8 @@ export interface CandleMetrics {
   maxBodyPx: number;
   /** Body width as a fraction of the per-candle slot width (0–1). Default `0.8`. */
   bodyWidthRatio: number;
+  /** Minimum horizontal gap (px) enforced between adjacent candle bodies. `0` lets `bodyWidthRatio` alone control body width on dense charts. Default `2`. */
+  minGapPx: number;
   /** Corner radius (px) of candle bodies. `0` = sharp corners. Default `0`. */
   bodyRadius: number;
   /** Wick (high–low line) stroke width in px. Default `1`. */
@@ -1778,6 +1780,17 @@ export interface TimeScrollConfig {
    * visible edge price, which IS in view.
    */
   hideLiveOnScrollBack?: boolean;
+  /**
+   * How far pan / fling / pinch may travel past the data bounds, as a fraction
+   * of the visible window (`0`–`1`). With overscroll you can drag the latest
+   * candle toward the middle of the plot (blank future space on the right) or
+   * pan left past the oldest point into blank history — TradingView-style free
+   * dragging. A released drag that settles within a small zone of the live edge
+   * re-attaches to live. Default `0`: the window hard-stops at the oldest data
+   * and the live edge (the classic behavior). Values outside `[0, 1)` are
+   * clamped. Applies to the pinch-zoom (`zoom`) clamps too.
+   */
+  overscroll?: number;
 }
 
 /**