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

package/dist/{types-Ch2HM3aP.d.ts → types-ChGKY28a.d.ts}

@@ -138,5 +138,31 @@ interface IntentResult<G extends GestureType> {
      */
     readonly isActive: SharedValue<boolean>;
 }
+/**
+ * How a gesture ended, handed to every intent's end callback as its second
+ * argument.
+ *
+ * The end callbacks — `onTap`, `onDoubleTap`, `onLongPressEnd`, `onDragEnd` —
+ * fire on both paths: a gesture the user completed, and one the system took
+ * away. This says which. Without it, a cancel is reported only by
+ * `onFinalize`, which is a worklet, so a consumer holding phase in React
+ * state has to write `'worklet'` plus `scheduleOnRN` by hand.
+ *
+ * It is an object rather than a bare boolean so a later field — a reason for
+ * the cancel, say — does not break the signature a second time.
+ */
+interface IntentEndInfo {
+    /**
+     * `true` when the system took the gesture away instead of the user
+     * completing it: a competing gesture won, the app went to the background,
+     * or a relation handed the touch to another recognizer.
+     *
+     * A gesture that never activated at all does not reach an end callback on
+     * either path, so this is never `true` for a touch that was never the
+     * intent. It separates "this ended, but not by the user" from "the user
+     * did it".
+     */
+    readonly cancelled: boolean;
+}
 
-export type { AttachableGesture as A, CoexistenceOptions as C, GestureReference as G, HitSlop as H, IntentResult as I, Point as P, ComposeMode as a, GestureReferences as b };
+export type { AttachableGesture as A, CoexistenceOptions as C, GestureReference as G, HitSlop as H, IntentEndInfo as I, Point as P, ComposeMode as a, GestureReferences as b, IntentResult as c };

package/dist/{useGestureMemo-Ccv8rB0C.d.ts → useGestureMemo-BRW1EKcJ.d.ts}

@@ -1,6 +1,6 @@
 import { RefObject } from 'react';
 import { GestureType } from 'react-native-gesture-handler';
-import { C as CoexistenceOptions } from './types-Ch2HM3aP.js';
+import { C as CoexistenceOptions } from './types-ChGKY28a.js';
 
 /** What every hook built on this helper accepts on top of its own options. */
 interface GestureMemoOptions extends CoexistenceOptions {

package/jest-setup.cjs

@@ -32,7 +32,8 @@ require('react-native-gesture-handler/jestSetup')
 //
 // What this means for tests:
 //   ✅ assert a shared value's `.value` after driving a gesture
-//   ✅ assert that a JS-thread callback fired, because `runOnJS` is identity
+//   ✅ assert that a JS-thread callback fired, because `scheduleOnRN` calls
+//      it synchronously
 //   ❌ frame-level timing is not observable — nothing schedules or animates
 jest.mock('react-native-reanimated', () => {
   const React = require('react')
@@ -54,3 +55,33 @@ jest.mock('react-native-reanimated', () => {
     setGestureState: () => {},
   }
 })
+
+// Worklets mock. Impulse crosses to the JS thread with `scheduleOnRN` from
+// `react-native-worklets`, not with Reanimated's deprecated `runOnJS`, so the
+// mock above no longer covers that call — source importing from this package
+// would load the real module, which needs its native module and cannot run
+// under Jest.
+//
+// `scheduleOnRN` calls the function synchronously here. The real one schedules
+// it on the JS thread, so a test asserts that a callback ran, never when it
+// ran relative to a frame. That limit is the same one the Reanimated mock
+// already carried.
+//
+// Only what Impulse imports is mocked. `runOnJS` is included because the
+// undeprecated curried form lives in this package too, and a consumer's own
+// code may use it under this setup file.
+//
+// `isWorkletFunction` reports every function as a worklet. The real one reads
+// a hash that only the Worklets Babel plugin writes, and a Jest run without
+// the plugin would then flag every phase callback. Here nothing runs on a UI
+// thread, so a plain function is correct and the phase-callback warning must
+// stay silent.
+jest.mock('react-native-worklets', () => ({
+  __esModule: true,
+  scheduleOnRN: (fn, ...args) => fn(...args),
+  isWorkletFunction: (value) => typeof value === 'function',
+  runOnJS:
+    (fn) =>
+    (...args) =>
+      fn(...args),
+}))

package/llms.txt

@@ -0,0 +1,155 @@
+# @rootnative/impulse
+
+> Declarative gesture primitives for React Native, built on
+> react-native-gesture-handler. One hook per intent. Hooks return shared values
+> and a gesture; Impulse starts no animation and ships no components.
+
+Status: 0.0.0-alpha.1. Eight intents ship. A device sweep on an Android
+emulator and an iOS simulator drove every intent. It proves mechanics, not
+feel, so every default below is still a design intention.
+
+Docs: https://rootnative.github.io/impulse/
+Full: https://rootnative.github.io/impulse/llms-full.txt
+Source: https://github.com/rootnative/impulse
+
+## Install
+
+npm install @rootnative/impulse
+
+Peers: react, react-native, react-native-gesture-handler,
+react-native-reanimated, react-native-worklets. Render a
+<GestureHandlerRootView> above any component using a gesture — if it is
+missing, gestures never fire and nothing warns.
+
+## What ships
+
+useTap, useDoubleTap, useLongPress, useDrag, usePan, useSwipe, usePinch,
+useRotate — intent hooks. useGestures — composition. useRawGesture — the
+escape hatch. GestureDetector is re-exported from the package entry.
+
+NOT IMPLEMENTED, do not import: useHover, useEdgeSwipe.
+They are designed only.
+
+usePan and useDrag are not synonyms. useDrag owns a position: x and y
+accumulate across gestures and bounds clamps them. usePan owns nothing: it
+reports translation, velocity, and a per-frame change the consumer adds up,
+and it zeroes at every gesture.
+
+useSwipe is a pan judged at release. directions is also the activation
+criterion — an all-horizontal list gives a directional threshold, so the
+swipe shares a view with a vertical scroller with no relation declared.
+
+usePinch owns a scale that accumulates across gestures, so min and max are
+the viewer's zoom range, not one gesture's. focal is the midpoint between the
+fingers and the point the zoom must happen about — scaling about the view's
+centre slides the content out from under them. It has NO activation criteria:
+RNGH's pinch exposes no threshold, so a pinch and a pan are separated by a
+relation alone — useGestures([pinch, pan], { mode: 'simultaneous' }).
+
+useRotate reports DEGREES, not the radians RNGH reports. This is the one
+place Impulse changes a unit: min: -45, not -Math.PI / 4. It applies to
+angle, gestureAngle, velocity and the min/max range. The angle accumulates
+and does NOT wrap — a second full turn reports 720. anchor is the point the
+turn happens about, the counterpart of pinch's focal. It has NO activation
+criteria either, so rotate and pinch are composed simultaneous.
+
+Subpaths: @rootnative/impulse/{tap,double-tap,long-press,drag,pan,swipe,pinch,rotate,compose,raw,gesture-handler}
+
+## The shape of every hook
+
+const tap = useTap({ onTap: select })
+tap.gesture    // hand to <GestureDetector>
+tap.ref        // name it in another hook's alongside / blocks / deferTo
+tap.isActive   // SharedValue<boolean>
+
+useDrag adds x and y, both SharedValue<number>, both writable, both
+accumulating across gestures.
+
+## Threads — the callback name states the thread
+
+JS thread: onTap, onDoubleTap, onLongPress, onLongPressEnd, onDragStart,
+onDragEnd, onPanStart, onPanEnd, onSwipe, onSwipeEnd, onPinchStart,
+onPinchEnd, onRotateStart, onRotateEnd. Ordinary functions; Impulse owns the
+scheduleOnRN boundary.
+
+Every callback that reports an ending takes a second argument, { cancelled }:
+onTap, onDoubleTap, onLongPressEnd, onDragEnd, onPanEnd, onSwipeEnd,
+onPinchEnd, onRotateEnd. It fires on both endings. cancelled is true when the
+system took the gesture away — a competing gesture won, the app went to the
+background, or a relation handed the touch on. onSwipe fires for a commit
+only and takes no second argument.
+
+Worklets: onBegin, onUpdate, onFinalize. Mark with 'worklet'. A plain
+function there makes Impulse warn once in development, and the warning names
+the hook and the callback. Without the directive, the first touch that
+reaches the phase throws "Tried to synchronously call a Remote Function".
+Worklets are direct gesture dependencies, so keep their identity stable — an
+inline worklet rebuilds the gesture every render. An inline JS-thread
+callback does not.
+
+## Composition
+
+useGestures(members, { mode }) where mode is race | simultaneous | exclusive.
+A composed result is itself a member. Precedence reads left to right.
+
+A tap and a double tap are exclusive with the double tap FIRST, never race — a
+single tap recognizes on first release and would win every race. The composed
+single tap then pays maxDelay in latency.
+
+useGestures does not accept coexistence options. Put them on the members.
+
+## Coexistence
+
+alongside -> both recognize          (simultaneousWithExternalGesture)
+blocks    -> this gesture wins       (blocksExternalGesture)
+deferTo   -> the named gesture wins  (requireExternalGestureToFail)
+
+Name another hook's .ref, not its .gesture.
+
+TRAP: a relation target must carry a handlerTag. React Native's ScrollView has
+none, so the relation is SILENTLY dropped on every platform. Use
+gesture-handler's ScrollView / FlatList, from @rootnative/impulse/gesture-handler.
+
+TRAP: a component ref needs `as unknown as GestureReference`. RNGH types the
+target as a ref to a component type, which is not what ref={} produces.
+
+## Defaults
+
+useTap: pointers 1, maxDuration 500ms, maxDistance 10pt
+useDoubleTap: same, plus maxDelay 500ms (probably too generous; 250-300 is
+  closer to what platforms use)
+useLongPress: minDuration 500ms, maxDistance 10pt
+useDrag: axis both, threshold 10pt, elastic 0, unbounded
+usePan: axis both, threshold 10pt
+useSwipe: directions all four, threshold 10pt, commitDistance 80pt,
+  commitSpeed 800pt/s
+usePinch: initial 1, unbounded, no activation criteria
+useRotate: initial 0, unbounded, no activation criteria
+
+No default has a feel result. The device sweep proved that the drag
+threshold, commitDistance, and maxDelay at 500ms and 250ms work. commitSpeed
+is not tested, because neither harness can make a swipe that fast.
+
+## isActive does not mean the same thing in every hook
+
+useTap and useDoubleTap set it at touch-down. For useTap that is a real
+pressed state. For useDoubleTap it is true for every ordinary single tap on
+the view too, so do not drive a pressed state from it.
+useLongPress, useDrag, usePan, useSwipe, usePinch and useRotate set it at
+recognition.
+
+## Known gaps a consumer can hit
+
+- A cancel is reported, but its velocity is not a throw. The finger never
+  lifted on a cancelled gesture, so springing on velocity when cancelled is
+  true flings a view the user never released.
+- useLongPress maxDistance cancels an ACTIVE press on web, against RNGH's own
+  documented contract. Hold-then-drag does not work there at the default.
+- A missing <GestureHandlerRootView> fails silently and Impulse cannot warn.
+- Web is surveyed by hand; no jsdom test pins any of it.
+
+## Out of scope, by decision
+
+No components. No animation vocabulary, springs or easing. No haptics policy.
+useDrag returns values and no style — @rootnative/inertia-gestures has a
+useDrag that returns an animatedStyle and requires @rootnative/inertia.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rootnative/impulse",
-  "version": "0.0.0-alpha.0",
+  "version": "0.0.0-alpha.1",
   "description": "Declarative gesture primitives for React Native, built on react-native-gesture-handler.",
   "license": "MIT",
   "author": "RootNative",
-  "homepage": "https://github.com/rootnative/impulse",
+  "homepage": "https://rootnative.github.io/impulse/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rootnative/impulse.git",
@@ -21,6 +21,8 @@
     "drag",
     "pinch",
     "tap",
+    "double-tap",
+    "long-press",
     "expo",
     "declarative"
   ],
@@ -53,11 +55,41 @@
       "react-native": "./dist/tap/index.js",
       "default": "./dist/tap/index.js"
     },
+    "./double-tap": {
+      "types": "./dist/double-tap/index.d.ts",
+      "react-native": "./dist/double-tap/index.js",
+      "default": "./dist/double-tap/index.js"
+    },
+    "./long-press": {
+      "types": "./dist/long-press/index.d.ts",
+      "react-native": "./dist/long-press/index.js",
+      "default": "./dist/long-press/index.js"
+    },
     "./drag": {
       "types": "./dist/drag/index.d.ts",
       "react-native": "./dist/drag/index.js",
       "default": "./dist/drag/index.js"
     },
+    "./pan": {
+      "types": "./dist/pan/index.d.ts",
+      "react-native": "./dist/pan/index.js",
+      "default": "./dist/pan/index.js"
+    },
+    "./swipe": {
+      "types": "./dist/swipe/index.d.ts",
+      "react-native": "./dist/swipe/index.js",
+      "default": "./dist/swipe/index.js"
+    },
+    "./pinch": {
+      "types": "./dist/pinch/index.d.ts",
+      "react-native": "./dist/pinch/index.js",
+      "default": "./dist/pinch/index.js"
+    },
+    "./rotate": {
+      "types": "./dist/rotate/index.d.ts",
+      "react-native": "./dist/rotate/index.js",
+      "default": "./dist/rotate/index.js"
+    },
     "./gesture-handler": {
       "types": "./dist/gesture-handler/index.d.ts",
       "react-native": "./dist/gesture-handler/index.js",
@@ -71,6 +103,7 @@
     "src",
     "jest-preset.cjs",
     "jest-setup.cjs",
+    "llms.txt",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/src/index.ts

@@ -6,11 +6,12 @@
  * RNGH models and Impulse does not, and the `alongside` / `blocks` /
  * `deferTo` options both accept.
  *
- * `useTap` and `useDrag` are the two intent hooks, and the pattern the rest
- * follow: an intent-shaped payload, JS-thread callbacks named for what
+ * `useTap`, `useDoubleTap`, `useLongPress`, `useDrag`, `usePan`, `useSwipe`,
+ * `usePinch`, and `useRotate` are the intent hooks, and they share one
+ * pattern: an intent-shaped payload, JS-thread callbacks named for what
  * happened, worklet phase callbacks named for when, and documented activation
- * criteria. The remaining intents — `useSwipe`, `usePinch`, and the rest — are
- * designed but not implemented; see the repository README for the roadmap.
+ * criteria. The remaining intents — `useHover`, `useEdgeSwipe` — are designed
+ * but not implemented; see the repository README for the roadmap.
  */
 
 // Re-exported because every hook's result has to be handed to it, and
@@ -32,6 +33,19 @@ export type { RawGestureResult, UseRawGestureOptions } from './raw'
 export { useTap } from './intents/tap'
 export type { TapEvent, UseTapOptions, UseTapResult } from './intents/tap'
 
+export { useDoubleTap } from './intents/double-tap'
+export type {
+  UseDoubleTapOptions,
+  UseDoubleTapResult,
+} from './intents/double-tap'
+
+export { useLongPress } from './intents/long-press'
+export type {
+  LongPressEvent,
+  UseLongPressOptions,
+  UseLongPressResult,
+} from './intents/long-press'
+
 export { useDrag } from './intents/drag'
 export type {
   DragAxis,
@@ -41,6 +55,37 @@ export type {
   UseDragResult,
 } from './intents/drag'
 
+export { usePan } from './intents/pan'
+export type {
+  PanAxis,
+  PanEvent,
+  UsePanOptions,
+  UsePanResult,
+} from './intents/pan'
+
+export { useSwipe } from './intents/swipe'
+export type {
+  CommittedSwipeEvent,
+  SwipeDirection,
+  SwipeEvent,
+  UseSwipeOptions,
+  UseSwipeResult,
+} from './intents/swipe'
+
+export { usePinch } from './intents/pinch'
+export type {
+  PinchEvent,
+  UsePinchOptions,
+  UsePinchResult,
+} from './intents/pinch'
+
+export { useRotate } from './intents/rotate'
+export type {
+  RotateEvent,
+  UseRotateOptions,
+  UseRotateResult,
+} from './intents/rotate'
+
 export type {
   AttachableGesture,
   ComposeMode,
@@ -48,6 +93,7 @@ export type {
   GestureReference,
   GestureReferences,
   HitSlop,
+  IntentEndInfo,
   IntentResult,
   Point,
 } from './types'

package/src/intents/double-tap/index.ts

@@ -0,0 +1,6 @@
+export { useDoubleTap } from '../useDoubleTap'
+export type {
+  TapEvent,
+  UseDoubleTapOptions,
+  UseDoubleTapResult,
+} from '../useDoubleTap'

package/src/intents/long-press/index.ts

@@ -0,0 +1,6 @@
+export { useLongPress } from '../useLongPress'
+export type {
+  LongPressEvent,
+  UseLongPressOptions,
+  UseLongPressResult,
+} from '../useLongPress'

package/src/intents/pan/index.ts

@@ -0,0 +1,2 @@
+export { usePan } from '../usePan'
+export type { PanAxis, PanEvent, UsePanOptions, UsePanResult } from '../usePan'

package/src/intents/pinch/index.ts

@@ -0,0 +1,2 @@
+export { usePinch } from '../usePinch'
+export type { PinchEvent, UsePinchOptions, UsePinchResult } from '../usePinch'

package/src/intents/rotate/index.ts

@@ -0,0 +1,6 @@
+export { useRotate } from '../useRotate'
+export type {
+  RotateEvent,
+  UseRotateOptions,
+  UseRotateResult,
+} from '../useRotate'

package/src/intents/swipe/index.ts

@@ -0,0 +1,8 @@
+export { useSwipe } from '../useSwipe'
+export type {
+  CommittedSwipeEvent,
+  SwipeDirection,
+  SwipeEvent,
+  UseSwipeOptions,
+  UseSwipeResult,
+} from '../useSwipe'

package/src/intents/tapEvent.ts

@@ -0,0 +1,50 @@
+import {
+  type GestureStateChangeEvent,
+  type TapGestureHandlerEventPayload,
+} from 'react-native-gesture-handler'
+import { type Point } from '../types'
+
+/**
+ * The intent-shaped payload a tap callback receives.
+ *
+ * Shared by `useTap` and `useDoubleTap`, because the two recognize the same
+ * touch and differ only in how many times it happens. One payload rather than
+ * two identical ones means a consumer who already knows `useTap`'s event
+ * knows this one, and a field added later cannot reach one hook and miss the
+ * other.
+ */
+export 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
+}
+
+/**
+ * Shape RNGH's flat state-change event into the tap payload.
+ *
+ * A worklet, because every caller is one. Keeping the normalizer in one
+ * module means the call sites across both tap hooks cannot disagree about
+ * which RNGH field means what — which is the defect the intent payload exists
+ * to remove.
+ */
+export function toTapEvent(
+  event: GestureStateChangeEvent<TapGestureHandlerEventPayload>,
+): TapEvent {
+  'worklet'
+  return {
+    x: event.x,
+    y: event.y,
+    absolute: { x: event.absoluteX, y: event.absoluteY },
+    pointers: event.numberOfPointers,
+  }
+}