react-native-livechart 4.12.0 → 4.13.0

package/src/hooks/useCrosshair.ts

@@ -20,6 +20,7 @@ import type {
   ScrubPoint,
 } from "../types";
 import {
+  clampPlotX,
   computeActionBadgeLayout,
   computeCandleTooltipLayout,
   computeCrosshairOpacity,
@@ -32,10 +33,13 @@ import {
   HIDDEN_TIME_BADGE,
   HIDDEN_TOOLTIP,
   pointInRect,
+  resolveScrubHitSlop,
   SCRUB_ACTIVATE_X_PX,
   SCRUB_FAIL_Y_PX,
   snapPrice,
+  startPlainScrub,
   type CrosshairState,
+  updatePlainScrub,
 } from "./crosshairShared";
 import {
   delayedPanTouchCancelled,
@@ -64,18 +68,6 @@ const SCRUB_ACTION_TAP_SLOP = 10;
  */
 const SCRUB_ACTION_PRESS_HOLD_MS = 200;
 
-/** Clamp an X pixel to the plot's horizontal bounds. */
-/* istanbul ignore next -- worklet, called only from UI-thread gesture handlers */
-function clampPlotX(
-  x: number,
-  padLeft: number,
-  canvasWidth: number,
-  padRight: number,
-): number {
-  "worklet";
-  return Math.min(canvasWidth - padRight, Math.max(padLeft, x));
-}
-
 /** Clamp a Y pixel to the plot's vertical bounds. */
 /* istanbul ignore next -- worklet, called only from UI-thread gesture handlers */
 function clampPlotY(
@@ -159,6 +151,12 @@ export function useCrosshair(
    * mature into a scrub (see `delayedPanGuard.shouldStartDelayedPan`).
    */
   scrollActive?: SharedValue<boolean>,
+  /**
+   * Reject plain-scrub starts beyond either horizontal plot edge and clamp
+   * active drags to those bounds. Scrub-action behavior is unchanged.
+   * Default `false`.
+   */
+  clampToPlot = false,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -195,6 +193,7 @@ export function useCrosshair(
   // tracks the price as the axis rescales instead of drifting under a fixed pixel.
   const lockPriceValue = useSharedValue<number | null>(null);
   const hasScrubAction = scrubAction != null;
+  const clampPlainScrubToPlot = clampToPlot && !hasScrubAction;
   const hasOnScrubAction = onScrubAction != null;
   const dismissOnTapOutside = scrubAction?.dismissOnTapOutside ?? false;
   const dismissOnAction = scrubAction?.dismissOnAction ?? false;
@@ -618,9 +617,15 @@ export function useCrosshair(
         // also keeps a follow-on drag from showing a crosshair — no `onUpdate`
         // guard needed. (Plain-scrub counterpart of the scrub-action tap defer.)
         if (deferTapHit !== undefined && deferTapHit(e.x, e.y)) return;
-        scrubX.set(e.x);
-        scrubActive.set(true);
-        gestureStarted.set(true);
+        startPlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampPlainScrubToPlot,
+          scrubX,
+          scrubActive,
+          gestureStarted,
+        );
         if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
@@ -647,7 +652,14 @@ export function useCrosshair(
           }
           return;
         }
-        scrubX.set(e.x);
+        updatePlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampPlainScrubToPlot,
+          scrubX,
+          scrubActive,
+        );
       },
     )
     .onFinalize(
@@ -686,13 +698,15 @@ export function useCrosshair(
       .failOffsetY([-SCRUB_FAIL_Y_PX, SCRUB_FAIL_Y_PX]);
   }
 
-  // Axis-drag time-scroll: carve the bottom "time ruler" band out of the scrub's
-  // hit area so a drag starting there scrolls (the pan-scroll gesture owns it)
-  // and never trips the crosshair. `shouldCancelWhenOutside(false)` above keeps a
-  // scrub that *started* in the plot tracking on into the band.
-  if (scrubBottomExclude > 0) {
-    gesture = gesture.hitSlop({ bottom: -scrubBottomExclude });
-  }
+  // Restrict recognition by touch-down position. This rejects before ACTIVE,
+  // leaving outside starts to competing/parent gestures. Once accepted,
+  // `shouldCancelWhenOutside(false)` keeps tracking beyond these bounds.
+  const scrubHitSlop = resolveScrubHitSlop(
+    padding,
+    clampPlainScrubToPlot,
+    scrubBottomExclude,
+  );
+  if (scrubHitSlop) gesture = gesture.hitSlop(scrubHitSlop);
 
   // Tap: place/move the reticle, press the action badge, or dismiss the lock.
   // Composed ahead of the pan by the controller, so a tap is never swallowed.
@@ -767,11 +781,15 @@ export function useCrosshair(
         .maxDistance(SCRUB_ACTION_TAP_SLOP)
         .onEnd(handleActionTap)
     : undefined;
-  // Keep the axis-drag band scroll-only for taps too — a tap there shouldn't
-  // drop an order-ticket reticle.
-  if (tapGesture && scrubBottomExclude > 0) {
-    tapGesture = tapGesture.hitSlop({ bottom: -scrubBottomExclude });
-  }
+  // Keep the bottom axis scroll-only. Do not apply horizontal plot bounds here:
+  // the action badge is intentionally tappable in the right gutter.
+  const tapHitSlop = resolveScrubHitSlop(
+    padding,
+    false,
+    scrubBottomExclude,
+  );
+  if (tapGesture && tapHitSlop)
+    tapGesture = tapGesture.hitSlop(tapHitSlop);
 
   return {
     scrubX,

package/src/hooks/useCrosshairSeries.ts

@@ -22,9 +22,12 @@ import {
   computeScrubDotY,
   computeScrubTime,
   HIDDEN_TOOLTIP,
+  resolveScrubHitSlop,
   SCRUB_ACTIVATE_X_PX,
   SCRUB_FAIL_Y_PX,
+  startPlainScrub,
   type CrosshairState,
+  updatePlainScrub,
 } from "./crosshairShared";
 import {
   delayedPanTouchCancelled,
@@ -65,6 +68,11 @@ export function useCrosshairSeries(
    */
   scrollActive?: SharedValue<boolean>,
   tooltip?: CrosshairSeriesTooltipOptions,
+  /**
+   * Reject scrub starts beyond either horizontal plot edge and clamp active
+   * drags to those bounds. Default `false`.
+   */
+  clampToPlot = false,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -290,9 +298,15 @@ export function useCrosshairSeries(
         )
           return;
         if (!enabled) return;
-        scrubX.set(e.x);
-        scrubActive.set(true);
-        gestureStarted.set(true);
+        startPlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampToPlot,
+          scrubX,
+          scrubActive,
+          gestureStarted,
+        );
         if (hasOnGestureStart) scheduleOnRN(handleGestureStart);
       },
     )
@@ -300,7 +314,14 @@ export function useCrosshairSeries(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;
-        scrubX.set(e.x);
+        updatePlainScrub(
+          e.x,
+          padding,
+          engine.canvasWidth.get(),
+          clampToPlot,
+          scrubX,
+          scrubActive,
+        );
       },
     )
     .onFinalize(
@@ -326,6 +347,12 @@ export function useCrosshairSeries(
     .activeOffsetX([-SCRUB_ACTIVATE_X_PX, SCRUB_ACTIVATE_X_PX])
     .failOffsetY([-SCRUB_FAIL_Y_PX, SCRUB_FAIL_Y_PX]);
 
+  // Gate by touch-down position so outside starts fail before activation and
+  // remain available to competing/parent gestures. Accepted pans keep tracking
+  // outside because `shouldCancelWhenOutside(false)` is set above.
+  const scrubHitSlop = resolveScrubHitSlop(padding, clampToPlot);
+  if (scrubHitSlop) gesture = gesture.hitSlop(scrubHitSlop);
+
   return {
     scrubX,
     scrubActive,

package/src/hooks/useCrosshairVisibleOpacity.ts

@@ -0,0 +1,57 @@
+import {
+  useDerivedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import { computeCrosshairOpacity } from "./crosshairShared";
+
+/**
+ * Opacity for the visible crosshair UI. The trailing-content dim keeps using
+ * the edge-faded opacity directly, independent of this setting.
+ */
+export function useCrosshairVisibleOpacity(
+  scrubX: SharedValue<number>,
+  canvasWidth: SharedValue<number>,
+  paddingRight: number,
+  active: SharedValue<number> | SharedValue<boolean>,
+  fade: boolean,
+  fadeDistance = 4,
+) {
+  return useDerivedValue(
+    () =>
+      resolveCrosshairVisibleOpacity(
+        Boolean(active.get()),
+        scrubX.get(),
+        canvasWidth.get(),
+        paddingRight,
+        fade,
+        fadeDistance,
+      ),
+    [
+      scrubX,
+      canvasWidth,
+      paddingRight,
+      active,
+      fade,
+      fadeDistance,
+    ],
+  );
+}
+
+export function resolveCrosshairVisibleOpacity(
+  active: boolean,
+  scrubX: number,
+  canvasWidth: number,
+  paddingRight: number,
+  fade: boolean,
+  fadeDistance = 4,
+): number {
+  "worklet";
+  if (!fade) return active ? 1 : 0;
+  return computeCrosshairOpacity(
+    active,
+    scrubX,
+    canvasWidth,
+    paddingRight,
+    fadeDistance,
+  );
+}

package/src/hooks/useReferenceLine.ts

@@ -2,6 +2,10 @@ import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { SkFont } from "@shopify/react-native-skia";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import {
+  rightAnchoredYAxisColumnLayout,
+  type YAxisEntry,
+} from "../draw/grid";
 import type { ChartPadding } from "../draw/line";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import {
@@ -293,6 +297,14 @@ export function useReferenceLine(
    */
   dragValues?: SharedValue<number[]>,
   index = 0,
+  /** Y-axis labels used to match the right-anchored grid endpoint. */
+  yAxisEntries?: SharedValue<YAxisEntry[]>,
+  /** Enables clipping when set; matches {@link YAxisConfig.labelRightMargin}. */
+  labelRightMargin?: number,
+  /** Gap before the label column; matches {@link YAxisConfig.gridEndGap}. */
+  gridEndGap = 0,
+  /** Font used by the Y-axis labels; badge font overrides must not move the line. */
+  yAxisFont: SkFont = font,
 ): SharedValue<ReferenceLineLayout> {
   const form = line ? referenceLineForm(line) : "none";
   // Badge presentation depends only on the (stable) line props — resolve once.
@@ -314,7 +326,20 @@ export function useReferenceLine(
     // the badge/label anchor (x1/x2) stays at the plot edges either way.
     const fullWidth = line.fullWidth ?? false;
     const lineX1 = fullWidth ? 0 : x1;
-    const lineX2 = fullWidth ? w : x2;
+    const yAxisColumn =
+      form === "line" &&
+      !fullWidth &&
+      yAxisEntries !== undefined &&
+      labelRightMargin !== undefined
+        ? rightAnchoredYAxisColumnLayout(
+            w,
+            yAxisEntries.value,
+            yAxisFont,
+            labelRightMargin,
+            gridEndGap,
+          )
+        : null;
+    const lineX2 = fullWidth ? w : (yAxisColumn?.gridEndX ?? x2);
 
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;

package/src/types.ts

@@ -647,6 +647,18 @@ export interface YAxisConfig {
    * (the label pool size). Omit (or `0`) for the default dynamic grid.
    */
   count?: number;
+  /**
+   * Place price labels in a shared left-aligned column whose right edge sits
+   * this many pixels from the canvas edge. When omitted, labels keep the
+   * default centered-gutter placement.
+   */
+  labelRightMargin?: number;
+  /**
+   * Gap (px) between the shared price-label column and the end of each grid or
+   * plain reference line. Only applies when {@link labelRightMargin} is set.
+   * Default `0`.
+   */
+  gridEndGap?: number;
   /**
    * Float the price axis over a full-width plot instead of reserving a right
    * gutter for it. The line/candles run all the way to the right edge, and the
@@ -831,6 +843,33 @@ export interface ScrubConfig {
   dimOpacity?: number;
   /** Vertical crosshair line stroke. Omit to use theme `crosshairLine`. */
   crosshairLineColor?: string;
+  /** Vertical crosshair line width in px. Default `1`. */
+  crosshairStrokeWidth?: number;
+  /**
+   * Extend the vertical crosshair line past the plot's top and bottom edges by
+   * this many px. A measured top custom-tooltip stop remains unchanged so the
+   * line does not draw through the tooltip. Negative values are clamped to `0`.
+   * Default `0`.
+   */
+  crosshairOvershoot?: number;
+  /**
+   * Fade the crosshair as it approaches the live edge. Set `false` to keep the
+   * line, selection dot, and tooltip fully opaque while scrubbing. The trailing
+   * content dim keeps its own edge fade. Default `true`.
+   */
+  crosshairFade?: boolean;
+  /**
+   * Distance in px over which the visible crosshair fades as it approaches the
+   * live edge. Applies to the line, selection dot, and tooltip when
+   * `crosshairFade` is enabled; the trailing-content dim keeps its existing
+   * fade. Negative values are clamped to `0`. Default `4`.
+   */
+  crosshairFadeDistance?: number;
+  /**
+   * Cap style for the vertical crosshair line. Omit to preserve the existing
+   * Skia default.
+   */
+  crosshairLineCap?: "butt" | "round" | "square";
   /**
    * Dash the vertical crosshair line. `true` → a default `[4, 4]` dash; an array
    * sets explicit Skia dash intervals `[on, off, …]` in px. Omit / `false` → a
@@ -898,6 +937,14 @@ export interface ScrubConfig {
    * `false` / omitted keeps the overlays visible while scrubbing (default).
    */
   hideOverlaysOnScrub?: boolean;
+  /**
+   * Keep plain scrubbing inside the horizontal plot bounds. A gesture that
+   * starts in the Y-axis gutter (or beyond either horizontal edge) is ignored;
+   * one that starts inside remains active and clamps to the nearest plot edge
+   * while dragging. Scrub-action gestures retain their existing behavior.
+   * Default `false`.
+   */
+  clampToPlot?: boolean;
 }
 
 /**