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

package/dist/long-press/index.js

@@ -0,0 +1,4 @@
+export { useLongPress } from '../chunk-HI5PHDJY.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
+import '../chunk-ZX7WNICB.js';

package/dist/pan/index.d.ts

@@ -0,0 +1,221 @@
+import { PanGesture } from 'react-native-gesture-handler';
+import { SharedValue } from 'react-native-reanimated';
+import { G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import { P as Point, H as HitSlop, I as IntentEndInfo, c as IntentResult } from '../types-ChGKY28a.js';
+import 'react';
+
+/** Which way the pan is allowed to move. */
+type PanAxis = 'x' | 'y' | 'both';
+/** The intent-shaped payload a {@link usePan} callback receives. */
+interface PanEvent {
+    /**
+     * How far the finger has moved since the pan activated.
+     *
+     * Measured from the activation point, not from touch-down, so it does not
+     * include the `threshold` travel the finger spent before the pan existed.
+     * It resets to zero at the start of every gesture — a pan reports movement
+     * and owns no position.
+     */
+    readonly translation: Point;
+    /**
+     * How far the finger moved since the previous frame.
+     *
+     * The field `useDrag` cannot give, and the reason to reach for this hook:
+     * a value the consumer owns is advanced by adding this, rather than by
+     * re-deriving it from a translation Impulse already clamped.
+     *
+     * Zero outside `onUpdate`. The first frame after activation reports the
+     * movement since activation, so a value advanced by `change` never jumps
+     * by `threshold`.
+     */
+    readonly change: Point;
+    /** Finger speed, in points per second. */
+    readonly velocity: Point;
+    /** The touch point relative to the window. */
+    readonly absolute: Point;
+    /** How many fingers are down. */
+    readonly pointers: number;
+}
+/** Options for {@link usePan}. */
+interface UsePanOptions extends GestureMemoOptions {
+    /**
+     * Which way the pan may move. Default `'both'`.
+     *
+     * The locked axis reports zero for the life of the hook — `axis: 'x'`
+     * leaves `y`, `translation.y`, and `change.y` at zero. The axis also
+     * decides the activation criterion, which is the part that matters inside
+     * a scroll view: see `threshold`.
+     */
+    axis?: PanAxis;
+    /**
+     * How far the finger must travel before the pan activates, in points.
+     * Default `10`.
+     *
+     * On a single axis this is a directional threshold, so a pan with
+     * `axis: 'x'` ignores vertical movement entirely and a vertical scroll view
+     * under it keeps working. On `'both'` it is a radial distance.
+     */
+    threshold?: number;
+    /**
+     * Movement across the axis that makes the pan fail, in points. Unset by
+     * default, which leaves RNGH's own behaviour in place.
+     *
+     * `threshold` decides when the pan wins; this decides when it gives up.
+     * Ignored when `axis` is `'both'`, which has no cross axis.
+     */
+    failOffset?: number;
+    /**
+     * 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 pan
+     * 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 pan passed `threshold` and now owns the touch. **Runs on the JS
+     * thread** — Impulse owns the `scheduleOnRN` boundary, so this is an
+     * ordinary function and may touch React state.
+     *
+     * This is the first moment the pan has definitely won. `onBegin` fires
+     * earlier and promises nothing.
+     */
+    onPanStart?: (event: PanEvent) => void;
+    /**
+     * The pan is over. **Runs on the JS thread.**
+     *
+     * Fires only for a pan that activated, so a touch that never passed the
+     * threshold never reaches here on either path.
+     *
+     * It fires for both endings, and `cancelled` says which. `false` is the
+     * finger lifting, and `velocity` then describes the release. `true` is the
+     * system taking the pan 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.**
+     */
+    onPanEnd?: (event: PanEvent, 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
+     * React state from it.
+     *
+     * Being a candidate is not the same as winning: the pan has not passed
+     * `threshold` yet and may never. Undo whatever it sets in `onFinalize`.
+     */
+    onBegin?: (event: PanEvent) => void;
+    /**
+     * The pan moved. **This is a worklet**, and it runs on every frame the
+     * finger moves.
+     *
+     * This is where `change` is read, and it is the reason the hook exists:
+     * advance the value the consumer owns from here, on the thread that already
+     * holds it.
+     *
+     * 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.
+     */
+    onUpdate?: (event: PanEvent) => void;
+    /**
+     * The gesture is over, whether it activated or not. **This is a worklet.**
+     *
+     * `success` is `true` when the pan activated and ended normally. This is
+     * the right place to clear anything `onBegin` set, because it runs on both
+     * paths.
+     */
+    onFinalize?: (event: PanEvent, success: boolean) => void;
+}
+/** What {@link usePan} returns. */
+interface UsePanResult extends IntentResult<PanGesture> {
+    /**
+     * How far the finger has moved along the x axis since the pan activated.
+     *
+     * **This is movement, not a position.** It is set to zero at the start of
+     * every gesture, so a second pan does not continue from where the first
+     * stopped. `useDrag` is the hook whose value accumulates.
+     *
+     * It keeps its final number after the gesture ends, so a release animation
+     * has something to animate from.
+     *
+     * Frozen at zero when `axis` is `'y'`.
+     */
+    readonly x: SharedValue<number>;
+    /**
+     * How far the finger has moved along the y axis since the pan activated.
+     * Same terms as `x`. Frozen at zero when `axis` is `'x'`.
+     */
+    readonly y: SharedValue<number>;
+}
+/**
+ * Recognize a pan, and report how the finger moved.
+ *
+ * ```tsx
+ * const camera = { x: useSharedValue(0), y: useSharedValue(0) }
+ * const pan = usePan({
+ *   onUpdate: (event) => {
+ *     'worklet'
+ *     camera.x.value += event.change.x
+ *     camera.y.value += event.change.y
+ *   },
+ * })
+ *
+ * return (
+ *   <GestureDetector gesture={pan.gesture}>
+ *     <Animated.View style={style} />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * **`usePan` reports movement; `useDrag` owns a position.** That is the whole
+ * difference, and it decides which one a screen wants. `useDrag` holds `x`
+ * and `y` as the place a thing sits: they accumulate across gestures, they
+ * are clamped by `bounds`, and `elastic` bends them. `usePan` holds no
+ * position at all — it hands over `translation`, `velocity`, and a per-frame
+ * `change`, and the consumer advances whatever it drives. Reach for `useDrag`
+ * to move a view. Reach for this one to pan a camera, scrub a value, or feed
+ * a number Impulse has no business clamping.
+ *
+ * **Activation criteria.** `threshold` defaults to 10 points. With
+ * `axis: 'x'` or `'y'` it is directional, so a horizontal pan inside a
+ * vertical `ScrollView` leaves the scroll alone until the finger commits
+ * sideways; with `'both'` it is a radial distance. The device sweep did not
+ * test the default.
+ *
+ * **Coexistence.** A threshold decides who moves first; it does not decide
+ * who wins a contested touch. Say which gesture the touch belongs to as well
+ * — `deferTo` for a pan that is the fallback, `blocks` for one that is the
+ * foreground affordance, `alongside` for a pan that shares the touch with a
+ * pinch.
+ *
+ * **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 pan is invisible to a screen reader and unreachable
+ * from a keyboard, and this hook does not fix that. Whatever the pan moves
+ * must be reachable another way: buttons that step the value, a reset
+ * control for a panned canvas, or `accessibilityActions` with
+ * `onAccessibilityAction`. A pan-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 usePan(options?: UsePanOptions): UsePanResult;
+
+export { type PanAxis, type PanEvent, type UsePanOptions, type UsePanResult, usePan };

package/dist/pan/index.js

@@ -0,0 +1,4 @@
+export { usePan } from '../chunk-PGOQSKEJ.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
+import '../chunk-ZX7WNICB.js';

package/dist/pinch/index.d.ts

@@ -0,0 +1,239 @@
+import { PinchGesture } from 'react-native-gesture-handler';
+import { SharedValue } from 'react-native-reanimated';
+import { G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import { P as Point, H as HitSlop, I as IntentEndInfo, c as IntentResult } from '../types-ChGKY28a.js';
+import 'react';
+
+/** The intent-shaped payload a {@link usePinch} callback receives. */
+interface PinchEvent {
+    /**
+     * How much the thing is scaled now — the same number as `scale`, after
+     * `min`, `max` and `elastic` were applied.
+     *
+     * This accumulates across gestures. A second pinch continues from where the
+     * first one stopped, which is why `min` and `max` can be written as the
+     * zoom range of the whole viewer rather than of one gesture.
+     */
+    readonly scale: number;
+    /**
+     * How much the fingers scaled during **this gesture alone**, raw.
+     *
+     * Untouched by `min`, `max` and `elastic`, and reset to `1` at the start of
+     * every gesture. This is RNGH's own `scale`. Read `scale` for how big the
+     * thing being pinched actually is.
+     */
+    readonly gestureScale: number;
+    /**
+     * The midpoint between the fingers, relative to the view.
+     *
+     * This is the point the zoom must happen about. A pinch scaled about the
+     * view's centre instead slides the content out from under the fingers, and
+     * that is the defect this field exists to prevent.
+     */
+    readonly focal: Point;
+    /** How fast the scale is changing, in scale units per second. */
+    readonly velocity: number;
+    /**
+     * The nearest scale inside `min` and `max`. Equal to `scale` whenever the
+     * pinch is in range, which with the default `elastic` of `0` is always.
+     *
+     * With `elastic` set, the fingers can pull the scale past an end 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 a range it already handed over.
+     */
+    readonly settled: number;
+    /** How many fingers are down. */
+    readonly pointers: number;
+}
+/** Options for {@link usePinch}. */
+interface UsePinchOptions extends GestureMemoOptions {
+    /**
+     * The scale before any pinch. Default `1`.
+     *
+     * Read once, at mount. `useSharedValue` keeps its first argument and
+     * ignores every later one, and that is the behaviour this option
+     * documents: after mount `scale` is the pinch's state, and the consumer
+     * moves it by writing it.
+     */
+    initial?: number;
+    /**
+     * The smallest scale. Unset by default, which lets the fingers shrink the
+     * thing without limit.
+     *
+     * Set it to `1` for a viewer that may zoom in but never out.
+     */
+    min?: number;
+    /**
+     * The largest scale. Unset by default, which lets the fingers grow the
+     * thing without limit.
+     */
+    max?: number;
+    /**
+     * How much of the travel past `min` or `max` reaches `scale`, from `0` to
+     * `1`. Default `0`.
+     *
+     * `0` stops dead at the end. `1` ignores the end while the fingers are
+     * down. Anything between is resistance — the pinch keeps moving and moves
+     * less than the fingers do.
+     *
+     * Impulse does not bring the scale back. The end callback carries
+     * `settled` — the scale to animate to — and `@rootnative/inertia` or a
+     * `withSpring` of your own does the rest.
+     */
+    elastic?: 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 pinch now owns the touch. **Runs on the JS thread** — Impulse owns
+     * the `scheduleOnRN` boundary, so this is an ordinary function and may
+     * touch React state.
+     *
+     * This is the first moment the pinch has definitely won. `onBegin` fires
+     * earlier and promises nothing.
+     */
+    onPinchStart?: (event: PinchEvent) => void;
+    /**
+     * The pinch is over. **Runs on the JS thread.**
+     *
+     * Fires only for a pinch that activated, so a touch that never became a
+     * pinch never reaches here on either path.
+     *
+     * It fires for both endings, and `cancelled` says which. `false` is the
+     * fingers lifting, and `velocity` then describes the release. `true` is the
+     * system taking the pinch 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.**
+     *
+     * Read `settled` on both paths for where an elastic overshoot belongs.
+     */
+    onPinchEnd?: (event: PinchEvent, info: IntentEndInfo) => void;
+    /**
+     * A 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: one finger is not a pinch,
+     * and a second one may never arrive. Undo whatever it sets in
+     * `onFinalize`.
+     */
+    onBegin?: (event: PinchEvent) => void;
+    /**
+     * The scale changed. **This is a worklet**, and it runs on every frame the
+     * fingers move.
+     *
+     * `scale` is already written by the time this runs, so a `useAnimatedStyle`
+     * reading it needs nothing from here. Use this for the work that scaling
+     * alone does not do — holding the focal point still, say.
+     *
+     * 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.
+     */
+    onUpdate?: (event: PinchEvent) => void;
+    /**
+     * The gesture is over, whether it activated or not. **This is a worklet.**
+     *
+     * `success` is `true` when the pinch activated and ended normally. This is
+     * the right place to clear anything `onBegin` set, because it runs on both
+     * paths.
+     */
+    onFinalize?: (event: PinchEvent, success: boolean) => void;
+}
+/** What {@link usePinch} returns. */
+interface UsePinchResult extends IntentResult<PinchGesture> {
+    /**
+     * How much the thing is scaled, after `min`, `max` and `elastic`.
+     *
+     * **This is a position, not a movement.** It accumulates across gestures,
+     * so a second pinch continues from where the first stopped. `usePan` is the
+     * hook whose value zeroes at every gesture.
+     *
+     * Writing it is allowed and is how a release animation, or a reset button,
+     * hands control back. The next pinch continues from whatever it holds.
+     */
+    readonly scale: SharedValue<number>;
+    /**
+     * The midpoint between the fingers, relative to the view.
+     *
+     * It keeps the last gesture's focal point after the fingers lift, so a
+     * release animation scales about the same place the pinch did rather than
+     * snapping to the origin.
+     */
+    readonly focal: SharedValue<Point>;
+}
+/**
+ * Recognize a two-finger pinch, and own the scale it produces.
+ *
+ * ```tsx
+ * const pinch = usePinch({ min: 1, max: 4 })
+ *
+ * const style = useAnimatedStyle(() => ({
+ *   transform: [{ scale: pinch.scale.value }],
+ * }))
+ *
+ * return (
+ *   <GestureDetector gesture={pinch.gesture}>
+ *     <Animated.Image style={style} source={source} />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * **The scale accumulates; RNGH's does not.** A bare `Gesture.Pinch()`
+ * reports a factor that restarts at `1` on every gesture, so a viewer built
+ * on it snaps back to its original size the moment the fingers lift again.
+ * Carrying the scale across gestures is the multiplication and the stored
+ * start that every consumer otherwise writes, and it is why `min` and `max`
+ * can be the range of the viewer rather than of one gesture.
+ *
+ * **`focal` is the field a zoom viewer cannot skip.** Scaling about the
+ * view's centre slides the content out from under the fingers. The focal
+ * point is where the zoom has to happen, and it is reported relative to the
+ * view so it can go straight into a `translate` / `scale` / `translate`
+ * transform.
+ *
+ * **Activation criteria.** There are none to set. RNGH's pinch takes the
+ * touch as soon as a second finger moves, and it exposes no threshold, so
+ * Impulse has none to pass on. This is the one continuous intent whose
+ * coexistence is decided entirely by relations — see below.
+ *
+ * **Coexistence.** A pinch almost always shares its view with a pan, and it
+ * has no threshold to separate them with. Say it: `alongside` on both, so the
+ * two recognize at once and the same two fingers can move and scale the
+ * thing. `useGestures` with `mode: 'simultaneous'` is the same statement for
+ * gestures this screen owns.
+ *
+ * **Web.** RNGH recognizes pinch from pointer events, so it needs two
+ * pointers — a touchscreen or a device that reports them. A trackpad's pinch
+ * arrives as a `wheel` event with `ctrlKey`, which is not a pointer pair and
+ * never reaches this hook, so a desktop browser with a trackpad alone cannot
+ * zoom. Give it a control that sets `scale` directly, which the
+ * accessibility fallback needs anyway. The browser's own page zoom is
+ * unaffected either way.
+ *
+ * **Accessibility.** A pinch is invisible to a screen reader and unreachable
+ * from a keyboard, and this hook does not fix that. Whatever the pinch scales
+ * must be reachable another way: zoom-in and zoom-out buttons that write
+ * `scale`, a control that resets it, or `accessibilityActions` with
+ * `onAccessibilityAction`. A pinch-only zoom is a bug, not a trade-off.
+ *
+ * @param options - The scale range, callbacks, and the `alongside` /
+ *   `blocks` / `deferTo` coexistence options every Impulse hook accepts.
+ */
+declare function usePinch(options?: UsePinchOptions): UsePinchResult;
+
+export { type PinchEvent, type UsePinchOptions, type UsePinchResult, usePinch };

package/dist/pinch/index.js

@@ -0,0 +1,4 @@
+export { usePinch } from '../chunk-DXXGWG4Q.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
+import '../chunk-ZX7WNICB.js';

package/dist/raw/index.d.ts

@@ -1,7 +1,7 @@
 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 { B as BuiltGesture, G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import '../types-ChGKY28a.js';
 import 'react-native-reanimated';
 
 /** Options for {@link useRawGesture}. */
@@ -35,7 +35,7 @@ type RawGestureResult<G extends GestureType> = BuiltGesture<G>;
  *   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
+ *   two. Impulse does not insert a `scheduleOnRN` 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.
  *

package/dist/raw/index.js

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