react-native-livechart 4.13.1 → 4.15.0

package/src/draw/candle.ts

@@ -144,7 +144,11 @@ export function buildCandleGeometry(
   const slotPx = (candleWidthSecs / windowSecs) * chartW;
   const bodyW = Math.max(
     1,
-    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+    Math.min(
+      slotPx * metrics.bodyWidthRatio,
+      slotPx - metrics.minGapPx,
+      metrics.maxBodyPx,
+    ),
   );
 
   const bodies: CandleRect[] = [];

package/src/draw/line.ts

@@ -229,6 +229,7 @@ export function buildLinePoints(
   canvasHeight: number,
   padding: ChartPadding,
   out?: number[],
+  omitTipBeyondData = false,
 ): number[] {
   "worklet";
   const pts: number[] = out ?? [];
@@ -328,6 +329,18 @@ export function buildLinePoints(
     }
   }
 
+  // A scrolled-back / overscrolled window can end after the last data point;
+  // the synthetic tip would then fabricate a flat segment from that point to
+  // the right edge. Callers pass `omitTipBeyondData` to end the line at the
+  // last real point instead.
+  if (
+    omitTipBeyondData &&
+    endIdx === data.length &&
+    data[endIdx - 1].time < now
+  ) {
+    return pts;
+  }
+
   // Live tip at current time with smoothed value
   pts.push(
     padding.left + chartW,

package/src/draw/volume.ts

@@ -113,7 +113,11 @@ export function buildVolumeGeometry(
   const slotPx = (candleWidthSecs / windowSecs) * chartW;
   const bodyW = Math.max(
     1,
-    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+    Math.min(
+      slotPx * metrics.bodyWidthRatio,
+      slotPx - metrics.minGapPx,
+      metrics.maxBodyPx,
+    ),
   );
 
   const winEnd = winStart + windowSecs;

package/src/hooks/useChartPaths.ts

@@ -105,6 +105,10 @@ export function useChartPaths(
       engine.canvasHeight.get(),
       padding,
       buf,
+      // Only a live-following chart may extend the line to the right edge; a
+      // parked (scrolled-back / overscrolled) window ends at its last real
+      // point rather than fabricating a flat line into dataless space.
+      engine.viewEnd.get() != null,
     );
 
     // Skip blending when fully revealed or no morphT provided

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/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;
 }
 
 /**
@@ -1993,6 +2006,17 @@ export interface LiveChartCoreProps {
    * axes (prices, market caps).
    */
   maxValue?: number;
+  /**
+   * Live manual Y-range multiplier around the fitted midpoint (`1` = auto-fit).
+   * Drive it from a gesture (e.g. dragging the price axis) to stretch or
+   * compress the price scale TradingView-style; the auto-fit keeps tracking
+   * the visible window underneath. Values must be positive and finite; invalid
+   * values fall back to `1`. Read on the UI thread each frame. Supported by
+   * both `LiveChart` and `LiveChartSeries`. Default `1`.
+   *
+   * @experimental
+   */
+  yRangeScale?: SharedValue<number>;
   /**
    * Label in the empty state when `loading` is false and there are fewer than
    * two samples (line points or committed candles). Default `"No data"`.