@rootnative/inertia-gestures 0.0.0-alpha.0

package/llms.txt

@@ -0,0 +1,189 @@
+> @rootnative/inertia-gestures — adapter package for @rootnative/inertia.
+> This file is generated from the matching docs page by scripts/build-llms.mjs — do not edit by hand.
+
+> Full docs:    https://rootnative.github.io/inertia/
+> Core overview: see @rootnative/inertia/llms.txt (or docs/static/llms.txt in the repo)
+> Source:        https://github.com/rootnative/inertia
+
+---
+# Gestures adapter
+
+`@rootnative/inertia-gestures` adds drag / swipe / pan hooks built on `react-native-gesture-handler`. It is an **optional** sibling package — install it only if you need richer-than-`pressable` gestures. The core library has no required `gesture-handler` dependency.
+
+The hooks compose with any `Motion.*` primitive via a `<GestureDetector>` and a single `style` slot — they don't replace the `gesture` prop, they extend what's reachable beside it.
+
+## Install
+
+```bash
+yarn add @rootnative/inertia-gestures react-native-gesture-handler
+```
+
+Then follow the [`react-native-gesture-handler` install guide](https://docs.swmansion.com/react-native-gesture-handler/docs/installation) — it needs `<GestureHandlerRootView>` near the root of your app.
+
+## `useDrag`
+
+Drag a Motion primitive on one or two axes, with optional bounds and rubber-band overshoot.
+
+```tsx
+import { GestureDetector } from 'react-native-gesture-handler'
+import { Motion } from '@rootnative/inertia'
+import { useDrag } from '@rootnative/inertia-gestures'
+
+function DraggableBox() {
+  const drag = useDrag({
+    axis: 'both',
+    constraints: { left: -100, right: 100, top: -60, bottom: 60 },
+    elastic: 0.4,
+  })
+  return (
+    <GestureDetector gesture={drag.gesture}>
+      <Motion.View style={[styles.box, drag.animatedStyle]} />
+    </GestureDetector>
+  )
+}
+```
+
+| Option        | Type                                           | Default  | Notes                                                                                               |
+| ------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `axis`        | `'x' \| 'y' \| 'both'`                         | `'both'` | Lock the gesture to one axis.                                                                       |
+| `constraints` | `{ left?, right?, top?, bottom? }`             | none     | Bounds in px from the resting position. Each side independently optional.                           |
+| `elastic`     | `number` (0–1)                                 | `0`      | Rubber-band coefficient past `constraints`. `0` hard-clamps; `0.4` is a typical Framer-Motion feel. |
+| `onDragStart` | `() => void`                                   | none     | Fires on JS thread when drag begins.                                                                |
+| `onDragEnd`   | `(info: { x, y, velocity: { x, y } }) => void` | none     | Fires on JS thread when drag ends.                                                                  |
+| `onRelease`   | `(info) => ReleaseResult \| void` (worklet)    | none     | UI-thread release transition — see below.                                                           |
+
+Returns `{ gesture, animatedStyle, dragX, dragY, isDragging }`. The shared values are exposed for power use cases (deriving secondary effects from drag position).
+
+### Release transitions (`onRelease`)
+
+By default `useDrag` leaves the shared values exactly where the finger lifted. Pass `onRelease` to animate them to a settled position via Inertia's transition vocabulary — spring snap-to-tick, decay with bounds, timing settle. The callback runs as a **worklet** so the release velocity stays on the UI thread (no JS round-trip):
+
+```tsx
+const drag = useDrag({
+  axis: 'x',
+  constraints: { left: 0, right: trackWidth },
+  onRelease: (e) => {
+    'worklet'
+    // Snap to the nearest tick using the release velocity for natural continuation.
+    const snap = nearestTick(e.x, ticks)
+    return {
+      x: { type: 'spring', to: snap, velocity: e.velocity.x },
+    }
+  },
+})
+```
+
+Return per-axis release transitions in a `ReleaseResult` shape — omit an axis (or return nothing) to leave that SV where it landed. The transition shapes mirror the core `transition` prop:
+
+```ts
+type ReleaseTransition =
+  | (SpringTransition & { to: number })
+  | (TimingTransition & { to: number })
+  | DecayTransition // no `to` — decay decelerates from current position
+  | (NoAnimationTransition & { to: number })
+```
+
+Decay-on-release (for free-flick behaviour without snapping):
+
+```tsx
+onRelease: (e) => {
+  'worklet'
+  return {
+    x: { type: 'decay', velocity: e.velocity.x, clamp: [0, trackWidth] },
+  }
+}
+```
+
+`onRelease` composes additively with `onDragEnd` — both fire on release. Use `onRelease` for the SV animation; use `onDragEnd` for JS-thread side effects (analytics, state updates).
+
+Internally this routes through `buildReleaseAnimation` exported from `@rootnative/inertia` — a worklet-safe builder that covers spring / timing / decay / no-animation single-step transitions. Reach for it directly if you're writing a custom `Gesture.Pan().onEnd(...)` worklet outside `useDrag`.
+
+## `useSwipe`
+
+Directional commit-or-snap-back gesture. Tracks live translation while the user drags; on release, fires `onSwipe` if either the distance or velocity threshold is met along an allowed axis. Whether or not it commits, the position springs back to zero — the consumer drives the side effect (delete, dismiss, advance).
+
+```tsx
+const swipe = useSwipe({
+  directions: ['left', 'right'],
+  distanceThreshold: 100,
+  onSwipe: (direction) => {
+    if (direction === 'left') dismiss()
+    if (direction === 'right') accept()
+  },
+})
+
+return (
+  <GestureDetector gesture={swipe.gesture}>
+    <Motion.View style={[styles.card, swipe.animatedStyle]}>
+      {children}
+    </Motion.View>
+  </GestureDetector>
+)
+```
+
+| Option              | Type                                          | Default  | Notes                                                             |
+| ------------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------- |
+| `directions`        | `Array<'left' \| 'right' \| 'up' \| 'down'>`  | all four | Only commits along listed directions. Off-axis swipes do nothing. |
+| `distanceThreshold` | `number` (px)                                 | `80`     | Distance past which a release commits.                            |
+| `velocityThreshold` | `number` (px/sec)                             | `800`    | Flick velocity that commits even before distance threshold.       |
+| `onSwipe`           | `(direction, { distance, velocity }) => void` | none     | JS-thread callback. Direction is one of the allowed values.       |
+
+The dominant axis (whichever of \|tx\|, \|ty\| is larger at release) decides which direction is checked.
+
+## `usePan`
+
+Camera-style pan with momentum on release. Position **persists across separate gestures** — the next pan starts from the current offset, not zero — and on release the position continues gliding via Reanimated's `withDecay`.
+
+```tsx
+const pan = usePan({
+  constraints: { left: -240, right: 240, top: -240, bottom: 240 },
+  deceleration: 0.997,
+})
+
+return (
+  <GestureDetector gesture={pan.gesture}>
+    <Motion.View style={[styles.canvas, pan.animatedStyle]}>
+      {/* large content */}
+    </Motion.View>
+  </GestureDetector>
+)
+```
+
+| Option            | Type                               | Default            | Notes                                                                         |
+| ----------------- | ---------------------------------- | ------------------ | ----------------------------------------------------------------------------- |
+| `constraints`     | `{ left?, right?, top?, bottom? }` | none               | Hard clamp during gesture and during decay.                                   |
+| `deceleration`    | `number`                           | Reanimated default | Higher = momentum dies faster. Roughly `0.99` (slow) to `0.999` (long glide). |
+| `disableMomentum` | `boolean`                          | `false`            | Hard stop on release (drag-like).                                             |
+
+For rubber-banded constraints, prefer `useDrag({ elastic })` — `usePan` hard-clamps because it composes with `withDecay`'s `clamp` parameter, which doesn't have an overshoot mode.
+
+## When to pick which
+
+| Gesture    | Snap back on release? | Momentum on release?         | Typical UX                                         |
+| ---------- | --------------------- | ---------------------------- | -------------------------------------------------- |
+| `useDrag`  | No — stays where left | No                           | Move-to-position, sliders, sortable handles.       |
+| `useSwipe` | Yes — always          | No (springs back)            | Swipe-to-delete rows, card stacks, dismiss sheets. |
+| `usePan`   | No — stays where left | Yes — coasts via `withDecay` | Maps, zoomable canvases, large-image navigation.   |
+
+## Scope: touch + mouse only
+
+All three hooks layer on `react-native-gesture-handler`, which surfaces touch and mouse events but **not keyboard**. For controls that need keyboard a11y in addition to drag — a Slider with arrow-key increment / decrement, a scrollbar with `PageUp` / `PageDown`, a range input — reach for [`useTouchDrag`](./api/hooks#usetouchdragoptions) from `@rootnative/inertia/touch` instead. It's a PanResponder-backed counterpart to `useDrag` that lives in core (no `react-native-gesture-handler` peer required) and composes cleanly with `onKeyDown` on the wrapping `Pressable`.
+
+The full ladder:
+
+1. `Motion.View` + `gesture` prop — pure state-overlay UX (hover, focus, press).
+2. `useTouchDrag` from `@rootnative/inertia/touch` — pointer + keyboard drag, no extra peer dep.
+3. `useDrag` / `useSwipe` / `usePan` from this package — pointer-only, gesture-handler-backed. Best for projects already using gesture-handler; the UI-thread release path is more precise than PanResponder's JS-thread velocity.
+4. Raw `PanResponder` + `useAnimation` — drop here when the gesture lifecycle itself needs customizing (multi-touch composition, custom capture predicates beyond axis lock).
+
+Both `useTouchDrag` and the gesture-handler `useDrag` accept the same `onRelease` shape and route through `buildReleaseAnimation`, so swapping between them only touches the wiring, not the release animation config.
+
+## Try it
+
+
+
+## Why a separate package?
+
+The core library's `gesture` prop covers `pressed` / `focused` / `focusVisible` / `hovered` — boolean state-overlay gestures with no continuous translation. Drag, swipe, and pan are **value-driven**: the gesture publishes a continuous position that the consumer composes into the view's style. They don't fit the boolean-state model, and they need `react-native-gesture-handler` (which we don't want as a required peer of core).
+
+Splitting them off keeps core's surface area minimal and lets the gesture-handler dependency stay opt-in. The hooks return primitives (`gesture`, `animatedStyle`, shared values) rather than wrapping Motion in a new component, so they layer cleanly on the existing `Motion.*` set.

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@rootnative/inertia-gestures",
+  "version": "0.0.0-alpha.0",
+  "description": "Gesture-handler-driven drag / pan / swipe adapters for @rootnative/inertia.",
+  "license": "MIT",
+  "author": "RootNative",
+  "homepage": "https://github.com/rootnative/inertia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rootnative/inertia.git",
+    "directory": "packages/gestures"
+  },
+  "bugs": {
+    "url": "https://github.com/rootnative/inertia/issues"
+  },
+  "keywords": [
+    "react-native",
+    "reanimated",
+    "gesture-handler",
+    "drag",
+    "pan",
+    "swipe",
+    "inertia"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "!**/__tests__",
+    "!**/*.test.*"
+  ],
+  "peerDependencies": {
+    "@rootnative/inertia": ">=0.0.0-alpha.0",
+    "react": ">=19.0.0",
+    "react-native": ">=0.81.0",
+    "react-native-gesture-handler": ">=2.0.0",
+    "react-native-reanimated": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@react-native/babel-preset": "^0.81.5",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.0",
+    "jest": "^29.7.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.1",
+    "react-test-renderer": "19.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "@rootnative/inertia": "0.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "lint": "eslint .",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@rootnative/inertia-gestures` — gesture-handler-driven adapters for
+ * `@rootnative/inertia`.
+ *
+ * v0.2 surface:
+ * - `useDrag` — one- or two-axis drag with optional constraints and
+ *   rubber-band elasticity.
+ * - `useSwipe` — directional commit-or-snap-back gesture (distance + velocity
+ *   thresholds).
+ * - `usePan` — camera-style pan with momentum on release.
+ */
+export { useDrag } from './useDrag'
+export type { UseDragResult } from './useDrag'
+export { useSwipe } from './useSwipe'
+export type { SwipeDirection, SwipeOptions, UseSwipeResult } from './useSwipe'
+export { usePan } from './usePan'
+export type { PanOptions, UsePanResult } from './usePan'
+export type {
+  DragConstraints,
+  DragOptions,
+  ReleaseInfo,
+  ReleaseResult,
+  ReleaseTransition,
+} from './types'

package/src/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Public types for `@rootnative/inertia-gestures`.
+ */
+
+import type {
+  DecayTransition,
+  NoAnimationTransition,
+  SpringTransition,
+  TimingTransition,
+} from '@rootnative/inertia'
+
+/**
+ * Bounds the dragged value can reach. Each side is optional — omit to leave
+ * that direction unbounded. Coordinates are in the same space the drag
+ * publishes (pixels of translation from the dragged element's resting
+ * position), so `{ left: -100, right: 100 }` allows ±100 px of horizontal
+ * travel.
+ */
+export interface DragConstraints {
+  left?: number
+  right?: number
+  top?: number
+  bottom?: number
+}
+
+/**
+ * UI-thread payload delivered to `onRelease` when the drag finishes. `x` and
+ * `y` are the final translations the SVs are sitting at; `velocity.x` /
+ * `velocity.y` are the release velocities in px/sec.
+ */
+export interface ReleaseInfo {
+  x: number
+  y: number
+  velocity: { x: number; y: number }
+}
+
+/**
+ * Per-axis release transition. Spring / timing / no-animation animate to a
+ * target value (`to`); decay decelerates from the current position via its
+ * own physics and has no `to`. Pass the release velocity from `ReleaseInfo`
+ * into the transition's own `velocity` field for natural continuation.
+ */
+export type ReleaseTransition =
+  | (SpringTransition & { to: number })
+  | (TimingTransition & { to: number })
+  | DecayTransition
+  | (NoAnimationTransition & { to: number })
+
+/**
+ * Per-axis release transitions returned by `onRelease`. Omit an axis to leave
+ * its SV where it landed (no release animation on that axis).
+ */
+export interface ReleaseResult {
+  x?: ReleaseTransition
+  y?: ReleaseTransition
+}
+
+/**
+ * Configuration for `useDrag`. All fields are optional; the defaults give an
+ * unconstrained two-axis drag with no elasticity.
+ */
+export interface DragOptions {
+  /**
+   * Restrict the drag to one axis. Defaults to `'both'`. When `'x'` is set
+   * the y-axis shared value never updates (and vice versa); the gesture
+   * still tracks both for velocity reporting on `onDragEnd`.
+   */
+  axis?: 'x' | 'y' | 'both'
+  /**
+   * Travel bounds. Out-of-bounds values clamp to the limit unless `elastic`
+   * is non-zero, in which case overshoot is dampened (rubber-band feel).
+   */
+  constraints?: DragConstraints
+  /**
+   * Rubber-band coefficient applied to overshoot past `constraints`. `0`
+   * (default) hard-clamps; `1` is fully elastic (no resistance). Typical
+   * Framer-Motion-style feel sits around `0.2`–`0.4`.
+   */
+  elastic?: number
+  /**
+   * Fired on the JS thread when the drag begins.
+   */
+  onDragStart?: () => void
+  /**
+   * Fired on the JS thread when the drag finishes (release or cancel). The
+   * payload is the final translation and the release velocity in px/sec.
+   */
+  onDragEnd?: (info: ReleaseInfo) => void
+  /**
+   * UI-thread callback fired on release. Return per-axis release transitions
+   * to animate the SVs to a settled position via Inertia's transition
+   * resolver — spring snap-to-tick, decay with bounds, timing settle, etc.
+   * Omit an axis (or return nothing) to leave that SV where it landed.
+   *
+   * This callback runs as a worklet so the release velocity stays on the UI
+   * thread. Author it with the `'worklet'` directive at the top of the body.
+   *
+   * Composes with `onDragEnd`: both fire on release. `onRelease` controls SV
+   * animation on the UI thread; `onDragEnd` is for JS-thread side effects
+   * (analytics, state updates).
+   */
+  onRelease?: (info: ReleaseInfo) => ReleaseResult | void
+}

package/src/useDrag.ts

@@ -0,0 +1,184 @@
+import { useMemo } from 'react'
+import { Gesture, type PanGesture } from 'react-native-gesture-handler'
+import {
+  runOnJS,
+  useAnimatedStyle,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { buildReleaseAnimation } from '@rootnative/inertia'
+import type { DragConstraints, DragOptions } from './types'
+
+export interface UseDragResult {
+  /** Pan gesture to pass to a `<GestureDetector>`. */
+  gesture: PanGesture
+  /**
+   * Animated style fragment (a single `transform` entry) to stack onto the
+   * dragged Motion primitive's `style` prop. Stable across renders.
+   */
+  animatedStyle: ReturnType<typeof useAnimatedStyle>
+  /** Current x translation in pixels. UI-thread shared value. */
+  dragX: SharedValue<number>
+  /** Current y translation in pixels. UI-thread shared value. */
+  dragY: SharedValue<number>
+  /** True while the gesture is active. */
+  isDragging: SharedValue<boolean>
+}
+
+/**
+ * Drag a Motion primitive with `react-native-gesture-handler`'s pan gesture.
+ *
+ * The hook owns a pair of shared values (`dragX`, `dragY`) and a `Pan`
+ * gesture that updates them on the UI thread. The returned `animatedStyle`
+ * is a self-contained `transform: [{ translateX }, { translateY }]` fragment;
+ * stack it onto the dragged component without colliding with Motion's own
+ * `animate` transforms.
+ *
+ * Usage:
+ * ```tsx
+ * const drag = useDrag({ axis: 'x', constraints: { left: -100, right: 100 } })
+ * return (
+ *   <GestureDetector gesture={drag.gesture}>
+ *     <Motion.View style={drag.animatedStyle} />
+ *   </GestureDetector>
+ * )
+ * ```
+ */
+export function useDrag(options: DragOptions = {}): UseDragResult {
+  const {
+    axis = 'both',
+    constraints,
+    elastic = 0,
+    onDragStart,
+    onDragEnd,
+    onRelease,
+  } = options
+
+  const dragX = useSharedValue(0)
+  const dragY = useSharedValue(0)
+  const startX = useSharedValue(0)
+  const startY = useSharedValue(0)
+  const isDragging = useSharedValue(false)
+
+  // Snapshot scalars into local consts so the Pan handlers (worklets) capture
+  // primitives, not the closing `options` object — a fresh `options` literal
+  // each render would otherwise force a new gesture identity.
+  const lockX = axis !== 'y'
+  const lockY = axis !== 'x'
+  const left = constraints?.left
+  const right = constraints?.right
+  const top = constraints?.top
+  const bottom = constraints?.bottom
+  const elasticCoef = elastic
+
+  const gesture = useMemo(() => {
+    const pan = Gesture.Pan()
+      .onStart(() => {
+        'worklet'
+        startX.value = dragX.value
+        startY.value = dragY.value
+        isDragging.value = true
+        if (onDragStart) runOnJS(onDragStart)()
+      })
+      .onUpdate((e) => {
+        'worklet'
+        if (lockX) {
+          dragX.value = applyBounds(
+            startX.value + e.translationX,
+            left,
+            right,
+            elasticCoef,
+          )
+        }
+        if (lockY) {
+          dragY.value = applyBounds(
+            startY.value + e.translationY,
+            top,
+            bottom,
+            elasticCoef,
+          )
+        }
+      })
+      .onEnd((e) => {
+        'worklet'
+        isDragging.value = false
+        const x = dragX.value
+        const y = dragY.value
+        const vx = e.velocityX
+        const vy = e.velocityY
+        if (onRelease) {
+          const result = onRelease({ x, y, velocity: { x: vx, y: vy } })
+          if (result) {
+            // Decay ignores `toValue` (it has no target); spring/timing/no-animation
+            // use it. Build per axis off the SV's current position when no `to`
+            // is given (decay branch), the destination otherwise.
+            if (result.x && lockX) {
+              const toX = 'to' in result.x ? result.x.to : x
+              dragX.value = buildReleaseAnimation(
+                result.x,
+                toX,
+              ) as unknown as number
+            }
+            if (result.y && lockY) {
+              const toY = 'to' in result.y ? result.y.to : y
+              dragY.value = buildReleaseAnimation(
+                result.y,
+                toY,
+              ) as unknown as number
+            }
+          }
+        }
+        if (onDragEnd) {
+          runOnJS(onDragEnd)({ x, y, velocity: { x: vx, y: vy } })
+        }
+      })
+    return pan
+  }, [
+    lockX,
+    lockY,
+    left,
+    right,
+    top,
+    bottom,
+    elasticCoef,
+    onDragStart,
+    onDragEnd,
+    onRelease,
+    dragX,
+    dragY,
+    startX,
+    startY,
+    isDragging,
+  ])
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: dragX.value }, { translateY: dragY.value }],
+  }))
+
+  return { gesture, animatedStyle, dragX, dragY, isDragging }
+}
+
+/**
+ * Clamp `value` to `[min, max]`. When `elastic > 0` the overshoot beyond a
+ * bound is scaled by `elastic` instead of hard-clamped, giving a rubber-band
+ * feel. `min` / `max` may be `undefined` to leave that side unbounded.
+ *
+ * Worklet — runs on the UI thread inside the pan handler.
+ */
+function applyBounds(
+  value: number,
+  min: number | undefined,
+  max: number | undefined,
+  elastic: number,
+): number {
+  'worklet'
+  if (min !== undefined && value < min) {
+    return elastic > 0 ? min + (value - min) * elastic : min
+  }
+  if (max !== undefined && value > max) {
+    return elastic > 0 ? max + (value - max) * elastic : max
+  }
+  return value
+}
+
+export type { DragConstraints, DragOptions }