@onlynative/inertia 0.0.1-alpha.2 → 0.0.1-alpha.3

package/README.md

@@ -42,7 +42,7 @@ export function FadeIn() {
 - **Primitives** — `Motion.View`, `Motion.Text`, `Motion.Image`, `Motion.Pressable`, `Motion.ScrollView`. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
 - **Sequences and keyframes** — `animate={{ x: [0, 100, 0] }}` with per-step transitions; unified `repeat: number | 'infinite' | { count, alternate }`.
 - **Variants** — `variants={{ open, closed }}` with `animate="open"`. Programmatic control via `useVariants` + `controller={...}`.
-- **Gestures** — single `gesture` prop on every primitive: `gesture={{ pressed, focused, focusVisible, hovered }}`. `focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. Zero overhead when omitted.
+- **Gestures** — single `gesture` prop on every primitive: `gesture={{ pressed, focused, focusVisible, hovered }}`. Sub-states layer **additively** in priority order (`hovered → focused → focusVisible → pressed`); each layer fades in/out on its own progress so MD3 release-while-hovered cross-fades correctly. Per-layer transitions via `transition.<stateName>`. `focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. Zero overhead when omitted.
 - **`<Presence>`** — mount/unmount transitions; exiting children automatically receive `pointerEvents: 'none'`.
 - **`<MotionConfig reducedMotion>`** — OS reduce-motion honored end-to-end (`'user' | 'never' | 'always'`).
 - **Per-primitive subpath imports** — `@onlynative/inertia/view`, `/text`, `/image`, `/pressable`, `/scroll-view`.
@@ -58,7 +58,13 @@ import { MotionPressable } from '@onlynative/inertia/pressable'
 import { MotionScrollView } from '@onlynative/inertia/scroll-view'
 ```
 
-A `Motion.View`-only import currently bundles to ~3.2 kB brotlied (excluding peers).
+Or the barrel — same primitives, named imports tree-shake cleanly because the package is `sideEffects: false`:
+
+```ts
+import { MotionView } from '@onlynative/inertia'
+```
+
+Both forms land at ~4.1–4.2 kB brotlied for a single primitive (peers excluded). The full namespace (`import { Motion } from '@onlynative/inertia'`, then `Motion.View`) cannot tree-shake — accessing one property of a literal object holds the whole object live — and lands at ~4.8 kB. CI checks all three forms via `size-limit` so the gap doesn't drift.
 
 ## Transitions
 
@@ -71,12 +77,33 @@ A `Motion.View`-only import currently bundles to ~3.2 kB brotlied (excluding pee
 
 Plus, on any transition: `delay`, `repeat`. Per-property transitions take precedence over the top-level transition. Spring config uses **react-spring vocabulary** (`tension`/`friction`); Reanimated's raw `stiffness`/`damping` is never on the public surface.
 
+## Caveats
+
+- **`Motion.Pressable` does not support function-form `style`.** RN's `Pressable` accepts `style={({ pressed }) => ...}` and re-runs it per state change; Inertia inherits Reanimated's `createAnimatedComponent` wrapper, which silently drops that form (no error, no warning). Drive press/focus/hover styling through `gesture` instead, or compute conditional styles once in render. See [primitives/pressable](https://onlynative.github.io/inertia/docs/primitives/pressable#style-must-be-a-value-not-a-function).
+- **`initial` is read once on mount.** Mutating `initial` after first render does nothing — change the component `key`, remount via `<Presence>`, or drive the value through a controller. Pass `initial={false}` to skip the initial-mount animation entirely.
+
 ## Animatable properties
 
 Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `width`, `height`, `borderRadius`. Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only — `Motion.View` rejects it at compile time). Layout transforms via `transform: [...]`. Color targets are forwarded straight through `withSpring` / `withTiming`; Reanimated's value setter packs the string to RGBA and interpolates on the UI thread.
 
 Out of scope for `0.x`: SVG path morphing, gradient interpolation, shared-element transitions across screens.
 
+## When not to use the core package alone
+
+The `gesture` prop in `@onlynative/inertia` covers `pressed` / `focused` / `focusVisible` / `hovered` — the Pressable-shaped sub-states. **Continuous, value-bearing gestures live in the adapter package** [`@onlynative/inertia-gestures`](../gestures), which wraps `react-native-gesture-handler` and ships:
+
+- `useDrag` — one- or two-axis drag with optional constraints and rubber-band elasticity
+- `usePan` — camera-style pan with momentum on release
+- `useSwipe` — directional commit-or-snap-back (distance + velocity thresholds)
+
+If your screen needs a thumb that follows the finger, a sheet that flicks closed, a carousel with momentum, or any gesture that produces a value other than "active / inactive" — install the adapter:
+
+```sh
+pnpm add @onlynative/inertia-gestures react-native-gesture-handler
+```
+
+A fully gesture-driven `Slider` (continuous thumb tracking + range clamping) is the canonical example: the core package can't build it on its own, the adapter can. This is intentional — keeping `react-native-gesture-handler` out of the core peer set means apps that animate buttons and sheets don't pay for a gesture engine they never invoke.
+
 ## Documentation
 
 Full docs, every primitive's example screen, and an `llms-full.txt` reference live at:

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DeZZzE_e.mjs';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DeZZzE_e.mjs';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DAhX3fC2.mjs';
+export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DAhX3fC2.mjs';
 export { MotionImage } from './motion/Image.mjs';
 export { MotionPressable } from './motion/Pressable.mjs';
 export { MotionScrollView } from './motion/ScrollView.mjs';

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DeZZzE_e.js';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DeZZzE_e.js';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DAhX3fC2.js';
+export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DAhX3fC2.js';
 export { MotionImage } from './motion/Image.js';
 export { MotionPressable } from './motion/Pressable.js';
 export { MotionScrollView } from './motion/ScrollView.js';

package/dist/index.js

@@ -9,7 +9,12 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var Animated__default = /*#__PURE__*/_interopDefault(Animated);
 
-// src/motion/Image.tsx
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var DEFAULT_MOTION_CONFIG = {
   reducedMotion: "user"
 };
@@ -285,6 +290,40 @@ function mergeTransition(base, override) {
   }
   return { ...base ?? { type: "spring" }, ...override };
 }
+
+// src/motion/installCheck.ts
+var alreadyChecked = false;
+function ensureReanimatedInstalled() {
+  if (!__DEV__ || alreadyChecked) return;
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "test") {
+    return;
+  }
+  alreadyChecked = true;
+  let version;
+  try {
+    const pkg = __require("react-native-reanimated/package.json");
+    version = pkg.version;
+  } catch {
+  }
+  if (version) {
+    const major = parseInt(version.split(".")[0] ?? "0", 10);
+    if (major < 4) {
+      console.error(
+        `[inertia] react-native-reanimated v${version} is installed, but @onlynative/inertia requires v4.0.0 or later. Upgrade with \`pnpm add react-native-reanimated@^4\` (or your package manager's equivalent).`
+      );
+      return;
+    }
+  }
+  const probe = function probe2() {
+    "worklet";
+    return 0;
+  };
+  if (typeof probe.__workletHash !== "number") {
+    console.error(
+      `[inertia] The Reanimated worklets babel plugin is not configured. Add \`'react-native-worklets/plugin'\` as the LAST entry in the \`plugins\` array of your \`babel.config.js\`, then restart Metro with a fresh cache: \`npx expo start -c\` or \`npx react-native start --reset-cache\`.`
+    );
+  }
+}
 var TRANSFORM_KEYS = [
   "translateX",
   "translateY",
@@ -311,6 +350,14 @@ var ALL_KEYS = [
   ...COLOR_KEYS
 ];
 var TRANSFORM_KEY_SET = new Set(TRANSFORM_KEYS);
+var COLOR_KEY_SET = new Set(COLOR_KEYS);
+var GESTURE_LAYER_NAMES = [
+  "hovered",
+  "focused",
+  "focusVisible",
+  "pressed"
+];
+var GESTURE_LAYER_NAME_SET = new Set(GESTURE_LAYER_NAMES);
 var EXITING_POINTER_EVENTS_STYLE = { pointerEvents: "none" };
 var DEFAULT_RESTING = {
   translateX: 0,
@@ -356,10 +403,18 @@ function isTopLevelTransition(t) {
 function transitionFor(prop, transition) {
   if (!transition) return void 0;
   if (isTopLevelTransition(transition)) return transition;
+  if (GESTURE_LAYER_NAME_SET.has(prop)) return void 0;
   return transition[prop];
 }
+function gestureLayerTransitionFor(layer, transition) {
+  if (!transition) return void 0;
+  if (isTopLevelTransition(transition)) return transition;
+  return transition[layer];
+}
 function createMotionComponent(Component) {
+  ensureReanimatedInstalled();
   const AnimatedComponent = Animated__default.default.createAnimatedComponent(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     Component
   );
   const Motion2 = react.forwardRef(function Motion3(props, ref) {
@@ -438,13 +493,19 @@ function createMotionComponent(Component) {
       }
       return initialRecord?.[key] ?? restValue(animateRecord[key]) ?? DEFAULT_RESTING[key];
     });
-    const mergedRecord = isExiting && exitRecord ? { ...animateRecord, ...exitRecord } : mergeGestureTargets(animateRecord, gesture, {
-      pressed,
-      focused,
-      focusVisible,
-      hovered
-    });
-    const mergedSig = stableSig(mergedRecord) + (isExiting ? "|exit" : "") + (shouldReduceMotion ? "|rm" : "");
+    const pressedProgress = Animated.useSharedValue(0);
+    const focusedProgress = Animated.useSharedValue(0);
+    const focusVisibleProgress = Animated.useSharedValue(0);
+    const hoveredProgress = Animated.useSharedValue(0);
+    const gestureSV = Animated.useSharedValue(
+      resolveGestureLayers(gesture)
+    );
+    const gestureTargetsSig = stableSig(gesture);
+    react.useEffect(() => {
+      gestureSV.value = resolveGestureLayers(gesture);
+    }, [gestureTargetsSig]);
+    const baseRecord = isExiting && exitRecord ? { ...animateRecord, ...exitRecord } : animateRecord;
+    const baseSig = stableSig(baseRecord) + (isExiting ? "|exit" : "") + (shouldReduceMotion ? "|rm" : "");
     const transitionSig = stableSig(transition);
     const safeToRemoveRef = react.useRef(void 0);
     safeToRemoveRef.current = presence?.safeToRemove;
@@ -465,13 +526,13 @@ function createMotionComponent(Component) {
       };
       let transformPending = 0;
       for (const k of ALL_KEYS) {
-        if (TRANSFORM_KEY_SET.has(k) && mergedRecord[k] !== void 0) {
+        if (TRANSFORM_KEY_SET.has(k) && baseRecord[k] !== void 0) {
           transformPending++;
         }
       }
       const transformGroup = transformPending > 0 ? { remaining: transformPending } : void 0;
       for (const key of ALL_KEYS) {
-        const target = mergedRecord[key];
+        const target = baseRecord[key];
         if (target === void 0) continue;
         const cfg = shouldReduceMotion ? { type: "no-animation" } : transitionFor(key, transition);
         if (isExiting) pending++;
@@ -496,14 +557,76 @@ function createMotionComponent(Component) {
       if (isExiting && pending === 0) {
         safeToRemoveRef.current?.();
       }
-    }, [mergedSig, transitionSig]);
+    }, [baseSig, transitionSig]);
+    useGestureLayerProgress(
+      pressedProgress,
+      pressed,
+      gesture?.pressed != null,
+      "pressed",
+      transition,
+      isExiting,
+      shouldReduceMotion
+    );
+    useGestureLayerProgress(
+      focusedProgress,
+      focused,
+      gesture?.focused != null,
+      "focused",
+      transition,
+      isExiting,
+      shouldReduceMotion
+    );
+    useGestureLayerProgress(
+      focusVisibleProgress,
+      focusVisible,
+      gesture?.focusVisible != null,
+      "focusVisible",
+      transition,
+      isExiting,
+      shouldReduceMotion
+    );
+    useGestureLayerProgress(
+      hoveredProgress,
+      hovered,
+      gesture?.hovered != null,
+      "hovered",
+      transition,
+      isExiting,
+      shouldReduceMotion
+    );
     const animatedStyle = Animated.useAnimatedStyle(() => {
       const activeKeys = activeKeysRef.current;
       const hasTransform = hasTransformRef.current;
       const out = {};
       const transform = [];
+      const ph = hoveredProgress.value;
+      const pf = focusedProgress.value;
+      const pfv = focusVisibleProgress.value;
+      const pp = pressedProgress.value;
+      const layers = gestureSV.value;
+      const hoveredLayer = layers ? layers.hovered : null;
+      const focusedLayer = layers ? layers.focused : null;
+      const focusVisibleLayer = layers ? layers.focusVisible : null;
+      const pressedLayer = layers ? layers.pressed : null;
       for (const key of activeKeys) {
-        const v = sharedValues[key].value;
+        let v = sharedValues[key].value;
+        const isColor = COLOR_KEY_SET.has(key);
+        if (hoveredLayer && ph > 0 && hoveredLayer[key] !== void 0) {
+          const t = hoveredLayer[key];
+          v = isColor ? Animated.interpolateColor(ph, [0, 1], [v, t]) : v + (t - v) * ph;
+        }
+        if (focusedLayer && pf > 0 && focusedLayer[key] !== void 0) {
+          const t = focusedLayer[key];
+          v = isColor ? Animated.interpolateColor(pf, [0, 1], [v, t]) : v + (t - v) * pf;
+        }
+        if (focusVisibleLayer && pfv > 0 && focusVisibleLayer[key] !== void 0) {
+          const t = focusVisibleLayer[key];
+          v = isColor ? Animated.interpolateColor(pfv, [0, 1], [v, t]) : v + (t - v) * pfv;
+        }
+        if (pressedLayer && pp > 0 && pressedLayer[key] !== void 0) {
+          const t = pressedLayer[key];
+          v = isColor ? Animated.interpolateColor(pp, [0, 1], [v, t]) : v + (t - v) * pp;
+        }
         if (TRANSFORM_KEY_SET.has(key)) {
           transform.push(
             key === "rotate" ? { rotate: `${v}deg` } : { [key]: v }
@@ -722,52 +845,41 @@ function stableStringify(v) {
   const keys = Object.keys(obj).sort();
   return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
 }
-function mergeGestureTargets(base, gesture, active) {
-  if (!gesture) return base;
-  const merged = {
-    ...base
-  };
-  const subStates = [
-    gesture.hovered,
-    gesture.focused,
-    gesture.focusVisible,
-    gesture.pressed
-  ];
-  for (const sub of subStates) {
-    if (!sub) continue;
-    for (const k of ALL_KEYS) {
-      if (k in sub && !(k in merged)) {
-        merged[k] = DEFAULT_RESTING[k];
-      }
+function resolveGestureLayers(gesture) {
+  if (!gesture) return null;
+  const out = {};
+  for (const layer of GESTURE_LAYER_NAMES) {
+    const subState = gesture[layer];
+    if (!subState) continue;
+    const resolved = {};
+    for (const key of ALL_KEYS) {
+      const raw = subState[key];
+      if (raw === void 0) continue;
+      const t = targetEndValue(raw);
+      if (t !== void 0) resolved[key] = t;
     }
+    out[layer] = resolved;
   }
-  if (active.hovered && gesture.hovered) {
-    Object.assign(
-      merged,
-      gesture.hovered
-    );
-  }
-  if (active.focused && gesture.focused) {
-    Object.assign(
-      merged,
-      gesture.focused
-    );
-  }
-  if (active.focusVisible && gesture.focusVisible) {
-    Object.assign(
-      merged,
-      gesture.focusVisible
-    );
-  }
-  if (active.pressed && gesture.pressed) {
-    Object.assign(
-      merged,
-      gesture.pressed
-    );
-  }
-  return merged;
+  return out;
+}
+function useGestureLayerProgress(progress, active, declared, layer, transition, isExiting, shouldReduceMotion) {
+  const layerCfgSig = stableSig(gestureLayerTransitionFor(layer, transition));
+  react.useEffect(() => {
+    if (!declared) return;
+    if (isExiting) {
+      progress.value = 0;
+      return;
+    }
+    const target = active ? 1 : 0;
+    const cfg = shouldReduceMotion ? { type: "no-animation" } : gestureLayerTransitionFor(layer, transition) ?? { type: "spring" };
+    progress.value = resolveTransition(cfg, target);
+  }, [active, declared, isExiting, shouldReduceMotion, layerCfgSig]);
 }
 function useGestureHandlers(gesture, rest, setPressed, setFocused, setFocusVisible, setHovered) {
+  const hasPressed = gesture?.pressed ? 1 : 0;
+  const hasFocused = gesture?.focused ? 1 : 0;
+  const hasFocusVisible = gesture?.focusVisible ? 1 : 0;
+  const hasHovered = gesture?.hovered ? 1 : 0;
   return react.useMemo(() => {
     if (!gesture) return {};
     const handlers = {};
@@ -800,10 +912,10 @@ function useGestureHandlers(gesture, rest, setPressed, setFocused, setFocusVisib
     }
     return handlers;
   }, [
-    gesture?.pressed ? 1 : 0,
-    gesture?.focused ? 1 : 0,
-    gesture?.focusVisible ? 1 : 0,
-    gesture?.hovered ? 1 : 0,
+    hasPressed,
+    hasFocused,
+    hasFocusVisible,
+    hasHovered,
     rest.onTouchStart,
     rest.onTouchEnd,
     rest.onTouchCancel,