@onlynative/inertia 0.0.1-alpha.3 → 0.0.1-alpha.4

package/src/transitions/sig.ts

@@ -0,0 +1,40 @@
+/**
+ * Stable string signature for an arbitrary value — used as a dep-array
+ * member so a fresh object literal each render doesn't re-fire an effect
+ * unless something structurally changed. Functions serialize as `null`
+ * (their identity isn't useful in a sig); `undefined` collapses to an empty
+ * string so omitted props compare equal across renders.
+ */
+export function stableSig(value: unknown): string {
+  if (value === undefined) return ''
+  try {
+    return stableStringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * JSON.stringify with keys sorted at every level so a sig is invariant under
+ * property-declaration order. Functions and `undefined` both serialize as
+ * `null` — we accept the latter's information loss (rare in practice) in
+ * exchange for not crashing on circular function-bearing graphs.
+ */
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== 'object') {
+    if (typeof v === 'function' || v === undefined) return 'null'
+    return JSON.stringify(v)
+  }
+  if (Array.isArray(v)) {
+    return '[' + v.map(stableStringify).join(',') + ']'
+  }
+  const obj = v as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return (
+    '{' +
+    keys
+      .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+      .join(',') +
+    '}'
+  )
+}

package/src/transitions/spring.ts

@@ -0,0 +1,41 @@
+import { type SpringTransition } from '../types'
+
+/**
+ * Default spring physics, expressed in react-spring vocabulary.
+ *
+ * `tension: 170` / `friction: 26` / `mass: 1` was picked over Reanimated's
+ * raw `stiffness: 100` / `damping: 10` default because the raw default
+ * overshoots noticeably for the small (~100px) translates that dominate
+ * UI work — buttons, sheets, popovers. These numbers settle in ~350ms with
+ * a single, almost-imperceptible overshoot, which matches the perceptual
+ * target the rest of the library is tuned against.
+ */
+export const DEFAULT_SPRING: Required<
+  Pick<SpringTransition, 'tension' | 'friction' | 'mass'>
+> = {
+  tension: 170,
+  friction: 26,
+  mass: 1,
+}
+
+/**
+ * Convert public react-spring vocabulary (`tension` / `friction` / `mass`)
+ * to Reanimated's raw `stiffness` / `damping` / `mass`. This is the single
+ * place the mapping lives; resolvers, value hooks, and any future surface
+ * that needs a Reanimated spring config import from here.
+ *
+ * The mapping is identity (tension ≡ stiffness, friction ≡ damping) — the
+ * names differ but the underlying physics constants are the same. We don't
+ * surface the raw names publicly because the react-spring vocabulary is
+ * what designers and prior-art consumers expect.
+ */
+export function springToReanimated(t: SpringTransition) {
+  return {
+    stiffness: t.tension ?? DEFAULT_SPRING.tension,
+    damping: t.friction ?? DEFAULT_SPRING.friction,
+    mass: t.mass ?? DEFAULT_SPRING.mass,
+    velocity: t.velocity,
+    restSpeedThreshold: t.restSpeedThreshold,
+    restDisplacementThreshold: t.restDisplacementThreshold,
+  }
+}

package/src/types.ts

@@ -95,13 +95,43 @@ export type Transition<S> =
   | TransitionConfig
   | (PerPropertyTransition<S> & GestureLayerTransitions)
 
+/**
+ * Transform shorthands that Inertia exposes on `animate` but that don't
+ * appear on RN's typed ViewStyle as top-level keys. RN keeps `scale`,
+ * `rotate`, `rotateX`, and `rotateY` inside the `transform` array; only
+ * `scaleX`/`scaleY` and `translateX`/`translateY` are surfaced as
+ * (deprecated) top-level shortcuts. Inertia's runtime treats these as
+ * transform-group keys (see `TRANSFORM_KEYS` in `createMotionComponent`),
+ * so they're documented as first-class animatables in `CLAUDE.md` and must
+ * be reachable from `animate` without dropping into the `transform: [...]`
+ * array form. Rotation values are degrees as numbers — the runtime appends
+ * `'deg'` before handing the transform to Reanimated.
+ */
+type AnimatableTransformExtras = {
+  scale?: AnimatableValue<number>
+  rotate?: AnimatableValue<number>
+  rotateX?: AnimatableValue<number>
+  rotateY?: AnimatableValue<number>
+}
+
 /**
  * The animation state shape inferred from the underlying component's style
  * prop. We narrow to the value side of `style` so consumers see ViewStyle on
  * `Motion.View`, TextStyle on `Motion.Text`, etc. — no shared union.
+ *
+ * Some components (notably `Pressable`) type `style` as a union of
+ * `StyleProp<T>` and a callback `(state) => StyleProp<T>`. If we infer `S`
+ * directly from `StyleProp<infer S>`, the callback branch widens `S` to
+ * `unknown`, which collapses the animate map to `| {}` and silently
+ * accepts any key. Excluding functions first keeps inference tight.
  */
-export type AnimateStyle<C> = C extends { style?: StyleProp<infer S> }
-  ? { [K in keyof S]?: AnimatableValue<S[K]> }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type _StyleValue<T> = Exclude<T, (...args: any[]) => any>
+
+export type AnimateStyle<C> = C extends { style?: infer Raw }
+  ? _StyleValue<Raw> extends StyleProp<infer S>
+    ? { [K in keyof S]?: AnimatableValue<S[K]> } & AnimatableTransformExtras
+    : never
   : never
 
 export interface AnimationCallbackInfo<S> {
@@ -231,6 +261,26 @@ export interface MotionProps<C> {
    * precedence over the top-level transition.
    */
   transition?: Transition<AnimateStyle<C>>
+  /**
+   * Auto-layout animation. When the component's position or size changes
+   * because of a parent layout change (a flex sibling growing, a list
+   * reordering, a column toggling its width), interpolate between the old
+   * and new layout instead of snapping.
+   *
+   * - `true` — animate with the library's default spring.
+   * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
+   *   resolver bridges to Reanimated's `LinearTransition` builder.
+   * - omitted / `false` — no layout animation (default).
+   *
+   * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
+   * — decay is downgraded to spring (no clear target). Reduced motion gates
+   * the prop the same way it gates `animate`.
+   *
+   * `layoutId` for shared element transitions across screens is deferred:
+   * Reanimated 4 dropped the underlying `sharedTransitionTag` API and a
+   * Inertia-side measure-based registry is the in-flight design.
+   */
+  layout?: boolean | TransitionConfig
   /**
    * Fired once per logical animation completion. See `AnimationCallbackInfo`
    * for the payload shape — transform parents fire once, not per axis.

package/src/values/index.ts

@@ -1 +1,15 @@
+export { useAnimation } from './useAnimation'
+export {
+  useGesture,
+  type UseGestureHandlers,
+  type UseGestureResult,
+} from './useGesture'
+export { useMotionValue } from './useMotionValue'
+export { useSpring } from './useSpring'
+export {
+  useTransform,
+  type ExtrapolationMode,
+  type UseTransformOptions,
+} from './useTransform'
+export { useScroll, type UseScrollResult } from './useScroll'
 export { useVariants } from './useVariants'

package/src/values/useAnimation.ts

@@ -0,0 +1,69 @@
+import { useEffect } from 'react'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { useShouldReduceMotion } from '../config'
+import { resolveTransition, stableSig } from '../transitions'
+import { type TransitionConfig } from '../types'
+
+/**
+ * Drive a `SharedValue<number>` toward `target` with **any** transition shape
+ * — spring, timing, decay, or no-animation. The general-purpose value-layer
+ * hook: reach for it when you need raw `useSharedValue + useEffect + withX`
+ * outside the declarative `animate` flow.
+ *
+ * Re-runs whenever `target` changes shape (`target` is in the dep array) or
+ * the transition signature changes (kept stable via JSON-style hashing).
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses the
+ * transition to `no-animation` so the value snaps instead of interpolating.
+ *
+ * **Spring shorthand.** Prefer [`useSpring`](./useSpring) when you only want
+ * spring physics — it accepts the same `tension`/`friction`/`mass` config and
+ * also supports a `SharedValue<number>` as the target (UI-thread reactive
+ * source). `useAnimation` is JS-thread-driven only.
+ *
+ * **Loops.** Repeat is part of `TransitionConfig` and flows through
+ * untouched — `useAnimation(1, { type: 'timing', duration: 1800, repeat: {
+ * count: 'infinite', alternate: false } })` produces an indeterminate-style
+ * progress driver.
+ *
+ * @example
+ * ```ts
+ * // Toggle progress (Switch / Checkbox / Radio).
+ * const progress = useAnimation(isChecked ? 1 : 0, {
+ *   type: 'spring',
+ *   tension: 380,
+ *   friction: 33,
+ * })
+ *
+ * // Float a TextField label when the value becomes non-empty.
+ * const floated = useAnimation(hasValue ? 1 : 0, {
+ *   type: 'timing',
+ *   duration: 150,
+ * })
+ *
+ * // Indeterminate progress slider (loops forever, snaps back).
+ * const slide = useAnimation(1, {
+ *   type: 'timing',
+ *   duration: 1800,
+ *   repeat: { count: 'infinite', alternate: false },
+ * })
+ * ```
+ */
+export function useAnimation(
+  target: number,
+  transition?: TransitionConfig,
+): SharedValue<number> {
+  const output = useSharedValue<number>(target)
+  const shouldReduceMotion = useShouldReduceMotion()
+  const cfgSig = stableSig(transition)
+
+  useEffect(() => {
+    const cfg = shouldReduceMotion
+      ? ({ type: 'no-animation' } as const)
+      : (transition ?? ({ type: 'spring' } as const))
+    output.value = resolveTransition(cfg, target) as never
+    // `output` is identity-stable per hook instance.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [target, cfgSig, shouldReduceMotion])
+
+  return output
+}

package/src/values/useGesture.ts

@@ -0,0 +1,144 @@
+import { useCallback, useMemo } from 'react'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { useShouldReduceMotion } from '../config'
+import { isFocusVisible } from '../gestures'
+import { isTopLevelTransition, resolveTransition } from '../transitions'
+import { type GestureLayerTransitions, type TransitionConfig } from '../types'
+
+type LayerName = 'pressed' | 'focused' | 'focusVisible' | 'hovered'
+
+/**
+ * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
+ * shared values returned alongside.
+ *
+ * Hover handlers use `Pressable`'s own `onHoverIn` / `onHoverOut` names (web
+ * only — no-ops on native). `onFocus` consults `isFocusVisible()` before
+ * raising the keyboard-only `focusVisible` layer; `focused` always raises.
+ */
+export interface UseGestureHandlers {
+  onPressIn: () => void
+  onPressOut: () => void
+  onHoverIn: () => void
+  onHoverOut: () => void
+  onFocus: () => void
+  onBlur: () => void
+}
+
+export interface UseGestureResult {
+  /** 0↔1 progress for the pressed layer. */
+  pressed: SharedValue<number>
+  /** 0↔1 progress for the focused layer (any focus modality). */
+  focused: SharedValue<number>
+  /** 0↔1 progress for the focusVisible layer (keyboard focus only). */
+  focusVisible: SharedValue<number>
+  /** 0↔1 progress for the hovered layer (web only — stays at 0 on native). */
+  hovered: SharedValue<number>
+  /** Handlers to spread on the receiving `Pressable`. */
+  handlers: UseGestureHandlers
+}
+
+/**
+ * Build a gesture-layer controller. The hook-form of the `gesture` prop —
+ * reach for it when you need to drive multiple animated views from the same
+ * gesture state (a focus ring + state-layer halo + content tint all on one
+ * Pressable), which the prop-form's "animate the receiver's own style" model
+ * can't express.
+ *
+ * Returns four 0↔1 shared values (one per layer) and a handler bag to spread
+ * on a `Pressable`. The shared values are stable across renders — feed them
+ * into any number of `useAnimatedStyle` blocks anywhere in the tree.
+ *
+ * Transitions follow the same shape as the `gesture` prop's accompanying
+ * `transition`: pass a single `TransitionConfig` to use for every layer, or a
+ * `GestureLayerTransitions` map to give each layer its own. Layers without an
+ * explicit transition fall back to the library default spring.
+ *
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
+ * transition to `no-animation` so state changes snap instead of interpolating
+ * — same behaviour the gesture prop applies.
+ *
+ * @example
+ * ```tsx
+ * import { useAnimatedStyle } from 'react-native-reanimated'
+ * import { useGesture } from '@onlynative/inertia'
+ *
+ * function Card() {
+ *   const { pressed, focused, hovered, handlers } = useGesture({
+ *     pressed: { type: 'timing', duration: 100 },
+ *     hovered: { type: 'timing', duration: 150 },
+ *     focused: { type: 'timing', duration: 200 },
+ *   })
+ *
+ *   const ringStyle = useAnimatedStyle(() => ({ opacity: focused.value }))
+ *   const haloStyle = useAnimatedStyle(() => ({
+ *     opacity: Math.max(
+ *       hovered.value * 0.08,
+ *       focused.value * 0.10,
+ *       pressed.value * 0.10,
+ *     ),
+ *   }))
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={ringStyle} />
+ *       <Animated.View style={haloStyle} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+export function useGesture(
+  transition?: TransitionConfig | GestureLayerTransitions,
+): UseGestureResult {
+  const pressed = useSharedValue(0)
+  const focused = useSharedValue(0)
+  const focusVisible = useSharedValue(0)
+  const hovered = useSharedValue(0)
+  const shouldReduceMotion = useShouldReduceMotion()
+
+  const setLayer = useCallback(
+    (sv: SharedValue<number>, layer: LayerName, target: 0 | 1) => {
+      const cfg = shouldReduceMotion
+        ? ({ type: 'no-animation' } as const)
+        : (layerTransition(layer, transition) ?? ({ type: 'spring' } as const))
+      sv.value = resolveTransition(cfg, target) as never
+    },
+    // The transition is intentionally read on every call rather than cooked
+    // into the dep array — a fresh literal each render would otherwise
+    // rebuild the handler bag and break composing consumers that key off
+    // handler identity. `transition` is read inside the callback closure;
+    // shared values are stable so the only dep that matters is the reduce-
+    // motion flag.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [shouldReduceMotion],
+  )
+
+  const handlers = useMemo<UseGestureHandlers>(
+    () => ({
+      onPressIn: () => setLayer(pressed, 'pressed', 1),
+      onPressOut: () => setLayer(pressed, 'pressed', 0),
+      onHoverIn: () => setLayer(hovered, 'hovered', 1),
+      onHoverOut: () => setLayer(hovered, 'hovered', 0),
+      onFocus: () => {
+        setLayer(focused, 'focused', 1)
+        if (isFocusVisible()) setLayer(focusVisible, 'focusVisible', 1)
+      },
+      onBlur: () => {
+        setLayer(focused, 'focused', 0)
+        setLayer(focusVisible, 'focusVisible', 0)
+      },
+    }),
+    [setLayer, pressed, focused, focusVisible, hovered],
+  )
+
+  return { pressed, focused, focusVisible, hovered, handlers }
+}
+
+function layerTransition(
+  layer: LayerName,
+  transition: TransitionConfig | GestureLayerTransitions | undefined,
+): TransitionConfig | undefined {
+  if (!transition) return undefined
+  if (isTopLevelTransition(transition)) return transition
+  return (transition as GestureLayerTransitions)[layer]
+}

package/src/values/useMotionValue.ts

@@ -0,0 +1,33 @@
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+
+/**
+ * Create an animatable value owned by JS but readable from worklets.
+ *
+ * This is the escape-hatch primitive that the rest of the value-layer hooks
+ * (`useSpring`, `useTransform`, `useScroll`) compose against. It is a thin
+ * pass-through over Reanimated's `useSharedValue`: a `SharedValue<T>` with
+ * `.value` for direct reads/writes (UI-thread reads in worklets, JS-thread
+ * writes from event handlers / effects).
+ *
+ * We intentionally do not introduce a `MotionValue` wrapper class around the
+ * shared value. The simplest object that interops with `useAnimatedStyle`,
+ * `useDerivedValue`, and every other Reanimated API _is_ the shared value
+ * itself; adding a `{ get, set, value }` shell would force consumers to
+ * unwrap it at every Reanimated boundary and break worklet capture.
+ *
+ * Worklet read:
+ * ```ts
+ * const x = useMotionValue(0)
+ * useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }))
+ * ```
+ *
+ * JS write:
+ * ```ts
+ * onPress={() => { x.value = 100 }}
+ * ```
+ */
+export function useMotionValue<T extends number | string>(
+  initial: T,
+): SharedValue<T> {
+  return useSharedValue<T>(initial)
+}

package/src/values/useScroll.ts

@@ -0,0 +1,72 @@
+import {
+  useAnimatedScrollHandler,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { type NativeScrollEvent, type NativeSyntheticEvent } from 'react-native'
+
+export interface UseScrollResult {
+  /** Horizontal scroll offset in points. */
+  scrollX: SharedValue<number>
+  /** Vertical scroll offset in points. */
+  scrollY: SharedValue<number>
+  /**
+   * Handler to pass to a `Motion.ScrollView`'s `onScroll` prop (or any other
+   * Reanimated `Animated.ScrollView`). The handler is opaque to JS — it runs
+   * as a worklet — but the type narrows to the same shape RN's native
+   * `onScroll` prop expects so it composes cleanly.
+   */
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void
+}
+
+/**
+ * Track the scroll offset of a `Motion.ScrollView` as shared values.
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ * const headerOpacity = useTransform(scrollY, [0, 100], [1, 0])
+ *
+ * return (
+ *   <>
+ *     <Motion.View animate={{ opacity: headerOpacity }} />
+ *     <Motion.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
+ *       …
+ *     </Motion.ScrollView>
+ *   </>
+ * )
+ * ```
+ *
+ * Scroll events fire on the UI thread, so `scrollX` / `scrollY` are safe to
+ * read from any worklet (`useAnimatedStyle`, `useDerivedValue`,
+ * `useTransform`) without a JS-thread bounce.
+ *
+ * Remember to set `scrollEventThrottle={16}` on the `ScrollView` for 60Hz
+ * updates — RN's default is to dispatch on every event, which on iOS still
+ * means one per frame, but Android benefits from the explicit cap.
+ */
+export function useScroll(): UseScrollResult {
+  const scrollX = useSharedValue(0)
+  const scrollY = useSharedValue(0)
+
+  const handler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      'worklet'
+      scrollX.value = event.contentOffset.x
+      scrollY.value = event.contentOffset.y
+    },
+  })
+
+  // `useAnimatedScrollHandler` returns an opaque worklet bag whose JS-side
+  // type is `(event) => void` but actually carries native event-handler
+  // wiring. Cast through `unknown` because the public RN `onScroll` type
+  // wants a `NativeSyntheticEvent`-taking function and Reanimated's handler
+  // is structurally compatible — the cast is to satisfy the consumer's
+  // prop type at the call site.
+  return {
+    scrollX,
+    scrollY,
+    onScroll: handler as unknown as (
+      event: NativeSyntheticEvent<NativeScrollEvent>,
+    ) => void,
+  }
+}

package/src/values/useSpring.ts

@@ -0,0 +1,93 @@
+import { useEffect, useMemo } from 'react'
+import {
+  useAnimatedReaction,
+  useSharedValue,
+  withSpring,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { springToReanimated } from '../transitions/spring'
+import { type SpringTransition } from '../types'
+
+/**
+ * Animate a shared value toward `target` with spring physics, using the
+ * library's react-spring vocabulary (`tension` / `friction` / `mass`).
+ *
+ * `target` may be a plain number or a `SharedValue<number>`. The plain-number
+ * path drives the spring from a JS `useEffect`, so the animation re-runs on
+ * every render where `target` changes. The shared-value path drives the
+ * spring from a Reanimated reaction on the UI thread, so values produced by
+ * gestures, scroll handlers, or other worklets flow through without bouncing
+ * back to JS.
+ *
+ * Both call sites end up at the same `withSpring` invocation; the split is
+ * just about which thread observes the source change.
+ */
+export function useSpring(
+  target: number | SharedValue<number>,
+  config?: SpringTransition,
+): SharedValue<number> {
+  // Reanimated config is rebuilt only when the public config object changes
+  // shape. The worklet path reads this from JS-thread closure capture, which
+  // is fine: it's the resolved config that's invariant across UI-thread
+  // ticks, not a JS-thread reference that would go stale.
+  const reanimConfig = useMemo(
+    () => springToReanimated(config ?? {}),
+    [
+      config?.tension,
+      config?.friction,
+      config?.mass,
+      config?.velocity,
+      config?.restSpeedThreshold,
+      config?.restDisplacementThreshold,
+    ],
+  )
+
+  const isSharedTarget = isSharedValue(target)
+  const initial = isSharedTarget ? target.value : (target as number)
+  const output = useSharedValue<number>(initial)
+
+  // Plain-number path. The reaction below is a no-op when `target` is a
+  // number, so this effect carries the change. Reading `target` directly in
+  // the dep array means React drives the schedule; we don't have to babysit
+  // a stale closure.
+  useEffect(() => {
+    if (isSharedTarget) return
+    output.value = withSpring(target as number, reanimConfig)
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSharedTarget, target, reanimConfig])
+
+  // SharedValue path. `useAnimatedReaction` runs the prepare worklet whenever
+  // its returned value changes; we read `.value` off the target SV and pipe
+  // it through `withSpring` on the UI thread. When the target is a plain
+  // number we never declare a source so the reaction is inert (returns
+  // `null`, never fires `react`).
+  useAnimatedReaction(
+    () => {
+      'worklet'
+      if (!isSharedTarget) return null
+      return (target as SharedValue<number>).value
+    },
+    (next, prev) => {
+      'worklet'
+      if (next === null || next === prev) return
+      output.value = withSpring(next, reanimConfig)
+    },
+    [isSharedTarget, reanimConfig],
+  )
+
+  return output
+}
+
+function isSharedValue(v: unknown): v is SharedValue<number> {
+  // SharedValues are plain objects with a single `value` accessor — there is
+  // no public constructor or instanceof check. Reading `'value' in v` on any
+  // POJO would also pass, but the hook's call site already narrows the type;
+  // this guard exists to dispatch between the two implementation paths, not
+  // to validate untrusted input.
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    'value' in (v as Record<string, unknown>)
+  )
+}