@rootnative/inertia 0.0.1 → 0.0.2

package/dist/index.mjs

@@ -1,21 +1,21 @@
 export { useGesture } from './chunk-RGNX6UZN.mjs';
-import { MotionView } from './chunk-6SMPIOIC.mjs';
-export { MotionView } from './chunk-6SMPIOIC.mjs';
-import { MotionText } from './chunk-JVBXPF2G.mjs';
-export { MotionText } from './chunk-JVBXPF2G.mjs';
-import { MotionImage } from './chunk-ALRHDFZE.mjs';
-export { MotionImage } from './chunk-ALRHDFZE.mjs';
-import { MotionPressable } from './chunk-NXDJZD6A.mjs';
-export { MotionPressable } from './chunk-NXDJZD6A.mjs';
-import { MotionScrollView } from './chunk-CWLFUYIY.mjs';
-export { MotionScrollView } from './chunk-CWLFUYIY.mjs';
-export { Presence, createMotionComponent, usePresence } from './chunk-DWCLIBYO.mjs';
+import { MotionView } from './chunk-TUMNV4P7.mjs';
+export { MotionView } from './chunk-TUMNV4P7.mjs';
+import { MotionText } from './chunk-ZN3PNGHQ.mjs';
+export { MotionText } from './chunk-ZN3PNGHQ.mjs';
+import { MotionImage } from './chunk-2DHKV2XY.mjs';
+export { MotionImage } from './chunk-2DHKV2XY.mjs';
+import { MotionPressable } from './chunk-V6BTXHZK.mjs';
+export { MotionPressable } from './chunk-V6BTXHZK.mjs';
+import { MotionScrollView } from './chunk-HFDZAHWP.mjs';
+export { MotionScrollView } from './chunk-HFDZAHWP.mjs';
+export { Presence, createMotionComponent, usePresence } from './chunk-LYMLQ6WQ.mjs';
 import { useShouldReduceMotion, resolveNamedTransition, useNamedTransitions, lookupNamedTransition } from './chunk-R63GIUNU.mjs';
 export { MotionConfig, resolveNamedTransition, useMotionConfig, useNamedTransitions, useShouldReduceMotion } from './chunk-R63GIUNU.mjs';
 import { stableSig, resolveTransition, springToReanimated, warnNonWorkletOnce } from './chunk-CY7Y64C3.mjs';
 export { buildReleaseAnimation, cubicBezier, ensureWorkletEasing, resolveAnimatableValue, resolveTransition } from './chunk-CY7Y64C3.mjs';
-import { useEffect, useMemo, useRef } from 'react';
-import { useSharedValue, withSpring, useAnimatedReaction, useAnimatedStyle, interpolateColor, useDerivedValue, Extrapolation, useAnimatedScrollHandler, interpolate } from 'react-native-reanimated';
+import { useEffect, useCallback, useMemo, useRef } from 'react';
+import { useSharedValue, cancelAnimation, withSpring, useAnimatedReaction, useAnimatedStyle, interpolateColor, interpolate, useDerivedValue, Extrapolation, useAnimatedScrollHandler } from 'react-native-reanimated';
 import { isWorkletFunction } from 'react-native-worklets';
 
 // src/motion/index.ts
@@ -35,8 +35,26 @@ function useAnimation(target, transition) {
     const cfg = shouldReduceMotion ? { type: "no-animation" } : resolved ?? { type: "spring" };
     output.value = resolveTransition(cfg, target);
   }, [target, cfgSig, shouldReduceMotion]);
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
   return output;
 }
+function useAnimator() {
+  const registry = useNamedTransitions();
+  const shouldReduceMotion = useShouldReduceMotion();
+  return useCallback(
+    (value, to, transition) => {
+      const resolved = resolveNamedTransition(transition, registry);
+      const cfg = shouldReduceMotion ? { type: "no-animation" } : resolved ?? { type: "spring" };
+      value.value = resolveTransition(cfg, to);
+    },
+    [registry, shouldReduceMotion]
+  );
+}
 function useSpring(target, config) {
   const spring = resolveSpringInput(config, useNamedTransitions());
   const reanimConfig = useMemo(
@@ -75,6 +93,12 @@ function useSpring(target, config) {
     },
     [isSharedTarget, reanimConfig]
   );
+  useEffect(
+    () => () => cancelAnimation(output),
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
   return output;
 }
 function resolveSpringInput(config, registry) {
@@ -96,6 +120,24 @@ function isSharedValue(v) {
 function useBooleanSpring(active, springConfig) {
   return useSpring(active ? 1 : 0, springConfig);
 }
+function useColorCascade(rest, layers, options) {
+  const key = options?.key ?? "backgroundColor";
+  const sig = `${key}|${rest}|${layers.length}|${layers.map((l) => l.color).join(",")}`;
+  const colors = useMemo(() => layers.map((l) => l.color), [sig]);
+  const progressValues = useMemo(() => layers.map((l) => l.progress), [sig]);
+  return useAnimatedStyle(() => {
+    "worklet";
+    let acc = rest;
+    for (let i = 0; i < colors.length; i++) {
+      acc = interpolateColor(
+        progressValues[i].value,
+        [0, 1],
+        [acc, colors[i]]
+      );
+    }
+    return { [key]: acc };
+  });
+}
 function useColorTransition(progress, range, options) {
   const key = options?.key ?? "backgroundColor";
   const from = range[0];
@@ -105,8 +147,139 @@ function useColorTransition(progress, range, options) {
     return { [key]: interpolateColor(progress.value, [0, 1], [from, to]) };
   });
 }
+var TRANSFORM_KEYS = /* @__PURE__ */ new Set([
+  "translateX",
+  "translateY",
+  "scale",
+  "scaleX",
+  "scaleY",
+  "rotate",
+  "rotateX",
+  "rotateY"
+]);
+var ROTATION_KEYS = /* @__PURE__ */ new Set(["rotate", "rotateX", "rotateY"]);
+var COLOR_KEYS = /* @__PURE__ */ new Set([
+  "backgroundColor",
+  "color",
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "tintColor",
+  "shadowColor"
+]);
+function evenlySpaced(count) {
+  if (count <= 1) return [0];
+  const out = [];
+  for (let i = 0; i < count; i++) out.push(i / (count - 1));
+  return out;
+}
+function mapExtrapolation(mode) {
+  if (mode === "identity") return Extrapolation.IDENTITY;
+  if (mode === "extend") return Extrapolation.EXTEND;
+  return Extrapolation.CLAMP;
+}
+function buildSignature(map, options) {
+  let sig = "";
+  for (const key of Object.keys(map)) {
+    const output = map[key];
+    sig += `${key}:${JSON.stringify(output)}|`;
+  }
+  sig += `#ir:${JSON.stringify(options?.inputRange)}|ex:${options?.extrapolate ?? ""}`;
+  return sig;
+}
+function buildEntries(map, options) {
+  const explicitInput = options?.inputRange;
+  const entries = [];
+  for (const key of Object.keys(map)) {
+    const output = map[key];
+    if (output === void 0 || output.length === 0) continue;
+    const input = explicitInput ? explicitInput : 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 \u2014 interpolation results are undefined otherwise.`
+      );
+    }
+    const isColor = COLOR_KEYS.has(key) && typeof output[0] === "string";
+    if (isColor) {
+      entries.push({
+        kind: "color",
+        key,
+        input,
+        output
+      });
+    } else if (ROTATION_KEYS.has(key)) {
+      entries.push({
+        kind: "rotation",
+        key,
+        input,
+        output
+      });
+    } else if (TRANSFORM_KEYS.has(key)) {
+      entries.push({
+        kind: "transform-numeric",
+        key,
+        input,
+        output
+      });
+    } else {
+      entries.push({
+        kind: "numeric",
+        key,
+        input,
+        output
+      });
+    }
+  }
+  return entries;
+}
+function useInterpolatedStyle(progress, map, options) {
+  const extrapolate = mapExtrapolation(options?.extrapolate);
+  const sig = buildSignature(map, options);
+  const entries = useMemo(() => buildEntries(map, options), [sig]);
+  return useAnimatedStyle(() => {
+    "worklet";
+    const out = {};
+    const transform = [];
+    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 {
+        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;
+  });
+}
 function useMotionValue(initial) {
-  return useSharedValue(initial);
+  const sv = useSharedValue(initial);
+  useEffect(
+    () => () => cancelAnimation(sv),
+    // `sv` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
+  return sv;
 }
 function useTransform(arg1, inputRange, outputRange, options) {
   let producer;
@@ -129,8 +302,8 @@ function useTransform(arg1, inputRange, outputRange, options) {
     const input = inputRange;
     const output = outputRange;
     const isColor = output.length > 0 && typeof output[0] === "string";
-    const extrapolateLeft = mapExtrapolation(options?.extrapolateLeft);
-    const extrapolateRight = mapExtrapolation(options?.extrapolateRight);
+    const extrapolateLeft = mapExtrapolation2(options?.extrapolateLeft);
+    const extrapolateRight = mapExtrapolation2(options?.extrapolateRight);
     producer = isColor ? () => {
       "worklet";
       return interpolateColor(
@@ -150,7 +323,7 @@ function useTransform(arg1, inputRange, outputRange, options) {
   }
   return useDerivedValue(producer);
 }
-function mapExtrapolation(mode) {
+function mapExtrapolation2(mode) {
   if (mode === "identity") return Extrapolation.IDENTITY;
   if (mode === "extend") return Extrapolation.EXTEND;
   return Extrapolation.CLAMP;
@@ -401,4 +574,4 @@ function useVariants(variants, initial) {
   }, []);
 }
 
-export { Motion, useAnimation, useBooleanSpring, useColorTransition, useMotionValue, useScroll, useShadow, useSpring, useTransform, useVariants };
+export { Motion, useAnimation, useAnimator, useBooleanSpring, useColorCascade, useColorTransition, useInterpolatedStyle, useMotionValue, useScroll, useShadow, useSpring, useTransform, useVariants };

package/dist/motion/Image.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk3UTJJ4A3_js = require('../chunk-3UTJJ4A3.js');
-require('../chunk-7UDYEFBU.js');
+var chunk34Q4UM6V_js = require('../chunk-34Q4UM6V.js');
+require('../chunk-IWLU3VDE.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionImage", {
   enumerable: true,
-  get: function () { return chunk3UTJJ4A3_js.MotionImage; }
+  get: function () { return chunk34Q4UM6V_js.MotionImage; }
 });

package/dist/motion/Image.mjs

@@ -1,4 +1,4 @@
-export { MotionImage } from '../chunk-ALRHDFZE.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionImage } from '../chunk-2DHKV2XY.mjs';
+import '../chunk-LYMLQ6WQ.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/Pressable.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkTDSO63CJ_js = require('../chunk-TDSO63CJ.js');
-require('../chunk-7UDYEFBU.js');
+var chunkNKA6XR77_js = require('../chunk-NKA6XR77.js');
+require('../chunk-IWLU3VDE.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionPressable", {
   enumerable: true,
-  get: function () { return chunkTDSO63CJ_js.MotionPressable; }
+  get: function () { return chunkNKA6XR77_js.MotionPressable; }
 });

package/dist/motion/Pressable.mjs

@@ -1,4 +1,4 @@
-export { MotionPressable } from '../chunk-NXDJZD6A.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionPressable } from '../chunk-V6BTXHZK.mjs';
+import '../chunk-LYMLQ6WQ.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/ScrollView.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk2HYD2ZBK_js = require('../chunk-2HYD2ZBK.js');
-require('../chunk-7UDYEFBU.js');
+var chunkTUYHTHVV_js = require('../chunk-TUYHTHVV.js');
+require('../chunk-IWLU3VDE.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionScrollView", {
   enumerable: true,
-  get: function () { return chunk2HYD2ZBK_js.MotionScrollView; }
+  get: function () { return chunkTUYHTHVV_js.MotionScrollView; }
 });

package/dist/motion/ScrollView.mjs

@@ -1,4 +1,4 @@
-export { MotionScrollView } from '../chunk-CWLFUYIY.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionScrollView } from '../chunk-HFDZAHWP.mjs';
+import '../chunk-LYMLQ6WQ.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/Text.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkZ7HIOFKQ_js = require('../chunk-Z7HIOFKQ.js');
-require('../chunk-7UDYEFBU.js');
+var chunkX5J5M3K3_js = require('../chunk-X5J5M3K3.js');
+require('../chunk-IWLU3VDE.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionText", {
   enumerable: true,
-  get: function () { return chunkZ7HIOFKQ_js.MotionText; }
+  get: function () { return chunkX5J5M3K3_js.MotionText; }
 });

package/dist/motion/Text.mjs

@@ -1,4 +1,4 @@
-export { MotionText } from '../chunk-JVBXPF2G.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionText } from '../chunk-ZN3PNGHQ.mjs';
+import '../chunk-LYMLQ6WQ.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/dist/motion/View.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk4QGXK6TF_js = require('../chunk-4QGXK6TF.js');
-require('../chunk-7UDYEFBU.js');
+var chunkKYJROYCG_js = require('../chunk-KYJROYCG.js');
+require('../chunk-IWLU3VDE.js');
 require('../chunk-7AOERN53.js');
 require('../chunk-PTRF47DA.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PTRF47DA.js');
 
 Object.defineProperty(exports, "MotionView", {
   enumerable: true,
-  get: function () { return chunk4QGXK6TF_js.MotionView; }
+  get: function () { return chunkKYJROYCG_js.MotionView; }
 });

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-6SMPIOIC.mjs';
-import '../chunk-DWCLIBYO.mjs';
+export { MotionView } from '../chunk-TUMNV4P7.mjs';
+import '../chunk-LYMLQ6WQ.mjs';
 import '../chunk-R63GIUNU.mjs';
 import '../chunk-CY7Y64C3.mjs';

package/llms.txt

@@ -26,6 +26,8 @@ import {
   useTransform,
   useShadow,
   useColorTransition,
+  useColorCascade,
+  useInterpolatedStyle,
   useScroll,
 } from '@rootnative/inertia'
 // Opt-in MD3 / iOS state-layer overlay helper:
@@ -50,11 +52,14 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `useVariants(variants, initial?)` — returns `{ current, transitionTo }` controller for the `controller` prop.
 - `useMotionValue(initial)` — thin pass-through over `useSharedValue<T>`. Returns a `SharedValue<T>` directly so it interops with every Reanimated API without unwrapping.
 - `useAnimation(target, transition?)` — drive a `SharedValue<number>` toward `target` with any `TransitionConfig` (spring / timing / decay / no-animation, plus `repeat`) or a registered `TransitionName`. The general-purpose value-layer hook for boolean-state progress, indeterminate loops, and anywhere the same value needs to feed multiple `useAnimatedStyle` blocks.
+- `useAnimator()` — the **imperative** counterpart to `useAnimation`. Returns an identity-stable `(value: SharedValue<number>, to: number, transition?: TransitionConfig | TransitionName) => void` setter to call from event handlers (hover-in, focus, press) rather than from an effect. Resolves registered `TransitionName`s through the nearest `<MotionConfig transitions>` and gates on `<MotionConfig reducedMotion>` (`'no-animation'` downgrade) — the two things a hand-rolled `resolveTransition` write in an event handler silently gets wrong. Default transition is the library spring. Not a new animation API — the hooks-layer equivalent of `useMotionValue` + `resolveTransition`, minus the footguns.
 - `useSpring(target, config?)` — spring-only shorthand. Animates a `SharedValue<number>` toward `target` with react-spring vocab (or a spring-typed registered `TransitionName`; non-spring names warn and fall back to the default spring). `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
 - `useBooleanSpring(active, config?)` — sugar over `useSpring` for the recurring "spring 0↔1 progress from a boolean" shape (checkbox checks, accordion expansions, drawer open/closed). Identical mechanics to `useSpring(active ? 1 : 0, config)` — the named form so the call site reads as the boolean it represents.
 - `useTransform(value, inputRange, outputRange, options?)` / `useTransform(transformer)` — interpolate a numeric shared value onto a number or color range, or derive any value from any number of shared values via a worklet. Non-worklet transformers are auto-wrapped.
 - `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`, plus `boxShadow` as a CSS string or `BoxShadowLayer[]` — the shadow surface on web and RN 0.76+ new-arch; multi-layer, CSS-transition padding semantics, malformed strings throw at setup) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
 - `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
+- `useColorCascade(rest, layers, options?)` — pure value-layer interpolator compositing a **priority-ordered** stack of color layers over a base `rest` color; each `layers` entry is `{ progress: SharedValue<number>, color: string }`, later entries win as their progress rises (equivalent to the nested `focus(error(hover(rest)))` `interpolateColor` chain). `options.key` reuses `ColorStyleKey` (default `backgroundColor`). Returns a spreadable animated style fragment; memoized on a colors+key signature. Color-only by design — cascade a numeric key separately via `useInterpolatedStyle` + `useTransform` max. `useColorTransition` stays the single-layer fast path.
+- `useInterpolatedStyle(progress, map, options?)` — pure value-layer interpolator mapping one `SharedValue<number>` onto **N** style props at once, returned as a spreadable animated style fragment (the multi-key, style-fragment counterpart to `useTransform`'s output-range form). Numeric keys (`opacity` / `height` / `fontSize` / …) route through `interpolate`; transform keys (`translateX` / `scale` / `rotate` / …) lift into a `transform` array in map key-order (`rotate*` emit `'<n>deg'`); color keys (`backgroundColor` / `borderColor` / …) route through `interpolateColor` (a multi-stop `useColorTransition`). Stop types are compile-checked. `options.inputRange` (default `[0,1]` / evenly-spaced) and `options.extrapolate` (default `'clamp'`) apply to every key. Memoized on an order-preserving signature. For function-valued or multi-source composition, drop to `useTransform`'s worklet form or a hand-rolled `useAnimatedStyle`.
 - `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
 - `buildReleaseAnimation(transition, toValue)` — worklet-safe single-step animation builder (spring / timing / decay / no-animation). For assigning Inertia-resolved animations to shared values from inside a gesture worklet. Used internally by `@rootnative/inertia-gestures`'s `useDrag({ onRelease })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",

package/src/index.ts

@@ -41,9 +41,12 @@ export {
 } from './transitions'
 export {
   useAnimation,
+  useAnimator,
   useBooleanSpring,
+  useColorCascade,
   useColorTransition,
   useGesture,
+  useInterpolatedStyle,
   useMotionValue,
   useScroll,
   useShadow,
@@ -57,13 +60,20 @@ export {
 // Runtime render-layer interop lives in `@rootnative/inertia/reanimated`.
 export type { SharedValue } from 'react-native-reanimated'
 export type {
+  Animator,
   BoxShadowLayer,
+  ColorCascadeLayer,
   ColorStyleKey,
   ExtrapolationMode,
+  InterpolatedStyleMap,
+  NumericStyleKey,
   ShadowConfig,
+  TransformKey,
+  UseColorCascadeOptions,
   UseColorTransitionOptions,
   UseGestureHandlers,
   UseGestureResult,
+  UseInterpolatedStyleOptions,
   UseScrollResult,
   UseShadowOptions,
   UseTransformOptions,