@rootnative/inertia 0.0.0-alpha.0

package/src/motion/index.ts

@@ -0,0 +1,26 @@
+import { MotionImage } from './Image'
+import { MotionPressable } from './Pressable'
+import { MotionScrollView } from './ScrollView'
+import { MotionText } from './Text'
+import { MotionView } from './View'
+
+export { createMotionComponent } from './createMotionComponent'
+export {
+  MotionView,
+  MotionText,
+  MotionImage,
+  MotionPressable,
+  MotionScrollView,
+}
+
+/**
+ * The `Motion.*` namespace. Each property is a primitive with its style prop
+ * inferred from the underlying RN component. There is no shared style fallback.
+ */
+export const Motion = {
+  View: MotionView,
+  Text: MotionText,
+  Image: MotionImage,
+  Pressable: MotionPressable,
+  ScrollView: MotionScrollView,
+} as const

package/src/motion/installCheck.ts

@@ -0,0 +1,65 @@
+import { reanimatedVersion } from 'react-native-reanimated'
+
+declare const __DEV__: boolean
+declare const process: { env?: Record<string, string | undefined> }
+
+let alreadyChecked = false
+
+/**
+ * Surface a clear, actionable error at first `createMotionComponent` call when
+ * the consumer's Reanimated install is broken. Production builds, repeat calls,
+ * and Jest test runs are all skipped — the check is purely a dev-time
+ * paper-cut sander for the two failure modes we can detect from JS:
+ *
+ * 1. `react-native-reanimated` resolves but is on a v3.x line we don't
+ *    support (the plugin name and worklet runtime both changed at v4).
+ * 2. The worklets babel plugin (`react-native-worklets/plugin` in v4) isn't
+ *    wired into `babel.config.js`, so `'worklet'` directives are dead strings
+ *    and the first `withSpring` / `withTiming` call would crash on the UI
+ *    thread with a generic "non-worklet function called" error.
+ *
+ * The "Reanimated isn't installed at all" case isn't handled here — Metro
+ * fails to resolve the static `import 'react-native-reanimated'` at the top
+ * of `createMotionComponent.tsx` long before this check runs.
+ */
+export function ensureReanimatedInstalled(): void {
+  if (!__DEV__ || alreadyChecked) return
+  // The standard `react-native-reanimated/mock` doesn't run the worklets
+  // babel plugin, so the marker probe would false-positive every test run.
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'test') {
+    return
+  }
+  alreadyChecked = true
+
+  // Read the version off Reanimated's own runtime export rather than reaching
+  // into its `package.json`. A `require('.../package.json')` here would make
+  // esbuild emit a `__require` shim that throws on web bundlers (Expo web), and
+  // Reanimated's `exports` field may block the subpath anyway.
+  const version: string | undefined = reanimatedVersion
+
+  if (version) {
+    const major = parseInt(version.split('.')[0] ?? '0', 10)
+    if (major < 4) {
+      console.error(
+        `[inertia] react-native-reanimated v${version} is installed, but @rootnative/inertia requires v4.0.0 or later. ` +
+          `Upgrade with \`pnpm add react-native-reanimated@^4\` (or your package manager's equivalent).`,
+      )
+      return
+    }
+  }
+
+  // The worklets plugin rewrites any function carrying a top-of-body
+  // `'worklet'` directive to expose a `__workletHash` property at runtime.
+  // Its absence means the plugin didn't run.
+  const probe = function probe() {
+    'worklet'
+    return 0
+  } as { __workletHash?: number }
+  if (typeof probe.__workletHash !== 'number') {
+    console.error(
+      `[inertia] The Reanimated worklets babel plugin is not configured. ` +
+        `Add \`'react-native-worklets/plugin'\` as the LAST entry in the \`plugins\` array of your \`babel.config.js\`, ` +
+        `then restart Metro with a fresh cache: \`npx expo start -c\` or \`npx react-native start --reset-cache\`.`,
+    )
+  }
+}

package/src/presence/Presence.tsx

@@ -0,0 +1,165 @@
+import {
+  Children,
+  isValidElement,
+  type Key,
+  type ReactElement,
+  type ReactNode,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { PresenceContext, type PresenceContextValue } from './PresenceContext'
+
+interface RenderEntry {
+  key: Key
+  element: ReactElement
+  isPresent: boolean
+}
+
+/**
+ * Wrap a list of children with mount / unmount transitions. When a child is
+ * removed from the incoming list it stays in the snapshot until its exit
+ * animation completes; descendants consume the per-child `<PresenceContext>`
+ * to coordinate.
+ *
+ * Children must be `<Motion.*>` primitives (or any component that consumes
+ * `usePresence()` and calls `safeToRemove`). Plain elements without that
+ * contract will linger in the snapshot once removed; document that and pick
+ * the right primitive.
+ *
+ * Children also need explicit `key`s so removal is detectable across
+ * renders. Without a key, React falls back to positional identity and
+ * removal looks like a prop change — Presence has nothing to mark exiting.
+ */
+export function Presence({ children }: { children: ReactNode }) {
+  const incoming = useMemo(() => {
+    const out: ReactElement[] = []
+    Children.forEach(children, (child) => {
+      if (!isValidElement(child)) return
+      if (child.key === null) {
+        if (__DEV__) {
+          console.warn(
+            '[inertia] <Presence> children must have a `key`. Skipping a keyless child.',
+          )
+        }
+        return
+      }
+      out.push(child)
+    })
+    return out
+  }, [children])
+
+  // Snapshot of elements removed from `incoming` whose exit animation is
+  // still in flight. setExiting is called synchronously during render below
+  // (the documented pattern for derived-from-prop-change state), so React
+  // re-renders with the new snapshot before committing — no visual frame
+  // where the departing child has vanished.
+  const [exiting, setExiting] = useState<Map<Key, ReactElement>>(
+    () => new Map(),
+  )
+
+  // Tracks the previous render's `incoming` so we can diff. Updated
+  // synchronously alongside the setState call.
+  const prevIncomingRef = useRef<ReactElement[]>(incoming)
+
+  if (prevIncomingRef.current !== incoming) {
+    const prev = prevIncomingRef.current
+    prevIncomingRef.current = incoming
+    const incomingKeys = new Set(incoming.map((el) => el.key as Key))
+    let next: Map<Key, ReactElement> | null = null
+    const ensureMutable = () => {
+      if (!next) next = new Map(exiting)
+      return next
+    }
+
+    // Departures: in prev but not in current → snapshot for exit.
+    for (const oldEl of prev) {
+      const key = oldEl.key as Key
+      if (!incomingKeys.has(key) && !exiting.has(key)) {
+        ensureMutable().set(key, oldEl)
+      }
+    }
+    // Returns: was exiting and reappears → drop the snapshot. The live
+    // `incoming` entry takes over with the same key, so React reconciles
+    // the underlying Motion instance and the in-flight exit animation
+    // interrupts back toward `animate` values.
+    for (const el of incoming) {
+      const key = el.key as Key
+      if (exiting.has(key)) {
+        ensureMutable().delete(key)
+      }
+    }
+
+    if (next) setExiting(next)
+  }
+
+  const handleRemove = useCallback((key: Key) => {
+    setExiting((prev) => {
+      if (!prev.has(key)) return prev
+      const next = new Map(prev)
+      next.delete(key)
+      return next
+    })
+  }, [])
+
+  // Single combined render list. Putting `incoming` and `exiting` entries in
+  // one array (rather than two `.map` calls inside a fragment) ensures React
+  // reconciles by `key` across positions — when an entry moves from
+  // present-list to exiting-list, the component instance persists.
+  const renderList: RenderEntry[] = []
+  for (const el of incoming) {
+    renderList.push({
+      key: el.key as Key,
+      element: el,
+      isPresent: true,
+    })
+  }
+  for (const [key, el] of exiting) {
+    if (!renderList.some((entry) => entry.key === key)) {
+      renderList.push({ key, element: el, isPresent: false })
+    }
+  }
+
+  return (
+    <>
+      {renderList.map(({ key, element, isPresent }) => (
+        <PresenceItem
+          key={key}
+          itemKey={key}
+          isPresent={isPresent}
+          onRemove={handleRemove}
+        >
+          {element}
+        </PresenceItem>
+      ))}
+    </>
+  )
+}
+
+function PresenceItem({
+  itemKey,
+  isPresent,
+  onRemove,
+  children,
+}: {
+  itemKey: Key
+  isPresent: boolean
+  onRemove: (key: Key) => void
+  children: ReactNode
+}) {
+  const value = useMemo<PresenceContextValue>(
+    () => ({
+      isPresent,
+      safeToRemove: () => onRemove(itemKey),
+    }),
+    [isPresent, itemKey, onRemove],
+  )
+  return (
+    <PresenceContext.Provider value={value}>
+      {children}
+    </PresenceContext.Provider>
+  )
+}
+
+declare const __DEV__: boolean

package/src/presence/PresenceContext.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-child contract between `<Presence>` and its descendant Motion
+ * primitives. `<Presence>` provides a fresh value to each rendered child;
+ * Motion primitives consume it to gate exit animations.
+ *
+ * - `isPresent`: `true` while the child is in the incoming children list.
+ *   Flips to `false` when the parent removes it; the child remains rendered
+ *   until `safeToRemove` is called.
+ * - `safeToRemove`: callback the child invokes when its exit animation has
+ *   settled. `<Presence>` then drops the snapshot entry and unmounts.
+ */
+export interface PresenceContextValue {
+  isPresent: boolean
+  safeToRemove: () => void
+}
+
+export const PresenceContext = createContext<PresenceContextValue | null>(null)
+
+/**
+ * Read the surrounding `<Presence>` contract from a child component. Returns
+ * `null` when there is no `<Presence>` ancestor — useful for components that
+ * want to support both standalone and Presence-wrapped use without branching.
+ */
+export function usePresence(): PresenceContextValue | null {
+  return useContext(PresenceContext)
+}

package/src/presence/index.ts

@@ -0,0 +1,6 @@
+export { Presence } from './Presence'
+export {
+  PresenceContext,
+  usePresence,
+  type PresenceContextValue,
+} from './PresenceContext'

package/src/testing/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Test helpers for Inertia consumers.
+ *
+ * The Reanimated Jest mock that ships with the library is **static-render**:
+ * `useAnimatedStyle` runs the worklet exactly once per call, and shared
+ * values are plain `{ value }` refs. After the animation effect fires
+ * (`sv.value = withSpring(target) → target` under the mock), the rendered
+ * style has already been captured at the at-rest shared-value snapshot —
+ * so without intervention, every Inertia component looks frozen at its
+ * `initial` values in tests.
+ *
+ * `renderWithMotion` papers over that by forcing a second render after the
+ * first effect pass. The shared values now hold their target values, so
+ * `useAnimatedStyle` re-evaluates against the post-animation state and the
+ * rendered styles match what a real device would settle on.
+ *
+ * Use this from `@rootnative/inertia/testing`:
+ *
+ * ```ts
+ * import { renderWithMotion } from '@rootnative/inertia/testing'
+ *
+ * const { getByTestId } = renderWithMotion(
+ *   <Motion.View testID="card" initial={{ opacity: 0 }} animate={{ opacity: 1 }} />,
+ * )
+ * // getByTestId('card') has opacity: 1, not 0.
+ * ```
+ *
+ * For tests that need to re-render with new props and re-flush, use
+ * `flushMotion(result, nextUi)`.
+ */
+import { render, type RenderOptions } from '@testing-library/react-native'
+import { cloneElement, type ReactElement } from 'react'
+
+type RenderResult = ReturnType<typeof render>
+
+/**
+ * Render a Motion subtree and immediately flush animations to their target
+ * values. Returns the standard `@testing-library/react-native` render result.
+ *
+ * Internally this calls `render(...)`, then re-renders the same element
+ * inside `act(...)` so the post-effect shared-value updates flow into the
+ * `useAnimatedStyle` re-run. Both passes happen synchronously — the call
+ * returns once styles reflect the `animate` target.
+ */
+export function renderWithMotion(
+  ui: ReactElement,
+  options?: RenderOptions,
+): RenderResult {
+  const result = render(ui, options)
+  // `cloneElement` produces a fresh element with the same props so React
+  // doesn't bail out of the second render via reference-equal short-circuit
+  // — that's what causes `useAnimatedStyle` to skip its post-effect re-read
+  // when the same element is passed to `rerender`.
+  flushMotion(result, cloneElement(ui))
+  return result
+}
+
+/**
+ * Re-render a previously-mounted Motion subtree to flush pending animations
+ * to their target values. Pass the same element you originally rendered
+ * (or a new one for tests that update props between flushes).
+ *
+ * The flush is synchronous. `@testing-library/react-native`'s `rerender`
+ * already wraps in `act` internally, so no explicit `act(...)` is needed
+ * here.
+ */
+export function flushMotion(rendered: RenderResult, ui: ReactElement): void {
+  // One re-render is enough for non-sequence animations: the mount-effect
+  // has run, shared values now hold their target values, and the next
+  // `useAnimatedStyle` invocation will read them. Sequence steps chain
+  // through `withSpring` / `withTiming` settle callbacks — those are still
+  // captured for tests that invoke them manually (see `onAnimationEnd.test`).
+  //
+  // `cloneElement` defeats React's reference-equal element bail-out so the
+  // second render actually reaches `useAnimatedStyle` instead of being
+  // short-circuited by the reconciler.
+  rendered.rerender(cloneElement(ui))
+}

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 `@rootnative/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 `@rootnative/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 `@rootnative/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
+ * `@rootnative/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 `@rootnative/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 '@rootnative/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
+      // `@rootnative/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
+}