react-native-livechart 4.24.1 → 4.26.0

package/src/math/rangeAnimation.ts

@@ -0,0 +1,28 @@
+import type { RangeAnimationConfig } from "../types";
+
+// Worklet closures capture local functions when the caller is initialized.
+function resolveSpeed(smoothing: number, speed: number | undefined): number {
+  "worklet";
+  return speed === undefined || !Number.isFinite(speed)
+    ? smoothing
+    : Math.max(0, Math.min(1, speed));
+}
+
+/** Select per-bound easing while preserving immediate expansion and reduced motion. */
+export function rangeAnimationSpeed(
+  smoothing: number,
+  config: RangeAnimationConfig | undefined,
+  expanding: boolean,
+  disjoint = false,
+): number {
+  "worklet";
+  if (smoothing >= 1 || (expanding && !config?.animateExpansion)) return 1;
+  const speed = resolveSpeed(
+    smoothing,
+    expanding ? config?.expansionSmoothing : config?.contractionSmoothing,
+  );
+  // Until the ranges overlap, contraction must not outrun the expanding bound.
+  return !expanding && disjoint && config?.animateExpansion
+    ? Math.min(speed, resolveSpeed(smoothing, config.expansionSmoothing))
+    : speed;
+}

package/src/math/referenceDrag.ts

@@ -17,16 +17,29 @@ export function clampToBounds(
   return Math.min(hi, Math.max(lo, value));
 }
 
+/**
+ * Where a touch may grab each line: the touch `x` and, index-aligned with the
+ * chart's `referenceLines`, each line's `grabRange` (`[from, to]`, canvas px) —
+ * `null` / `undefined` for a line grabbed anywhere along it.
+ */
+export interface GrabRangeProbe {
+  x: number;
+  ranges: readonly (readonly [number, number] | null | undefined)[];
+}
+
 /**
  * Index of the draggable line whose handle-Y is nearest the touch `y`, within
  * `slop` px — or `-1` when none is in reach. `handleYs` is index-aligned with the
- * chart's `referenceLines`; entries `< 0` (not draggable / off-screen / not laid
- * out) are skipped. Ties favor the later (topmost-drawn) line.
+ * chart's `referenceLines`; entries `< 0` (not draggable / not laid out) are
+ * skipped; off-screen lines pin to the nearest plot edge. Ties favor the later
+ * (topmost-drawn) line. With `grab`, a line
+ * whose `grabRange` does not contain the touch `x` is skipped too.
  */
 export function nearestDraggableIndex(
   handleYs: number[],
   y: number,
   slop: number,
+  grab?: GrabRangeProbe,
 ): number {
   "worklet";
   let best = -1;
@@ -34,6 +47,8 @@ export function nearestDraggableIndex(
   for (let i = 0; i < handleYs.length; i++) {
     const hy = handleYs[i];
     if (hy < 0) continue;
+    const range = grab?.ranges[i];
+    if (range && (grab.x < range[0] || grab.x > range[1])) continue;
     const d = Math.abs(hy - y);
     if (d <= bestDist) {
       bestDist = d;
@@ -49,17 +64,19 @@ export function nearestDraggableIndex(
  * or already dragging) owns the touch outright, wherever the asking gesture says
  * the finger is: the scrub pan can activate mid-drag and asks with its
  * touch-DOWN point, which a longer drag has carried the line away from. With no
- * line grabbed, it is the geometric reach test around the handles.
+ * line grabbed, it is the geometric reach test around the handles (and, with
+ * `grab`, inside each line's `grabRange`).
  */
 export function referenceDragOwnsTouch(
   dragIndex: number,
   handleYs: number[],
   y: number,
   slop: number,
+  grab?: GrabRangeProbe,
 ): boolean {
   "worklet";
   if (dragIndex >= 0) return true;
-  return nearestDraggableIndex(handleYs, y, slop) >= 0;
+  return nearestDraggableIndex(handleYs, y, slop, grab) >= 0;
 }
 
 /**

package/src/math/referenceGroup.ts

@@ -26,8 +26,8 @@ export interface ReferenceGrouping {
 
 /**
  * Single-linkage cluster of reference-line handle Ys: lines whose sorted Y gaps are
- * all `<= radius` chain into one group. Entries `< 0` (not a Form-A line / off the
- * canvas) are ignored. Returns which lines are collapsed (`hidden`) plus a centroid
+ * all `<= radius` chain into one group. Entries `< 0` (not a Form-A line / not laid
+ * out) are ignored. Returns which lines are collapsed (`hidden`) plus a centroid
  * + count per multi-line cluster. A non-positive `radius` disables grouping.
  */
 export function groupReferenceLines(

package/src/math/spline.ts

@@ -60,6 +60,9 @@ export function drawSpline(
   startPoint = 0,
   /** Last point index to draw (exclusive). Defaults to the full array. */
   endPoint = pts.length >> 1,
+  /** Optional paired sinks receive identical verbs from the same curve math. */
+  second?: SplinePathSink,
+  third?: SplinePathSink,
 ) {
   "worklet";
   const start = Math.max(0, startPoint);
@@ -70,12 +73,16 @@ export function drawSpline(
     for (let i = 1; i < n; i++) {
       const point = (start + i) * 2;
       path.lineTo(pts[point], pts[point + 1]);
+      second?.lineTo(pts[point], pts[point + 1]);
+      third?.lineTo(pts[point], pts[point + 1]);
     }
     return;
   }
   if (n === 2) {
     const point = (start + 1) * 2;
     path.lineTo(pts[point], pts[point + 1]);
+    second?.lineTo(pts[point], pts[point + 1]);
+    third?.lineTo(pts[point], pts[point + 1]);
     return;
   }
 
@@ -123,14 +130,15 @@ export function drawSpline(
     const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     const hi = h[i];
-    path.cubicTo(
-      pts[i2] + hi / 3,
-      pts[i2 + 1] + (m[i] * hi) / 3,
-      pts[j2] - hi / 3,
-      pts[j2 + 1] - (m[i + 1] * hi) / 3,
-      pts[j2],
-      pts[j2 + 1],
-    );
+    const x1 = pts[i2] + hi / 3;
+    const y1 = pts[i2 + 1] + (m[i] * hi) / 3;
+    const x2 = pts[j2] - hi / 3;
+    const y2 = pts[j2 + 1] - (m[i + 1] * hi) / 3;
+    const x = pts[j2],
+      y = pts[j2 + 1];
+    path.cubicTo(x1, y1, x2, y2, x, y);
+    second?.cubicTo(x1, y1, x2, y2, x, y);
+    third?.cubicTo(x1, y1, x2, y2, x, y);
   }
 }
 

package/src/math/squiggly.ts

@@ -27,6 +27,18 @@ export function squigglyYAt(
   );
 }
 
+/**
+ * The squiggle's clock, in seconds: wall time. The loading shell
+ * (`LoadingOverlay`) and the reveal's morph (`useChartPaths`) both phase their
+ * wave on it rather than on `engine.timestamp`, which a `nowOverride` freezes
+ * between data updates (freezing the loading line with it). Sharing one clock
+ * keeps the wave continuous where the shell hands over to the morph.
+ */
+export function squiggleClockSeconds(): number {
+  "worklet";
+  return Date.now() / 1000;
+}
+
 /**
  * Build a flat [x0,y0,x1,y1,...] point array for a standalone squiggly line
  * spanning the full chart area (used in loading / empty state).

package/src/types.ts

@@ -191,6 +191,18 @@ export interface ReferenceLine {
    * it controlled. No effect on bands / time bands. Default `false`.
    */
   draggable?: boolean;
+  /**
+   * Where along a draggable line a press may grab it: a canvas x-range in px,
+   * `[from, to]`, ends included — typically the span of a custom tag drawn with
+   * `renderReferenceLine` (measure it with `onLayout`; a left-pinned tag starts 2 px
+   * inside the plot's left edge). Omit to grab the line anywhere along it (the
+   * default). With a range, a pan, scrub or page scroll that merely starts near the
+   * line no longer moves it; a press inside the range grabs it as before (same Y
+   * reach). `from > to` makes the line ungrabbable. A JS value: leave a little
+   * slack for a tag that changes width (off-axis, a live price). Applies only to
+   * draggable Form-A lines.
+   */
+  grabRange?: [number, number];
   /**
    * Snap the dragged value to this increment (e.g. `0.01` for cents, `0.5` for a
    * tick size) so drops land on round levels. Omit for free dragging. Applies only
@@ -334,7 +346,9 @@ export interface ReferenceLineRenderProps {
  * lines whose handles fall within {@link ReferenceLineGroupingConfig.radius} px of
  * each other collapse into a single count handle, so a cluster of nearby orders /
  * alerts reads as one tag instead of an unreadable pile. Pass `true` for defaults
- * or an object to tune the proximity radius.
+ * or an object to tune the proximity radius. Badged off-axis lines group at either
+ * plot edge; off-axis lines with no badge are hidden and do not count. Custom tags
+ * are excluded.
  */
 export interface ReferenceLineGroupingConfig {
   /**
@@ -757,8 +771,8 @@ export interface YAxisConfig {
    * numbers; they track the live range each frame.
    *
    * `minGap` still acts as a floor: if `count` labels won't fit at least
-   * `minGap` px apart, the count is reduced to what fits. Clamped to at most 15
-   * (the label pool size). Omit (or `0`) for the default dynamic grid.
+   * `minGap` px apart, the count is reduced to what fits. Clamped to at most 15.
+   * Omit (or `0`) for the default dynamic grid.
    */
   count?: number;
   /**
@@ -2258,6 +2272,25 @@ export interface LoadingConfig {
   axisLabels?: boolean;
 }
 
+/** Y-range easing shared by both charts, independent of value/window tracking. */
+export interface RangeAnimationConfig {
+  /** Ease outward bounds instead of snapping. Default `false`. */
+  animateExpansion?: boolean;
+  /**
+   * Fraction of the remaining gap closed per 60fps frame when a bound expands.
+   * Inherits `smoothing`; only used with `animateExpansion: true`. Finite values
+   * are clamped to 0..1; non-finite values inherit `smoothing`.
+   */
+  expansionSmoothing?: number;
+  /**
+   * Fraction of the remaining gap closed per 60fps frame when a bound contracts.
+   * Inherits `smoothing`. Finite values are clamped to 0..1; non-finite values
+   * inherit `smoothing`. While animated expansion moves toward a disjoint fit,
+   * contraction is limited to the expansion speed so bounds cannot cross.
+   */
+  contractionSmoothing?: number;
+}
+
 /** Props shared between `LiveChart` and `LiveChartSeries`. */
 export interface LiveChartCoreProps {
   /** Color scheme. Default `"dark"`. */
@@ -2324,6 +2357,14 @@ export interface LiveChartCoreProps {
    * `lerpSpeed`. Default `0.08`.
    */
   smoothing?: number;
+  /**
+   * Control Y-range expansion and contraction independently of `smoothing` for
+   * value/window tracking. Omission preserves instant expansion and eased
+   * contraction. Uses frame-rate-independent exponential easing, not a fixed
+   * duration. `smoothing: 1`, explicit `snapKey` changes, static charts, and active
+   * manual Y-scale dragging remain immediate. Axis-label fades use `metrics.grid`.
+   */
+  rangeAnimation?: RangeAnimationConfig;
   /**
    * Snap the framing to its target in a single frame whenever this key changes —
    * without giving up smooth live ticks. On a timeframe / dataset switch, the
@@ -2704,6 +2745,15 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * @experimental
    */
   isFrameLoopActive?: SharedValue<boolean>;
+  /**
+   * Experimental single-series demand scheduling. Stop engine frames after a
+   * paused, parked, or fixed-time chart settles; shared input changes and
+   * gestures wake it on the UI thread. Default false. Live scrolling, pulse,
+   * loading/reveal, and enabled degen/trade effects keep the engine awake.
+   * Does not cache a bitmap or disable gestures. `static` takes precedence.
+   * @experimental
+   */
+  autoSleep?: boolean;
   /**
    * Optional development counter for engine frames that did or did not change
    * tracked engine values. It is not a count of Skia redraws. Supplying it adds