@rootnative/inertia 0.0.0-alpha.7 → 0.0.2

package/dist/{chunk-TDSO63CJ.js → chunk-NKA6XR77.js}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunk7UDYEFBU_js = require('./chunk-7UDYEFBU.js');
+var chunkIWLU3VDE_js = require('./chunk-IWLU3VDE.js');
 var reactNative = require('react-native');
 
-var MotionPressable = chunk7UDYEFBU_js.createMotionComponent(reactNative.Pressable);
+var MotionPressable = chunkIWLU3VDE_js.createMotionComponent(reactNative.Pressable);
 
 exports.MotionPressable = MotionPressable;

package/dist/{chunk-6SMPIOIC.mjs → chunk-TUMNV4P7.mjs}

@@ -1,4 +1,4 @@
-import { createMotionComponent } from './chunk-DWCLIBYO.mjs';
+import { createMotionComponent } from './chunk-LYMLQ6WQ.mjs';
 import { View } from 'react-native';
 
 var MotionView = createMotionComponent(View);

package/dist/{chunk-2HYD2ZBK.js → chunk-TUYHTHVV.js}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunk7UDYEFBU_js = require('./chunk-7UDYEFBU.js');
+var chunkIWLU3VDE_js = require('./chunk-IWLU3VDE.js');
 var reactNative = require('react-native');
 
-var MotionScrollView = chunk7UDYEFBU_js.createMotionComponent(reactNative.ScrollView);
+var MotionScrollView = chunkIWLU3VDE_js.createMotionComponent(reactNative.ScrollView);
 
 exports.MotionScrollView = MotionScrollView;

package/dist/{chunk-NXDJZD6A.mjs → chunk-V6BTXHZK.mjs}

@@ -1,4 +1,4 @@
-import { createMotionComponent } from './chunk-DWCLIBYO.mjs';
+import { createMotionComponent } from './chunk-LYMLQ6WQ.mjs';
 import { Pressable } from 'react-native';
 
 var MotionPressable = createMotionComponent(Pressable);

package/dist/chunk-X5J5M3K3.js

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

package/dist/{chunk-JVBXPF2G.mjs → chunk-ZN3PNGHQ.mjs}

@@ -1,4 +1,4 @@
-import { createMotionComponent } from './chunk-DWCLIBYO.mjs';
+import { createMotionComponent } from './chunk-LYMLQ6WQ.mjs';
 import { Text } from 'react-native';
 
 var MotionText = createMotionComponent(Text);

package/dist/index.d.mts

@@ -339,6 +339,50 @@ declare function buildReleaseAnimation(transition: TransitionConfig, toValue: nu
  */
 declare function useAnimation(target: number, transition?: TransitionInput): SharedValue<number>;
 
+/**
+ * Imperative setter that drives a `SharedValue<number>` toward `to`, resolving
+ * the transition through the **same context** the declarative surface uses. It
+ * is the imperative escape hatch that closes the two footguns of writing
+ * `value.value = resolveTransition(config, to)` by hand from an event handler:
+ *
+ * 1. **Named transitions resolve.** A `TransitionName` registered on the
+ *    nearest `<MotionConfig transitions>` works here just as it does on the
+ *    `transition` prop or in `useAnimation`. Raw `resolveTransition` can't
+ *    reach the registry (names resolve via context), so imperative call sites
+ *    otherwise rebuild configs the provider already owns.
+ * 2. **Reduced motion is respected.** Writes route through the same
+ *    `no-animation` downgrade `useAnimation` applies under
+ *    `<MotionConfig reducedMotion>`. Hand-rolled `resolveTransition` writes
+ *    silently bypass that setting — a correctness bug this hook fixes.
+ *
+ * The returned callback is stable across renders (it reads the registry and
+ * the reduced-motion flag live inside the body), so it can be dropped straight
+ * into memoized handlers.
+ *
+ * This is not a new animation API — it starts animations in Inertia's existing
+ * transition vocabulary, so it does not conflict with the "no imperative-only
+ * APIs that bypass the declarative surface" scope rule. It is the hooks-layer
+ * equivalent of `useMotionValue` + `resolveTransition`, minus the footguns.
+ *
+ * @example
+ * ```tsx
+ * const hovered = useMotionValue(0)
+ * const animate = useAnimator()
+ *
+ * const onHoverIn = () => animate(hovered, 1, 'state-hover')
+ * const onHoverOut = () => animate(hovered, 0, 'state-hover')
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Inline config works too; default is spring when omitted.
+ * animate(progress, 1, { type: 'timing', duration: 150 })
+ * animate(progress, 0) // spring
+ * ```
+ */
+type Animator = (value: SharedValue<number>, to: number, transition?: TransitionInput) => void;
+declare function useAnimator(): Animator;
+
 /**
  * Toggle a 0↔1 progress value with a spring whenever `active` flips.
  *
@@ -406,56 +450,64 @@ interface UseColorTransitionOptions {
 declare function useColorTransition(progress: SharedValue<number>, range: readonly [string, string], options?: UseColorTransitionOptions): ReturnType<typeof useAnimatedStyle>;
 
 /**
- * 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).
+ * One layer in a color cascade: its own `progress` shared value (0→1) and the
+ * color it blends toward as that progress rises. Layers are ordered lowest
+ * priority first; a later layer wins over an earlier one at equal progress.
+ */
+interface ColorCascadeLayer {
+    /** 0→1 driver for this layer. Drive it upstream (spring / boolean / gesture). */
+    progress: SharedValue<number>;
+    /** The color this layer blends toward as `progress` moves 0→1. */
+    color: string;
+}
+interface UseColorCascadeOptions {
+    /**
+     * Which style slot the composited color is emitted under. Defaults to
+     * `backgroundColor` — identical to `useColorTransition`. Override for ring
+     * colors (`borderColor`), text (`color`), image tints (`tintColor`), etc.
+     */
+    key?: ColorStyleKey;
+}
+/**
+ * Priority-ordered layered color crossfade: each layer owns an independent
+ * `progress` value and blends the accumulated color below it toward its own
+ * color as that progress moves 0→1. Later layers win over earlier ones — the
+ * array is priority order, **lowest first** (matching the `gesture` prop's
+ * fixed-priority cascade, Decision 5).
  *
- * 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.
+ * Equivalent to the hand-chained nested-`interpolateColor` shape
+ * `focus(error(hover(rest)))`, collapsed into one hook and one worklet:
  *
- * Worklet read:
- * ```ts
- * const x = useMotionValue(0)
- * useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }))
- * ```
+ * ```tsx
+ * const borderStyle = useColorCascade(
+ *   colors.border,
+ *   [
+ *     { progress: hovered, color: colors.borderHover },
+ *     { progress: errored, color: colors.borderError },
+ *     { progress: focused, color: colors.borderFocus },
+ *   ],
+ *   { key: 'borderColor' },
+ * )
  *
- * JS write:
- * ```ts
- * onPress={() => { x.value = 100 }}
+ * return <Motion.View style={[styles.field, borderStyle]} />
  * ```
- */
-declare function useMotionValue(initial: number): SharedValue<number>;
-declare function useMotionValue(initial: string): SharedValue<string>;
-declare function useMotionValue<T extends number | string>(initial: T): SharedValue<T>;
-
-/**
- * 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.
+ * This is a pure interpolator — it does not animate on its own. Drive each
+ * layer's `progress` upstream with a `useSpring`, `useBooleanSpring`, gesture
+ * progress, or anything else producing a 0→1 shared value.
  *
- * Both call sites end up at the same `withSpring` invocation; the split is
- * just about which thread observes the source change.
+ * For the single-layer case (`rest` ⇄ one active color), reach for
+ * [`useColorTransition`](./useColorTransition) — it is the fast path and this
+ * hook is not a replacement for it. For a mixed numeric + color cascade, or
+ * function-valued layers, drop to a hand-rolled `useAnimatedStyle`.
  *
- * `config` also accepts a `TransitionName` registered on the nearest
- * `<MotionConfig transitions>`. Because this hook is spring-only, the name
- * must resolve to a spring config — a name registered as timing / decay /
- * no-animation warns in dev and falls back to the default spring (reach for
- * `useAnimation` when the named transition's type should be honored).
+ * The layer chain is resolved once on the JS thread and memoized on a
+ * structural signature (colors + key), so a fresh-but-equal `layers` array
+ * each render produces no new UI-thread closure (CLAUDE.md principle 8). The
+ * `progress` shared values are read live in the worklet, so their identity is
+ * intentionally excluded from the signature.
  */
-declare function useSpring(target: number | SharedValue<number>, config?: SpringTransition | TransitionName): SharedValue<number>;
+declare function useColorCascade(rest: string, layers: readonly ColorCascadeLayer[], options?: UseColorCascadeOptions): ReturnType<typeof useAnimatedStyle>;
 
 /**
  * Extrapolation behavior at the edges of the input range. Mirrors
@@ -509,6 +561,140 @@ declare function useTransform<T>(transformer: () => T): SharedValue<T>;
 declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly number[], options?: UseTransformOptions): SharedValue<number>;
 declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly string[], options?: UseTransformOptions): SharedValue<string>;
 
+/**
+ * Numeric style keys `useInterpolatedStyle` can emit directly (not lifted into
+ * the transform array). Mirrors the flat numeric surface of the `animate`
+ * prop.
+ */
+type NumericStyleKey = 'opacity' | 'width' | 'height' | 'borderRadius' | 'shadowOpacity' | 'shadowRadius' | 'elevation' | 'top' | 'left' | 'right' | 'bottom' | 'fontSize' | 'lineHeight' | 'letterSpacing' | 'borderWidth';
+/**
+ * Transform keys, lifted into a `transform: [...]` array in the order they
+ * appear in the map — the same key-order convention the `animate` prop uses.
+ * `rotate` / `rotateX` / `rotateY` take numeric degrees and emit
+ * `'<n>deg'` strings.
+ */
+type TransformKey = 'translateX' | 'translateY' | 'scale' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY';
+/**
+ * Interpolation map: each entry maps `progress` onto an output range for one
+ * style or transform key. Numeric / transform keys take number stops; color
+ * keys take color-string stops. Mixing stop types per key is a compile error.
+ */
+type InterpolatedStyleMap = {
+    [K in NumericStyleKey | TransformKey]?: readonly number[];
+} & {
+    [K in ColorStyleKey]?: readonly string[];
+};
+interface UseInterpolatedStyleOptions {
+    /**
+     * Input range mapped onto every key's output range. Defaults to `[0, 1]`
+     * for 2-stop outputs, and to evenly-spaced stops across `[0, 1]` for
+     * longer outputs. When provided, it applies to all keys; a key whose
+     * output length differs from `inputRange.length` throws in dev.
+     */
+    inputRange?: readonly number[];
+    /**
+     * Edge behavior outside the input range. Defaults to `'clamp'`, matching
+     * `useColorTransition`. Applies to numeric keys; color interpolation
+     * always clamps (Reanimated's `interpolateColor` has no extrapolation
+     * option).
+     */
+    extrapolate?: ExtrapolationMode;
+}
+/**
+ * Map one `progress` shared value onto N style props via `interpolate` /
+ * `interpolateColor`, returning an animated style fragment that composes in a
+ * style array on any Reanimated-aware host (`Motion.*`, a hand-rolled
+ * `Animated.View`). The style-fragment counterpart to `useTransform`'s
+ * output-range form, in the same family as `useColorTransition` / `useShadow`.
+ *
+ * ```tsx
+ * const collapseStyle = useInterpolatedStyle(collapseProgress, {
+ *   height: [expandedHeight, collapsedHeight],
+ *   fontSize: [expanded.fontSize, collapsed.fontSize],
+ * })
+ *
+ * const labelStyle = useInterpolatedStyle(floatProgress, {
+ *   translateY: [restingOffset, 0],
+ *   scale: [restingScale, 1],
+ * })
+ *
+ * return <Motion.View style={[base, collapseStyle, labelStyle]} />
+ * ```
+ *
+ * This is a pure interpolator — it does not animate on its own. Drive
+ * `progress` upstream with a `useSpring`, `useBooleanSpring`, gesture
+ * progress, or scroll-derived `useTransform`.
+ *
+ * - Numeric / transform keys route through `interpolate`; color-string stops
+ *   on a color key route through `interpolateColor` (a multi-stop
+ *   `useColorTransition` without touching that hook).
+ * - Transform keys (`translateX`, `scale`, `rotate`, …) are lifted into a
+ *   single `transform` array in the order they appear in the map. `rotate*`
+ *   keys take numeric degrees and emit `'<n>deg'` strings, consistent with
+ *   the `animate` surface.
+ * - `options.inputRange` defaults to `[0, 1]` for 2-stop outputs and to
+ *   evenly-spaced stops otherwise. `options.extrapolate` defaults to
+ *   `'clamp'`.
+ *
+ * For function-valued entries or multi-source composition, drop to a
+ * hand-rolled `useAnimatedStyle` (or `useTransform`'s worklet form) — this
+ * hook stays fully declarative and hashable so unchanged maps produce zero
+ * new UI-thread closures.
+ */
+declare function useInterpolatedStyle(progress: SharedValue<number>, map: InterpolatedStyleMap, options?: UseInterpolatedStyleOptions): ReturnType<typeof useAnimatedStyle>;
+
+/**
+ * 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 }}
+ * ```
+ */
+declare function useMotionValue(initial: number): SharedValue<number>;
+declare function useMotionValue(initial: string): SharedValue<string>;
+declare function useMotionValue<T extends number | string>(initial: T): SharedValue<T>;
+
+/**
+ * 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.
+ *
+ * `config` also accepts a `TransitionName` registered on the nearest
+ * `<MotionConfig transitions>`. Because this hook is spring-only, the name
+ * must resolve to a spring config — a name registered as timing / decay /
+ * no-animation warns in dev and falls back to the default spring (reach for
+ * `useAnimation` when the named transition's type should be honored).
+ */
+declare function useSpring(target: number | SharedValue<number>, config?: SpringTransition | TransitionName): SharedValue<number>;
+
 interface UseScrollResult {
     /** Horizontal scroll offset in points. */
     scrollX: SharedValue<number>;
@@ -681,4 +867,4 @@ declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnTyp
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type BoxShadowLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, TransitionInput, TransitionName, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };
+export { AnimatableValue, type Animator, type BoxShadowLayer, type ColorCascadeLayer, type ColorStyleKey, EasingInput, type ExtrapolationMode, type InterpolatedStyleMap, Motion, MotionComponent, MotionConfig, type MotionConfigProps, type MotionConfigValue, NamedTransitions, type NumericStyleKey, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, type TransformKey, TransitionConfig, TransitionInput, TransitionName, type UseColorCascadeOptions, type UseColorTransitionOptions, type UseInterpolatedStyleOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveNamedTransition, resolveTransition, useAnimation, useAnimator, useBooleanSpring, useColorCascade, useColorTransition, useInterpolatedStyle, useMotionConfig, useMotionValue, useNamedTransitions, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };