@rootnative/inertia 0.0.0-alpha.7 → 0.0.2

package/src/values/index.ts

@@ -1,5 +1,11 @@
 export { useAnimation } from './useAnimation'
+export { useAnimator, type Animator } from './useAnimator'
 export { useBooleanSpring } from './useBooleanSpring'
+export {
+  useColorCascade,
+  type ColorCascadeLayer,
+  type UseColorCascadeOptions,
+} from './useColorCascade'
 export {
   useColorTransition,
   type ColorStyleKey,
@@ -10,6 +16,13 @@ export {
   type UseGestureHandlers,
   type UseGestureResult,
 } from './useGesture'
+export {
+  useInterpolatedStyle,
+  type InterpolatedStyleMap,
+  type NumericStyleKey,
+  type TransformKey,
+  type UseInterpolatedStyleOptions,
+} from './useInterpolatedStyle'
 export { useMotionValue } from './useMotionValue'
 export { useSpring } from './useSpring'
 export {

package/src/values/useAnimation.ts

@@ -1,5 +1,9 @@
 import { useEffect } from 'react'
-import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import {
+  cancelAnimation,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
 import {
   resolveNamedTransition,
   useNamedTransitions,
@@ -71,5 +75,15 @@ export function useAnimation(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [target, cfgSig, shouldReduceMotion])
 
+  // Cancel the in-flight animation on unmount so an infinite-repeat or
+  // still-settling `withX` doesn't keep ticking against an orphaned value.
+  // `output` is identity-stable per hook instance and owned here.
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
   return output
 }

package/src/values/useAnimator.ts

@@ -0,0 +1,72 @@
+import { useCallback } from 'react'
+import { type SharedValue } from 'react-native-reanimated'
+import {
+  resolveNamedTransition,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from '../config'
+import { resolveTransition } from '../transitions'
+import { type TransitionInput } from '../types'
+
+/**
+ * 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
+ * ```
+ */
+export type Animator = (
+  value: SharedValue<number>,
+  to: number,
+  transition?: TransitionInput,
+) => void
+
+export function useAnimator(): Animator {
+  const registry = useNamedTransitions()
+  const shouldReduceMotion = useShouldReduceMotion()
+
+  return useCallback(
+    (value, to, transition) => {
+      const resolved = resolveNamedTransition(transition, registry)
+      const cfg = shouldReduceMotion
+        ? ({ type: 'no-animation' } as const)
+        : (resolved ?? ({ type: 'spring' } as const))
+      value.value = resolveTransition(cfg, to) as never
+    },
+    [registry, shouldReduceMotion],
+  )
+}

package/src/values/useColorCascade.ts

@@ -0,0 +1,107 @@
+import { useMemo } from 'react'
+import {
+  interpolateColor,
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated'
+import type { ColorStyleKey } from './useColorTransition'
+
+/**
+ * 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.
+ */
+export 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
+}
+
+export 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).
+ *
+ * Equivalent to the hand-chained nested-`interpolateColor` shape
+ * `focus(error(hover(rest)))`, collapsed into one hook and one worklet:
+ *
+ * ```tsx
+ * const borderStyle = useColorCascade(
+ *   colors.border,
+ *   [
+ *     { progress: hovered, color: colors.borderHover },
+ *     { progress: errored, color: colors.borderError },
+ *     { progress: focused, color: colors.borderFocus },
+ *   ],
+ *   { key: 'borderColor' },
+ * )
+ *
+ * return <Motion.View style={[styles.field, borderStyle]} />
+ * ```
+ *
+ * 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.
+ *
+ * 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`.
+ *
+ * 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.
+ */
+export function useColorCascade(
+  rest: string,
+  layers: readonly ColorCascadeLayer[],
+  options?: UseColorCascadeOptions,
+): ReturnType<typeof useAnimatedStyle> {
+  const key = options?.key ?? 'backgroundColor'
+
+  // Resolve the layer chain into two flat, memoized arrays the worklet closes
+  // over — the static colors and the live progress shared values. Both are
+  // memoized on the same structural signature so a fresh-but-equal `layers`
+  // literal each render yields the same array references; Reanimated then sees
+  // an unchanged closure dependency and does not rebuild the UI-thread worklet
+  // (CLAUDE.md principle 8). The `progress` shared values are identity-stable
+  // per hook instance, so signing the colors + count is enough to detect a
+  // real change to the chain.
+  const sig = `${key}|${rest}|${layers.length}|${layers
+    .map((l) => l.color)
+    .join(',')}`
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const colors = useMemo(() => layers.map((l) => l.color), [sig])
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const progressValues = useMemo(() => layers.map((l) => l.progress), [sig])
+
+  return useAnimatedStyle(() => {
+    'worklet'
+    // Fold the layers bottom-up: each layer blends the accumulated color below
+    // it toward its own color as its progress rises, so a higher-priority
+    // layer at full progress overrides everything beneath it.
+    let acc = rest
+    for (let i = 0; i < colors.length; i++) {
+      acc = interpolateColor(
+        progressValues[i]!.value,
+        [0, 1],
+        [acc, colors[i]!],
+      )
+    }
+    return { [key]: acc }
+  })
+}

package/src/values/useInterpolatedStyle.ts

@@ -0,0 +1,319 @@
+import { useMemo } from 'react'
+import {
+  Extrapolation,
+  interpolate,
+  interpolateColor,
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated'
+import type { ColorStyleKey } from './useColorTransition'
+import type { ExtrapolationMode } from './useTransform'
+
+/**
+ * Numeric style keys `useInterpolatedStyle` can emit directly (not lifted into
+ * the transform array). Mirrors the flat numeric surface of the `animate`
+ * prop.
+ */
+export 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.
+ */
+export type TransformKey =
+  | 'translateX'
+  | 'translateY'
+  | 'scale'
+  | 'scaleX'
+  | 'scaleY'
+  | 'rotate'
+  | 'rotateX'
+  | 'rotateY'
+
+const TRANSFORM_KEYS = new Set<string>([
+  'translateX',
+  'translateY',
+  'scale',
+  'scaleX',
+  'scaleY',
+  'rotate',
+  'rotateX',
+  'rotateY',
+])
+
+const ROTATION_KEYS = new Set<string>(['rotate', 'rotateX', 'rotateY'])
+
+const COLOR_KEYS = new Set<string>([
+  'backgroundColor',
+  'color',
+  'borderColor',
+  'borderTopColor',
+  'borderRightColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'tintColor',
+  'shadowColor',
+])
+
+/**
+ * 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.
+ */
+export type InterpolatedStyleMap = {
+  [K in NumericStyleKey | TransformKey]?: readonly number[]
+} & {
+  [K in ColorStyleKey]?: readonly string[]
+}
+
+export 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
+}
+
+/** One key's pre-resolved plan; the worklet consumes these flat records. */
+interface NumericEntry {
+  kind: 'numeric'
+  key: string
+  input: number[]
+  output: number[]
+}
+interface RotationEntry {
+  kind: 'rotation'
+  key: string
+  input: number[]
+  output: number[]
+}
+interface TransformNumericEntry {
+  kind: 'transform-numeric'
+  key: string
+  input: number[]
+  output: number[]
+}
+interface ColorEntry {
+  kind: 'color'
+  key: string
+  input: number[]
+  output: string[]
+}
+type Entry = NumericEntry | RotationEntry | TransformNumericEntry | ColorEntry
+
+function evenlySpaced(count: number): number[] {
+  if (count <= 1) return [0]
+  const out: number[] = []
+  for (let i = 0; i < count; i++) out.push(i / (count - 1))
+  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
+ * transform lifting depends on it.
+ */
+function buildSignature(
+  map: InterpolatedStyleMap,
+  options: UseInterpolatedStyleOptions | undefined,
+): string {
+  let sig = ''
+  for (const key of Object.keys(map)) {
+    const output = (map as Record<string, readonly (number | string)[]>)[key]
+    sig += `${key}:${JSON.stringify(output)}|`
+  }
+  sig += `#ir:${JSON.stringify(options?.inputRange)}|ex:${options?.extrapolate ?? ''}`
+  return sig
+}
+
+/**
+ * Resolve the map into flat per-key plans the worklet consumes. Walks `map`
+ * in insertion order so transform axes emit in author order.
+ */
+function buildEntries(
+  map: InterpolatedStyleMap,
+  options: UseInterpolatedStyleOptions | undefined,
+): Entry[] {
+  const explicitInput = options?.inputRange
+  const entries: Entry[] = []
+  for (const key of Object.keys(map) as (keyof InterpolatedStyleMap)[]) {
+    const output = map[key] as readonly (number | string)[] | undefined
+    if (output === undefined || output.length === 0) continue
+
+    const input = explicitInput
+      ? (explicitInput as number[])
+      : output.length === 2
+        ? [0, 1]
+        : evenlySpaced(output.length)
+
+    if (__DEV__ && explicitInput && explicitInput.length !== output.length) {
+      console.warn(
+        `[inertia] useInterpolatedStyle: inputRange has ${explicitInput.length} stops but the "${String(
+          key,
+        )}" output has ${output.length}. They must match — interpolation results are undefined otherwise.`,
+      )
+    }
+
+    const isColor =
+      COLOR_KEYS.has(key as string) && typeof output[0] === 'string'
+    if (isColor) {
+      entries.push({
+        kind: 'color',
+        key: key as string,
+        input,
+        output: output as string[],
+      })
+    } else if (ROTATION_KEYS.has(key as string)) {
+      entries.push({
+        kind: 'rotation',
+        key: key as string,
+        input,
+        output: output as number[],
+      })
+    } else if (TRANSFORM_KEYS.has(key as string)) {
+      entries.push({
+        kind: 'transform-numeric',
+        key: key as string,
+        input,
+        output: output as number[],
+      })
+    } else {
+      entries.push({
+        kind: 'numeric',
+        key: key as string,
+        input,
+        output: output as number[],
+      })
+    }
+  }
+  return entries
+}
+
+/**
+ * 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.
+ */
+export function useInterpolatedStyle(
+  progress: SharedValue<number>,
+  map: InterpolatedStyleMap,
+  options?: UseInterpolatedStyleOptions,
+): ReturnType<typeof useAnimatedStyle> {
+  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)
+
+  // 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
+  // that keeps `Object.keys`-style walks off the UI thread (CLAUDE.md
+  // 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])
+
+  return useAnimatedStyle(() => {
+    'worklet'
+    const out: Record<string, unknown> = {}
+    const transform: Record<string, unknown>[] = []
+    for (const e of entries) {
+      if (e.kind === 'color') {
+        out[e.key] = interpolateColor(progress.value, e.input, e.output)
+      } else if (e.kind === 'numeric') {
+        out[e.key] = interpolate(progress.value, e.input, e.output, {
+          extrapolateLeft: extrapolate,
+          extrapolateRight: extrapolate,
+        })
+      } else if (e.kind === 'transform-numeric') {
+        transform.push({
+          [e.key]: interpolate(progress.value, e.input, e.output, {
+            extrapolateLeft: extrapolate,
+            extrapolateRight: extrapolate,
+          }),
+        })
+      } else {
+        // rotation — emit a deg string
+        const deg = interpolate(progress.value, e.input, e.output, {
+          extrapolateLeft: extrapolate,
+          extrapolateRight: extrapolate,
+        })
+        transform.push({ [e.key]: `${deg}deg` })
+      }
+    }
+    if (transform.length > 0) out.transform = transform
+    return out
+  })
+}
+
+declare const __DEV__: boolean

package/src/values/useMotionValue.ts

@@ -1,4 +1,9 @@
-import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { useEffect } from 'react'
+import {
+  cancelAnimation,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
 
 /**
  * Create an animatable value owned by JS but readable from worklets.
@@ -40,5 +45,18 @@ export function useMotionValue<T extends number | string>(
 export function useMotionValue<T extends number | string>(
   initial: T,
 ): SharedValue<T> {
-  return useSharedValue<T>(initial)
+  const sv = useSharedValue<T>(initial)
+  // Cancel any in-flight animation when the owning component unmounts, so a
+  // mid-flight (or infinite-repeat) `withX` driving this value stops ticking
+  // its worklet once the value is orphaned. The shared value is
+  // identity-stable per hook instance and owned by this component, so
+  // cancelling on unmount is always safe. Mid-life cancellation stays the
+  // consumer's job via the `/reanimated` interop `cancelAnimation`.
+  useEffect(
+    () => () => cancelAnimation(sv),
+    // `sv` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+  return sv
 }

package/src/values/useSpring.ts

@@ -1,5 +1,6 @@
 import { useEffect, useMemo } from 'react'
 import {
+  cancelAnimation,
   useAnimatedReaction,
   useSharedValue,
   withSpring,
@@ -95,6 +96,17 @@ export function useSpring(
     [isSharedTarget, reanimConfig],
   )
 
+  // Stop the in-flight spring when the owning component unmounts so its
+  // worklet doesn't keep ticking against an orphaned value. `output` is
+  // identity-stable per hook instance and owned here, so cancelling on
+  // unmount is always safe.
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
   return output
 }
 

package/dist/chunk-3UTJJ4A3.js

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

package/dist/chunk-4QGXK6TF.js

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

package/dist/chunk-Z7HIOFKQ.js

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