@rootnative/inertia 0.0.7 → 0.0.9

package/src/motion/createMotionComponent.tsx

@@ -43,7 +43,9 @@ import {
   useSharedLayout,
 } from '../layout'
 import { usePresence } from '../presence'
+import { useStaggerDelay } from '../stagger'
 import {
+  applyDelay,
   isTopLevelTransition,
   resolveAnimatableValue,
   resolveTransition,
@@ -547,6 +549,13 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // at app start — a runtime toggle takes effect on the next launch.
       const shouldReduceMotion = useShouldReduceMotion()
 
+      // Per-child delay assigned by the nearest <Stagger> ancestor; 0 outside
+      // one. Applied in the value-driving effect, not here: the effect's
+      // closure reads the value current at the render that starts an
+      // animation, and a delay change alone must not re-trigger anything —
+      // so it is deliberately absent from the effect's deps.
+      const staggerDelay = useStaggerDelay()
+
       // Pin the latest `onAnimationEnd` in a ref so the worklet callback always
       // dispatches against the current closure without re-resolving the
       // animation graph. Worklets can read refs via `runOnJS`.
@@ -962,6 +971,22 @@ export function createMotionComponent<C extends ComponentType<any>>(
                 transition,
               )
 
+        // <Stagger> delay for this run, wrapped around each key's fully
+        // resolved animation via `applyDelay` — once per animation, never
+        // merged into the base config (a sequence applies a base `delay` per
+        // step, which would stretch the whole sequence by N × delay). Composes
+        // with a consumer's own `transition.delay`, which `resolveTransition`
+        // has already applied inside.
+        //
+        // Deliberately 0 while exiting (an exit delayed by list position holds
+        // <Presence>'s unmount hostage to the cascade) and under reduced
+        // motion (a snap must not be deferred — same contract as `delayOf`
+        // returning `undefined` for `no-animation`).
+        const runStagger =
+          shouldReduceMotion || isExiting || staggerDelay <= 0
+            ? 0
+            : staggerDelay
+
         // Count transform axes participating in this effect run so the factory
         // can coalesce their terminal callbacks into a single transform-group
         // event. `undefined` when no transform axis is animating, which lets
@@ -996,6 +1021,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
               boxShadowInsets,
               shadowTarget,
               cfg,
+              runStagger,
               makeKeyCallbackFactory(
                 'boxShadow',
                 sharedValues.boxShadow,
@@ -1051,12 +1077,15 @@ export function createMotionComponent<C extends ComponentType<any>>(
           // `'no-animation'` (and so under reduced motion) it is assigned
           // straight into the slot, and the next animation would start from a
           // value that can't be parsed.
-          sharedValues[key].value = resolveAnimatableValue(
-            COLOR_KEY_SET.has(key)
-              ? normalizeAnimatableColorTarget(target)
-              : target,
-            cfg,
-            factory,
+          sharedValues[key].value = applyDelay(
+            resolveAnimatableValue(
+              COLOR_KEY_SET.has(key)
+                ? normalizeAnimatableColorTarget(target)
+                : target,
+              cfg,
+              factory,
+            ),
+            runStagger,
           ) as never
         }
 
@@ -1655,6 +1684,7 @@ function driveBoxShadow(
   insetSlot: SharedValue<boolean[] | null>,
   target: BoxShadowInput,
   cfg: TransitionConfig | undefined,
+  staggerDelay: number,
   factory: CallbackFactory | undefined,
 ): void {
   const currentLayers = payloadToLayers(slot.value as BoxShadowPayload)
@@ -1666,10 +1696,15 @@ function driveBoxShadow(
   if (from.length !== currentLayers.length) slot.value = layersToPayload(from)
   // `resolveTransition` is typed for the scalar surface it was written for;
   // Reanimated itself accepts the structured target and recurses into it.
-  slot.value = resolveTransition(
-    cfg,
-    layersToPayload(to) as unknown as number,
-    factory?.('animation', undefined),
+  // The stagger wrap sits outside, same as the scalar path — this key can't
+  // be a sequence, but keeping the delay out of `cfg` keeps one rule.
+  slot.value = applyDelay(
+    resolveTransition(
+      cfg,
+      layersToPayload(to) as unknown as number,
+      factory?.('animation', undefined),
+    ),
+    staggerDelay,
   ) as AnimatableSlotValue
 }
 

package/src/stagger/Stagger.tsx

@@ -0,0 +1,75 @@
+import { Children, isValidElement, type ReactNode } from 'react'
+import { StaggerContext } from './StaggerContext'
+
+export interface StaggerProps {
+  children?: ReactNode
+  /**
+   * Milliseconds between consecutive children. Child `i` (in render order)
+   * receives a delay of `delay + i * interval`.
+   */
+  interval: number
+  /**
+   * Base delay in milliseconds applied to every child before the interval,
+   * so the whole cascade can start late without pushing the spacing into
+   * each child. Defaults to `0`.
+   */
+  delay?: number
+  /**
+   * Which end of the child list starts the cascade. `'first'` (default)
+   * staggers top-down in render order; `'last'` reverses it, so the final
+   * child animates first.
+   */
+  from?: 'first' | 'last'
+  /**
+   * Turn the stagger on or off in one place. When `false`, every child gets
+   * a delay of `0` — the single-switch escape hatch for "cascade in, but
+   * not back out": pass `enabled={revealed}` and the hide direction snaps
+   * together. Defaults to `true`.
+   */
+  enabled?: boolean
+}
+
+/**
+ * Assign each child a stagger delay from its position, so a list entrance
+ * cascades without every child computing `index * ms` itself.
+ *
+ * The parent owns the timing: reordering, filtering, or reversing the list
+ * re-derives every delay from the new render order, and `enabled` turns the
+ * whole cascade off in one place. Each child slot gets its own provider, so
+ * a `Motion.*` primitive anywhere inside child `i`'s subtree inherits child
+ * `i`'s delay.
+ *
+ * The delay applies to the declarative animations of the `Motion.*`
+ * primitives underneath — the mount animation (`initial` → `animate`) and
+ * any later `animate` change. It deliberately does not delay `gesture`
+ * feedback, `<Presence>` exits, or reduced-motion snaps.
+ *
+ * `<Stagger>` renders no host view — only per-child context providers.
+ */
+export function Stagger({
+  children,
+  interval,
+  delay = 0,
+  from = 'first',
+  enabled = true,
+}: StaggerProps) {
+  // `Children.toArray` drops `null` / `undefined` / booleans, so conditional
+  // children don't leave holes in the cascade, and it assigns stable
+  // element keys that the providers below reuse.
+  const items = Children.toArray(children)
+  const count = items.length
+  return (
+    <>
+      {items.map((child, index) => {
+        const position = from === 'last' ? count - 1 - index : index
+        const childDelay = enabled ? delay + position * interval : 0
+        const key = isValidElement(child) ? (child.key ?? index) : index
+        return (
+          <StaggerContext.Provider key={key} value={childDelay}>
+            {child}
+          </StaggerContext.Provider>
+        )
+      })}
+    </>
+  )
+}

package/src/stagger/StaggerContext.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-child stagger delay in milliseconds, provided by `<Stagger>`. `0`
+ * outside a `<Stagger>` (or under a disabled one), which every consumer
+ * treats as "no stagger".
+ *
+ * Internal wiring — consumers use `<Stagger>`; custom animated components
+ * read the value through `useStaggerDelay()`.
+ */
+export const StaggerContext = createContext(0)
+
+/**
+ * The stagger delay (in milliseconds) assigned to this element's child slot
+ * by the nearest `<Stagger>` ancestor. `0` when there is none, when the
+ * stagger is disabled, or for the first child of a zero-`delay` stagger.
+ *
+ * The `Motion.*` primitives consume this automatically. Custom animated
+ * components built on `resolveTransition` / `resolveAnimatableValue` call
+ * this hook and add the returned value to their animation delay so they
+ * participate in a `<Stagger>` the same way the built-in primitives do.
+ */
+export function useStaggerDelay(): number {
+  return useContext(StaggerContext)
+}

package/src/stagger/index.ts

@@ -0,0 +1,2 @@
+export { Stagger, type StaggerProps } from './Stagger'
+export { useStaggerDelay } from './StaggerContext'

package/src/transitions/index.ts

@@ -1,4 +1,9 @@
-export { resolveTransition, type CallbackFactory } from './resolve'
+export {
+  applyDelay,
+  resolveTransition,
+  type AnimationCallback,
+  type CallbackFactory,
+} from './resolve'
 export { resolveAnimatableValue } from './resolveSequence'
 export { cubicBezier } from './cubicBezier'
 export { ensureWorkletEasing } from './easing'

package/src/transitions/resolve.ts

@@ -116,7 +116,13 @@ export function applyRepeat(
   return withRepeat(animation as never, count, alternate)
 }
 
-function applyDelay(animation: unknown, delay: number | undefined) {
+/**
+ * Wrap an animation in `withDelay`. A missing / zero / negative delay is a
+ * pass-through. Exported for the factory's stagger wrap, which must delay a
+ * fully-resolved animation exactly once — merging the delay into the base
+ * config instead would re-apply it per sequence step.
+ */
+export function applyDelay(animation: unknown, delay: number | undefined) {
   if (!delay || delay <= 0) return animation
   return withDelay(delay, animation as never)
 }

package/src/transitions/runtime.ts

@@ -5,6 +5,7 @@ import {
   withTiming,
 } from 'react-native-reanimated'
 import { springToReanimated } from './spring'
+import { type AnimationCallback } from './resolve'
 import { type TransitionConfig } from '../types'
 
 const DEFAULT_TIMING_DURATION = 250
@@ -26,13 +27,23 @@ const DEFAULT_TIMING_DURATION = 250
  *
  * 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.
+ *
+ * `callback`, when provided, fires once when the animation settles — the same
+ * `(finished) => void` shape Reanimated's `with*` factories accept. It runs on
+ * the UI thread, so bridge to JS with `runOnJS(...)` inside it. For
+ * `no-animation` the callback fires synchronously with `finished: true`, since
+ * a direct assignment has no settle point of its own.
  */
 export function buildReleaseAnimation(
   transition: TransitionConfig,
   toValue: number,
+  callback?: AnimationCallback,
 ): unknown {
   'worklet'
-  if (transition.type === 'no-animation') return toValue
+  if (transition.type === 'no-animation') {
+    if (callback) callback(true, toValue)
+    return toValue
+  }
   if (transition.type === 'decay') {
     const cfg: {
       velocity: number
@@ -43,7 +54,7 @@ export function buildReleaseAnimation(
       cfg.deceleration = transition.deceleration
     }
     if (transition.clamp !== undefined) cfg.clamp = transition.clamp
-    return withDecay(cfg)
+    return withDecay(cfg, callback as never)
   }
   if (transition.type === 'timing') {
     // Reanimated 4's `Easing.bezier(...)` returns an `EasingFunctionFactory`
@@ -54,10 +65,14 @@ export function buildReleaseAnimation(
       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 withTiming(
+      toValue,
+      {
+        duration: transition.duration ?? DEFAULT_TIMING_DURATION,
+        easing: easingFn,
+      },
+      callback as never,
+    )
   }
-  return withSpring(toValue, springToReanimated(transition))
+  return withSpring(toValue, springToReanimated(transition), callback as never)
 }

package/src/values/index.ts

@@ -18,6 +18,7 @@ export {
 } from './useGesture'
 export {
   useInterpolatedStyle,
+  type InterpolatedStyle,
   type InterpolatedStyleMap,
   type NumericStyleKey,
   type TransformKey,

package/src/values/useInterpolatedStyle.ts

@@ -1,4 +1,5 @@
 import { useMemo } from 'react'
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native'
 import {
   Extrapolation,
   interpolate,
@@ -83,6 +84,29 @@ export type InterpolatedStyleMap = {
   [K in ColorStyleKey]?: readonly string[]
 }
 
+/**
+ * The style shape a map of `K` produces. Transform keys collapse into the
+ * single `transform` array the worklet emits; every other key survives under
+ * its own name, typed from the RN style family it belongs to.
+ *
+ * This is what lets the return narrow to `ViewStyle` at a call site whose map
+ * holds only view keys. Reanimated's own `useAnimatedStyle` resolves to
+ * `DefaultStyle` (`ViewStyle | ImageStyle | TextStyle`), and that union is
+ * rejected inside a `StyleProp<ViewStyle>` array — `TextStyle` fails on
+ * `cursor` — so a consumer had to cast.
+ */
+export type InterpolatedStyle<K extends keyof InterpolatedStyleMap> = {
+  [P in Exclude<K, TransformKey>]: P extends keyof TextStyle
+    ? TextStyle[P]
+    : P extends keyof ImageStyle
+      ? ImageStyle[P]
+      : P extends keyof ViewStyle
+        ? ViewStyle[P]
+        : never
+} & (Extract<K, TransformKey> extends never
+  ? unknown
+  : { transform: NonNullable<ViewStyle['transform']> })
+
 export interface UseInterpolatedStyleOptions {
   /**
    * Input range mapped onto every key's output range. Defaults to `[0, 1]`
@@ -262,17 +286,17 @@ function buildEntries(
  * hook stays fully declarative and hashable so unchanged maps produce zero
  * new UI-thread closures.
  */
-export function useInterpolatedStyle(
+export function useInterpolatedStyle<K extends keyof InterpolatedStyleMap>(
   progress: SharedValue<number>,
-  map: InterpolatedStyleMap,
+  map: Pick<InterpolatedStyleMap, K>,
   options?: UseInterpolatedStyleOptions,
-): ReturnType<typeof useAnimatedStyle> {
+): InterpolatedStyle<K> {
   const extrapolate = mapExtrapolation(options?.extrapolate)
 
   // Order-preserving signature: the map's key order is load-bearing (transform
   // lifting emits axes in author order), so `stableSig` (which sorts keys) is
   // wrong here — sign the ordered key/output pairs plus the options directly.
-  const sig = buildSignature(map, options)
+  const sig = buildSignature(map as InterpolatedStyleMap, options)
 
   // Resolve every key's plan once on the JS thread so the worklet body only
   // consumes flat arrays — consistent with the JS-thread resolver principle
@@ -280,9 +304,15 @@ export function useInterpolatedStyle(
   // principle 8). Memoized on `sig` so a fresh-but-equal map literal each
   // render yields the same `entries` reference — Reanimated then sees an
   // unchanged closure dependency and does not rebuild the UI-thread worklet.
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const entries = useMemo<Entry[]>(() => buildEntries(map, options), [sig])
+  const entries = useMemo<Entry[]>(
+    () => buildEntries(map as InterpolatedStyleMap, options),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sig],
+  )
 
+  // 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.
   return useAnimatedStyle(() => {
     'worklet'
     const out: Record<string, unknown> = {}
@@ -313,7 +343,7 @@ export function useInterpolatedStyle(
     }
     if (transform.length > 0) out.transform = transform
     return out
-  })
+  }) as InterpolatedStyle<K>
 }
 
 declare const __DEV__: boolean

package/dist/chunk-NPJ46457.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunk6V7MOBXO_js = require('./chunk-6V7MOBXO.js');
-var reactNative = require('react-native');
-
-var MotionView = chunk6V7MOBXO_js.createMotionComponent(reactNative.View);
-
-exports.MotionView = MotionView;

package/dist/chunk-YUTS6JRU.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunk6V7MOBXO_js = require('./chunk-6V7MOBXO.js');
-var reactNative = require('react-native');
-
-var MotionImage = chunk6V7MOBXO_js.createMotionComponent(reactNative.Image);
-
-exports.MotionImage = MotionImage;

package/dist/chunk-ZSOCRHU3.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunk6V7MOBXO_js = require('./chunk-6V7MOBXO.js');
-var reactNative = require('react-native');
-
-var MotionText = chunk6V7MOBXO_js.createMotionComponent(reactNative.Text);
-
-exports.MotionText = MotionText;