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

package/src/motion/createMotionComponent.tsx

@@ -67,6 +67,9 @@ const NUMERIC_TOP_LEVEL_KEYS = [
   'width',
   'height',
   'borderRadius',
+  'shadowOpacity',
+  'shadowRadius',
+  'elevation',
 ] as const
 
 // Color-valued keys. Reanimated's value setter detects color strings and
@@ -83,8 +86,17 @@ const COLOR_KEYS = [
   'borderColor',
   'color',
   'tintColor',
+  'shadowColor',
 ] as const
 
+// Synthetic axes for the `shadowOffset: { width, height }` nested-object style
+// prop. RN doesn't surface these as top-level keys; the worklet recomposes
+// `shadowOffset` from the two synthetic SVs before emitting the style. The
+// consumer's animate value (`shadowOffset: { width, height }`) decomposes into
+// these at the activation / value-driving boundary; consumers don't write
+// these keys directly.
+const SHADOW_OFFSET_KEYS = ['shadowOffsetWidth', 'shadowOffsetHeight'] as const
+
 /**
  * Per-effect transform-group coordinator. Counts how many transform-axis
  * terminal callbacks are still pending; when the last one fires, the
@@ -97,12 +109,15 @@ const ALL_KEYS = [
   ...TRANSFORM_KEYS,
   ...NUMERIC_TOP_LEVEL_KEYS,
   ...COLOR_KEYS,
+  ...SHADOW_OFFSET_KEYS,
 ] as const
 type AnimatableKey = (typeof ALL_KEYS)[number]
 type TransformKey = (typeof TRANSFORM_KEYS)[number]
+type ShadowOffsetKey = (typeof SHADOW_OFFSET_KEYS)[number]
 
 const TRANSFORM_KEY_SET = new Set<AnimatableKey>(TRANSFORM_KEYS)
 const COLOR_KEY_SET = new Set<AnimatableKey>(COLOR_KEYS)
+const SHADOW_OFFSET_KEY_SET = new Set<AnimatableKey>(SHADOW_OFFSET_KEYS)
 
 const GESTURE_LAYER_NAMES = [
   'hovered',
@@ -131,6 +146,9 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   width: 0,
   height: 0,
   borderRadius: 0,
+  shadowOpacity: 0,
+  shadowRadius: 0,
+  elevation: 0,
   // 'transparent' is the only safe universal default for colors: it works as
   // an initial seed for any color animation (no jarring opaque flash on mount
   // when `initial` is omitted) and rgba(0,0,0,0) interpolates cleanly into
@@ -139,6 +157,9 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   borderColor: 'transparent',
   color: 'transparent',
   tintColor: 'transparent',
+  shadowColor: 'transparent',
+  shadowOffsetWidth: 0,
+  shadowOffsetHeight: 0,
 }
 
 function transitionFor<S>(
@@ -237,18 +258,12 @@ export function createMotionComponent<C extends ComponentType<any>>(
       variantKey,
     )
 
-    const animateRecord = (resolvedAnimate ?? {}) as Partial<
-      Record<AnimatableKey, AnimatableValue<number | string>>
-    >
+    const animateRecord = (resolvedAnimate ?? {}) as InternalAnimateRecord
     const initialRecord =
       initial && initial !== false
-        ? (initial as Partial<Record<AnimatableKey, number | string>>)
+        ? (initial as InternalInitialRecord)
         : undefined
-    const exitRecord = exit
-      ? (exit as Partial<
-          Record<AnimatableKey, AnimatableValue<number | string>>
-        >)
-      : undefined
+    const exitRecord = exit ? (exit as InternalAnimateRecord) : undefined
 
     // Gesture sub-state activation tracked as JS state. Activation flips drive
     // the per-layer progress shared values (0↔1); they intentionally do NOT
@@ -268,16 +283,12 @@ export function createMotionComponent<C extends ComponentType<any>>(
     const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
     if (activeKeysRef.current === null) {
       const touched = new Set<AnimatableKey>()
-      for (const k of ALL_KEYS) {
-        if (k in animateRecord) touched.add(k)
-        if (initialRecord && k in initialRecord) touched.add(k)
-      }
+      collectTouchedKeys(touched, animateRecord)
+      if (initialRecord) collectTouchedKeys(touched, initialRecord)
       if (variants) {
         for (const variant of Object.values(variants) as object[]) {
           if (!variant) continue
-          for (const k of ALL_KEYS) {
-            if (k in variant) touched.add(k)
-          }
+          collectTouchedKeys(touched, variant as Record<string, unknown>)
         }
       }
       if (gesture) {
@@ -288,23 +299,43 @@ export function createMotionComponent<C extends ComponentType<any>>(
           gesture.hovered,
         ] as Array<object | undefined>) {
           if (!subState) continue
-          for (const k of ALL_KEYS) {
-            if (k in subState) touched.add(k)
-          }
-        }
-      }
-      if (exitRecord) {
-        for (const k of ALL_KEYS) {
-          if (k in exitRecord) touched.add(k)
+          collectTouchedKeys(touched, subState as Record<string, unknown>)
         }
       }
+      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)),
+    )
 
     const sharedValues = useAnimatableSharedValues((key) => {
+      // Shadow offset synthetics seed from the corresponding axis on the
+      // `shadowOffset: { width, height }` source — the consumer doesn't write
+      // `shadowOffsetWidth` / `shadowOffsetHeight` directly. Fall back to the
+      // generic resting default when neither initial nor animate touched it.
+      if (SHADOW_OFFSET_KEY_SET.has(key)) {
+        const axis = shadowOffsetAxisFor(key as ShadowOffsetKey)
+        if (initial === false) {
+          return (
+            shadowOffsetAxisValue(animateRecord.shadowOffset, axis) ??
+            DEFAULT_RESTING[key]
+          )
+        }
+        return (
+          shadowOffsetAxisValue(
+            initialRecord?.shadowOffset as
+              | { width?: number; height?: number }
+              | undefined,
+            axis,
+          ) ??
+          shadowOffsetAxisValue(animateRecord.shadowOffset, axis) ??
+          DEFAULT_RESTING[key]
+        )
+      }
       if (initial === false) {
         const a = animateRecord[key]
         return restValue(a) ?? DEFAULT_RESTING[key]
@@ -398,7 +429,18 @@ export function createMotionComponent<C extends ComponentType<any>>(
         transformPending > 0 ? { remaining: transformPending } : undefined
 
       for (const key of ALL_KEYS) {
-        const target = baseRecord[key]
+        // Shadow offset synthetics read their target from the nested
+        // `shadowOffset: { width, height }` source on `baseRecord` — the
+        // animate / exit record never has `shadowOffsetWidth` etc. on it
+        // directly. The synthetic transition follows the same `shadowOffset`
+        // top-level transition entry (no per-axis split).
+        const target: AnimatableValue<number | string> | undefined =
+          SHADOW_OFFSET_KEY_SET.has(key)
+            ? shadowOffsetAxisValue(
+                baseRecord.shadowOffset,
+                shadowOffsetAxisFor(key as ShadowOffsetKey),
+              )
+            : baseRecord[key]
         if (target === undefined) continue
         // Reduced-motion overrides every per-key transition (and any nested
         // sequence-step transition) with `no-animation`, which the resolver
@@ -407,7 +449,12 @@ export function createMotionComponent<C extends ComponentType<any>>(
         // state" expectation.
         const cfg = shouldReduceMotion
           ? ({ type: 'no-animation' } as const)
-          : transitionFor(key, transition)
+          : transitionFor(
+              SHADOW_OFFSET_KEY_SET.has(key)
+                ? ('shadowOffset' as keyof typeof baseRecord)
+                : key,
+              transition,
+            )
         if (isExiting) pending++
         const factory = makeKeyCallbackFactory(
           key,
@@ -487,8 +534,14 @@ export function createMotionComponent<C extends ComponentType<any>>(
     const animatedStyle = useAnimatedStyle(() => {
       const activeKeys = activeKeysRef.current!
       const hasTransform = hasTransformRef.current
+      const hasShadowOffset = hasShadowOffsetRef.current
       const out: Record<string, unknown> = {}
       const transform: Array<Record<string, unknown>> = []
+      // shadow-offset reassembly buffers. The two synthetic axis SVs feed in
+      // here and the recomposed `{ width, height }` object lands on `out`
+      // after the loop so RN gets a single `shadowOffset` style prop.
+      let shadowOffsetW = 0
+      let shadowOffsetH = 0
 
       // Read each progress SV exactly once so the chain below sees a coherent
       // snapshot for this frame. Reading them on the UI thread is cheap.
@@ -550,11 +603,18 @@ export function createMotionComponent<C extends ComponentType<any>>(
           transform.push(
             ROTATION_KEYS.has(key) ? { [key]: `${v}deg` } : { [key]: v },
           )
+        } else if (key === 'shadowOffsetWidth') {
+          shadowOffsetW = v as number
+        } else if (key === 'shadowOffsetHeight') {
+          shadowOffsetH = v as number
         } else {
           out[key] = v
         }
       }
       if (hasTransform) out.transform = transform
+      if (hasShadowOffset) {
+        out.shadowOffset = { width: shadowOffsetW, height: shadowOffsetH }
+      }
       return out
     })
 
@@ -643,12 +703,22 @@ function useAnimatableSharedValues(
   const width = useSharedValue<number | string>(init('width'))
   const height = useSharedValue<number | string>(init('height'))
   const borderRadius = useSharedValue<number | string>(init('borderRadius'))
+  const shadowOpacity = useSharedValue<number | string>(init('shadowOpacity'))
+  const shadowRadius = useSharedValue<number | string>(init('shadowRadius'))
+  const elevation = useSharedValue<number | string>(init('elevation'))
   const backgroundColor = useSharedValue<number | string>(
     init('backgroundColor'),
   )
   const borderColor = useSharedValue<number | string>(init('borderColor'))
   const color = useSharedValue<number | string>(init('color'))
   const tintColor = useSharedValue<number | string>(init('tintColor'))
+  const shadowColor = useSharedValue<number | string>(init('shadowColor'))
+  const shadowOffsetWidth = useSharedValue<number | string>(
+    init('shadowOffsetWidth'),
+  )
+  const shadowOffsetHeight = useSharedValue<number | string>(
+    init('shadowOffsetHeight'),
+  )
 
   const ref = useRef<SharedValueMap | null>(null)
   if (ref.current === null) {
@@ -665,10 +735,16 @@ function useAnimatableSharedValues(
       width,
       height,
       borderRadius,
+      shadowOpacity,
+      shadowRadius,
+      elevation,
       backgroundColor,
       borderColor,
       color,
       tintColor,
+      shadowColor,
+      shadowOffsetWidth,
+      shadowOffsetHeight,
     }
   }
   return ref.current
@@ -791,6 +867,65 @@ function makeKeyCallbackFactory(
   }
 }
 
+/**
+ * Internal shape of the `animate` / `exit` record after the cast, widened to
+ * include the `shadowOffset: { width, height }` nested-object source. The
+ * nested object decomposes into the `shadowOffsetWidth` / `shadowOffsetHeight`
+ * synthetic axes downstream; consumers don't see the synthetics.
+ *
+ * v0.1 contract: `shadowOffset` accepts a single `{ width, height }` literal
+ * (no sequences, no `{ to }` step objects, no array keyframes). Sequence
+ * forms on the nested axes can land in v0.2 if real consumers ask for them.
+ */
+type InternalAnimateRecord = Partial<
+  Record<AnimatableKey, AnimatableValue<number | string>>
+> & {
+  shadowOffset?: { width?: number; height?: number }
+}
+
+type InternalInitialRecord = Partial<Record<AnimatableKey, number | string>> & {
+  shadowOffset?: { width?: number; height?: number }
+}
+
+/**
+ * Resolve a `shadowOffsetWidth` / `shadowOffsetHeight` synthetic key to the
+ * axis it represents on the nested-object source.
+ */
+function shadowOffsetAxisFor(key: ShadowOffsetKey): 'width' | 'height' {
+  return key === 'shadowOffsetWidth' ? 'width' : 'height'
+}
+
+/**
+ * Read a single axis off a `shadowOffset: { width, height }` source. Returns
+ * `undefined` when the source is absent or the axis isn't set, so callers can
+ * fall back to the next source in the precedence chain.
+ */
+function shadowOffsetAxisValue(
+  source: { width?: number; height?: number } | undefined,
+  axis: 'width' | 'height',
+): number | undefined {
+  return source?.[axis]
+}
+
+/**
+ * Populate `touched` with the `AnimatableKey`s mentioned in `record`. Direct
+ * matches (e.g. `opacity`, `width`) come from the key iteration; the nested
+ * `shadowOffset` source decomposes into the two `shadowOffset*` synthetics.
+ */
+function collectTouchedKeys(
+  touched: Set<AnimatableKey>,
+  record: Record<string, unknown>,
+): void {
+  for (const k of ALL_KEYS) {
+    if (k in record) touched.add(k)
+  }
+  if ('shadowOffset' in record && record.shadowOffset) {
+    const so = record.shadowOffset as { width?: unknown; height?: unknown }
+    if (so.width !== undefined) touched.add('shadowOffsetWidth')
+    if (so.height !== undefined) touched.add('shadowOffsetHeight')
+  }
+}
+
 /**
  * Number of sequence steps in an animatable value. `1` for plain values and
  * single-step `{ to }` objects; the array length for keyframe arrays.
@@ -930,6 +1065,17 @@ function resolveGestureLayers(
     if (!subState) continue
     const resolved: Record<string, number | string> = {}
     for (const key of ALL_KEYS) {
+      // Shadow offset synthetics decompose from the nested `shadowOffset:
+      // { width, height }` source on the sub-state, the same as on `animate`.
+      if (SHADOW_OFFSET_KEY_SET.has(key)) {
+        const axis = shadowOffsetAxisFor(key as ShadowOffsetKey)
+        const so = (
+          subState as { shadowOffset?: { width?: number; height?: number } }
+        ).shadowOffset
+        const v = shadowOffsetAxisValue(so, axis)
+        if (v !== undefined) resolved[key] = v
+        continue
+      }
       const raw = (subState as Record<string, unknown>)[key]
       if (raw === undefined) continue
       const t = targetEndValue(raw as AnimatableValue<number | string>)

package/src/transitions/easing.ts

@@ -1,6 +1,7 @@
 // `isWorkletFunction` lives in `react-native-worklets` (the Reanimated 4 peer
 // dep); Reanimated's own re-export is deprecated.
 import { isWorkletFunction } from 'react-native-worklets'
+import { type EasingInput } from '../types'
 
 /**
  * Reanimated 3.9+ validates that easing functions used in nested-transition
@@ -15,17 +16,38 @@ import { isWorkletFunction } from 'react-native-worklets'
  * the consumer's worklets babel plugin (the default Expo/RN setup), the
  * wrapper becomes a real worklet that captures the user fn via closure.
  *
+ * Reanimated 4 changed `Easing.bezier(...)` to return an
+ * `EasingFunctionFactory` (`{ factory: () => EasingFunction }`) rather than
+ * the function itself. The helper accepts both shapes — `EasingFunction` and
+ * `EasingFunctionFactory` — and unwraps the factory automatically so
+ * consumers don't have to call `.factory()` manually.
+ *
  * The user fn must be pure: no JS-thread captured refs, no shared mutable
  * state, no calls to non-worklet APIs.
  */
 export function ensureWorkletEasing(
-  easing: ((t: number) => number) | undefined,
+  easing: EasingInput | undefined,
 ): ((t: number) => number) | undefined {
   if (!easing) return undefined
-  if (isWorkletFunction(easing)) return easing
+  // Reanimated 4 `EasingFunctionFactory` — unwrap via `.factory()` before
+  // checking worklet status, so the wrapped fn (not the factory wrapper)
+  // ends up in the transition config.
+  const fn = isEasingFactory(easing) ? easing.factory() : easing
+  if (isWorkletFunction(fn)) return fn
   const wrapped = (t: number) => {
     'worklet'
-    return easing(t)
+    return fn(t)
   }
   return wrapped
 }
+
+function isEasingFactory(
+  value: EasingInput,
+): value is { factory: () => (t: number) => number } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'factory' in value &&
+    typeof (value as { factory: unknown }).factory === 'function'
+  )
+}

package/src/transitions/index.ts

@@ -1,5 +1,6 @@
 export { resolveTransition, resolveAnimatableValue } from './resolve'
 export { ensureWorkletEasing } from './easing'
 export { isTopLevelTransition, TRANSITION_CONFIG_KEYS } from './keys'
+export { buildReleaseAnimation } from './runtime'
 export { stableSig } from './sig'
 export { DEFAULT_SPRING, springToReanimated } from './spring'

package/src/transitions/runtime.ts

@@ -0,0 +1,63 @@
+import {
+  Easing,
+  withDecay,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated'
+import { springToReanimated } from './spring'
+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
+ * picked at gesture-release time, not at render time.
+ *
+ * Supported: spring / timing / decay / no-animation, single-step only.
+ * Not supported: sequences, top-level repeat, easing-function
+ * auto-worklet-wrapping (pass an already-worklet easing if you need a custom
+ * one — most release transitions don't).
+ *
+ * Use this from gesture worklets (`useDrag` / `usePan` release callbacks, or
+ * any custom `Gesture.Pan().onEnd(() => ...)` worklet) to animate a shared
+ * value with an Inertia transition without the JS round-trip that would lose
+ * the release velocity.
+ *
+ * For decay transitions, `toValue` is ignored — decay decelerates from the
+ * SV's current position via its own physics. Pass `0` if you don't have one.
+ */
+export function buildReleaseAnimation(
+  transition: TransitionConfig,
+  toValue: number,
+): unknown {
+  'worklet'
+  if (transition.type === 'no-animation') return toValue
+  if (transition.type === 'decay') {
+    const cfg: {
+      velocity: number
+      deceleration?: number
+      clamp?: [number, number]
+    } = { velocity: transition.velocity ?? 0 }
+    if (transition.deceleration !== undefined) {
+      cfg.deceleration = transition.deceleration
+    }
+    if (transition.clamp !== undefined) cfg.clamp = transition.clamp
+    return withDecay(cfg)
+  }
+  if (transition.type === 'timing') {
+    // Reanimated 4's `Easing.bezier(...)` returns an `EasingFunctionFactory`
+    // rather than the function itself. Unwrap inline 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))
+    return withTiming(toValue, {
+      duration: transition.duration ?? DEFAULT_TIMING_DURATION,
+      easing: easingFn,
+    })
+  }
+  return withSpring(toValue, springToReanimated(transition))
+}

package/src/transitions/spring.ts

@@ -30,6 +30,7 @@ export const DEFAULT_SPRING: Required<
  * what designers and prior-art consumers expect.
  */
 export function springToReanimated(t: SpringTransition) {
+  'worklet'
   return {
     stiffness: t.tension ?? DEFAULT_SPRING.tension,
     damping: t.friction ?? DEFAULT_SPRING.friction,

package/src/types.ts

@@ -32,10 +32,24 @@ export interface SpringTransition {
   repeat?: RepeatConfig
 }
 
+/**
+ * Easing input accepted by `TimingTransition`. Either a plain easing function
+ * `(t: number) => number` (the pre-Reanimated-4 shape and the shape consumers
+ * author by hand) or an `EasingFunctionFactory` (the Reanimated 4 shape
+ * returned by `Easing.bezier(...)` and similar builders). The resolver
+ * unwraps the factory automatically — consumers don't have to call
+ * `.factory()` themselves.
+ */
+export type EasingFunction = (t: number) => number
+export interface EasingFunctionFactory {
+  factory: () => EasingFunction
+}
+export type EasingInput = EasingFunction | EasingFunctionFactory
+
 export interface TimingTransition {
   type: 'timing'
   duration?: number
-  easing?: (t: number) => number
+  easing?: EasingInput
   delay?: number
   repeat?: RepeatConfig
 }
@@ -192,6 +206,14 @@ export type VariantsMap<C> = Record<string, AnimateStyle<C>>
  * Configure per-layer fade timing via `transition.<stateName>` on the parent
  * primitive (see `GestureLayerTransitions`); without it, layers default to
  * the parent transition or the library default spring.
+ *
+ * **Priority cascade is the only composition mode on this prop.** Non-priority
+ * blends — clamped-max (`Math.max(hover*α, focus*β, press*γ)`, as used by MD3
+ * state-layer haloes), additive accumulation, or any per-key custom blend —
+ * are not expressible declaratively. Drop to `useGesture()` for those: it
+ * returns the four progress shared values and a handler bag, and you write
+ * a `useAnimatedStyle` block with whatever composition you need. The hook's
+ * JSDoc shows the clamped-max halo pattern in full.
  */
 export interface GestureSubStates<C> {
   pressed?: AnimateStyle<C>