react-native-livechart 3.2.0 → 3.4.0

package/src/hooks/useCrosshair.ts

@@ -8,20 +8,77 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
+import { BADGE_METRICS_DEFAULTS, X_AXIS_LABEL_OFFSET_Y } from "../constants";
+import type { ResolvedScrubActionConfig } from "../core/resolveConfig";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { type ChartPadding } from "../draw/line";
 import { interpolateAtTime } from "../math/interpolate";
 import { pickCandleAtTime } from "../math/pickCandle";
-import type { CandlePoint, LiveChartPalette, ScrubPoint } from "../types";
+import type {
+  BadgeMetrics,
+  CandlePoint,
+  LiveChartPalette,
+  ScrubActionPoint,
+  ScrubPoint,
+} from "../types";
 import {
+  computeActionBadgeLayout,
   computeCandleTooltipLayout,
   computeCrosshairOpacity,
   computeScrubDotY,
   computeScrubTime,
+  computeTimeBadgeLayout,
+  computeValueAtY,
   deriveCrosshairTooltipSingle,
+  HIDDEN_ACTION_BADGE,
+  HIDDEN_TIME_BADGE,
+  pointInRect,
+  snapPrice,
   type CrosshairState,
 } from "./crosshairShared";
 
+const ACTION_HIT_SLOP = 6;
+const RETICLE_HIT = 14;
+
+/**
+ * Movement (px) a scrub-action *tap* (place / press / dismiss) may travel before
+ * it's treated as a drag — the Tap's `maxDistance`. ~Touch slop, so a finger that
+ * jitters a few px still registers as a tap rather than failing.
+ */
+const SCRUB_ACTION_TAP_SLOP = 10;
+
+/**
+ * Default press-hold (ms) before the live scrub / lock-adjust pan activates in
+ * scrub-action ("order ticket") mode. A quick tap places or acts on the reticle;
+ * the scrub crosshair only appears on a deliberate hold, so a tap never flashes
+ * it. Overridden by an explicit `scrub.panGestureDelay`.
+ */
+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(
+  y: number,
+  padTop: number,
+  canvasHeight: number,
+  padBottom: number,
+): number {
+  "worklet";
+  return Math.min(canvasHeight - padBottom, Math.max(padTop, y));
+}
+
 export type { CrosshairState, TooltipLayout } from "./crosshairShared";
 export type { ScrubPoint };
 
@@ -60,6 +117,18 @@ export function useCrosshair(
   panGestureDelay = 0,
   onGestureStart?: () => void,
   onGestureEnd?: () => void,
+  /** Scrub-action ("order ticket") config; `null`/omitted disables lock mode. */
+  scrubAction?: ResolvedScrubActionConfig | null,
+  onScrubAction?: (point: ScrubActionPoint) => void,
+  /** Badge geometry (gutter margins / pad) for the action pill. */
+  badgeMetrics: BadgeMetrics = BADGE_METRICS_DEFAULTS,
+  /**
+   * Worklet predicate: true when a tap at (x, y) lands on another interactive
+   * overlay (a marker, or a pressable reference-line badge). The scrub-action tap
+   * defers to it (no reticle placed) so that overlay's tap handler can act.
+   * Omitted when nothing coexists.
+   */
+  deferTapHit?: (x: number, y: number) => boolean,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -67,6 +136,22 @@ export function useCrosshair(
   // activates doesn't emit a spurious onGestureEnd.
   const gestureStarted = useSharedValue(false);
 
+  // Scrub-action lock state. Created unconditionally (hooks must be), but the
+  // lock gestures are only wired by the controller when `scrubAction` is set.
+  const lockActive = useSharedValue(false);
+  const lockX = useSharedValue(-1);
+  // The chosen PRICE is the source of truth (frozen on place/drag); the reticle's
+  // screen Y is re-derived from it each frame (see `lockY` below) so the level
+  // 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 hasOnScrubAction = onScrubAction != null;
+  const dismissOnTapOutside = scrubAction?.dismissOnTapOutside ?? false;
+  const snapIncrement = scrubAction?.snap;
+  const actionIcon = scrubAction?.icon ?? "+";
+  const actionShowText = scrubAction?.text ?? true;
+  const hasTimeBadge = scrubAction?.timeBadge ?? false;
+
   const scrubTime = useDerivedValue(() =>
     computeScrubTime(
       scrubActive.get(),
@@ -165,6 +250,113 @@ export function useCrosshair(
     );
   });
 
+  // ── Scrub-action lock derivations ──────────────────────────────────────────
+  // Reported price = the frozen chosen price, optionally snapped. Independent of
+  // the display range (the point of freezing it), so the badge readout and the
+  // onScrubAction payload stay stable while the chart auto-rescales. Null until a
+  // reticle is placed.
+  /* istanbul ignore next -- worklet (locked branch only runs on the UI thread) */
+  const lockPrice = useDerivedValue(() => {
+    if (!lockActive.get()) return null;
+    const p = lockPriceValue.get();
+    return p === null ? null : snapPrice(p, snapIncrement);
+  });
+
+  // Screen Y of the locked level, DERIVED from the frozen price each frame so the
+  // line + badge track the chosen price as displayMin/Max move (rather than the
+  // price drifting under a pixel-fixed reticle). Pins to the plot edge when the
+  // price scrolls out of the visible range; -1 until placed / laid out.
+  /* istanbul ignore next -- worklet (locked branch only runs on the UI thread) */
+  const lockY = useDerivedValue(() => {
+    const p = lockPriceValue.get();
+    const ch = engine.canvasHeight.get();
+    if (p === null || ch - padding.top - padding.bottom <= 0) return -1;
+    const y = computeScrubDotY(
+      p,
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      ch,
+      padding.top,
+      padding.bottom,
+    );
+    return clampPlotY(y, padding.top, ch, padding.bottom);
+  });
+
+  const lockTime = useDerivedValue(() =>
+    computeScrubTime(
+      lockActive.get(),
+      lockX.get(),
+      padding,
+      engine.canvasWidth.get(),
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+    ),
+  );
+
+  /* istanbul ignore next -- worklet */
+  const lockCandle = useDerivedValue(() => {
+    if (!isCandleMode || !candlesSV || !lockActive.get() || lockTime.get() < 0)
+      return null;
+    return pickCandleAtTime(
+      candlesSV.get(),
+      liveCandleSV?.get() ?? null,
+      lockTime.get(),
+      candleWidthSecs,
+    );
+  });
+
+  // Right-gutter action-badge layout — also the tap hit rect. Hidden when not locked.
+  /* istanbul ignore next -- worklet (locked branch only runs on the UI thread) */
+  const actionBadge = useDerivedValue(() => {
+    const price = lockPrice.get();
+    if (price === null) return HIDDEN_ACTION_BADGE;
+    return computeActionBadgeLayout(
+      lockActive.get(),
+      lockY.get(),
+      actionShowText ? formatValue(price) : "",
+      actionIcon,
+      engine.canvasWidth.get(),
+      engine.canvasWidth.get() - padding.right,
+      font,
+      badgeMetrics.marginEdge,
+      badgeMetrics.padX,
+      badgeMetrics.padY,
+    );
+  });
+
+  // X-axis time badge at the reticle (opt-in). Hidden unless enabled + locked.
+  /* istanbul ignore next -- worklet (locked branch only runs on the UI thread) */
+  const timeBadge = useDerivedValue(() => {
+    if (!hasTimeBadge || !lockActive.get()) return HIDDEN_TIME_BADGE;
+    const t = lockTime.get();
+    if (t < 0) return HIDDEN_TIME_BADGE;
+    return computeTimeBadgeLayout(
+      lockActive.get(),
+      lockX.get(),
+      formatTime(t),
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get() - padding.bottom + X_AXIS_LABEL_OFFSET_Y,
+      font,
+      badgeMetrics.padX,
+      badgeMetrics.padY,
+      badgeMetrics.marginEdge,
+    );
+  });
+
+  /* istanbul ignore next -- invoked only via scheduleOnRN from UI-thread gesture */
+  function handleScrubAction(
+    price: number,
+    time: number,
+    x: number,
+    y: number,
+    candleJson: string | null,
+  ) {
+    const candle: CandlePoint | undefined = candleJson
+      ? (JSON.parse(candleJson) as CandlePoint)
+      : undefined;
+    onScrubAction?.({ price, time, x, y, candle });
+  }
+
   /* istanbul ignore next -- invoked only via scheduleOnRN from UI-thread gesture */
   function handleScrub(
     x: number,
@@ -246,9 +438,25 @@ export function useCrosshair(
     },
   );
 
+  // In scrub-action mode the live scrub / lock-adjust requires a deliberate
+  // press-hold: a quick tap (even a sloppy one that travels a few px) places or
+  // acts on the reticle, and must never flash the crosshair. The press-hold is
+  // what gates activation — and because movement during the hold *fails* the pan
+  // (RNGH), a tap can't trip the scrub by moving. Honor an explicit
+  // `scrub.panGestureDelay`, else default to the hold. Outside scrub-action the
+  // pan keeps its normal (no-hold) activation unless a delay was set.
+  const longPressMs =
+    hasScrubAction && panGestureDelay <= 0
+      ? SCRUB_ACTION_PRESS_HOLD_MS
+      : panGestureDelay;
+
   let gesture = Gesture.Pan()
-    .minDistance(Platform.OS === "android" ? 10 : 0)
-    .activateAfterLongPress(panGestureDelay)
+    // Scrub-action: minDistance 0 — the press-hold above is the sole activator
+    // (movement during the hold fails the pan), so the crosshair never appears
+    // from a tap's travel. The Tap (maxDistance SCRUB_ACTION_TAP_SLOP) owns quick
+    // gestures; only a held press becomes a scrub/adjust drag.
+    .minDistance(!hasScrubAction && Platform.OS === "android" ? 10 : 0)
+    .activateAfterLongPress(longPressMs)
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
     // Start scrubbing on ACTIVE (onStart), not on touch-down (onBegin):
@@ -259,6 +467,28 @@ export function useCrosshair(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;
+        // Scrub-action: once a reticle is placed, drag adjusts it (2D — the Y is
+        // the price). The ephemeral live-scrub never engages, so scrubActive
+        // stays false and the live crosshair hides itself.
+        if (hasScrubAction && lockActive.get()) {
+          lockX.set(
+            clampPlotX(e.x, padding.left, engine.canvasWidth.get(), padding.right),
+          );
+          // Freeze the chosen price (value at the pointer Y); the line's Y is
+          // re-derived from it so the level stays put in PRICE as the axis rescales.
+          {
+            const p = computeValueAtY(
+              e.y,
+              engine.displayMin.get(),
+              engine.displayMax.get(),
+              engine.canvasHeight.get(),
+              padding.top,
+              padding.bottom,
+            );
+            if (p !== null) lockPriceValue.set(p);
+          }
+          return;
+        }
         scrubX.set(e.x);
         scrubActive.set(true);
         gestureStarted.set(true);
@@ -269,14 +499,38 @@ export function useCrosshair(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;
+        if (hasScrubAction && lockActive.get()) {
+          lockX.set(
+            clampPlotX(e.x, padding.left, engine.canvasWidth.get(), padding.right),
+          );
+          // Freeze the chosen price (value at the pointer Y); the line's Y is
+          // re-derived from it so the level stays put in PRICE as the axis rescales.
+          {
+            const p = computeValueAtY(
+              e.y,
+              engine.displayMin.get(),
+              engine.displayMax.get(),
+              engine.canvasHeight.get(),
+              padding.top,
+              padding.bottom,
+            );
+            if (p !== null) lockPriceValue.set(p);
+          }
+          return;
+        }
         scrubX.set(e.x);
       },
     )
     .onFinalize(
       /* istanbul ignore next */ () => {
         "worklet";
-        scrubActive.set(false);
-        if (hasOnScrub) scheduleOnRN(handleScrubEnd);
+        // A lock-adjust drag leaves the reticle in place (scrubActive was never
+        // set); a live-scrub clears its crosshair. Always clear scrubActive so a
+        // stray scrub can never linger behind a placed reticle.
+        if (scrubActive.get()) {
+          scrubActive.set(false);
+          if (hasOnScrub) scheduleOnRN(handleScrubEnd);
+        }
         if (gestureStarted.get()) {
           gestureStarted.set(false);
           if (hasOnGestureEnd) scheduleOnRN(handleGestureEnd);
@@ -285,10 +539,83 @@ export function useCrosshair(
     );
 
   /* istanbul ignore next -- Android-only gesture axis config */
-  if (Platform.OS === "android") {
+  if (Platform.OS === "android" && !hasScrubAction) {
+    // Lock mode needs free vertical drag (Y = price), so the failOffsetY clamp —
+    // which would kill a vertical adjust — is applied only outside scrub-action.
     gesture = gesture.activeOffsetX([-25, 25]).failOffsetY([-25, 25]);
   }
 
+  // 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.
+  // Built only in scrub-action mode (the plain-scrub path never constructs a Tap).
+  /* istanbul ignore next -- gesture worklet runs on the UI thread, not in Jest */
+  const handleActionTap = (e: { x: number; y: number }, success: boolean) => {
+    "worklet";
+    if (!enabled || !hasScrubAction || !success) return;
+    if (lockActive.get()) {
+      // 1. Action-badge press → fire onScrubAction with the chosen price.
+      const rect = actionBadge.get();
+      if (rect.visible && pointInRect(e.x, e.y, rect, ACTION_HIT_SLOP)) {
+        const price = lockPrice.get();
+        if (price !== null) {
+          let candleJson: string | null = null;
+          if (isCandleMode) {
+            const c = lockCandle.get();
+            if (c) candleJson = JSON.stringify(c);
+          }
+          if (hasOnScrubAction)
+            scheduleOnRN(
+              handleScrubAction,
+              price,
+              lockTime.get(),
+              lockX.get(),
+              lockY.get(),
+              candleJson,
+            );
+        }
+        return;
+      }
+      // 2. Dismiss: tap the reticle itself, or any empty tap when configured.
+      const onReticle =
+        Math.abs(e.x - lockX.get()) <= RETICLE_HIT &&
+        Math.abs(e.y - lockY.get()) <= RETICLE_HIT;
+      if (onReticle || dismissOnTapOutside) {
+        lockActive.set(false);
+        return;
+      }
+    }
+    // 2.5. Defer to a marker / reference-line badge under the tap: when one
+    //      coexists, the tap fires both this handler and that overlay's tap
+    //      (Simultaneous) — yield so it acts instead of dropping a reticle on top.
+    if (deferTapHit !== undefined && deferTapHit(e.x, e.y)) return;
+    // 3. Place / move the reticle. Clear any in-progress live-scrub so its
+    //    crosshair never shows behind the placed reticle.
+    scrubActive.set(false);
+    lockX.set(
+      clampPlotX(e.x, padding.left, engine.canvasWidth.get(), padding.right),
+    );
+    // Freeze the chosen price at the tap Y; the line's Y derives from it (see
+    // `lockY`). No-op until the canvas is laid out (price === null).
+    const placedPrice = computeValueAtY(
+      e.y,
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    );
+    if (placedPrice === null) return;
+    lockPriceValue.set(placedPrice);
+    lockActive.set(true);
+  };
+
+  const tapGesture = hasScrubAction
+    ? Gesture.Tap()
+        .maxDuration(250)
+        .maxDistance(SCRUB_ACTION_TAP_SLOP)
+        .onEnd(handleActionTap)
+    : undefined;
+
   return {
     scrubX,
     scrubActive,
@@ -298,5 +625,12 @@ export function useCrosshair(
     tooltipLayout,
     scrubDotY,
     gesture,
+    lockActive,
+    lockX,
+    lockY,
+    lockPrice,
+    actionBadge,
+    timeBadge,
+    tapGesture,
   };
 }

package/src/hooks/useMarkers.ts

@@ -32,7 +32,12 @@ export function useMarkers(
   lineData?: SharedValue<LiveChartPoint[]>,
   /** Static charts run no loops: register without starting. Default `true`. */
   autostart = true,
-): { projected: SharedValue<ProjectedMarker[]>; tapGesture: ReturnType<typeof Gesture.Tap> } {
+): {
+  projected: SharedValue<ProjectedMarker[]>;
+  tapGesture: ReturnType<typeof Gesture.Tap>;
+  /** Worklet hit-test: true when (x, y) lands on a projected marker. */
+  hitTest: (x: number, y: number) => boolean;
+} {
   const projected = useSharedValue<ProjectedMarker[]>([]);
   const cacheRef = useRef<{
     a: ProjectedMarker[];
@@ -94,5 +99,16 @@ export function useMarkers(
     },
   );
 
-  return { projected, tapGesture };
+  // Lets a coexisting gesture (e.g. the scrub-action tap) defer to a marker
+  // under the finger instead of acting on it.
+  const hitTest =
+    /* istanbul ignore next -- worklet, runs on the UI thread, not in Jest */ (
+      x: number,
+      y: number,
+    ) => {
+      "worklet";
+      return nearestMarkerIndex(projected.get(), x, y, hitRadius) >= 0;
+    };
+
+  return { projected, tapGesture, hitTest };
 }