@rootnative/impulse 0.0.0-alpha.0 → 0.0.0-alpha.1

package/src/intents/useDoubleTap.ts

@@ -0,0 +1,321 @@
+import { useMemo } from 'react'
+import { Gesture, type TapGesture } from 'react-native-gesture-handler'
+import { useSharedValue } from 'react-native-reanimated'
+import { scheduleOnRN } from 'react-native-worklets'
+import {
+  useGestureMemo,
+  type GestureMemoOptions,
+} from '../internal/useGestureMemo'
+import { buildIntentResult } from '../internal/intentResult'
+import { useLatestCallback } from '../internal/useLatestCallback'
+import { useStableRecord } from '../internal/useStableRecord'
+import { toTapEvent, type TapEvent } from './tapEvent'
+import { type HitSlop, type IntentEndInfo, type IntentResult } from '../types'
+
+export type { TapEvent } from './tapEvent'
+
+/**
+ * How long each tap may hold the finger down, in milliseconds.
+ *
+ * RNGH's own default, restated for the same reason `useTap` restates it: the
+ * number is part of the documented behaviour, and inheriting it means an RNGH
+ * release can move it underneath Impulse without a word.
+ */
+const DEFAULT_MAX_DURATION = 500
+
+/**
+ * How long the gap between the two taps may be, in milliseconds.
+ *
+ * RNGH's own default, restated. It is also the number that decides how much
+ * latency a single tap pays when the two are composed — see `maxDelay`.
+ */
+const DEFAULT_MAX_DELAY = 500
+
+/**
+ * How far the finger may travel and still count as a tap, in points.
+ *
+ * Impulse's number rather than RNGH's, exactly as in `useTap`: RNGH leaves
+ * the slop to the platform, so the same tap is accepted on one operating
+ * system and rejected on the other. The two hooks share the value on purpose
+ * — a double tap that is fussier than a single tap on the same view is a
+ * difference the consumer never asked for.
+ *
+ * **This number is a design intention, not a measurement.** The device sweep
+ * of 2026-09-19 did not test it. See Known gaps in docs/docs/roadmap.md.
+ */
+const DEFAULT_MAX_DISTANCE = 10
+
+/** Options for {@link useDoubleTap}. */
+export interface UseDoubleTapOptions extends GestureMemoOptions {
+  /**
+   * How many fingers must be down. Default `1`.
+   *
+   * The count applies to both taps — a two-finger double tap is two taps of
+   * two fingers, not a tap of two followed by a tap of one.
+   */
+  pointers?: number
+  /**
+   * How long each tap may hold the finger down, in milliseconds. Default
+   * `500`.
+   *
+   * This is per tap, not for the pair. A finger that stays down past it fails
+   * the gesture rather than counting as the second tap.
+   */
+  maxDuration?: number
+  /**
+   * How long the gap between the two taps may be, in milliseconds. Default
+   * `500`.
+   *
+   * **Lowering it is how a composed single tap stops feeling slow.** When a
+   * `useTap` is composed `exclusive` behind this hook, the single tap cannot
+   * report until this window has passed without a second tap, so every
+   * ordinary tap on that view waits this long. 500ms is RNGH's number and is
+   * generous; 250 to 300 is closer to what the platforms themselves use.
+   *
+   * The device sweep of 2026-09-19 found that a deliberate double tap still
+   * registers at 250, on an Android emulator and an iOS simulator. Whether
+   * the single-tap latency feels acceptable is unmeasured. See Known gaps in
+   * docs/docs/roadmap.md.
+   */
+  maxDelay?: number
+  /**
+   * How far the finger may travel within a tap, in points. Default `10`.
+   *
+   * This does not limit how far the second tap may land from the first — RNGH
+   * measures each tap on its own.
+   */
+  maxDistance?: number
+  /**
+   * Extra touchable area around the view, in points.
+   *
+   * Written inline as an object is fine — the gesture is not rebuilt when the
+   * contents are unchanged.
+   */
+  hitSlop?: HitSlop
+  /**
+   * Whether the gesture is recognized at all. Default `true`.
+   *
+   * Prefer this over unmounting the `<GestureDetector>`: a disabled gesture
+   * keeps its identity and its relations, so re-enabling it does not
+   * re-attach anything.
+   */
+  enabled?: boolean
+  /**
+   * The double tap ended. **Runs on the JS thread** — Impulse owns the
+   * `scheduleOnRN` boundary, so this is an ordinary function and may touch React
+   * state.
+   *
+   * The payload describes the second tap, which is the one the consumer means
+   * when they ask where the double tap was.
+   *
+   * It fires only for a double tap the recognizer accepted, and `cancelled`
+   * says what happened after that. `false` is the ordinary double tap. `true`
+   * means the system took the recognized double tap away — a competing
+   * gesture in a relation won it, or the app went to the background.
+   *
+   * **Check `cancelled` before you act on it.** A handler that zooms or
+   * navigates should do nothing when it is `true`. The path is rare: a single
+   * tap that was never followed by a second reaches `onFinalize` with
+   * `success: false` and never gets here.
+   */
+  onDoubleTap?: (event: TapEvent, info: IntentEndInfo) => void
+  /**
+   * The first finger went down and the gesture is now a candidate. **This is
+   * a worklet** — mark it with the `'worklet'` directive, and do not touch
+   * React state from it.
+   *
+   * It fires once for the pair, on the first touch, not once per tap. Most of
+   * the touches that reach it are ordinary single taps that will fail this
+   * gesture, so it is a poor place to show anything the user would read as
+   * commitment.
+   */
+  onBegin?: (event: TapEvent) => void
+  /**
+   * The gesture is over, whether both taps happened or not. **This is a
+   * worklet.**
+   *
+   * `success` is `true` when the double tap was recognized. This is the right
+   * place to clear anything `onBegin` set, because it runs on both paths.
+   */
+  onFinalize?: (event: TapEvent, success: boolean) => void
+}
+
+/**
+ * What {@link useDoubleTap} returns.
+ *
+ * Its own name rather than an alias of `UseTapResult`, so the two can diverge
+ * without a breaking rename. A double tap produces no continuous value, so
+ * the gesture, the ref, and `isActive` are the whole result.
+ */
+export type UseDoubleTapResult = IntentResult<TapGesture>
+
+/**
+ * Recognize two taps in quick succession.
+ *
+ * ```tsx
+ * const double = useDoubleTap({ onDoubleTap: () => zoomIn() })
+ *
+ * return (
+ *   <GestureDetector gesture={double.gesture}>
+ *     <View />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * `onDoubleTap` runs on the JS thread and may set React state directly.
+ * `onBegin` and `onFinalize` are worklets and run on the UI thread — the name
+ * states the thread, so there is nothing to configure and no `scheduleOnRN` to
+ * write.
+ *
+ * `isActive` is a shared value that is `true` from the first finger down
+ * until the pair resolves. It is **not** a useful pressed state on its own:
+ * it is `true` for every ordinary single tap on the view as well, and those
+ * mostly end in failure. Drive a pressed state from a `useTap` composed with
+ * this one, and use `isActive` here only for something that should show while
+ * a double tap is genuinely in progress.
+ *
+ * **Pairing with a single tap.** This is the composition that makes both
+ * work, and the mode matters:
+ *
+ * ```tsx
+ * const double = useDoubleTap({ maxDelay: 250, onDoubleTap: zoomIn })
+ * const tap = useTap({ onTap: select })
+ * const { gesture } = useGestures([double, tap], { mode: 'exclusive' })
+ * ```
+ *
+ * `exclusive` tries the members in order and lets a later one activate only
+ * after every earlier one has failed, so the single tap waits to learn
+ * whether a second tap is coming. `race` does not work: a single tap
+ * recognizes on the first release and would win every time. The cost is
+ * latency — the single tap cannot report for `maxDelay` milliseconds — which
+ * is why lowering `maxDelay` is the first thing to reach for when a composed
+ * single tap feels slow.
+ *
+ * **A view that only needs a double tap does not need the composition.** Use
+ * this hook alone; there is nothing for it to wait on.
+ *
+ * **Three taps and up are not modelled.** A triple tap is rare enough that a
+ * named intent would be dead API. Build it with `useRawGesture` and
+ * `Gesture.Tap().numberOfTaps(3)`.
+ *
+ * **Activation criteria.** `maxDuration` and `maxDelay` default to 500ms, and
+ * `maxDistance` to 10 points. The distance default is Impulse's, not RNGH's,
+ * and matches `useTap` so the two agree about what counts as a tap on one
+ * view. The device sweep found that `maxDelay` works at 500ms and at 250ms.
+ * It did not test `maxDuration` or `maxDistance`, and it measured no feel.
+ *
+ * **Web.** RNGH's web implementation recognizes tap from pointer events, so a
+ * double click behaves as a double tap. The browser's own double-click
+ * handling — text selection, zoom — is not suppressed by this hook, and
+ * `pointers` above 1 is unreliable there because a mouse reports one pointer
+ * and touch emulation varies by browser.
+ *
+ * **Accessibility.** A double tap is invisible to a screen reader and
+ * unreachable from a keyboard, and it is worse than a single tap on both
+ * counts: VoiceOver and TalkBack both consume a double tap as their own
+ * activation gesture, so a screen-reader user cannot reach this at all.
+ * Whatever it does must be reachable another way — an explicit control, or
+ * `accessibilityActions` with `onAccessibilityAction` on the view the gesture
+ * is attached to. A double-tap-only affordance is a bug, not a trade-off.
+ *
+ * @param options - Activation criteria, callbacks, and the `alongside` /
+ *   `blocks` / `deferTo` coexistence options every Impulse hook accepts.
+ */
+export function useDoubleTap(
+  options: UseDoubleTapOptions = {},
+): UseDoubleTapResult {
+  const {
+    pointers = 1,
+    maxDuration = DEFAULT_MAX_DURATION,
+    maxDelay = DEFAULT_MAX_DELAY,
+    maxDistance = DEFAULT_MAX_DISTANCE,
+    enabled,
+    onDoubleTap,
+    onBegin,
+    onFinalize,
+  } = options
+
+  const isActive = useSharedValue(false)
+  // `hitSlop` is the one option a consumer writes as an object literal, so it
+  // is the one that would rebuild the gesture every render if taken as-is.
+  const hitSlop = useStableRecord(options.hitSlop)
+  // JS-thread callback: reached through a stable identity so it is never a
+  // gesture dependency. The worklet callbacks below stay direct dependencies,
+  // because a worklet is captured as written.
+  const handleDoubleTap = useLatestCallback(onDoubleTap)
+  // Attaching a handler is not the same as calling it: RNGH decides which
+  // thread a gesture's callbacks run on by inspecting the ones it was given,
+  // so the gesture does have to change when `onDoubleTap` appears or
+  // disappears. This is a boolean, so it changes only when that is actually
+  // true.
+  const hasDoubleTapHandler = onDoubleTap !== undefined
+
+  const built = useGestureMemo(
+    'useDoubleTap',
+    () => {
+      const tap = Gesture.Tap()
+        .numberOfTaps(2)
+        .minPointers(pointers)
+        .maxDuration(maxDuration)
+        .maxDelay(maxDelay)
+        .maxDistance(maxDistance)
+        .onBegin((event) => {
+          'worklet'
+          isActive.value = true
+          onBegin?.(toTapEvent(event))
+        })
+        .onEnd((event, success) => {
+          'worklet'
+          // Not guarded on `success`: RNGH calls `onEnd` only when the old
+          // state was ACTIVE, so reaching here at all means the double tap
+          // was recognized. `cancelled` then separates the one the user
+          // completed from the one the system took away. Without it the
+          // cancel is reportable only from `onFinalize`, which is a worklet.
+          if (hasDoubleTapHandler) {
+            scheduleOnRN(handleDoubleTap, toTapEvent(event), {
+              cancelled: !success,
+            })
+          }
+        })
+        .onFinalize((event, success) => {
+          'worklet'
+          isActive.value = false
+          onFinalize?.(toTapEvent(event), success)
+        })
+
+      // Applied conditionally rather than with a default, so an option the
+      // consumer did not set leaves RNGH's own default in place instead of
+      // Impulse overwriting it with a guess.
+      if (hitSlop !== undefined) {
+        tap.hitSlop(hitSlop)
+      }
+      if (enabled !== undefined) {
+        tap.enabled(enabled)
+      }
+      return tap
+    },
+    [
+      pointers,
+      maxDuration,
+      maxDelay,
+      maxDistance,
+      hitSlop,
+      enabled,
+      hasDoubleTapHandler,
+      handleDoubleTap,
+      isActive,
+      onBegin,
+      onFinalize,
+    ],
+    options,
+  )
+
+  // Memoised for the same reason `useGestureMemo` memoises its own result: a
+  // consumer may put the whole hook result in a dependency list, and a fresh
+  // object every render would make that dependency useless. `isActive` is
+  // stable for the life of the hook, so `built` is the only real input.
+  return useMemo(
+    () => buildIntentResult(built, { isActive }),
+    [built, isActive],
+  )
+}

package/src/intents/useDrag.ts

@@ -6,18 +6,21 @@ import {
   type PanGesture,
   type PanGestureHandlerEventPayload,
 } from 'react-native-gesture-handler'
-import {
-  runOnJS,
-  useSharedValue,
-  type SharedValue,
-} from 'react-native-reanimated'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { scheduleOnRN } from 'react-native-worklets'
 import {
   useGestureMemo,
   type GestureMemoOptions,
 } from '../internal/useGestureMemo'
+import { buildIntentResult } from '../internal/intentResult'
 import { useLatestCallback } from '../internal/useLatestCallback'
 import { useStableRecord } from '../internal/useStableRecord'
-import { type HitSlop, type IntentResult, type Point } from '../types'
+import {
+  type HitSlop,
+  type IntentEndInfo,
+  type IntentResult,
+  type Point,
+} from '../types'
 
 /**
  * How far the finger must travel before the drag takes the touch, in points.
@@ -28,8 +31,10 @@ import { type HitSlop, type IntentResult, type Point } from '../types'
  * can share a view, so it is set here rather than left to the consumer to
  * discover.
  *
- * **This number is a design intention, not a measurement.** No hardware pass
- * has happened. See Known gaps in CLAUDE.md.
+ * **This number is a design intention, not a measurement.** The device sweep
+ * of 2026-09-19 found that it works mechanically on an Android emulator and
+ * an iOS simulator. Whether it feels right is unmeasured. See Known gaps in
+ * docs/docs/roadmap.md.
  */
 const DEFAULT_THRESHOLD = 10
 
@@ -179,7 +184,7 @@ export interface UseDragOptions extends GestureMemoOptions {
   enabled?: boolean
   /**
    * The drag passed `threshold` and now owns the touch. **Runs on the JS
-   * thread** — Impulse owns the `runOnJS` boundary, so this is an ordinary
+   * thread** — Impulse owns the `scheduleOnRN` boundary, so this is an ordinary
    * function and may touch React state.
    *
    * This is the first moment the drag has definitely won. `onBegin` fires
@@ -187,17 +192,21 @@ export interface UseDragOptions extends GestureMemoOptions {
    */
   onDragStart?: (event: DragEvent) => void
   /**
-   * The finger lifted and the drag is over. **Runs on the JS thread.**
+   * The drag is over. **Runs on the JS thread.**
    *
-   * Fires only for a drag that activated and then released. A drag the system
-   * took away — a competing gesture won, or the app went to the background —
-   * reaches `onFinalize` with `success: false` and never gets here, because
-   * there was no release and so no velocity worth seeding a spring with.
+   * Fires only for a drag that activated, so a touch that never passed the
+   * threshold never reaches here on either path.
    *
-   * Read `velocity` to seed that release animation, and `settled` for where
-   * an elastic overshoot should return to.
+   * It fires for both endings, and `cancelled` says which. `false` is the
+   * finger lifting, and `velocity` then seeds the release animation. `true`
+   * is the system taking the drag away — a competing gesture won, or the app
+   * went to the background. **There was no release on that path, so the
+   * velocity describes the last movement rather than a throw.** Return the
+   * view to `settled` instead of springing it.
+   *
+   * Read `settled` on both paths for where an elastic overshoot belongs.
    */
-  onDragEnd?: (event: DragEvent) => void
+  onDragEnd?: (event: DragEvent, info: IntentEndInfo) => void
   /**
    * The finger went down and the gesture is now a candidate. **This is a
    * worklet** — mark it with the `'worklet'` directive, and do not touch
@@ -212,7 +221,7 @@ export interface UseDragOptions extends GestureMemoOptions {
    * The drag moved. **This is a worklet**, and it runs on every frame the
    * finger moves.
    *
-   * There is no JS-thread counterpart on purpose. A per-frame `runOnJS` is a
+   * There is no JS-thread counterpart on purpose. A per-frame `scheduleOnRN` is a
    * scheduling cost paid sixty times a second for a value that is already on
    * the thread that needs it — read `x` and `y` from a `useAnimatedStyle`
    * instead, and let this callback handle what the style cannot.
@@ -324,7 +333,8 @@ function clamp(
  * vertical `ScrollView` leaves the scroll alone until the finger commits
  * sideways; with `'both'` it is a radial distance. Set `failOffset` as well
  * when a mostly-diagonal move should go to the other gesture rather than to
- * this one. The default has not been measured on hardware yet.
+ * this one. The default works mechanically in the device sweep, and its feel
+ * is unmeasured.
  *
  * **Coexistence.** A threshold decides who moves first; it does not decide
  * who wins a contested touch. For a drag inside a scroll view, say which one
@@ -452,7 +462,7 @@ export function useDrag(options: UseDragOptions = {}): UseDragResult {
           startY.value = y.value - event.translationY
           isActive.value = true
           if (hasDragStart) {
-            runOnJS(handleDragStart)(toDragEvent(event))
+            scheduleOnRN(handleDragStart, toDragEvent(event))
           }
         })
         .onUpdate((event) => {
@@ -477,13 +487,21 @@ export function useDrag(options: UseDragOptions = {}): UseDragResult {
         })
         .onEnd((event, success) => {
           'worklet'
-          // Guarded on `success`, because RNGH calls this for a cancelled
-          // drag too. A cancelled drag had its touch taken away — by a
-          // competing gesture winning, or the app going to the background —
-          // and there was no release, so there is no velocity worth seeding a
-          // spring with. That path reaches `onFinalize` instead.
-          if (success && hasDragEnd) {
-            runOnJS(handleDragEnd)(toDragEvent(event))
+          // Not guarded on `success`: RNGH calls this for a cancelled drag
+          // too, and `cancelled` is what separates the two. The guard used to
+          // be here, which left the cancel reportable only from `onFinalize`
+          // — a worklet — so a consumer holding phase in React state had to
+          // cross the thread boundary by hand. A drag that is taken away
+          // still has to put its view somewhere, and that decision belongs on
+          // the JS thread as much as the release does.
+          //
+          // Reporting the cancel is safe because RNGH calls `onEnd` only when
+          // the old state was ACTIVE. A touch that never passed the threshold
+          // reaches `onFinalize` and never gets here.
+          if (hasDragEnd) {
+            scheduleOnRN(handleDragEnd, toDragEvent(event), {
+              cancelled: !success,
+            })
           }
         })
         .onFinalize((event, success) => {
@@ -559,5 +577,8 @@ export function useDrag(options: UseDragOptions = {}): UseDragResult {
   // consumer may put the whole hook result in a dependency list, and a fresh
   // object every render would make that dependency useless. The shared values
   // are stable for the life of the hook, so `built` is the only real input.
-  return useMemo(() => ({ ...built, x, y, isActive }), [built, x, y, isActive])
+  return useMemo(
+    () => buildIntentResult(built, { x, y, isActive }),
+    [built, x, y, isActive],
+  )
 }