@rootnative/impulse 0.0.0-alpha.0

package/src/raw/useRawGesture.ts

@@ -0,0 +1,71 @@
+import { type DependencyList } from 'react'
+import { type GestureType } from 'react-native-gesture-handler'
+import {
+  useGestureMemo,
+  type BuiltGesture,
+  type GestureMemoOptions,
+} from '../internal/useGestureMemo'
+
+/** Options for {@link useRawGesture}. */
+export type UseRawGestureOptions = GestureMemoOptions
+
+/** What {@link useRawGesture} returns. */
+export type RawGestureResult<G extends GestureType> = BuiltGesture<G>
+
+/**
+ * Build an RNGH gesture by hand, with Impulse's memoisation and coexistence
+ * handling applied to it.
+ *
+ * The mechanism-level escape hatch. Impulse's intent hooks cover the common
+ * cases; this covers a recognizer they do not model, or a configuration they
+ * do not expose, without giving up the two things that are tedious to get
+ * right by hand:
+ *
+ * ```tsx
+ * const fling = useRawGesture(
+ *   () => Gesture.Fling().direction(Directions.RIGHT).onEnd(onFling),
+ *   [onFling],
+ *   { deferTo: scrollRef },
+ * )
+ *
+ * <GestureDetector gesture={fling.gesture}>…</GestureDetector>
+ * ```
+ *
+ * What you still own here, because you are building the gesture yourself:
+ *
+ * - **The dependency list.** `build` runs only when `deps` change, and a
+ *   stale capture is a stale gesture. A worklet callback belongs in `deps`,
+ *   because a worklet is captured as written. A JS-thread callback does not —
+ *   put it through `useLatestCallback` and depend on the stable result.
+ * - **The thread.** RNGH decides per callback, by whether it carries the
+ *   `'worklet'` directive, and warns in development when a gesture mixes the
+ *   two. Impulse does not insert a `runOnJS` boundary for you here; that is
+ *   something the intent hooks do because they know what each callback means.
+ * - **The payload.** You get RNGH's flat event, not an intent-shaped one.
+ *
+ * What Impulse still owns:
+ *
+ * - Gesture identity across renders, so an inline option cannot re-attach a
+ *   gesture mid-drag.
+ * - `alongside` / `blocks` / `deferTo` resolution, so the three RNGH
+ *   relations are chosen by outcome rather than by method name.
+ * - A `ref` other hooks can name in their own coexistence options.
+ *
+ * **Accessibility.** Nothing here is reachable by a screen reader or a
+ * keyboard, and Impulse cannot name a fallback for a gesture it did not
+ * design. Whatever this gesture does must also be doable another way — an
+ * `accessibilityActions` entry, or a visible control.
+ *
+ * @param build - Constructs the gesture. Do not call the relation methods
+ *   here; pass `alongside` / `blocks` / `deferTo` in `options` instead, so
+ *   the three-way choice stays in one place and is applied exactly once.
+ * @param deps - What the gesture depends on, in `useMemo` terms.
+ * @param options - Coexistence options and `testId`.
+ */
+export function useRawGesture<G extends GestureType>(
+  build: () => G,
+  deps: DependencyList,
+  options?: UseRawGestureOptions,
+): RawGestureResult<G> {
+  return useGestureMemo('useRawGesture', build, deps, options)
+}

package/src/relations/index.ts

@@ -0,0 +1,120 @@
+import { type GestureType } from 'react-native-gesture-handler'
+import { isDevBuild, warnOnce } from '../internal/warnOnce'
+import { type GestureReference } from '../types'
+
+/**
+ * `CoexistenceOptions` after normalization: every option is an array, and an
+ * option the consumer omitted is an empty one.
+ */
+export interface ResolvedCoexistence {
+  readonly alongside: readonly GestureReference[]
+  readonly blocks: readonly GestureReference[]
+  readonly deferTo: readonly GestureReference[]
+}
+
+/**
+ * The three options, paired with the RNGH method each one means. This list is
+ * the mapping — it exists once, in one file, because choosing wrongly between
+ * the three is the single thing consumers get wrong most often and a mapping
+ * repeated per hook is a mapping that drifts.
+ *
+ * The direction of each relation is the part worth re-reading:
+ *
+ * - `alongside` → `simultaneousWithExternalGesture`. Symmetric. Both
+ *   recognize; neither waits.
+ * - `blocks` → `blocksExternalGesture`. *This* gesture wins. The named
+ *   gesture cannot activate until this one fails.
+ * - `deferTo` → `requireExternalGestureToFail`. The *named* gesture wins.
+ *   This one activates only after that one fails.
+ *
+ * `blocks` and `deferTo` are the same relation read from opposite ends, which
+ * is exactly why RNGH's names for them are so easy to swap by accident.
+ */
+const RELATIONS = [
+  ['alongside', 'simultaneousWithExternalGesture'],
+  ['blocks', 'blocksExternalGesture'],
+  ['deferTo', 'requireExternalGestureToFail'],
+] as const satisfies ReadonlyArray<readonly [keyof ResolvedCoexistence, string]>
+
+/**
+ * Apply coexistence relations to a freshly built gesture.
+ *
+ * Call this exactly once per gesture object, at construction. RNGH's relation
+ * methods append to the gesture's config rather than replacing it, so calling
+ * them twice on one gesture adds the same reference twice. Impulse builds
+ * gestures inside a `useMemo` and configures them there, which makes "once
+ * per object" structural rather than a rule to remember.
+ *
+ * An empty option is skipped rather than passed as a zero-argument call, so
+ * a gesture with no coexistence options leaves RNGH's config keys absent
+ * instead of set to an empty array. The two are equivalent to RNGH, and the
+ * absent form is easier to read in a debugger.
+ *
+ * @param gesture - The gesture to configure. Mutated in place, and returned
+ *   by nothing: the caller already holds it.
+ * @param relations - Normalized options. Use `useStableList` to produce them.
+ * @param hookName - The hook to name in a dev warning, e.g. `useRawGesture`.
+ */
+export function applyRelations(
+  gesture: GestureType,
+  relations: ResolvedCoexistence,
+  hookName: string,
+): void {
+  warnOnConflictingRelations(relations, hookName)
+
+  for (const [option, method] of RELATIONS) {
+    const references = relations[option]
+    if (references.length > 0) {
+      gesture[method](...references)
+    }
+  }
+}
+
+/**
+ * Warn when one gesture is named by more than one coexistence option.
+ *
+ * RNGH applies all three relations independently and never complains, so
+ * `{ alongside: ref, deferTo: ref }` installs two contradictory rules about
+ * the same pair and the result is whatever the platform's recognizer decides.
+ * There is no reading of the three names under which that is intentional,
+ * which makes it worth reporting rather than resolving silently.
+ *
+ * The warning key names the option pair rather than the reference, because a
+ * gesture reference has no stable string form — and because the message a
+ * reader needs is the same either way.
+ */
+function warnOnConflictingRelations(
+  relations: ResolvedCoexistence,
+  hookName: string,
+): void {
+  if (!isDevBuild()) {
+    return
+  }
+
+  const namedBy = new Map<GestureReference, string[]>()
+  for (const [option] of RELATIONS) {
+    for (const reference of relations[option]) {
+      const options = namedBy.get(reference)
+      if (options) {
+        options.push(option)
+      } else {
+        namedBy.set(reference, [option])
+      }
+    }
+  }
+
+  for (const options of namedBy.values()) {
+    if (options.length > 1) {
+      const listed = options.map((option) => `\`${option}\``).join(' and ')
+      warnOnce(
+        `relations:conflict:${hookName}:${options.join('+')}`,
+        `${hookName} names the same gesture in ${listed}. Those are ` +
+          'independent relations, not a choice of one, so both are applied ' +
+          'and they contradict each other. Keep the one that describes the ' +
+          'outcome you want: `alongside` for both recognizing at once, ' +
+          '`blocks` for this gesture winning, `deferTo` for the other one ' +
+          'winning.',
+      )
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,187 @@
+import { type ComponentProps, type ComponentType, type RefObject } from 'react'
+import {
+  type ComposedGesture,
+  type GestureDetector,
+  type GestureType,
+} from 'react-native-gesture-handler'
+import { type SharedValue } from 'react-native-reanimated'
+
+/**
+ * A gesture that an Impulse gesture can be placed in a relation with.
+ *
+ * The value is either a ref returned by another Impulse hook (`drag.ref`), a
+ * ref on a component that owns a gesture — a `ScrollView`, say — or a raw
+ * RNGH gesture object.
+ *
+ * RNGH models this as `GestureRef` and does **not** export it, so the union
+ * is written out here. It is RNGH's own minus the numeric form: RNGH accepts
+ * a handler tag as a number for its legacy API, and the three relation
+ * methods reject it. `AssertRelationArgument` below is what catches an
+ * upstream change to the shape.
+ */
+export type GestureReference =
+  | GestureType
+  | RefObject<GestureType | undefined>
+  | RefObject<ComponentType | undefined | null>
+
+/**
+ * Compile-time proof that `GestureReference` is exactly what RNGH's relation
+ * methods accept — assignable in both directions, so neither too wide nor too
+ * narrow. Nothing reads these types; they exist to fail the build if RNGH
+ * changes `GestureRef` under us, which a hand-copied union would otherwise
+ * absorb silently. They are type aliases rather than a checked `const` so the
+ * guard emits no runtime value and cannot defeat tree-shaking.
+ */
+type RelationArgument = Parameters<
+  GestureType['simultaneousWithExternalGesture']
+>[number]
+type Assert<T extends true> = T
+type _AssertReferenceIsAccepted = Assert<
+  GestureReference extends RelationArgument ? true : false
+>
+type _AssertReferenceIsComplete = Assert<
+  RelationArgument extends GestureReference ? true : false
+>
+
+/**
+ * A gesture that can be handed to `<GestureDetector>`: a single recognizer,
+ * or a composition of them.
+ *
+ * RNGH spells this inline in `GestureDetector`'s props and exports no name
+ * for it, so Impulse names it — every hook result's `gesture` has this type,
+ * and so does every member `useGestures` accepts.
+ */
+export type AttachableGesture = GestureType | ComposedGesture
+
+/**
+ * Compile-time proof that `AttachableGesture` is exactly what
+ * `<GestureDetector>` accepts. Same purpose as the assertions above: RNGH
+ * does not export the type, so this one is written out, and a hand-copied
+ * type is one that absorbs an upstream change without a word.
+ */
+type DetectorGesture = ComponentProps<typeof GestureDetector>['gesture']
+type _AssertAttachableIsAccepted = Assert<
+  AttachableGesture extends DetectorGesture ? true : false
+>
+type _AssertAttachableIsComplete = Assert<
+  DetectorGesture extends AttachableGesture ? true : false
+>
+
+/**
+ * Extra touchable area around a view, in points. A number widens every edge;
+ * an object widens the edges it names.
+ *
+ * Derived from RNGH's own method signature rather than copied, for the same
+ * reason `GestureReference` is: RNGH does not export the type from its package
+ * entry, and a hand-written copy is one that absorbs an upstream change
+ * without a word.
+ */
+export type HitSlop = Parameters<GestureType['hitSlop']>[0]
+
+/** One reference, or several. Every coexistence option accepts both. */
+export type GestureReferences = GestureReference | GestureReference[]
+
+/**
+ * How an Impulse gesture coexists with a gesture it does not own — most often
+ * a scroll view it lives inside.
+ *
+ * RNGH exposes this as three methods whose names describe the mechanism
+ * (`simultaneousWithExternalGesture`, `blocksExternalGesture`,
+ * `requireExternalGestureToFail`) and give no hint about which one a given
+ * case wants. These three name the outcome instead. Each maps to exactly one
+ * RNGH relation, and they are not interchangeable — picking the wrong one is
+ * the single thing consumers get wrong most often.
+ *
+ * All three may be set at once. They are independent relations, not a choice
+ * of one.
+ */
+export interface CoexistenceOptions {
+  /**
+   * Both gestures recognize at the same time. Neither waits for the other.
+   * Maps to `simultaneousWithExternalGesture`.
+   *
+   * Use it when the two gestures read different things from the same touch —
+   * a pinch and a pan on one image, say.
+   */
+  alongside?: GestureReferences
+  /**
+   * This gesture wins. The named gesture cannot activate until this one has
+   * failed. Maps to `blocksExternalGesture`.
+   *
+   * Use it when this gesture is the foreground affordance — a bottom sheet
+   * that must take the drag before the list behind it does.
+   */
+  blocks?: GestureReferences
+  /**
+   * The named gesture wins. This one activates only after that one fails.
+   * Maps to `requireExternalGestureToFail`.
+   *
+   * Use it when this gesture is the fallback — a horizontal drag that should
+   * start only once the vertical scroll has declined the touch.
+   */
+  deferTo?: GestureReferences
+}
+
+/**
+ * How the members of a `useGestures` composition relate to one another.
+ *
+ * - `race` — the first to activate wins, and the rest are cancelled.
+ * - `simultaneous` — every member recognizes independently.
+ * - `exclusive` — members are tried in order, and a later one activates only
+ *   after every earlier one has failed.
+ *
+ * Composition is a flat call carrying this mode rather than a nested builder
+ * chain, so precedence reads left to right instead of inside out.
+ */
+export type ComposeMode = 'race' | 'simultaneous' | 'exclusive'
+
+/**
+ * A point in a gesture payload, in points.
+ *
+ * Grouped rather than spelled as two flat fields, because every payload that
+ * carries more than one point — a drag's position and its origin, a pinch's
+ * focal point — would otherwise need a prefix per pair and the consumer would
+ * pick between `absoluteX` and `focalX` from memory. That flat union is
+ * exactly what the intent payloads exist to replace.
+ */
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * What every intent hook returns: the gesture, a handle other hooks can name
+ * in their coexistence options, and whether the gesture is being recognized
+ * right now.
+ *
+ * Each hook extends this with the shared values its own intent produces —
+ * `drag.x`, `pinch.scale`, `rotate.angle`. The three members here are the
+ * part that is the same whatever the intent.
+ */
+export interface IntentResult<G extends GestureType> {
+  /** The configured gesture. Hand it to `<GestureDetector>`. */
+  readonly gesture: G
+  /**
+   * A handle on this gesture for another hook's `alongside` / `blocks` /
+   * `deferTo`.
+   *
+   * Prefer it over passing `other.gesture`: a gesture object is replaced when
+   * its dependencies change, and this ref is created once and read by RNGH at
+   * the moment it resolves relations, so a relation written against it keeps
+   * pointing at the live gesture.
+   *
+   * It is populated when `<GestureDetector>` mounts the gesture, not when the
+   * hook runs, so reading `.current` during the first render gives
+   * `undefined`.
+   */
+  readonly ref: RefObject<GestureType | undefined>
+  /**
+   * `true` while the gesture is active — for a tap, while the finger is down;
+   * for a drag, while it is being dragged.
+   *
+   * A shared value, so a pressed or grabbed state can be driven on the UI
+   * thread through `useAnimatedStyle` without a re-render. Reading `.value`
+   * during render works but tells you only what was true at the last commit.
+   */
+  readonly isActive: SharedValue<boolean>
+}