react-native-livechart 4.25.0 → 4.26.0

package/src/hooks/useReferenceDrag.ts

@@ -18,11 +18,7 @@ import {
 } from "../math/referenceDrag";
 import { referenceLineForm } from "../math/referenceLines";
 import type { ReferenceLine } from "../types";
-import {
-  computeScrubDotY,
-  computeValueAtY,
-  snapPrice,
-} from "./crosshairShared";
+import { computeValueAtY, pinnedPlotY, snapPrice } from "./crosshairShared";
 
 /** Vertical reach (px) around a line within which a touch grabs it. */
 const GRAB_SLOP = 14;
@@ -37,12 +33,13 @@ const EMPTY: never[] = [];
  * Builds the per-line **drag** gesture for draggable Form-A reference lines: grab a
  * line near its value-Y and drag vertically to set a new value, with optional
  * `snap` + `bounds` clamp. Mirrors the order-ticket reticle in {@link useCrosshair}
- * (value↔Y via `computeValueAtY` / `computeScrubDotY`, frozen value re-projected
+ * (value↔Y via `computeValueAtY` / `pinnedPlotY`, frozen value re-projected
  * each frame) but per line, writing into the shared `dragValues` array the layout
  * and overlays read.
  *
  * The pan uses `manualActivation`: it grabs only when a touch starts within
- * {@link GRAB_SLOP} of a draggable line, then **owns** that touch — any drag past
+ * {@link GRAB_SLOP} of a draggable line (and inside its `grabRange`, when it has
+ * one), then **owns** that touch — any drag past
  * {@link DRAG_ACTIVATE_PX} (in either axis) drags the line. A touch off every line
  * fails fast so the chart's other gestures (scrub / scroll) run everywhere else
  * (compose this ahead of them via `Gesture.Exclusive`). Crucially it no longer
@@ -86,6 +83,7 @@ export function useReferenceDrag(
     const dMax = engine.displayMax.get();
     const top = padding.top;
     const bottom = ch - padding.bottom;
+    if (bottom <= top) return EMPTY;
     const out: number[] = [];
     for (let i = 0; i < lines.length; i++) {
       const l = lines[i];
@@ -98,12 +96,16 @@ export function useReferenceDrag(
         continue;
       }
       const v = dragValues.get()[i] ?? l.value;
-      const y = computeScrubDotY(v, dMin, dMax, ch, top, padding.bottom);
-      out.push(y < 0 ? -1 : Math.min(bottom, Math.max(top, y)));
+      out.push(pinnedPlotY(v, dMin, dMax, ch, top, padding.bottom));
     }
     return out;
   });
 
+  // Per-line grab x-ranges (`ReferenceLine.grabRange`), index-aligned with
+  // `lines`; null = anywhere along the line. Read by the gesture worklets below,
+  // which close over this render's `lines` as the callbacks do.
+  const grabRanges = lines.map((l) => l.grabRange ?? null);
+
   const dragIndex = useSharedValue(-1);
   const startX = useSharedValue(0);
   const startY = useSharedValue(0);
@@ -175,7 +177,10 @@ export function useReferenceDrag(
     "worklet";
     const t = e.changedTouches[0];
     if (!t) return;
-    const i = nearestDraggableIndex(handleYs.get(), t.y, GRAB_SLOP);
+    const i = nearestDraggableIndex(handleYs.get(), t.y, GRAB_SLOP, {
+      x: t.x,
+      ranges: grabRanges,
+    });
     if (i < 0) {
       manager.fail();
       return;
@@ -266,13 +271,22 @@ export function useReferenceDrag(
   // is grabbed the answer is yes regardless of position: the scrub asks with its
   // touch-DOWN point, which a longer drag has carried the line away from, so the
   // geometric test alone said "no line here" and a crosshair opened mid-drag.
-  // Otherwise it is the y-reach around the handles (x is unused — a Form-A line
-  // spans the full width).
+  // Otherwise it is the y-reach around the handles, along the whole line — or,
+  // for a line with a `grabRange`, only inside it.
   /* istanbul ignore next -- worklet, runs on the UI thread */
-  const hitTest = (_x: number, y: number): boolean => {
+  const hitTest = (x: number, y: number): boolean => {
     "worklet";
     if (!anyDraggable) return false;
-    return referenceDragOwnsTouch(dragIndex.get(), handleYs.get(), y, GRAB_SLOP);
+    return referenceDragOwnsTouch(
+      dragIndex.get(),
+      handleYs.get(),
+      y,
+      GRAB_SLOP,
+      {
+        x,
+        ranges: grabRanges,
+      },
+    );
   };
 
   const gesture = Gesture.Pan()

package/src/hooks/useReferenceLineGrouping.ts

@@ -0,0 +1,72 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { groupReferenceLines, type ReferenceGrouping } from "../math/referenceGroup";
+import { referenceLineForm } from "../math/referenceLines";
+import type { ReferenceLine } from "../types";
+import { pinnedPlotY } from "./crosshairShared";
+
+/** Stable result while grouping is disabled. */
+const EMPTY_GROUPING: ReferenceGrouping = { hidden: [], groups: [] };
+
+/** Cluster the built-in tags that can actually render in the current plot. */
+export function useReferenceLineGrouping({
+  radius,
+  engine,
+  padding,
+  lines,
+  custom,
+  offAxisCustom,
+  dragValues,
+}: {
+  radius: number | null;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  lines: ReferenceLine[];
+  custom: boolean[];
+  offAxisCustom: boolean[];
+  dragValues: SharedValue<number[]>;
+}) {
+  const hasOffAxisBadge = lines.map((line) => Boolean(line.badge || line.offAxisBadge));
+  const result = useDerivedValue<ReferenceGrouping>(() => {
+    if (radius == null) return EMPTY_GROUPING;
+    const canvasHeight = engine.canvasHeight.get();
+    const displayMin = engine.displayMin.get();
+    const displayMax = engine.displayMax.get();
+    const top = padding.top;
+    const yPositions: number[] = [];
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      if (
+        referenceLineForm(line) !== "line" ||
+        line.value === undefined ||
+        custom[index] ||
+        offAxisCustom[index]
+      ) {
+        yPositions.push(-1);
+        continue;
+      }
+      const value = dragValues.get()[index] ?? line.value;
+      // Plain off-axis lines are culled by useReferenceLine. Only a configured
+      // badge can contribute a visible tag to the edge's count pill.
+      if ((value < displayMin || value > displayMax) && !hasOffAxisBadge[index]) {
+        yPositions.push(-1);
+        continue;
+      }
+      yPositions.push(
+        pinnedPlotY(
+          value,
+          displayMin,
+          displayMax,
+          canvasHeight,
+          top,
+          padding.bottom,
+        ),
+      );
+    }
+    return groupReferenceLines(yPositions, radius);
+  });
+  const hidden = useDerivedValue<boolean[]>(() => result.get().hidden);
+  return { refGroupResult: result, groupHidden: hidden };
+}

package/src/index.ts

@@ -97,6 +97,7 @@ export type {
   MultiSeriesDotConfig,
   PerSeriesTooltipConfig,
   PulseConfig,
+  RangeAnimationConfig,
   ReferenceLine,
   ReferenceLineBadgeConfig,
   ReferenceLineGroupingConfig,

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/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 {
   /**
@@ -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