@rootnative/impulse 0.0.0-alpha.0

package/dist/chunk-ZX7WNICB.js

@@ -0,0 +1,39 @@
+import { useRef } from 'react';
+
+// src/internal/warnOnce.ts
+var warned = /* @__PURE__ */ new Set();
+function isDevBuild() {
+  return typeof __DEV__ !== "undefined" && __DEV__;
+}
+function warnOnce(key, message) {
+  if (!isDevBuild() || warned.has(key)) {
+    return;
+  }
+  warned.add(key);
+  console.warn(`[impulse] ${message}`);
+}
+var EMPTY = [];
+function sameContents(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let index = 0; index < a.length; index += 1) {
+    if (!Object.is(a[index], b[index])) {
+      return false;
+    }
+  }
+  return true;
+}
+function useStableList(value) {
+  const next = value === void 0 ? EMPTY : Array.isArray(value) ? value : [value];
+  const held = useRef(EMPTY);
+  if (!sameContents(held.current, next)) {
+    held.current = next;
+  }
+  return held.current;
+}
+
+export { isDevBuild, useStableList, warnOnce };

package/dist/compose/index.d.ts

@@ -0,0 +1,80 @@
+import { ComposedGesture } from 'react-native-gesture-handler';
+import { A as AttachableGesture, a as ComposeMode } from '../types-Ch2HM3aP.js';
+import 'react';
+import 'react-native-reanimated';
+
+/**
+ * Anything carrying a gesture — every Impulse hook result, including the one
+ * `useGestures` itself returns.
+ */
+interface GestureCarrier {
+    readonly gesture: AttachableGesture;
+}
+/**
+ * A member of a composition: a hook result, or a bare gesture from
+ * `@rootnative/impulse/gesture-handler`.
+ */
+type GestureMember = GestureCarrier | AttachableGesture;
+/** What `useGestures` returns. It is itself a valid composition member. */
+interface GesturesResult {
+    /** The composed gesture. Hand it to `<GestureDetector>`. */
+    readonly gesture: ComposedGesture;
+}
+/** Options for {@link useGestures}. */
+interface UseGesturesOptions {
+    /** How the members relate to one another. */
+    mode: ComposeMode;
+}
+/**
+ * Compose gestures under one relation.
+ *
+ * ```tsx
+ * // tap and double-tap race; the winner runs alongside the drag
+ * const { gesture } = useGestures(
+ *   [useGestures([tap, double], { mode: 'race' }), drag],
+ *   { mode: 'simultaneous' },
+ * )
+ *
+ * return (
+ *   <GestureDetector gesture={gesture}>
+ *     <View />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * Composition is **data, not nesting**. RNGH expresses the same thing as
+ * `Gesture.Simultaneous(Gesture.Race(tap, doubleTap), drag)`, which has to be
+ * read backwards to learn what wins and gains a level of nesting per
+ * relation. Here each call is one flat list plus the relation that holds over
+ * it, and the result is itself a member, so precedence reads left to right
+ * and depth is a choice rather than a consequence.
+ *
+ * The modes:
+ *
+ * - `race` — the first member to activate wins and cancels the rest. This is
+ *   what you want for mutually exclusive readings of one touch.
+ * - `simultaneous` — every member recognizes independently. A pinch and a
+ *   rotate on one image.
+ * - `exclusive` — members are tried in order, and a later one activates only
+ *   after every earlier one has failed. A tap and a double-tap, where the tap
+ *   must wait to learn whether a second one is coming.
+ *
+ * **Coexistence options are not accepted here, and that is a limitation
+ * rather than a choice.** RNGH's three external-gesture relations are methods
+ * on a single gesture; a composed gesture does not have them. Put
+ * `alongside` / `blocks` / `deferTo` on the member hooks instead — Impulse
+ * cannot apply them for you without mutating gestures another hook owns and
+ * memoised.
+ *
+ * **Accessibility.** A composition is as reachable as its members, which is
+ * to say a screen reader and a keyboard see none of it. Each member hook
+ * documents its own fallback; a composition needs the union of them.
+ *
+ * @param members - The gestures to compose, in precedence order. The order
+ *   matters for `exclusive` and is ignored by the other two modes.
+ * @param options - The relation to compose under.
+ * @returns The composed gesture, stable while the members and the mode are.
+ */
+declare function useGestures(members: readonly GestureMember[], options: UseGesturesOptions): GesturesResult;
+
+export { type GestureCarrier, type GestureMember, type GesturesResult, type UseGesturesOptions, useGestures };

package/dist/compose/index.js

@@ -0,0 +1,2 @@
+export { useGestures } from '../chunk-LM645QQT.js';
+import '../chunk-ZX7WNICB.js';

package/dist/drag/index.d.ts

@@ -0,0 +1,277 @@
+import { PanGesture } from 'react-native-gesture-handler';
+import { SharedValue } from 'react-native-reanimated';
+import { G as GestureMemoOptions } from '../useGestureMemo-Ccv8rB0C.js';
+import { P as Point, H as HitSlop, I as IntentResult } from '../types-Ch2HM3aP.js';
+import 'react';
+
+/** Which way the drag is allowed to move. */
+type DragAxis = 'x' | 'y' | 'both';
+/**
+ * How far the drag may travel, in the same coordinates as `x` and `y`.
+ *
+ * Every edge is optional, and an omitted edge is unbounded. The names are the
+ * edges of the travel, not of the view: `left` is the smallest `x`, `bottom`
+ * is the largest `y`.
+ */
+interface DragBounds {
+    /** Smallest `x`. */
+    left?: number;
+    /** Largest `x`. */
+    right?: number;
+    /** Smallest `y`. */
+    top?: number;
+    /** Largest `y`. */
+    bottom?: number;
+}
+/** The intent-shaped payload a {@link useDrag} callback receives. */
+interface DragEvent {
+    /**
+     * Where the drag is now — the same numbers as `x` and `y`, after `bounds`
+     * and `elastic` were applied.
+     *
+     * This accumulates across gestures. A second drag continues from where the
+     * first one stopped, which is why `bounds` can be written against a layout
+     * rather than against one gesture's travel.
+     */
+    readonly position: Point;
+    /**
+     * How far the finger moved since this gesture activated, raw.
+     *
+     * Untouched by `bounds` and `elastic`, and reset to zero at the start of
+     * every gesture. Read `position` for where the thing being dragged actually
+     * sits.
+     */
+    readonly translation: Point;
+    /** Finger speed, in points per second. The input a release spring needs. */
+    readonly velocity: Point;
+    /** The touch point relative to the window. */
+    readonly absolute: Point;
+    /**
+     * The nearest point inside `bounds`. Equal to `position` whenever the drag
+     * is in bounds, which with the default `elastic` of `0` is always.
+     *
+     * With `elastic` set, the finger can pull the value past an edge and
+     * Impulse leaves it there on release — moving it back is an animation, and
+     * Impulse owns no animation vocabulary. This field is the destination that
+     * animation needs, so the consumer does not have to re-derive the clamp
+     * from bounds it already handed over.
+     */
+    readonly settled: Point;
+    /** How many fingers are down. */
+    readonly pointers: number;
+}
+/** Options for {@link useDrag}. */
+interface UseDragOptions extends GestureMemoOptions {
+    /**
+     * Which way the drag may move. Default `'both'`.
+     *
+     * The locked axis's shared value never changes — `axis: 'x'` leaves `y` at
+     * its initial value for the life of the hook. The axis also decides the
+     * activation criterion, which is the part that matters inside a scroll
+     * view: see `threshold`.
+     */
+    axis?: DragAxis;
+    /**
+     * How far the finger must travel before the drag activates, in points.
+     * Default `10`.
+     *
+     * On a single axis this is a directional threshold, so a drag with
+     * `axis: 'x'` ignores vertical movement entirely and a vertical scroll view
+     * under it keeps working. On `'both'` it is a radial distance.
+     *
+     * Lower it for a drag that must feel immediate and owns its view. Raise it
+     * when the drag shares the view with something that should usually win.
+     */
+    threshold?: number;
+    /**
+     * Movement across the axis that makes the drag fail, in points. Unset by
+     * default, which leaves RNGH's own behaviour in place.
+     *
+     * `threshold` decides when the drag wins; this decides when it gives up.
+     * Set it when the cross-axis gesture must win a diagonal — a horizontal
+     * row action inside a vertical list, where a mostly-vertical drag should
+     * scroll rather than half-open the row. Ignored when `axis` is `'both'`,
+     * which has no cross axis.
+     */
+    failOffset?: number;
+    /**
+     * How far the drag may travel. Unbounded by default.
+     *
+     * Written inline as an object is fine — the gesture is not rebuilt when the
+     * contents are unchanged.
+     */
+    bounds?: DragBounds;
+    /**
+     * How much of the finger's movement survives past a bound, `0` to `1`.
+     * Default `0`.
+     *
+     * `0` clamps hard at the edge. `1` ignores the bound while the finger is
+     * down. `0.3` or so gives the rubber-band pull an over-scroll has.
+     *
+     * **Impulse does not put the value back on release.** That is an animation,
+     * and Principle 5 keeps animation out of this library. `onDragEnd` carries
+     * `settled` — the point to animate to — and `@rootnative/inertia` or a
+     * plain `withSpring` does the moving.
+     */
+    elastic?: number;
+    /**
+     * Where `x` and `y` start. Default `{ x: 0, y: 0 }`.
+     *
+     * Read once, when the hook mounts. Changing it later does nothing, because
+     * the shared values are the drag's state from then on — write
+     * `drag.x.value` to move it instead.
+     */
+    initial?: Point;
+    /**
+     * How many fingers must be on the view. Unset by default, which leaves
+     * RNGH's range of one to ten in place.
+     *
+     * Setting it fixes the count exactly, so `pointers: 2` is a two-finger drag
+     * that neither starts with one finger nor survives a third.
+     */
+    pointers?: 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 drag passed `threshold` and now owns the touch. **Runs on the JS
+     * thread** — Impulse owns the `runOnJS` boundary, so this is an ordinary
+     * function and may touch React state.
+     *
+     * This is the first moment the drag has definitely won. `onBegin` fires
+     * earlier and promises nothing.
+     */
+    onDragStart?: (event: DragEvent) => void;
+    /**
+     * The finger lifted and 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.
+     *
+     * Read `velocity` to seed that release animation, and `settled` for where
+     * an elastic overshoot should return to.
+     */
+    onDragEnd?: (event: DragEvent) => 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
+     * React state from it.
+     *
+     * Being a candidate is not the same as winning: the drag has not passed
+     * `threshold` yet and may never. Use it to show a grabbed state, and undo
+     * that state in `onFinalize`.
+     */
+    onBegin?: (event: DragEvent) => void;
+    /**
+     * 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
+     * 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.
+     */
+    onUpdate?: (event: DragEvent) => void;
+    /**
+     * The gesture is over, whether it activated or not. **This is a worklet.**
+     *
+     * `success` is `true` when the drag activated and ended normally. This is
+     * the right place to clear anything `onBegin` set, because it runs on both
+     * paths.
+     */
+    onFinalize?: (event: DragEvent, success: boolean) => void;
+}
+/** What {@link useDrag} returns. */
+interface UseDragResult extends IntentResult<PanGesture> {
+    /**
+     * Where the drag is along the x axis, after `bounds` and `elastic`.
+     *
+     * Writable: assigning `drag.x.value` moves the drag, and the next gesture
+     * continues from the new number rather than snapping back. That is how a
+     * release animation hands control back — animate this value, and the drag
+     * picks up wherever the animation left it.
+     *
+     * Frozen at its initial value when `axis` is `'y'`.
+     */
+    readonly x: SharedValue<number>;
+    /**
+     * Where the drag is along the y axis, after `bounds` and `elastic`.
+     *
+     * Writable, on the same terms as `x`. Frozen at its initial value when
+     * `axis` is `'x'`.
+     */
+    readonly y: SharedValue<number>;
+}
+/**
+ * Recognize a drag, and stream where it is.
+ *
+ * ```tsx
+ * const drag = useDrag({ axis: 'x', bounds: { left: -120, right: 0 } })
+ * const style = useAnimatedStyle(() => ({
+ *   transform: [{ translateX: drag.x.value }],
+ * }))
+ *
+ * return (
+ *   <GestureDetector gesture={drag.gesture}>
+ *     <Animated.View style={style} />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * `x` and `y` are shared values, so the view follows the finger on the UI
+ * thread with no re-render. They accumulate across gestures: a second drag
+ * continues from where the first stopped.
+ *
+ * **No style, and no animation.** This hook returns numbers and stops there.
+ * Building the `transform` is the consumer's call, and so is any spring back.
+ * `@rootnative/inertia-gestures` has a `useDrag` that does both, and needs
+ * `@rootnative/inertia` to do it — reach for that one when a `Motion.View`
+ * should follow a finger and spring home, and for this one when the values
+ * are what you want.
+ *
+ * **Activation criteria.** `threshold` defaults to 10 points. With
+ * `axis: 'x'` or `'y'` it is directional, so a horizontal drag inside a
+ * 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.
+ *
+ * **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
+ * the touch belongs to as well — `deferTo: scrollRef` for a drag that is the
+ * fallback, `blocks: listRef` for one that is the foreground affordance.
+ *
+ * **Web.** RNGH recognizes pan from pointer events, so a mouse drag behaves
+ * the same as a touch drag and `velocity` is reported in the same units. A
+ * trackpad's momentum scroll is not a pan and never reaches this hook.
+ * `pointers` above 1 is unreliable on web.
+ *
+ * **Accessibility.** A drag is invisible to a screen reader and unreachable
+ * from a keyboard, and this hook does not fix that. Whatever the drag
+ * adjusts must be reachable another way: a pair of buttons for a slider, a
+ * visible action for a swipeable row, or `accessibilityActions` with
+ * `onAccessibilityAction` — `increment` and `decrement` for a value,
+ * `magicTap` or a named action for a dismissal. A drag-only affordance is a
+ * bug, not a trade-off.
+ *
+ * @param options - Activation criteria, bounds, callbacks, and the
+ *   `alongside` / `blocks` / `deferTo` coexistence options every Impulse hook
+ *   accepts.
+ */
+declare function useDrag(options?: UseDragOptions): UseDragResult;
+
+export { type DragAxis, type DragBounds, type DragEvent, type UseDragOptions, type UseDragResult, useDrag };

package/dist/drag/index.js

@@ -0,0 +1,4 @@
+export { useDrag } from '../chunk-FR242SUF.js';
+import '../chunk-5BMRKYVY.js';
+import '../chunk-F4RHM4ZK.js';
+import '../chunk-ZX7WNICB.js';

package/dist/gesture-handler/index.d.ts

@@ -0,0 +1 @@
+export * from 'react-native-gesture-handler';

package/dist/gesture-handler/index.js

@@ -0,0 +1 @@
+export * from 'react-native-gesture-handler';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { GestureDetector } from 'react-native-gesture-handler';
+export { GestureCarrier, GestureMember, GesturesResult, UseGesturesOptions, useGestures } from './compose/index.js';
+export { RawGestureResult, UseRawGestureOptions, useRawGesture } from './raw/index.js';
+export { TapEvent, UseTapOptions, UseTapResult, useTap } from './tap/index.js';
+export { DragAxis, DragBounds, DragEvent, UseDragOptions, UseDragResult, useDrag } from './drag/index.js';
+export { A as AttachableGesture, C as CoexistenceOptions, a as ComposeMode, G as GestureReference, b as GestureReferences, H as HitSlop, I as IntentResult, P as Point } from './types-Ch2HM3aP.js';
+import 'react';
+import './useGestureMemo-Ccv8rB0C.js';
+import 'react-native-reanimated';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { useGestures } from './chunk-LM645QQT.js';
+export { useRawGesture } from './chunk-PMR25UCT.js';
+export { useTap } from './chunk-IG5RXCYR.js';
+export { useDrag } from './chunk-FR242SUF.js';
+import './chunk-5BMRKYVY.js';
+import './chunk-F4RHM4ZK.js';
+import './chunk-ZX7WNICB.js';
+export { GestureDetector } from 'react-native-gesture-handler';

package/dist/raw/index.d.ts

@@ -0,0 +1,63 @@
+import { DependencyList } from 'react';
+import { GestureType } from 'react-native-gesture-handler';
+import { B as BuiltGesture, G as GestureMemoOptions } from '../useGestureMemo-Ccv8rB0C.js';
+import '../types-Ch2HM3aP.js';
+import 'react-native-reanimated';
+
+/** Options for {@link useRawGesture}. */
+type UseRawGestureOptions = GestureMemoOptions;
+/** What {@link useRawGesture} returns. */
+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`.
+ */
+declare function useRawGesture<G extends GestureType>(build: () => G, deps: DependencyList, options?: UseRawGestureOptions): RawGestureResult<G>;
+
+export { type RawGestureResult, type UseRawGestureOptions, useRawGesture };

package/dist/raw/index.js

@@ -0,0 +1,3 @@
+export { useRawGesture } from '../chunk-PMR25UCT.js';
+import '../chunk-F4RHM4ZK.js';
+import '../chunk-ZX7WNICB.js';

package/dist/tap/index.d.ts

@@ -0,0 +1,150 @@
+import { TapGesture } from 'react-native-gesture-handler';
+import { G as GestureMemoOptions } from '../useGestureMemo-Ccv8rB0C.js';
+import { P as Point, H as HitSlop, I as IntentResult } from '../types-Ch2HM3aP.js';
+import 'react';
+import 'react-native-reanimated';
+
+/** The intent-shaped payload a {@link useTap} callback receives. */
+interface TapEvent {
+    /** X of the tap, in points, relative to the view the gesture is attached to. */
+    readonly x: number;
+    /** Y of the tap, in points, relative to the view the gesture is attached to. */
+    readonly y: number;
+    /**
+     * The same point relative to the window.
+     *
+     * Prefer it over `x` / `y` when the view itself is being transformed by the
+     * gesture — a tap on a view that is mid-animation reports a moving `x`.
+     */
+    readonly absolute: Point;
+    /** How many fingers were down when the tap was recognized. */
+    readonly pointers: number;
+}
+/** Options for {@link useTap}. */
+interface UseTapOptions extends GestureMemoOptions {
+    /**
+     * How many fingers must be down. Default `1`.
+     *
+     * A two-finger tap is a common "undo" or "zoom out" affordance, and it is
+     * the same intent with a different pointer count rather than a separate
+     * one.
+     */
+    pointers?: number;
+    /**
+     * How long the finger may stay down, in milliseconds. Default `500`.
+     *
+     * Past this the gesture fails rather than firing, which is what leaves the
+     * touch available to a `useLongPress` racing against it.
+     */
+    maxDuration?: number;
+    /**
+     * How far the finger may travel, in points. Default `10`.
+     *
+     * Raising it makes the tap more forgiving and makes it harder for a drag in
+     * the same view to win the touch.
+     */
+    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 tap happened. **Runs on the JS thread** — Impulse owns the
+     * `runOnJS` boundary, so this is an ordinary function and may touch React
+     * state.
+     *
+     * It fires only for a successful tap. A touch that moved too far or stayed
+     * down too long reaches `onFinalize` with `success: false` instead.
+     */
+    onTap?: (event: TapEvent) => 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
+     * React state from it.
+     *
+     * Being a candidate is not the same as winning: in a race with a
+     * long press or a drag, this fires and the gesture may still fail. Use it
+     * to show a pressed state, and undo that state in `onFinalize`.
+     */
+    onBegin?: (event: TapEvent) => void;
+    /**
+     * The gesture is over, whether it was recognized or not. **This is a
+     * worklet.**
+     *
+     * `success` is `true` when the 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 useTap} returns.
+ *
+ * An alias rather than an extending interface, because a tap produces no
+ * continuous value of its own: the gesture, the ref, and `isActive` are the
+ * whole result. An intent that does produce one — a drag's `x`, a pinch's
+ * `scale` — extends {@link IntentResult} instead.
+ */
+type UseTapResult = IntentResult<TapGesture>;
+/**
+ * Recognize a single tap.
+ *
+ * ```tsx
+ * const tap = useTap({ onTap: () => select(item.id) })
+ *
+ * return (
+ *   <GestureDetector gesture={tap.gesture}>
+ *     <View />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * `onTap` 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 `runOnJS` to write.
+ *
+ * `isActive` is a shared value that is `true` while the finger is down. Drive
+ * a pressed state from it without a re-render:
+ *
+ * ```tsx
+ * const tap = useTap({ onTap: select })
+ * const style = useAnimatedStyle(() => ({ opacity: tap.isActive.value ? 0.6 : 1 }))
+ * ```
+ *
+ * **Activation criteria.** `maxDuration` defaults to 500ms and `maxDistance`
+ * to 10 points. The distance default is Impulse's, not RNGH's: RNGH defers to
+ * the platform there, so the same tap is accepted on one operating system and
+ * rejected on the other. Neither default has been measured on hardware yet.
+ *
+ * **Racing a double tap.** A single tap and a double tap on one view is a
+ * composition, not an option — `useGestures([tap, double], { mode: 'race' })`.
+ * Do not reach for `maxDelay` to build it by hand.
+ *
+ * **Web.** RNGH's web implementation recognizes tap from pointer events, and
+ * `pointers` above 1 is unreliable there because a mouse reports one pointer
+ * and touch emulation varies by browser. A single-finger tap behaves the same
+ * as on native.
+ *
+ * **Accessibility.** A tap gesture is invisible to a screen reader and
+ * unreachable from a keyboard. This hook does not fix that, and it cannot.
+ * Whatever the tap does must also be reachable another way: put the same
+ * action on a `<Pressable>`, or declare it with `accessibilityActions` and
+ * `onAccessibilityAction` on the view the gesture is attached to. A 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.
+ */
+declare function useTap(options?: UseTapOptions): UseTapResult;
+
+export { type TapEvent, type UseTapOptions, type UseTapResult, useTap };

package/dist/tap/index.js

@@ -0,0 +1,4 @@
+export { useTap } from '../chunk-IG5RXCYR.js';
+import '../chunk-5BMRKYVY.js';
+import '../chunk-F4RHM4ZK.js';
+import '../chunk-ZX7WNICB.js';