@rootnative/inertia 0.0.9 → 0.0.11

package/src/transitions/resolve.ts

@@ -6,8 +6,10 @@ import {
   withSpring,
   withTiming,
 } from 'react-native-reanimated'
+import { DEFAULT_TIMING_DURATION } from './constants'
 import { ensureWorkletEasing } from './easing'
 import { springToReanimated } from './spring'
+import { warnOnce } from '../internal/warnOnce'
 import {
   type DecayTransition,
   type RepeatConfig,
@@ -37,8 +39,6 @@ export type CallbackFactory = (
   step: number | undefined,
 ) => AnimationCallback | undefined
 
-const DEFAULT_TIMING_DURATION = 250
-
 function buildSpring(
   cfg: SpringTransition,
   toValue: number | string,
@@ -94,26 +94,101 @@ function buildOne(
   return buildSpring(cfg as SpringTransition, toValue, cb)
 }
 
+/**
+ * Normalised repeat: `count` is the total number of iterations
+ * (`Number.POSITIVE_INFINITY` for `'infinite'`), `alternate` is the resolved
+ * flag, `explicitAlternate` says whether the caller set `alternate` by hand.
+ */
+export interface NormalizedRepeat {
+  count: number
+  alternate: boolean
+  explicitAlternate: boolean
+}
+
+/**
+ * Reduce the three public `repeat` shapes to one record, or `undefined` when
+ * the animation runs once. A count below `1` is treated as "run once" and
+ * warns in dev: Reanimated's `withRepeat` reads `0` and negative counts as
+ * endless, so forwarding them would turn `repeat: 0` into an infinite loop.
+ */
+export function normalizeRepeat(
+  repeat: RepeatConfig | undefined,
+): NormalizedRepeat | undefined {
+  if (repeat === undefined) return undefined
+  if (repeat === 'infinite') {
+    return {
+      count: Number.POSITIVE_INFINITY,
+      alternate: true,
+      explicitAlternate: false,
+    }
+  }
+  const rawCount = typeof repeat === 'number' ? repeat : repeat.count
+  const alternate = typeof repeat === 'number' ? true : repeat.alternate
+  if (rawCount === 'infinite') {
+    return {
+      count: Number.POSITIVE_INFINITY,
+      alternate: alternate ?? true,
+      explicitAlternate: alternate !== undefined,
+    }
+  }
+  if (!(rawCount >= 1)) {
+    warnOnce(
+      `repeat-count:${String(rawCount)}`,
+      `[inertia] repeat count ${String(rawCount)} is below 1 — the ` +
+        `animation runs once. Use \`repeat: 2\` or more to repeat, or ` +
+        `\`repeat: 'infinite'\`. (Reanimated reads a count of 0 as endless, ` +
+        `so it is not forwarded.)`,
+    )
+    return undefined
+  }
+  return {
+    count: rawCount,
+    alternate: alternate ?? true,
+    explicitAlternate: alternate !== undefined,
+  }
+}
+
+/**
+ * Total number of iterations an animation built from `repeat` runs, including
+ * the first pass. `1` when there is no repeat or the count is below 1;
+ * `Number.POSITIVE_INFINITY` for `'infinite'`.
+ */
+export function repeatIterationsOf(repeat: RepeatConfig | undefined): number {
+  return normalizeRepeat(repeat)?.count ?? 1
+}
+
 /**
  * Wrap an animation in `withRepeat` per the unified `repeat` shape:
  *   - `number`              → finite count, alternating direction
  *   - `'infinite'`          → endless, alternating direction
  *   - `{ count, alternate }`→ explicit; `alternate` defaults to `true`
+ *
+ * Pass `{ sequence: true }` when `animation` is a `withSequence` result.
+ * Reanimated's `reverse` flag only swaps the wrapped animation's `toValue`,
+ * which a sequence ignores — it restarts at step 0 on every pass — so the
+ * flag is not forwarded for sequences. An explicit `alternate: true` on a
+ * sequence warns in dev; write the reverse steps into the sequence instead.
  */
 export function applyRepeat(
   animation: unknown,
   repeat: RepeatConfig | undefined,
+  options?: { sequence?: boolean },
 ) {
-  if (repeat === undefined) return animation
-  if (repeat === 'infinite') {
-    return withRepeat(animation as never, -1, true)
-  }
-  if (typeof repeat === 'number') {
-    return withRepeat(animation as never, repeat, true)
+  const r = normalizeRepeat(repeat)
+  if (r === undefined) return animation
+  const count = Number.isFinite(r.count) ? r.count : -1
+  if (options?.sequence) {
+    if (r.explicitAlternate && r.alternate) {
+      warnOnce(
+        'repeat-sequence-alternate',
+        '[inertia] repeat.alternate has no effect on a sequence — Reanimated ' +
+          'restarts a sequence at its first step on every pass. Append the ' +
+          'reverse steps to the sequence to alternate.',
+      )
+    }
+    return withRepeat(animation as never, count, false)
   }
-  const count = repeat.count === 'infinite' ? -1 : repeat.count
-  const alternate = repeat.alternate ?? true
-  return withRepeat(animation as never, count, alternate)
+  return withRepeat(animation as never, count, r.alternate)
 }
 
 /**

package/src/transitions/resolveSequence.ts

@@ -1,4 +1,4 @@
-import { withSequence } from 'react-native-reanimated'
+import { withSequence, withTiming } from 'react-native-reanimated'
 import {
   applyRepeat,
   repeatOf,
@@ -13,6 +13,18 @@ import {
   type TransitionConfig,
 } from '../types'
 
+/** A zero-length timing, for a snapped step inside an animated sequence. */
+const INSTANT = { duration: 0 } as const
+
+/**
+ * True when a resolved step is a bare target rather than a Reanimated
+ * animation object. `buildOne` returns the target itself for `no-animation`,
+ * which is what the reduced-motion gate collapses every step to.
+ */
+function isSnapped(step: unknown): step is number | string {
+  return typeof step === 'number' || typeof step === 'string'
+}
+
 /**
  * True when the value is a `{ to, ...transitionOverride }` sequence step.
  * Plain numbers and plain transition objects fail this check.
@@ -37,6 +49,12 @@ function isStepObject<V>(
  *   3. array of either   → `withSequence` of resolved steps, with the
  *      top-level `repeat` applied at the **sequence level** (not per step).
  *      Per-step `repeat` overrides remain step-local.
+ *
+ * `withSequence` writes a `finished` flag onto each argument it is handed, so
+ * a bare target throws `Cannot create property 'finished' on number` and takes
+ * the whole render down with it. Two paths produce bare targets, and both are
+ * handled below rather than at the call site: reduced motion (every step) and
+ * a per-step `{ type: 'no-animation' }` override (some steps).
  */
 export function resolveAnimatableValue<V extends number | string>(
   value: AnimatableValue<V>,
@@ -49,8 +67,32 @@ export function resolveAnimatableValue<V extends number | string>(
     const animations = steps.map((step, i) =>
       resolveStep(step, stepBase, factory?.('step', i)),
     )
-    const seq = withSequence(...(animations as never[]))
-    return applyRepeat(seq, base ? repeatOf(base) : undefined)
+    // The reduced-motion gate. `mergeTransition` hands a `no-animation` base
+    // back untouched for every step, so the whole sequence is a snap and there
+    // is nothing to sequence. Settle on the last step — where the sequence
+    // would have ended. `repeat` and `delay` are already dropped for
+    // `no-animation` (`repeatOf` and `delayOf` both return `undefined`), so
+    // nothing needs to wrap this.
+    //
+    // Read off the config rather than sniffing the resolved values: under the
+    // Jest mock `withSpring` and `withTiming` also return bare targets, so a
+    // shape test reports every sequence as snapped and the gate stops being
+    // observable in either direction.
+    if (stepBase?.type === 'no-animation' && animations.length > 0) {
+      return animations[animations.length - 1]
+    }
+    // A step that declares `{ type: 'no-animation' }` inside a sequence that
+    // otherwise animates resolves to a bare target of its own. The step still
+    // owns its slot in the order, so it becomes an instant timing rather than
+    // being dropped.
+    const seq = withSequence(
+      ...(animations.map((a) =>
+        isSnapped(a) ? withTiming(a as number, INSTANT) : a,
+      ) as never[]),
+    )
+    return applyRepeat(seq, base ? repeatOf(base) : undefined, {
+      sequence: true,
+    })
   }
   const step = value as SequenceStep<V>
   const cb = factory?.('animation', undefined)

package/src/transitions/runtime.ts

@@ -4,12 +4,12 @@ import {
   withSpring,
   withTiming,
 } from 'react-native-reanimated'
+import { DEFAULT_TIMING_DURATION } from './constants'
+import { unwrapEasingFactory } from './easing'
 import { springToReanimated } from './spring'
 import { type AnimationCallback } from './resolve'
 import { type TransitionConfig } from '../types'
 
-const DEFAULT_TIMING_DURATION = 250
-
 /**
  * Worklet-safe single-step animation builder. Mirrors a subset of
  * `resolveTransition` for the UI-thread path where the transition config is
@@ -58,13 +58,10 @@ export function buildReleaseAnimation(
   }
   if (transition.type === 'timing') {
     // Reanimated 4's `Easing.bezier(...)` returns an `EasingFunctionFactory`
-    // rather than the function itself. Unwrap inline so consumers calling
+    // rather than the function itself. Unwrap so consumers calling
     // `buildReleaseAnimation` from a gesture worklet don't have to.
     const e = transition.easing
-    const easingFn =
-      e && typeof e === 'object' && 'factory' in e
-        ? e.factory()
-        : (e ?? Easing.inOut(Easing.ease))
+    const easingFn = e ? unwrapEasingFactory(e) : Easing.inOut(Easing.ease)
     return withTiming(
       toValue,
       {

package/src/transitions/spring.ts

@@ -28,6 +28,13 @@ export const DEFAULT_SPRING: Required<
  * 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.
+ *
+ * Settle control is deliberately absent: Reanimated 4 settles springs on an
+ * internal `energyThreshold` and ignores Reanimated 3's `restSpeedThreshold`
+ * / `restDisplacementThreshold`. Inertia surfaced those two names through
+ * `0.0.9`, where they were silently inert — do not re-add them. If a settle
+ * knob is ever needed, expose Reanimated 4's `overshootClamping` or
+ * `energyThreshold`, which the runtime actually reads.
  */
 export function springToReanimated(t: SpringTransition) {
   'worklet'
@@ -36,7 +43,5 @@ export function springToReanimated(t: SpringTransition) {
     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

@@ -5,6 +5,7 @@ import {
   type Ref,
 } from 'react'
 import { type BoxShadowValue, type StyleProp } from 'react-native'
+import { type AnimatedProps } from 'react-native-reanimated'
 
 /**
  * A single animation step's destination, optionally overriding the transition
@@ -31,8 +32,6 @@ export interface SpringTransition {
   friction?: number
   mass?: number
   velocity?: number
-  restSpeedThreshold?: number
-  restDisplacementThreshold?: number
   delay?: number
   repeat?: RepeatConfig
 }
@@ -130,6 +129,15 @@ export type TransitionInput = TransitionConfig | TransitionName
 
 /**
  * Repeat config — one shape, not three flags. Default `alternate: true`.
+ *
+ * `count` is the total number of iterations, including the first pass, so
+ * `repeat: 2` plays the animation twice. A count below `1` runs the animation
+ * once and warns in dev.
+ *
+ * `alternate` reverses direction on every other pass for a single-value
+ * animation. It has no effect on a sequence (an array target): Reanimated
+ * restarts a sequence at its first step on every pass. Append the reverse
+ * steps to the sequence to alternate.
  */
 export type RepeatConfig =
   | number
@@ -548,6 +556,14 @@ export interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
  * Props of a Motion primitive for a given underlying component `C` and a
  * concrete variants map `V`: the component's own props (minus `style`, which
  * we replace with an animated style) intersected with the Motion props.
+ *
+ * `style` is taken from `AnimatedProps<…>`, not from `C` directly, because a
+ * Motion primitive renders `Animated.createAnimatedComponent(C)` — so the
+ * styles it accepts are the ones that animated component accepts. Reanimated
+ * 4.5 brands what `useAnimatedStyle` returns, and `ComponentProps<C>['style']`
+ * rejects a branded value, which would have made the sanctioned escape hatch
+ * (Principle 2: own your `useAnimatedStyle` over Inertia-driven shared values,
+ * then pass it to a `Motion.*` primitive) require a cast at every call site.
  */
 export type MotionComponentProps<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -555,7 +571,11 @@ export type MotionComponentProps<
   V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>,
 > = Omit<ComponentProps<C>, 'style'> &
   MotionProps<ComponentProps<C>, V> & {
-    style?: ComponentProps<C>['style']
+    style?: AnimatedProps<ComponentProps<C>> extends {
+      style?: infer S
+    }
+      ? S
+      : ComponentProps<C>['style']
     ref?: Ref<unknown>
   }
 

package/src/values/extrapolation.ts

@@ -0,0 +1,21 @@
+import { Extrapolation } from 'react-native-reanimated'
+
+/**
+ * Extrapolation behavior at the edges of the input range. Mirrors
+ * Reanimated's enum so consumers don't need a separate import.
+ *
+ * - `'clamp'` (default) — output stays pinned at the first/last value
+ *   outside the input range. Matches Framer Motion's default.
+ * - `'identity'` — return the input unchanged outside the range.
+ * - `'extend'` — continue the linear slope beyond the range.
+ */
+export type ExtrapolationMode = 'clamp' | 'identity' | 'extend'
+
+/** Map the public mode name to Reanimated's `Extrapolation` enum. */
+export function mapExtrapolation(
+  mode: ExtrapolationMode | undefined,
+): Extrapolation {
+  if (mode === 'identity') return Extrapolation.IDENTITY
+  if (mode === 'extend') return Extrapolation.EXTEND
+  return Extrapolation.CLAMP
+}

package/src/values/index.ts

@@ -8,6 +8,7 @@ export {
 } from './useColorCascade'
 export {
   useColorTransition,
+  type ColorStyle,
   type ColorStyleKey,
   type UseColorTransitionOptions,
 } from './useColorTransition'
@@ -36,6 +37,8 @@ export {
   useShadow,
   type BoxShadowLayer,
   type ShadowConfig,
+  type ShadowStyle,
   type UseShadowOptions,
 } from './useShadow'
+export { useTranslateStyle, type TranslateStyle } from './useTranslateStyle'
 export { useVariants } from './useVariants'

package/src/values/useColorCascade.ts

@@ -4,7 +4,7 @@ import {
   useAnimatedStyle,
   type SharedValue,
 } from 'react-native-reanimated'
-import type { ColorStyleKey } from './useColorTransition'
+import type { ColorStyle, ColorStyleKey } from './useColorTransition'
 
 /**
  * One layer in a color cascade: its own `progress` shared value (0→1) and the
@@ -70,7 +70,7 @@ export function useColorCascade(
   rest: string,
   layers: readonly ColorCascadeLayer[],
   options?: UseColorCascadeOptions,
-): ReturnType<typeof useAnimatedStyle> {
+): ColorStyle {
   const key = options?.key ?? 'backgroundColor'
 
   // Resolve the layer chain into two flat arrays the worklet closes over — the
@@ -121,5 +121,5 @@ export function useColorCascade(
       )
     }
     return { [key]: acc }
-  })
+  }) as unknown as ColorStyle
 }

package/src/values/useColorTransition.ts

@@ -20,6 +20,21 @@ export type ColorStyleKey =
   | 'tintColor'
   | 'shadowColor'
 
+/**
+ * A one-key colour style fragment, as returned by {@link useColorTransition}
+ * and {@link useColorCascade}.
+ *
+ * Deliberately **not** `ReturnType<typeof useAnimatedStyle>`. Reanimated 4.5
+ * brands that value (`AnimatedStyleHandle`), and a branded type is rejected
+ * inside a `StyleProp` array — so every call site would need a cast, which is
+ * the defect `InterpolatedStyle` was introduced to remove in `0.0.9`. The brand
+ * is compile-time only, so the runtime value is unchanged.
+ *
+ * Optional per key because which slot is filled is chosen at run time from
+ * `options.key`; exactly one is ever present.
+ */
+export type ColorStyle = { [K in ColorStyleKey]?: string }
+
 export interface UseColorTransitionOptions {
   /**
    * Which style slot the interpolated color is emitted under. Defaults to
@@ -56,7 +71,7 @@ export function useColorTransition(
   progress: SharedValue<number>,
   range: readonly [string, string],
   options?: UseColorTransitionOptions,
-): ReturnType<typeof useAnimatedStyle> {
+): ColorStyle {
   // Resolve the slot key once on the JS thread so the worklet body
   // consumes a single string literal — consistent with the JS-thread
   // resolver principle that keeps `Object.keys`-style walks off the UI
@@ -68,5 +83,5 @@ export function useColorTransition(
   return useAnimatedStyle(() => {
     'worklet'
     return { [key]: interpolateColor(progress.value, [0, 1], [from, to]) }
-  })
+  }) as unknown as ColorStyle
 }

package/src/values/useGesture.ts

@@ -1,11 +1,11 @@
-import { useCallback, useMemo } from 'react'
+import { useCallback, useEffect, useMemo } from 'react'
 import { useSharedValue, type SharedValue } from 'react-native-reanimated'
 import {
   resolveNamedTransitionProp,
   useNamedTransitions,
   useShouldReduceMotion,
 } from '../config'
-import { isFocusVisible } from '../gestures'
+import { installFocusVisibility, isFocusVisible } from '../gestures'
 import { isTopLevelTransition, resolveTransition } from '../transitions'
 import {
   type GestureLayerTransitions,
@@ -110,6 +110,13 @@ export function useGesture(
   // the callbacks below only ever see concrete configs.
   const resolved = resolveNamedTransitionProp(transition, useNamedTransitions())
 
+  // The web modality listeners behind `focusVisible` attach on mount — see
+  // `focusVisibility.ts` for why mount time is early enough and import time
+  // is not an option.
+  useEffect(() => {
+    installFocusVisibility()
+  }, [])
+
   const setLayer = useCallback(
     (sv: SharedValue<number>, layer: LayerName, target: 0 | 1) => {
       const cfg = shouldReduceMotion

package/src/values/useInterpolatedStyle.ts

@@ -1,14 +1,14 @@
 import { useMemo } from 'react'
 import type { ImageStyle, TextStyle, ViewStyle } from 'react-native'
 import {
-  Extrapolation,
   interpolate,
   interpolateColor,
   useAnimatedStyle,
   type SharedValue,
 } from 'react-native-reanimated'
+import { warnOnce } from '../internal/warnOnce'
+import { mapExtrapolation, type ExtrapolationMode } from './extrapolation'
 import type { ColorStyleKey } from './useColorTransition'
-import type { ExtrapolationMode } from './useTransform'
 
 /**
  * Numeric style keys `useInterpolatedStyle` can emit directly (not lifted into
@@ -158,12 +158,6 @@ function evenlySpaced(count: number): number[] {
   return out
 }
 
-function mapExtrapolation(mode: ExtrapolationMode | undefined): Extrapolation {
-  if (mode === 'identity') return Extrapolation.IDENTITY
-  if (mode === 'extend') return Extrapolation.EXTEND
-  return Extrapolation.CLAMP
-}
-
 /**
  * Order-preserving structural signature of the map + options. Unlike
  * `stableSig` (which sorts keys), this walks `map` in insertion order because
@@ -202,8 +196,9 @@ function buildEntries(
         ? [0, 1]
         : evenlySpaced(output.length)
 
-    if (__DEV__ && explicitInput && explicitInput.length !== output.length) {
-      console.warn(
+    if (explicitInput && explicitInput.length !== output.length) {
+      warnOnce(
+        `interpolated-style-range:${String(key)}:${explicitInput.length}:${output.length}`,
         `[inertia] useInterpolatedStyle: inputRange has ${explicitInput.length} stops but the "${String(
           key,
         )}" output has ${output.length}. They must match — interpolation results are undefined otherwise.`,
@@ -313,6 +308,13 @@ export function useInterpolatedStyle<K extends keyof InterpolatedStyleMap>(
   // The worklet builds a `Record<string, unknown>` by design — the emitted keys
   // are only known from `entries` at run time. `InterpolatedStyle<K>` is the
   // static statement of that same shape, so the cast is where the two meet.
+  //
+  // Through `unknown` because Reanimated 4.5 brands what `useAnimatedStyle`
+  // returns (`AnimatedStyleHandle`), and a branded type no longer overlaps a
+  // plain style object. Erasing the brand is the point of this hook: the
+  // returned value has to drop into a `StyleProp<ViewStyle>` array without the
+  // consumer casting. The brand is compile-time only, so the runtime value is
+  // unchanged — it is still the animated style Reanimated produced.
   return useAnimatedStyle(() => {
     'worklet'
     const out: Record<string, unknown> = {}
@@ -343,7 +345,5 @@ export function useInterpolatedStyle<K extends keyof InterpolatedStyleMap>(
     }
     if (transform.length > 0) out.transform = transform
     return out
-  }) as InterpolatedStyle<K>
+  }) as unknown as InterpolatedStyle<K>
 }
-
-declare const __DEV__: boolean

package/src/values/useShadow.ts

@@ -1,3 +1,4 @@
+import { useMemo } from 'react'
 import {
   interpolate,
   interpolateColor,
@@ -9,6 +10,7 @@ import {
   resolveBoxShadowInput,
   type BoxShadowLayer,
 } from '../internal/boxShadow'
+import { stableSig } from '../transitions/sig'
 
 export type { BoxShadowLayer }
 
@@ -41,6 +43,22 @@ export interface ShadowConfig {
   boxShadow?: string | readonly BoxShadowLayer[]
 }
 
+/**
+ * The style fragment {@link useShadow} returns: the native shadow keys plus the
+ * CSS `boxShadow`, each present only when the paired configs drive it.
+ *
+ * Deliberately **not** `ReturnType<typeof useAnimatedStyle>` — see
+ * {@link ColorStyle} for why the brand is erased here.
+ */
+export type ShadowStyle = {
+  shadowColor?: string
+  shadowOffset?: { width: number; height: number }
+  shadowOpacity?: number
+  shadowRadius?: number
+  elevation?: number
+  boxShadow?: string
+}
+
 export interface UseShadowOptions {
   /** Shadow state at `progress === 0`. */
   from: ShadowConfig
@@ -95,7 +113,7 @@ export function useShadow({
   from,
   to,
   progress,
-}: UseShadowOptions): ReturnType<typeof useAnimatedStyle> {
+}: UseShadowOptions): ShadowStyle {
   // Resolve presence + endpoints once on the JS thread so the worklet body
   // consumes flat literals — consistent with the JS-thread resolver
   // principle that keeps `Object.keys`-style walks off the UI thread.
@@ -113,13 +131,22 @@ export function useShadow({
   // boxShadow layers: parse/pair once on the JS thread into flat records so
   // the worklet only interpolates numbers/colors and concatenates — no
   // frame-time parsing. `[]` when neither side provides the key.
-  const boxShadowPairs =
-    from.boxShadow !== undefined || to.boxShadow !== undefined
-      ? pairBoxShadowLayers(
-          resolveBoxShadowInput(from.boxShadow),
-          resolveBoxShadowInput(to.boxShadow),
-        )
-      : []
+  //
+  // Memoised on the inputs' structure: the pairs array is the one non-scalar
+  // the worklet captures, and `from` / `to` are usually inline literals, so
+  // without the memo a fresh array each render would rebuild the worklet.
+  const boxShadowSig = stableSig([from.boxShadow, to.boxShadow])
+  const boxShadowPairs = useMemo(
+    () =>
+      from.boxShadow !== undefined || to.boxShadow !== undefined
+        ? pairBoxShadowLayers(
+            resolveBoxShadowInput(from.boxShadow),
+            resolveBoxShadowInput(to.boxShadow),
+          )
+        : [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [boxShadowSig],
+  )
 
   const opacityFrom = from.shadowOpacity ?? 0
   const opacityTo = to.shadowOpacity ?? 0
@@ -187,5 +214,5 @@ export function useShadow({
       out.boxShadow = css
     }
     return out
-  })
+  }) as unknown as ShadowStyle
 }