@onlynative/inertia 0.0.1-alpha.7 → 0.0.1-alpha.8

package/src/layout/useSharedLayout.ts

@@ -0,0 +1,289 @@
+import {
+  type MutableRefObject,
+  type Ref,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react'
+import { type LayoutChangeEvent } from 'react-native'
+import {
+  type SharedValue,
+  useSharedValue,
+  withSequence,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated'
+import { DEFAULT_SPRING, springToReanimated } from '../transitions/spring'
+import { type SpringTransition, type TransitionConfig } from '../types'
+import {
+  consumeLayout,
+  registerLayout,
+  releaseLayout,
+  type SharedRect,
+} from './sharedRegistry'
+
+/**
+ * Shared values produced by `useSharedLayout`. The worklet inside
+ * `createMotionComponent` appends `translateX/Y` and `scaleX/Y` transforms
+ * built from these so a shared-layout source rect maps onto the new
+ * element's transform stack without conflicting with the user's `animate`
+ * transforms — multiple transform entries of the same key compose
+ * additively (for translates) and multiplicatively (for scales), which is
+ * exactly the FLIP semantic.
+ *
+ * At rest the values are `(0, 0, 1, 1)` — the identity transform — so when
+ * no shared-layout transition is active the worklet's contribution is a
+ * no-op.
+ */
+export interface SharedLayoutValues {
+  dx: SharedValue<number>
+  dy: SharedValue<number>
+  sx: SharedValue<number>
+  sy: SharedValue<number>
+}
+
+/** What the host component needs to wire into its rendered tree. */
+export interface SharedLayoutBindings {
+  flip: SharedLayoutValues
+  /**
+   * Composite ref the consumer attaches to the rendered animated
+   * component. Forwards the underlying ref to the user-supplied `ref`
+   * (when present); kept as a stable callback so a `<Motion.*>` with no
+   * `layoutId` doesn't pay anything extra.
+   */
+  setRef: (node: unknown) => void
+  /** onLayout handler the consumer must attach to the animated component. */
+  onLayout: (event: LayoutChangeEvent) => void
+}
+
+/**
+ * Hook backing `<Motion.* layoutId="..." />`.
+ *
+ * Responsibilities, in order:
+ *   1. Allocate FLIP shared values (identity at rest).
+ *   2. Track the latest layout rect via the `onLayout` event, and push it
+ *      into the registry under `layoutId` so this primitive can serve as
+ *      the source for a future transition.
+ *   3. On unmount, hand the last measured rect to `releaseLayout` so the
+ *      next mount with the same id can consume it.
+ *   4. On the first layout commit, consume any pending source rect and
+ *      drive the FLIP shared values: snap them to the (delta, scale) that
+ *      visually places the new element at the source position, then
+ *      animate back to identity. `withSequence(snap, animate)` keeps the
+ *      animation starting from the snapped delta rather than from zero.
+ *
+ * Coordinate space note: rects are in parent-relative coordinates (what
+ * `onLayout` reports). For the common cross-screen navigator pattern —
+ * both screens share an outer content container — parent-relative deltas
+ * match what the user perceives. Nested-parent setups where the source
+ * and target screens sit under containers at different screen offsets
+ * will be off by that offset; v1 documents this and leaves a precise
+ * window-coords path for v2.
+ *
+ * When `layoutId` is `undefined`, every callback is a no-op and the FLIP
+ * shared values stay at identity — the host's worklet then skips the
+ * transform contribution entirely.
+ */
+export function useSharedLayout(options: {
+  layoutId: string | undefined
+  userRef: Ref<unknown> | undefined
+  transition: TransitionConfig | undefined
+  shouldReduceMotion: boolean
+  userOnLayout: ((event: LayoutChangeEvent) => void) | undefined
+}): SharedLayoutBindings {
+  const { layoutId, userRef, transition, shouldReduceMotion, userOnLayout } =
+    options
+
+  const dx = useSharedValue(0)
+  const dy = useSharedValue(0)
+  const sx = useSharedValue(1)
+  const sy = useSharedValue(1)
+
+  // Most-recent rect for this primitive. Updated on every layout commit;
+  // read on unmount to populate the registry as the FLIP source for the
+  // next mount with the same id.
+  const lastRectRef = useRef<SharedRect | null>(null)
+
+  // First-layout latch — only the first measurement after a fresh mount
+  // can consume a source rect. Subsequent layouts (resizes, prop changes)
+  // refresh the registry but never re-trigger a FLIP from an old source.
+  const consumedRef = useRef(false)
+
+  const transitionRef = useRef(transition)
+  transitionRef.current = transition
+  const reducedMotionRef = useRef(shouldReduceMotion)
+  reducedMotionRef.current = shouldReduceMotion
+
+  const setRef = useCallback(
+    (node: unknown) => {
+      if (typeof userRef === 'function') userRef(node)
+      else if (userRef) (userRef as MutableRefObject<unknown>).current = node
+    },
+    [userRef],
+  )
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      userOnLayout?.(event)
+      if (!layoutId) return
+
+      const { x, y, width, height } = event.nativeEvent.layout
+      const rect: SharedRect = { x, y, width, height }
+      lastRectRef.current = rect
+
+      // First-layout-only: read the registry BEFORE writing our own rect
+      // so a previously-released source rect can be consumed cleanly
+      // without being overwritten by the current rect first.
+      let source: SharedRect | undefined
+      if (!consumedRef.current) {
+        consumedRef.current = true
+        source = consumeLayout(layoutId)
+      }
+      registerLayout(layoutId, rect)
+
+      if (source) {
+        applyFlip({
+          source,
+          target: rect,
+          dx,
+          dy,
+          sx,
+          sy,
+          transition: transitionRef.current,
+          shouldReduceMotion: reducedMotionRef.current,
+        })
+      }
+    },
+    // dx/dy/sx/sy are stable refs from useSharedValue, but eslint's
+    // exhaustive-deps would flag them — including them is harmless and
+    // silences the warning.
+    [layoutId, userOnLayout, dx, dy, sx, sy],
+  )
+
+  // Reset the first-layout latch when the id changes — a new id is logically
+  // a new shared-element identity and should be allowed to consume a source.
+  useEffect(() => {
+    consumedRef.current = false
+  }, [layoutId])
+
+  // On unmount, hand the latest rect to the registry under this id so the
+  // next mount can consume it as a FLIP source.
+  useEffect(() => {
+    return () => {
+      if (!layoutId) return
+      const rect = lastRectRef.current
+      if (!rect) return
+      releaseLayout(layoutId, rect)
+    }
+  }, [layoutId])
+
+  return useMemo<SharedLayoutBindings>(
+    () => ({
+      flip: { dx, dy, sx, sy },
+      setRef,
+      onLayout,
+    }),
+    [dx, dy, sx, sy, setRef, onLayout],
+  )
+}
+
+/**
+ * Snap the FLIP shared values so the new element visually overlays its
+ * source rect, then animate back to identity. The `withSequence(snap,
+ * animate)` shape is what makes the spring start from the snapped delta —
+ * a plain `withSpring(0)` from a zero base would animate from-zero, not
+ * from-source.
+ */
+function applyFlip(args: {
+  source: SharedRect
+  target: SharedRect
+  dx: SharedValue<number>
+  dy: SharedValue<number>
+  sx: SharedValue<number>
+  sy: SharedValue<number>
+  transition: TransitionConfig | undefined
+  shouldReduceMotion: boolean
+}): void {
+  const { source, target, dx, dy, sx, sy, transition, shouldReduceMotion } =
+    args
+
+  // Compute the delta that would visually place the new element at the
+  // source rect. The transform origin matters: RN scales around the
+  // element's center, so the translation needs to account for the
+  // center-of-source vs center-of-target offset, not the top-left offset.
+  const sourceCenterX = source.x + source.width / 2
+  const sourceCenterY = source.y + source.height / 2
+  const targetCenterX = target.x + target.width / 2
+  const targetCenterY = target.y + target.height / 2
+  const deltaX = sourceCenterX - targetCenterX
+  const deltaY = sourceCenterY - targetCenterY
+  // Guard against zero-sized targets (degenerate layout) — keep scale at 1
+  // so the element at least renders even if the FLIP isn't a perfect match.
+  const scaleX = target.width > 0 ? source.width / target.width : 1
+  const scaleY = target.height > 0 ? source.height / target.height : 1
+
+  if (shouldReduceMotion) {
+    // Reduced-motion: skip the visual transition entirely. The element
+    // appears at its natural position; the source rect is discarded.
+    dx.value = 0
+    dy.value = 0
+    sx.value = 1
+    sy.value = 1
+    return
+  }
+
+  if (transition?.type === 'no-animation') {
+    dx.value = 0
+    dy.value = 0
+    sx.value = 1
+    sy.value = 1
+    return
+  }
+
+  if (transition?.type === 'timing') {
+    const duration = transition.duration ?? 300
+    dx.value = withSequence(
+      withTiming(deltaX, { duration: 0 }),
+      withTiming(0, { duration }),
+    )
+    dy.value = withSequence(
+      withTiming(deltaY, { duration: 0 }),
+      withTiming(0, { duration }),
+    )
+    sx.value = withSequence(
+      withTiming(scaleX, { duration: 0 }),
+      withTiming(1, { duration }),
+    )
+    sy.value = withSequence(
+      withTiming(scaleY, { duration: 0 }),
+      withTiming(1, { duration }),
+    )
+    return
+  }
+
+  // Spring path (default, and the fallback for `'decay'` which doesn't
+  // have a meaningful target value for a FLIP transition).
+  const springCfg: SpringTransition =
+    transition?.type === 'spring'
+      ? { ...DEFAULT_SPRING, ...transition }
+      : { type: 'spring', ...DEFAULT_SPRING }
+  const springParams = springToReanimated(springCfg)
+
+  dx.value = withSequence(
+    withTiming(deltaX, { duration: 0 }),
+    withSpring(0, springParams),
+  )
+  dy.value = withSequence(
+    withTiming(deltaY, { duration: 0 }),
+    withSpring(0, springParams),
+  )
+  sx.value = withSequence(
+    withTiming(scaleX, { duration: 0 }),
+    withSpring(1, springParams),
+  )
+  sy.value = withSequence(
+    withTiming(scaleY, { duration: 0 }),
+    withSpring(1, springParams),
+  )
+}

package/src/motion/createMotionComponent.tsx

@@ -13,9 +13,14 @@ import Animated, {
   useSharedValue,
   type SharedValue,
 } from 'react-native-reanimated'
+import { type LayoutChangeEvent } from 'react-native'
 import { useShouldReduceMotion } from '../config'
 import { isFocusVisible } from '../gestures'
-import { resolveLayoutTransition, type LayoutProp } from '../layout'
+import {
+  resolveLayoutTransition,
+  type LayoutProp,
+  useSharedLayout,
+} from '../layout'
 import { usePresence } from '../presence'
 import {
   isTopLevelTransition,
@@ -223,10 +228,31 @@ export function createMotionComponent<C extends ComponentType<any>>(
       controller,
       gesture,
       layout,
+      layoutId,
       onAnimationEnd,
       style,
+      onLayout: userOnLayout,
       ...rest
-    } = props as Props & { style?: unknown; layout?: LayoutProp }
+    } = props as Props & {
+      style?: unknown
+      layout?: LayoutProp
+      layoutId?: string
+      onLayout?: (event: LayoutChangeEvent) => void
+    }
+
+    // Function-form `style={(state) => ...}` is the Pressable render-prop API.
+    // Inertia drives press/focus state through `gesture.*` and merges its own
+    // animated style; a function passed here lands inside a style array where
+    // the underlying component never invokes it, so the resulting styles are
+    // silently dropped. Throw loudly in dev rather than ship the footgun.
+    if (__DEV__ && typeof style === 'function') {
+      throw new Error(
+        '[inertia] `style` must be a style object or array of style objects, ' +
+          'not a function. The function-form `style={(state) => ...}` Pressable ' +
+          'API is not supported — use `gesture.pressed` (or `gesture.focused`, ' +
+          'etc.) to drive state-dependent styling instead.',
+      )
+    }
 
     // <Presence> contract: when an ancestor flips `isPresent` to false the
     // child stays rendered until `safeToRemove` is called, giving the exit
@@ -531,6 +557,23 @@ export function createMotionComponent<C extends ComponentType<any>>(
       shouldReduceMotion,
     )
 
+    // Shared-element transition wiring. `useSharedLayout` allocates FLIP
+    // shared values (identity at rest), measures via the merged `onLayout`,
+    // and on first-mount snaps the FLIP transform to a source rect popped
+    // from the registry. The worklet below appends those entries to the
+    // transform array so they compose with the user's animate transforms —
+    // multiple `translateX` entries sum, multiple `scaleX` entries multiply,
+    // which is exactly the FLIP semantic.
+    const sharedLayout = useSharedLayout({
+      layoutId,
+      userRef: ref,
+      transition: isTopLevelTransition(transition) ? transition : undefined,
+      shouldReduceMotion,
+      userOnLayout,
+    })
+    const flip = sharedLayout.flip
+    const hasLayoutId = layoutId !== undefined
+
     const animatedStyle = useAnimatedStyle(() => {
       const activeKeys = activeKeysRef.current!
       const hasTransform = hasTransformRef.current
@@ -611,7 +654,19 @@ export function createMotionComponent<C extends ComponentType<any>>(
           out[key] = v
         }
       }
-      if (hasTransform) out.transform = transform
+      // Shared-element FLIP transforms append after the user's transform
+      // entries so they compose multiplicatively in the same `transform`
+      // array — separate style entries with `transform` keys would
+      // last-write-wins, which is what we explicitly avoid here. At rest
+      // (dx, dy, sx, sy) = (0, 0, 1, 1) so the contribution is a no-op
+      // when no shared-element transition is active.
+      if (hasLayoutId) {
+        transform.push({ translateX: flip.dx.value })
+        transform.push({ translateY: flip.dy.value })
+        transform.push({ scaleX: flip.sx.value })
+        transform.push({ scaleY: flip.sy.value })
+      }
+      if (hasTransform || hasLayoutId) out.transform = transform
       if (hasShadowOffset) {
         out.shadowOffset = { width: shadowOffsetW, height: shadowOffsetH }
       }
@@ -654,9 +709,10 @@ export function createMotionComponent<C extends ComponentType<any>>(
 
     return (
       <AnimatedComponent
-        ref={ref as never}
+        ref={sharedLayout.setRef as never}
         {...(rest as object)}
         {...gestureHandlers}
+        onLayout={sharedLayout.onLayout}
         layout={layoutTransition}
         style={mergedStyle}
       />

package/src/touch/index.ts

@@ -0,0 +1,18 @@
+/**
+ * PanResponder-backed drag hook. Lives in core because `PanResponder` is
+ * built into React Native — no extra peer dependency. Use this when you
+ * need keyboard a11y alongside drag, or when you don't want to take
+ * `react-native-gesture-handler` as a dependency.
+ *
+ * For pointer-only drag in a project that already uses gesture-handler,
+ * prefer `useDrag` from `@onlynative/inertia-gestures` — its UI-thread
+ * release path is more precise.
+ */
+export { useTouchDrag } from './useTouchDrag'
+export type {
+  TouchReleaseInfo,
+  TouchReleaseResult,
+  TouchReleaseTransition,
+  UseTouchDragOptions,
+  UseTouchDragResult,
+} from './useTouchDrag'

package/src/touch/useTouchDrag.ts

@@ -0,0 +1,289 @@
+import { useMemo } from 'react'
+import {
+  PanResponder,
+  type PanResponderGestureState,
+  type PanResponderInstance,
+} from 'react-native'
+import {
+  useAnimatedStyle,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { buildReleaseAnimation } from '../transitions'
+import type { TransitionConfig } from '../types'
+
+/**
+ * Same drag-result shape as `useDrag` from `@onlynative/inertia-gestures`,
+ * minus the `gesture` field (PanResponder spreads handlers, no
+ * `<GestureDetector>` wrapper). The shared values + animatedStyle are
+ * interchangeable across both hooks; consumers can swap implementations
+ * without touching their `useAnimatedStyle` consumers.
+ */
+export interface UseTouchDragResult {
+  /** Spread onto a `View` / `Pressable` to install the pan responder. */
+  panHandlers: PanResponderInstance['panHandlers']
+  /** Stable animated `transform` style. */
+  animatedStyle: ReturnType<typeof useAnimatedStyle>
+  /** Live x translation, persistent across gestures. */
+  dragX: SharedValue<number>
+  /** Live y translation, persistent across gestures. */
+  dragY: SharedValue<number>
+  /** True while the gesture is active. */
+  isDragging: SharedValue<boolean>
+}
+
+/**
+ * Release transition shape for PanResponder's JS-thread `onRelease`. Mirrors
+ * the gesture-handler adapter's `ReleaseTransition` but with `to` typed as
+ * required for spring/timing/no-animation (decay omits it).
+ */
+export type TouchReleaseTransition =
+  | (TransitionConfig & { type: 'spring'; to: number })
+  | (TransitionConfig & { type: 'timing'; to: number })
+  | (TransitionConfig & { type: 'decay' })
+  | (TransitionConfig & { type: 'no-animation'; to: number })
+
+export interface TouchReleaseInfo {
+  x: number
+  y: number
+  velocity: { x: number; y: number }
+}
+
+export interface TouchReleaseResult {
+  x?: TouchReleaseTransition
+  y?: TouchReleaseTransition
+}
+
+export interface UseTouchDragOptions {
+  /**
+   * Restrict the drag to one axis. Defaults to `'both'`. When `'x'` is set
+   * the y-axis shared value never updates (and vice versa); velocity is
+   * still reported on both for `onDragEnd`.
+   */
+  axis?: 'x' | 'y' | 'both'
+  /**
+   * Travel bounds (px from resting). Each side is independently optional.
+   * Out-of-bounds values clamp to the limit unless `elastic > 0`.
+   */
+  constraints?: {
+    left?: number
+    right?: number
+    top?: number
+    bottom?: number
+  }
+  /**
+   * Rubber-band coefficient applied to overshoot past `constraints`. `0`
+   * (default) hard-clamps; `0.2`-`0.4` is a typical Framer-Motion feel.
+   */
+  elastic?: number
+  /**
+   * Fires when the user starts dragging. JS thread.
+   */
+  onDragStart?: () => void
+  /**
+   * Fires when the user releases or the gesture terminates. JS thread.
+   *
+   * Velocity is in px/sec to match the `@onlynative/inertia-gestures` API
+   * (PanResponder's native `vx` / `vy` are px/ms; the hook normalizes).
+   */
+  onDragEnd?: (info: TouchReleaseInfo) => void
+  /**
+   * Optional release-animation callback. 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.
+   *
+   * Unlike the gesture-handler version, this callback runs on the **JS
+   * thread** (PanResponder is JS-only). The returned transitions still drive
+   * UI-thread animations via Reanimated — only the decision logic is JS-side.
+   */
+  onRelease?: (info: TouchReleaseInfo) => TouchReleaseResult | void
+}
+
+/**
+ * PanResponder-backed drag hook. Pointer-equivalent of `useDrag` from
+ * `@onlynative/inertia-gestures`, with two differences:
+ *
+ *   1. No `react-native-gesture-handler` peer dep required — PanResponder is
+ *      built into React Native, so this lives in core.
+ *   2. Returns `panHandlers` to spread on a `View` / `Pressable` instead of
+ *      a `gesture` to plug into `<GestureDetector>`.
+ *
+ * Use this when:
+ *   - You need keyboard a11y alongside drag (a slider with arrow-key step,
+ *     a scrollbar with `PageUp` / `PageDown`). PanResponder composes
+ *     cleanly with `onKeyDown`; gesture-handler doesn't surface keyboard.
+ *   - You don't want to take `react-native-gesture-handler` as a dependency
+ *     (smaller bundle, simpler install).
+ *
+ * Skip this when:
+ *   - You're already using `react-native-gesture-handler` elsewhere (use
+ *     `useDrag` from `@onlynative/inertia-gestures` for consistency and
+ *     better worklet-thread fidelity on release velocity).
+ *   - You need momentum semantics like the gesture-handler `usePan` —
+ *     PanResponder's release velocity is JS-thread and slightly less precise.
+ *
+ * @example
+ * ```tsx
+ * import { useTouchDrag } from '@onlynative/inertia/touch'
+ *
+ * function Slider({ ticks }: { ticks: number[] }) {
+ *   const drag = useTouchDrag({
+ *     axis: 'x',
+ *     constraints: { left: 0, right: 280 },
+ *     onRelease: (e) => {
+ *       const snap = nearestTick(e.x, ticks)
+ *       return { x: { type: 'spring', to: snap, velocity: e.velocity.x } }
+ *     },
+ *   })
+ *
+ *   return (
+ *     <Motion.View
+ *       style={[styles.thumb, drag.animatedStyle]}
+ *       {...drag.panHandlers}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useTouchDrag(
+  options: UseTouchDragOptions = {},
+): UseTouchDragResult {
+  const { axis = 'both', constraints, elastic = 0 } = 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 responder callbacks close over
+  // primitives, not the `options` literal — a fresh `options` each render
+  // would otherwise force the PanResponder identity to change.
+  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 { onDragStart, onDragEnd, onRelease } = options
+
+  const responder = useMemo(
+    () => buildResponder(),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      lockX,
+      lockY,
+      left,
+      right,
+      top,
+      bottom,
+      elasticCoef,
+      onDragStart,
+      onDragEnd,
+      onRelease,
+    ],
+  )
+
+  // Hoisted out of the inline `useMemo` factory to keep the dep list readable
+  // and avoid re-declaring closure helpers each render.
+  function buildResponder(): PanResponderInstance {
+    const handleEnd = (g: PanResponderGestureState) => {
+      isDragging.value = false
+      const x = dragX.value
+      const y = dragY.value
+      // PanResponder velocity is px/ms; multiply to match the
+      // `@onlynative/inertia-gestures` API (px/sec from gesture-handler).
+      const vx = g.vx * 1000
+      const vy = g.vy * 1000
+      if (onRelease) {
+        const result = onRelease({ x, y, velocity: { x: vx, y: vy } })
+        if (result) {
+          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) onDragEnd({ x, y, velocity: { x: vx, y: vy } })
+    }
+
+    return PanResponder.create({
+      // Always claim the start so taps that turn into drags don't slip
+      // through to a parent ScrollView. Consumers can compose their own
+      // capture predicates by wrapping the returned `panHandlers`.
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: () => true,
+      onPanResponderGrant: () => {
+        startX.value = dragX.value
+        startY.value = dragY.value
+        isDragging.value = true
+        if (onDragStart) onDragStart()
+      },
+      onPanResponderMove: (_e, g) => {
+        if (lockX) {
+          dragX.value = applyBounds(
+            startX.value + g.dx,
+            left,
+            right,
+            elasticCoef,
+          )
+        }
+        if (lockY) {
+          dragY.value = applyBounds(
+            startY.value + g.dy,
+            top,
+            bottom,
+            elasticCoef,
+          )
+        }
+      },
+      onPanResponderRelease: (_e, g) => handleEnd(g),
+      onPanResponderTerminate: (_e, g) => handleEnd(g),
+    })
+  }
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: dragX.value }, { translateY: dragY.value }],
+  }))
+
+  return {
+    panHandlers: responder.panHandlers,
+    animatedStyle,
+    dragX,
+    dragY,
+    isDragging,
+  }
+}
+
+/**
+ * Clamp `value` to `[min, max]`. When `elastic > 0` the overshoot past a
+ * bound is scaled by `elastic`, giving a rubber-band feel. `min` / `max`
+ * may be `undefined` to leave that side unbounded.
+ *
+ * JS-thread (PanResponder callbacks are JS, not worklets).
+ */
+function applyBounds(
+  value: number,
+  min: number | undefined,
+  max: number | undefined,
+  elastic: number,
+): number {
+  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
+}