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

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
@@ -274,43 +300,73 @@ export function createMotionComponent<C extends ComponentType<any>>(
     const [focusVisible, setFocusVisible] = useState(false)
     const [hovered, setHovered] = useState(false)
 
-    // The set of keys this instance animates is locked at first render. With
-    // variants in play the union across all variants is what matters — a key
-    // touched by any variant must be active so the worklet picks it up when
-    // the controller transitions. Gesture sub-states join the same union so
-    // pressed/focused/focusVisible/hovered targets can drive any key they
-    // declare even when the base `animate` doesn't touch it.
-    const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
-    if (activeKeysRef.current === null) {
-      const touched = new Set<AnimatableKey>()
-      collectTouchedKeys(touched, animateRecord)
-      if (initialRecord) collectTouchedKeys(touched, initialRecord)
-      if (variants) {
-        for (const variant of Object.values(variants) as object[]) {
-          if (!variant) continue
-          collectTouchedKeys(touched, variant as Record<string, unknown>)
-        }
+    // The set of keys this instance animates is a *monotonically growing*
+    // union, recomputed every render and expanded when a render introduces a
+    // key not seen before. It never shrinks. Two requirements meet here:
+    //
+    //   1. Variants and gesture sub-states contribute the union across *all*
+    //      their branches up front — a key touched by any variant must be
+    //      active so the worklet picks it up when the controller transitions
+    //      to a branch the base `animate` never mentions.
+    //   2. A literal `animate` object is reactive: a parent that changes
+    //      `animate={{ opacity: 1 }}` to `animate={{ opacity: 1, scale: 2 }}`
+    //      after mount must get `scale` animating. Freezing the set at first
+    //      render silently dropped the new key (its SV updated, but the
+    //      worklet — which iterates this set — never read it).
+    //
+    // Growing-only keeps the worklet stable: the `activeKeysRef.current` array
+    // identity only changes on the renders that actually add a key, so the
+    // `useAnimatedStyle` worklet (which reads `.current` each frame) sees the
+    // expansion without churning frame-to-frame.
+    const touched = new Set<AnimatableKey>()
+    collectTouchedKeys(touched, animateRecord)
+    if (initialRecord) collectTouchedKeys(touched, initialRecord)
+    if (variants) {
+      for (const variant of Object.values(variants) as object[]) {
+        if (!variant) continue
+        collectTouchedKeys(touched, variant as Record<string, unknown>)
       }
-      if (gesture) {
-        for (const subState of [
-          gesture.pressed,
-          gesture.focused,
-          gesture.focusVisible,
-          gesture.hovered,
-        ] as Array<object | undefined>) {
-          if (!subState) continue
-          collectTouchedKeys(touched, subState as Record<string, unknown>)
+    }
+    if (gesture) {
+      for (const subState of [
+        gesture.pressed,
+        gesture.focused,
+        gesture.focusVisible,
+        gesture.hovered,
+      ] as Array<object | undefined>) {
+        if (!subState) continue
+        collectTouchedKeys(touched, subState as Record<string, unknown>)
+      }
+    }
+    if (exitRecord) collectTouchedKeys(touched, exitRecord)
+
+    const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
+    const hasTransformRef = useRef<boolean>(false)
+    const hasShadowOffsetRef = useRef<boolean>(false)
+    // Expand the active set only when this render touched a key we haven't
+    // recorded yet. When nothing new appears we keep the existing array
+    // identity so the worklet's captured ref doesn't see a fresh value.
+    const prevActive = activeKeysRef.current
+    let grew = prevActive === null
+    if (!grew && prevActive) {
+      for (const k of touched) {
+        if (!prevActive.includes(k)) {
+          grew = true
+          break
         }
       }
-      if (exitRecord) collectTouchedKeys(touched, exitRecord)
-      activeKeysRef.current = ALL_KEYS.filter((k) => touched.has(k))
     }
-    const hasTransformRef = useRef<boolean>(
-      activeKeysRef.current.some((k) => TRANSFORM_KEY_SET.has(k)),
-    )
-    const hasShadowOffsetRef = useRef<boolean>(
-      activeKeysRef.current.some((k) => SHADOW_OFFSET_KEY_SET.has(k)),
-    )
+    if (grew) {
+      const merged = new Set<AnimatableKey>(prevActive ?? [])
+      for (const k of touched) merged.add(k)
+      activeKeysRef.current = ALL_KEYS.filter((k) => merged.has(k))
+      hasTransformRef.current = activeKeysRef.current.some((k) =>
+        TRANSFORM_KEY_SET.has(k),
+      )
+      hasShadowOffsetRef.current = activeKeysRef.current.some((k) =>
+        SHADOW_OFFSET_KEY_SET.has(k),
+      )
+    }
 
     const sharedValues = useAnimatableSharedValues((key) => {
       // Shadow offset synthetics seed from the corresponding axis on the
@@ -531,6 +587,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 +684,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 +739,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/motion/installCheck.ts

@@ -1,6 +1,7 @@
+import { reanimatedVersion } from 'react-native-reanimated'
+
 declare const __DEV__: boolean
 declare const process: { env?: Record<string, string | undefined> }
-declare const require: (path: string) => unknown
 
 let alreadyChecked = false
 
@@ -30,16 +31,11 @@ export function ensureReanimatedInstalled(): void {
   }
   alreadyChecked = true
 
-  let version: string | undefined
-  try {
-    const pkg = require('react-native-reanimated/package.json') as {
-      version?: string
-    }
-    version = pkg.version
-  } catch {
-    // package.json subpath blocked by `exports` field — skip the version
-    // probe rather than emit a misleading error.
-  }
+  // 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)

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'