r3f-motion 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Framer B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# React Three Fiber - Motion
+
+### (React 19 version of framer-motion-3d)
+
+Framer Motion is now [Motion](https://motion.dev/). Subsequently, and due to React19, the creators of Framer Motion deprecated [framer-motion-3d](https://motion.dev/docs/react-three-fiber).
+
+This acts as a drop-in replacement for that. Targeting React 19 and using motion / motion/react under the hood.
+
+## Storybook demo
+
+[demo](https://r3f-motion.vercel.app/)

package/dist/cjs/index.js

@@ -0,0 +1,465 @@
+"use client";
+'use strict';
+
+var tslib = require('tslib');
+var react = require('react');
+var motion$1 = require('motion');
+var jsxRuntime = require('react/jsx-runtime');
+var fiber = require('@react-three/fiber');
+var three = require('three');
+
+const useRender = (Component, props, forwardedRef, instanceRef, initialValues) => {
+    /**
+     * Create a callback ref that captures the Three.js instance
+     */
+    const callbackRef = react.useCallback((instance) => {
+        if (!instance)
+            return;
+        // Apply initial values immediately to prevent FOUC
+        if (initialValues) {
+            // Property mapping configuration
+            const propertyMap = {
+                x: (val) => instance.position && (instance.position.x = val),
+                y: (val) => instance.position && (instance.position.y = val),
+                z: (val) => instance.position && (instance.position.z = val),
+                rotateX: (val) => instance.rotation && (instance.rotation.x = val),
+                rotateY: (val) => instance.rotation && (instance.rotation.y = val),
+                rotateZ: (val) => instance.rotation && (instance.rotation.z = val),
+                scale: (val) => instance.scale &&
+                    instance.scale.set(val, val, val),
+                scaleX: (val) => instance.scale && (instance.scale.x = val),
+                scaleY: (val) => instance.scale && (instance.scale.y = val),
+                scaleZ: (val) => instance.scale && (instance.scale.z = val),
+                color: (val) => {
+                    const color = instance.color;
+                    if (color && color.set) {
+                        color.set(val);
+                    }
+                },
+                opacity: (val) => instance.opacity !== undefined &&
+                    (instance.opacity = val),
+                emissive: (val) => {
+                    const emissive = instance.emissive;
+                    if (emissive && emissive.set) {
+                        emissive.set(val);
+                    }
+                },
+                emissiveIntensity: (val) => instance.emissiveIntensity !== undefined &&
+                    (instance.emissiveIntensity = val),
+                roughness: (val) => instance.roughness !== undefined &&
+                    (instance.roughness = val),
+                metalness: (val) => instance.metalness !== undefined &&
+                    (instance.metalness = val),
+            };
+            for (const key in initialValues) {
+                const setter = propertyMap[key];
+                if (setter) {
+                    setter(initialValues[key]);
+                }
+            }
+        }
+        // Store instance in the ref so animations can access it
+        instanceRef.current = instance;
+        // Call the forwarded ref if it exists
+        if (typeof forwardedRef === "function") {
+            forwardedRef(instance);
+        }
+        else if (forwardedRef) {
+            // eslint-disable-next-line react-hooks/immutability, @typescript-eslint/no-explicit-any
+            forwardedRef.current = instance;
+        }
+    }, [instanceRef, forwardedRef, initialValues]);
+    return react.createElement(Component, Object.assign({ ref: callbackRef }, props));
+};
+
+function useHover(isStatic, props, options) {
+    const { whileHover, onHoverStart, onHoverEnd, onPointerOver, onPointerOut } = props;
+    const { captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, transition, } = options;
+    const preHoverStateRef = react.useRef(null);
+    const returnTimeoutRef = react.useRef(null);
+    const handlePointerEnter = react.useCallback((event) => {
+        if (whileHover) {
+            if (returnTimeoutRef.current) {
+                clearTimeout(returnTimeoutRef.current);
+                returnTimeoutRef.current = null;
+            }
+            if (!preHoverStateRef.current) {
+                preHoverStateRef.current = captureInstanceState();
+            }
+            const targetValues = typeof whileHover === "string"
+                ? resolveVariant(whileHover)
+                : whileHover;
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+        }
+        onHoverStart === null || onHoverStart === void 0 ? void 0 : onHoverStart(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerOver === null || onPointerOver === void 0 ? void 0 : onPointerOver(event);
+    }, [
+        whileHover,
+        onHoverStart,
+        onPointerOver,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerLeave = react.useCallback((event) => {
+        if (whileHover && preHoverStateRef.current) {
+            const targetValues = buildTargetFromState(preHoverStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preHoverStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+        }
+        onHoverEnd === null || onHoverEnd === void 0 ? void 0 : onHoverEnd(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerOut === null || onPointerOut === void 0 ? void 0 : onPointerOut(event);
+    }, [
+        whileHover,
+        onHoverEnd,
+        onPointerOut,
+        buildTargetFromState,
+        animateToTarget,
+        transition,
+    ]);
+    const isHoverEnabled = whileHover || onHoverStart || onHoverEnd;
+    if (!isHoverEnabled)
+        return {};
+    return {
+        onPointerEnter: handlePointerEnter,
+        onPointerLeave: handlePointerLeave,
+    };
+}
+
+function useTap(isStatic, props, options) {
+    const { whileTap, onTapStart, onTap, onTapCancel, onPointerDown, onPointerUp, } = props;
+    const { captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, transition, } = options;
+    const preTapStateRef = react.useRef(null);
+    const returnTimeoutRef = react.useRef(null);
+    const handlePointerDown = react.useCallback((event) => {
+        if (whileTap) {
+            if (returnTimeoutRef.current) {
+                clearTimeout(returnTimeoutRef.current);
+                returnTimeoutRef.current = null;
+            }
+            if (!preTapStateRef.current) {
+                preTapStateRef.current = captureInstanceState();
+            }
+            const targetValues = typeof whileTap === "string"
+                ? resolveVariant(whileTap)
+                : whileTap;
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+        }
+        onTapStart === null || onTapStart === void 0 ? void 0 : onTapStart(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerDown === null || onPointerDown === void 0 ? void 0 : onPointerDown(event);
+    }, [
+        whileTap,
+        onTapStart,
+        onPointerDown,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerUp = react.useCallback((event) => {
+        if (whileTap && preTapStateRef.current) {
+            const targetValues = buildTargetFromState(preTapStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preTapStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+            onTap === null || onTap === void 0 ? void 0 : onTap(event.nativeEvent, {
+                point: {
+                    x: event.nativeEvent.clientX,
+                    y: event.nativeEvent.clientY,
+                },
+            });
+        }
+        onPointerUp === null || onPointerUp === void 0 ? void 0 : onPointerUp(event);
+    }, [
+        whileTap,
+        onTap,
+        onPointerUp,
+        buildTargetFromState,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerCancel = react.useCallback((event) => {
+        if (whileTap && preTapStateRef.current) {
+            const targetValues = buildTargetFromState(preTapStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preTapStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+            onTapCancel === null || onTapCancel === void 0 ? void 0 : onTapCancel(event.nativeEvent, {
+                point: {
+                    x: event.nativeEvent.clientX,
+                    y: event.nativeEvent.clientY,
+                },
+            });
+        }
+    }, [whileTap, onTapCancel, buildTargetFromState, animateToTarget, transition]);
+    const isTapEnabled = onTap || onTapStart || onTapCancel || whileTap;
+    if (!isTapEnabled)
+        return {};
+    return {
+        onPointerDown: handlePointerDown,
+        onPointerUp: handlePointerUp,
+        onPointerCancel: handlePointerCancel,
+    };
+}
+
+const MotionContext = react.createContext(null);
+function custom(Component) {
+    const MotionComponent = react.forwardRef((props, ref) => {
+        const instanceRef = react.useRef(null);
+        const animationRef = react.useRef(null);
+        const childIndexCounterRef = react.useRef(0);
+        const parentContext = react.useContext(MotionContext);
+        const childIndex = react.useMemo(() => { var _a, _b; return (_b = (_a = parentContext === null || parentContext === void 0 ? void 0 : parentContext.getNextChildIndex) === null || _a === void 0 ? void 0 : _a.call(parentContext)) !== null && _b !== void 0 ? _b : 0; }, 
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        []);
+        const _a = props, { initial: initialProp, animate: animateProp, transition, variants, custom, inherit = true, children } = _a, restProps = tslib.__rest(_a, ["initial", "animate", "transition", "variants", "custom", "inherit", "children"]);
+        const initial = initialProp !== undefined
+            ? initialProp
+            : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.initial);
+        const animate = animateProp !== undefined
+            ? animateProp
+            : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.animate);
+        const effectiveVariants = variants || (inherit ? parentContext === null || parentContext === void 0 ? void 0 : parentContext.variants : undefined);
+        const effectiveCustom = custom !== undefined ? custom : parentContext === null || parentContext === void 0 ? void 0 : parentContext.custom;
+        const resolveVariant = react.useCallback((variantKey) => {
+            if (!effectiveVariants || !variantKey)
+                return null;
+            const variant = effectiveVariants[variantKey];
+            return typeof variant === "function"
+                ? variant(effectiveCustom)
+                : variant;
+        }, [effectiveVariants, effectiveCustom]);
+        const captureInstanceState = react.useCallback(() => {
+            const instance = instanceRef.current;
+            if (!instance)
+                return null;
+            return {
+                position: {
+                    x: instance.position.x,
+                    y: instance.position.y,
+                    z: instance.position.z,
+                },
+                rotation: {
+                    x: instance.rotation.x,
+                    y: instance.rotation.y,
+                    z: instance.rotation.z,
+                },
+                scale: {
+                    x: instance.scale.x,
+                    y: instance.scale.y,
+                    z: instance.scale.z,
+                },
+            };
+        }, []);
+        const buildTargetFromState = react.useCallback((capturedState) => ({
+            x: capturedState.position.x,
+            y: capturedState.position.y,
+            z: capturedState.position.z,
+            rotateX: capturedState.rotation.x,
+            rotateY: capturedState.rotation.y,
+            rotateZ: capturedState.rotation.z,
+            scale: capturedState.scale.x,
+        }), []);
+        const animateToTarget = react.useCallback((targetValues, options) => {
+            var _a;
+            const instance = instanceRef.current;
+            if (!instance || !targetValues)
+                return;
+            (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+            const convertOptions = (opts) => {
+                if (!opts)
+                    return { type: "tween" };
+                const base = {
+                    type: opts.type === "spring"
+                        ? "spring"
+                        : opts.type === "inertia"
+                            ? "inertia"
+                            : "tween",
+                };
+                const validKeys = [
+                    "duration",
+                    "ease",
+                    "delay",
+                    "repeat",
+                    "repeatType",
+                    "repeatDelay",
+                    "stiffness",
+                    "damping",
+                    "mass",
+                ];
+                return Object.assign(base, ...validKeys
+                    .filter((key) => opts[key] !== undefined)
+                    .map((key) => ({ [key]: opts[key] })));
+            };
+            const getPropertyOpts = (key) => options && typeof options === "object" && key in options
+                ? convertOptions(options[key])
+                : convertOptions(options);
+            const transformMap = {
+                x: { target: instance.position, prop: "x" },
+                y: { target: instance.position, prop: "y" },
+                z: { target: instance.position, prop: "z" },
+                rotateX: { target: instance.rotation, prop: "x" },
+                rotateY: { target: instance.rotation, prop: "y" },
+                rotateZ: { target: instance.rotation, prop: "z" },
+                scale: { target: instance.scale, prop: "x", multi: true },
+                scaleX: { target: instance.scale, prop: "x" },
+                scaleY: { target: instance.scale, prop: "y" },
+                scaleZ: { target: instance.scale, prop: "z" },
+            };
+            const animations = [];
+            const animateColor = (target, value, opts) => {
+                const ColorConstructor = target.constructor;
+                const tempColor = new ColorConstructor(value);
+                ["r", "g", "b"].forEach((channel) => animations.push(motion$1.animate(target, { [channel]: tempColor[channel] }, opts)));
+            };
+            Object.entries(targetValues).forEach(([key, value]) => {
+                const opts = getPropertyOpts(key);
+                const mapping = transformMap[key];
+                if (mapping === null || mapping === void 0 ? void 0 : mapping.target) {
+                    if (mapping.multi) {
+                        ["x", "y", "z"].forEach((axis) => animations.push(motion$1.animate(mapping.target, { [axis]: value }, opts)));
+                    }
+                    else {
+                        animations.push(motion$1.animate(mapping.target, { [mapping.prop]: value }, opts));
+                    }
+                }
+                else if (key === "color" && instance.color) {
+                    animateColor(instance.color, value, opts);
+                }
+                else if (key === "emissive" && instance.emissive) {
+                    animateColor(instance.emissive, value, opts);
+                }
+                else if (key === "opacity" && instance.opacity !== undefined) {
+                    animations.push(motion$1.animate(instance, { opacity: value }, opts));
+                }
+                else if (key === "emissiveIntensity" &&
+                    instance.emissiveIntensity !== undefined) {
+                    animations.push(motion$1.animate(instance, { emissiveIntensity: value }, opts));
+                }
+                else if (key === "roughness" &&
+                    instance.roughness !== undefined) {
+                    animations.push(motion$1.animate(instance, { roughness: value }, opts));
+                }
+                else if (key === "metalness" &&
+                    instance.metalness !== undefined) {
+                    animations.push(motion$1.animate(instance, { metalness: value }, opts));
+                }
+            });
+            animationRef.current = {
+                stop: () => animations.forEach((anim) => { var _a; return (_a = anim.stop) === null || _a === void 0 ? void 0 : _a.call(anim); }),
+            };
+        }, []);
+        react.useEffect(() => {
+            if (!instanceRef.current || !animate)
+                return;
+            const resolved = typeof animate === "string" ? resolveVariant(animate) : animate;
+            if (!resolved)
+                return;
+            const resolvedObj = resolved;
+            const { transition: variantTransition } = resolvedObj, targetValues = tslib.__rest(resolvedObj, ["transition"]);
+            let effectiveTransition = variantTransition || transition;
+            const parentTrans = parentContext === null || parentContext === void 0 ? void 0 : parentContext.transition;
+            if ((parentTrans === null || parentTrans === void 0 ? void 0 : parentTrans.delayChildren) !== undefined ||
+                (parentTrans === null || parentTrans === void 0 ? void 0 : parentTrans.staggerChildren) !== undefined) {
+                const orchestrationDelay = (parentTrans.delayChildren || 0) +
+                    childIndex * (parentTrans.staggerChildren || 0);
+                effectiveTransition = Object.assign(Object.assign({}, effectiveTransition), { delay: ((effectiveTransition === null || effectiveTransition === void 0 ? void 0 : effectiveTransition.delay) || 0) + orchestrationDelay });
+            }
+            animateToTarget(targetValues, effectiveTransition);
+            return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
+        }, [
+            animate,
+            transition,
+            resolveVariant,
+            animateToTarget,
+            childIndex,
+            parentContext,
+        ]);
+        const gestureProps = {
+            captureInstanceState,
+            buildTargetFromState,
+            animateToTarget,
+            resolveVariant,
+            transition,
+        };
+        const gestureHandlers = Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps));
+        const resolvedInitialValues = typeof initial === "string" ? resolveVariant(initial) : initial;
+        const element = useRender(Component, Object.assign(Object.assign(Object.assign({}, restProps), gestureHandlers), { children }), ref, instanceRef, resolvedInitialValues);
+        const getNextChildIndex = react.useCallback(() => {
+            const index = childIndexCounterRef.current;
+            childIndexCounterRef.current += 1;
+            return index;
+        }, []);
+        if (initial !== undefined || animate !== undefined || effectiveVariants) {
+            const contextValue = {
+                initial,
+                animate,
+                variants: effectiveVariants,
+                transition,
+                custom: effectiveCustom,
+                getNextChildIndex,
+            };
+            return react.createElement(MotionContext.Provider, { value: contextValue }, element);
+        }
+        return element;
+    });
+    MotionComponent.displayName = `Motion(${Component})`;
+    return MotionComponent;
+}
+const componentCache = new Map();
+const motion = new Proxy(custom, {
+    get: (_, key) => {
+        if (!componentCache.has(key)) {
+            componentCache.set(key, custom(key));
+        }
+        return componentCache.get(key);
+    },
+});
+
+const MotionCamera = (props) => {
+    const { fov = 75, near = 0.1, far = 1000, type = "perspective" } = props, restProps = tslib.__rest(props, ["fov", "near", "far", "type"]);
+    const { size, set } = fiber.useThree();
+    const camera = react.useMemo(() => {
+        const aspect = size.width / size.height;
+        let cam;
+        if (type === "perspective") {
+            cam = new three.PerspectiveCamera(fov, aspect, near, far);
+        }
+        else {
+            const frustumSize = 10;
+            cam = new three.OrthographicCamera((-frustumSize * aspect) / 2, (frustumSize * aspect) / 2, frustumSize / 2, -frustumSize / 2, near, far);
+        }
+        cam.updateProjectionMatrix();
+        return cam;
+    }, [type, fov, near, far, size.width, size.height]);
+    react.useLayoutEffect(() => {
+        set({ camera });
+    }, [camera, set]);
+    return jsxRuntime.jsx(motion.primitive, Object.assign({ object: camera }, restProps));
+};
+
+exports.MotionCamera = MotionCamera;
+exports.motion = motion;

package/dist/es/components/MotionCamera.mjs

@@ -0,0 +1,31 @@
+"use client";
+import { __rest } from 'tslib';
+import { jsx } from 'react/jsx-runtime';
+import { useMemo, useLayoutEffect } from 'react';
+import { useThree } from '@react-three/fiber';
+import { motion } from '../render/motion.mjs';
+import { PerspectiveCamera, OrthographicCamera } from 'three';
+
+const MotionCamera = (props) => {
+    const { fov = 75, near = 0.1, far = 1000, type = "perspective" } = props, restProps = __rest(props, ["fov", "near", "far", "type"]);
+    const { size, set } = useThree();
+    const camera = useMemo(() => {
+        const aspect = size.width / size.height;
+        let cam;
+        if (type === "perspective") {
+            cam = new PerspectiveCamera(fov, aspect, near, far);
+        }
+        else {
+            const frustumSize = 10;
+            cam = new OrthographicCamera((-frustumSize * aspect) / 2, (frustumSize * aspect) / 2, frustumSize / 2, -frustumSize / 2, near, far);
+        }
+        cam.updateProjectionMatrix();
+        return cam;
+    }, [type, fov, near, far, size.width, size.height]);
+    useLayoutEffect(() => {
+        set({ camera });
+    }, [camera, set]);
+    return jsx(motion.primitive, Object.assign({ object: camera }, restProps));
+};
+
+export { MotionCamera as default };

package/dist/es/index.mjs

@@ -0,0 +1,3 @@
+"use client";
+export { motion } from './render/motion.mjs';
+export { default as MotionCamera } from './components/MotionCamera.mjs';

package/dist/es/render/gestures/use-hover.mjs

@@ -0,0 +1,72 @@
+"use client";
+import { useRef, useCallback } from 'react';
+
+function useHover(isStatic, props, options) {
+    const { whileHover, onHoverStart, onHoverEnd, onPointerOver, onPointerOut } = props;
+    const { captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, transition, } = options;
+    const preHoverStateRef = useRef(null);
+    const returnTimeoutRef = useRef(null);
+    const handlePointerEnter = useCallback((event) => {
+        if (whileHover) {
+            if (returnTimeoutRef.current) {
+                clearTimeout(returnTimeoutRef.current);
+                returnTimeoutRef.current = null;
+            }
+            if (!preHoverStateRef.current) {
+                preHoverStateRef.current = captureInstanceState();
+            }
+            const targetValues = typeof whileHover === "string"
+                ? resolveVariant(whileHover)
+                : whileHover;
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+        }
+        onHoverStart === null || onHoverStart === void 0 ? void 0 : onHoverStart(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerOver === null || onPointerOver === void 0 ? void 0 : onPointerOver(event);
+    }, [
+        whileHover,
+        onHoverStart,
+        onPointerOver,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerLeave = useCallback((event) => {
+        if (whileHover && preHoverStateRef.current) {
+            const targetValues = buildTargetFromState(preHoverStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preHoverStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+        }
+        onHoverEnd === null || onHoverEnd === void 0 ? void 0 : onHoverEnd(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerOut === null || onPointerOut === void 0 ? void 0 : onPointerOut(event);
+    }, [
+        whileHover,
+        onHoverEnd,
+        onPointerOut,
+        buildTargetFromState,
+        animateToTarget,
+        transition,
+    ]);
+    const isHoverEnabled = whileHover || onHoverStart || onHoverEnd;
+    if (!isHoverEnabled)
+        return {};
+    return {
+        onPointerEnter: handlePointerEnter,
+        onPointerLeave: handlePointerLeave,
+    };
+}
+
+export { useHover };

package/dist/es/render/gestures/use-tap.mjs

@@ -0,0 +1,89 @@
+"use client";
+import { useRef, useCallback } from 'react';
+
+function useTap(isStatic, props, options) {
+    const { whileTap, onTapStart, onTap, onTapCancel, onPointerDown, onPointerUp, } = props;
+    const { captureInstanceState, buildTargetFromState, animateToTarget, resolveVariant, transition, } = options;
+    const preTapStateRef = useRef(null);
+    const returnTimeoutRef = useRef(null);
+    const handlePointerDown = useCallback((event) => {
+        if (whileTap) {
+            if (returnTimeoutRef.current) {
+                clearTimeout(returnTimeoutRef.current);
+                returnTimeoutRef.current = null;
+            }
+            if (!preTapStateRef.current) {
+                preTapStateRef.current = captureInstanceState();
+            }
+            const targetValues = typeof whileTap === "string"
+                ? resolveVariant(whileTap)
+                : whileTap;
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+        }
+        onTapStart === null || onTapStart === void 0 ? void 0 : onTapStart(event.nativeEvent, {
+            point: {
+                x: event.nativeEvent.clientX,
+                y: event.nativeEvent.clientY,
+            },
+        });
+        onPointerDown === null || onPointerDown === void 0 ? void 0 : onPointerDown(event);
+    }, [
+        whileTap,
+        onTapStart,
+        onPointerDown,
+        captureInstanceState,
+        resolveVariant,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerUp = useCallback((event) => {
+        if (whileTap && preTapStateRef.current) {
+            const targetValues = buildTargetFromState(preTapStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preTapStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+            onTap === null || onTap === void 0 ? void 0 : onTap(event.nativeEvent, {
+                point: {
+                    x: event.nativeEvent.clientX,
+                    y: event.nativeEvent.clientY,
+                },
+            });
+        }
+        onPointerUp === null || onPointerUp === void 0 ? void 0 : onPointerUp(event);
+    }, [
+        whileTap,
+        onTap,
+        onPointerUp,
+        buildTargetFromState,
+        animateToTarget,
+        transition,
+    ]);
+    const handlePointerCancel = useCallback((event) => {
+        if (whileTap && preTapStateRef.current) {
+            const targetValues = buildTargetFromState(preTapStateRef.current);
+            animateToTarget(targetValues, transition || { duration: 0.2 });
+            returnTimeoutRef.current = setTimeout(() => {
+                preTapStateRef.current = null;
+                returnTimeoutRef.current = null;
+            }, ((transition === null || transition === void 0 ? void 0 : transition.duration) || 0.2) * 1000);
+            onTapCancel === null || onTapCancel === void 0 ? void 0 : onTapCancel(event.nativeEvent, {
+                point: {
+                    x: event.nativeEvent.clientX,
+                    y: event.nativeEvent.clientY,
+                },
+            });
+        }
+    }, [whileTap, onTapCancel, buildTargetFromState, animateToTarget, transition]);
+    const isTapEnabled = onTap || onTapStart || onTapCancel || whileTap;
+    if (!isTapEnabled)
+        return {};
+    return {
+        onPointerDown: handlePointerDown,
+        onPointerUp: handlePointerUp,
+        onPointerCancel: handlePointerCancel,
+    };
+}
+
+export { useTap };

package/dist/es/render/motion.mjs

@@ -0,0 +1,223 @@
+"use client";
+import { __rest } from 'tslib';
+import { createContext, forwardRef, useRef, useContext, useMemo, useCallback, useEffect, createElement } from 'react';
+import { animate } from 'motion';
+import { useRender } from './use-render.mjs';
+import { useHover } from './gestures/use-hover.mjs';
+import { useTap } from './gestures/use-tap.mjs';
+
+const MotionContext = createContext(null);
+function custom(Component) {
+    const MotionComponent = forwardRef((props, ref) => {
+        const instanceRef = useRef(null);
+        const animationRef = useRef(null);
+        const childIndexCounterRef = useRef(0);
+        const parentContext = useContext(MotionContext);
+        const childIndex = useMemo(() => { var _a, _b; return (_b = (_a = parentContext === null || parentContext === void 0 ? void 0 : parentContext.getNextChildIndex) === null || _a === void 0 ? void 0 : _a.call(parentContext)) !== null && _b !== void 0 ? _b : 0; }, 
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        []);
+        const _a = props, { initial: initialProp, animate: animateProp, transition, variants, custom, inherit = true, children } = _a, restProps = __rest(_a, ["initial", "animate", "transition", "variants", "custom", "inherit", "children"]);
+        const initial = initialProp !== undefined
+            ? initialProp
+            : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.initial);
+        const animate$1 = animateProp !== undefined
+            ? animateProp
+            : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.animate);
+        const effectiveVariants = variants || (inherit ? parentContext === null || parentContext === void 0 ? void 0 : parentContext.variants : undefined);
+        const effectiveCustom = custom !== undefined ? custom : parentContext === null || parentContext === void 0 ? void 0 : parentContext.custom;
+        const resolveVariant = useCallback((variantKey) => {
+            if (!effectiveVariants || !variantKey)
+                return null;
+            const variant = effectiveVariants[variantKey];
+            return typeof variant === "function"
+                ? variant(effectiveCustom)
+                : variant;
+        }, [effectiveVariants, effectiveCustom]);
+        const captureInstanceState = useCallback(() => {
+            const instance = instanceRef.current;
+            if (!instance)
+                return null;
+            return {
+                position: {
+                    x: instance.position.x,
+                    y: instance.position.y,
+                    z: instance.position.z,
+                },
+                rotation: {
+                    x: instance.rotation.x,
+                    y: instance.rotation.y,
+                    z: instance.rotation.z,
+                },
+                scale: {
+                    x: instance.scale.x,
+                    y: instance.scale.y,
+                    z: instance.scale.z,
+                },
+            };
+        }, []);
+        const buildTargetFromState = useCallback((capturedState) => ({
+            x: capturedState.position.x,
+            y: capturedState.position.y,
+            z: capturedState.position.z,
+            rotateX: capturedState.rotation.x,
+            rotateY: capturedState.rotation.y,
+            rotateZ: capturedState.rotation.z,
+            scale: capturedState.scale.x,
+        }), []);
+        const animateToTarget = useCallback((targetValues, options) => {
+            var _a;
+            const instance = instanceRef.current;
+            if (!instance || !targetValues)
+                return;
+            (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+            const convertOptions = (opts) => {
+                if (!opts)
+                    return { type: "tween" };
+                const base = {
+                    type: opts.type === "spring"
+                        ? "spring"
+                        : opts.type === "inertia"
+                            ? "inertia"
+                            : "tween",
+                };
+                const validKeys = [
+                    "duration",
+                    "ease",
+                    "delay",
+                    "repeat",
+                    "repeatType",
+                    "repeatDelay",
+                    "stiffness",
+                    "damping",
+                    "mass",
+                ];
+                return Object.assign(base, ...validKeys
+                    .filter((key) => opts[key] !== undefined)
+                    .map((key) => ({ [key]: opts[key] })));
+            };
+            const getPropertyOpts = (key) => options && typeof options === "object" && key in options
+                ? convertOptions(options[key])
+                : convertOptions(options);
+            const transformMap = {
+                x: { target: instance.position, prop: "x" },
+                y: { target: instance.position, prop: "y" },
+                z: { target: instance.position, prop: "z" },
+                rotateX: { target: instance.rotation, prop: "x" },
+                rotateY: { target: instance.rotation, prop: "y" },
+                rotateZ: { target: instance.rotation, prop: "z" },
+                scale: { target: instance.scale, prop: "x", multi: true },
+                scaleX: { target: instance.scale, prop: "x" },
+                scaleY: { target: instance.scale, prop: "y" },
+                scaleZ: { target: instance.scale, prop: "z" },
+            };
+            const animations = [];
+            const animateColor = (target, value, opts) => {
+                const ColorConstructor = target.constructor;
+                const tempColor = new ColorConstructor(value);
+                ["r", "g", "b"].forEach((channel) => animations.push(animate(target, { [channel]: tempColor[channel] }, opts)));
+            };
+            Object.entries(targetValues).forEach(([key, value]) => {
+                const opts = getPropertyOpts(key);
+                const mapping = transformMap[key];
+                if (mapping === null || mapping === void 0 ? void 0 : mapping.target) {
+                    if (mapping.multi) {
+                        ["x", "y", "z"].forEach((axis) => animations.push(animate(mapping.target, { [axis]: value }, opts)));
+                    }
+                    else {
+                        animations.push(animate(mapping.target, { [mapping.prop]: value }, opts));
+                    }
+                }
+                else if (key === "color" && instance.color) {
+                    animateColor(instance.color, value, opts);
+                }
+                else if (key === "emissive" && instance.emissive) {
+                    animateColor(instance.emissive, value, opts);
+                }
+                else if (key === "opacity" && instance.opacity !== undefined) {
+                    animations.push(animate(instance, { opacity: value }, opts));
+                }
+                else if (key === "emissiveIntensity" &&
+                    instance.emissiveIntensity !== undefined) {
+                    animations.push(animate(instance, { emissiveIntensity: value }, opts));
+                }
+                else if (key === "roughness" &&
+                    instance.roughness !== undefined) {
+                    animations.push(animate(instance, { roughness: value }, opts));
+                }
+                else if (key === "metalness" &&
+                    instance.metalness !== undefined) {
+                    animations.push(animate(instance, { metalness: value }, opts));
+                }
+            });
+            animationRef.current = {
+                stop: () => animations.forEach((anim) => { var _a; return (_a = anim.stop) === null || _a === void 0 ? void 0 : _a.call(anim); }),
+            };
+        }, []);
+        useEffect(() => {
+            if (!instanceRef.current || !animate$1)
+                return;
+            const resolved = typeof animate$1 === "string" ? resolveVariant(animate$1) : animate$1;
+            if (!resolved)
+                return;
+            const resolvedObj = resolved;
+            const { transition: variantTransition } = resolvedObj, targetValues = __rest(resolvedObj, ["transition"]);
+            let effectiveTransition = variantTransition || transition;
+            const parentTrans = parentContext === null || parentContext === void 0 ? void 0 : parentContext.transition;
+            if ((parentTrans === null || parentTrans === void 0 ? void 0 : parentTrans.delayChildren) !== undefined ||
+                (parentTrans === null || parentTrans === void 0 ? void 0 : parentTrans.staggerChildren) !== undefined) {
+                const orchestrationDelay = (parentTrans.delayChildren || 0) +
+                    childIndex * (parentTrans.staggerChildren || 0);
+                effectiveTransition = Object.assign(Object.assign({}, effectiveTransition), { delay: ((effectiveTransition === null || effectiveTransition === void 0 ? void 0 : effectiveTransition.delay) || 0) + orchestrationDelay });
+            }
+            animateToTarget(targetValues, effectiveTransition);
+            return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
+        }, [
+            animate$1,
+            transition,
+            resolveVariant,
+            animateToTarget,
+            childIndex,
+            parentContext,
+        ]);
+        const gestureProps = {
+            captureInstanceState,
+            buildTargetFromState,
+            animateToTarget,
+            resolveVariant,
+            transition,
+        };
+        const gestureHandlers = Object.assign(Object.assign({}, useHover(false, props, gestureProps)), useTap(false, props, gestureProps));
+        const resolvedInitialValues = typeof initial === "string" ? resolveVariant(initial) : initial;
+        const element = useRender(Component, Object.assign(Object.assign(Object.assign({}, restProps), gestureHandlers), { children }), ref, instanceRef, resolvedInitialValues);
+        const getNextChildIndex = useCallback(() => {
+            const index = childIndexCounterRef.current;
+            childIndexCounterRef.current += 1;
+            return index;
+        }, []);
+        if (initial !== undefined || animate$1 !== undefined || effectiveVariants) {
+            const contextValue = {
+                initial,
+                animate: animate$1,
+                variants: effectiveVariants,
+                transition,
+                custom: effectiveCustom,
+                getNextChildIndex,
+            };
+            return createElement(MotionContext.Provider, { value: contextValue }, element);
+        }
+        return element;
+    });
+    MotionComponent.displayName = `Motion(${Component})`;
+    return MotionComponent;
+}
+const componentCache = new Map();
+const motion = new Proxy(custom, {
+    get: (_, key) => {
+        if (!componentCache.has(key)) {
+            componentCache.set(key, custom(key));
+        }
+        return componentCache.get(key);
+    },
+});
+
+export { motion };

package/dist/es/render/use-render.mjs

@@ -0,0 +1,68 @@
+"use client";
+import { useCallback, createElement } from 'react';
+
+const useRender = (Component, props, forwardedRef, instanceRef, initialValues) => {
+    /**
+     * Create a callback ref that captures the Three.js instance
+     */
+    const callbackRef = useCallback((instance) => {
+        if (!instance)
+            return;
+        // Apply initial values immediately to prevent FOUC
+        if (initialValues) {
+            // Property mapping configuration
+            const propertyMap = {
+                x: (val) => instance.position && (instance.position.x = val),
+                y: (val) => instance.position && (instance.position.y = val),
+                z: (val) => instance.position && (instance.position.z = val),
+                rotateX: (val) => instance.rotation && (instance.rotation.x = val),
+                rotateY: (val) => instance.rotation && (instance.rotation.y = val),
+                rotateZ: (val) => instance.rotation && (instance.rotation.z = val),
+                scale: (val) => instance.scale &&
+                    instance.scale.set(val, val, val),
+                scaleX: (val) => instance.scale && (instance.scale.x = val),
+                scaleY: (val) => instance.scale && (instance.scale.y = val),
+                scaleZ: (val) => instance.scale && (instance.scale.z = val),
+                color: (val) => {
+                    const color = instance.color;
+                    if (color && color.set) {
+                        color.set(val);
+                    }
+                },
+                opacity: (val) => instance.opacity !== undefined &&
+                    (instance.opacity = val),
+                emissive: (val) => {
+                    const emissive = instance.emissive;
+                    if (emissive && emissive.set) {
+                        emissive.set(val);
+                    }
+                },
+                emissiveIntensity: (val) => instance.emissiveIntensity !== undefined &&
+                    (instance.emissiveIntensity = val),
+                roughness: (val) => instance.roughness !== undefined &&
+                    (instance.roughness = val),
+                metalness: (val) => instance.metalness !== undefined &&
+                    (instance.metalness = val),
+            };
+            for (const key in initialValues) {
+                const setter = propertyMap[key];
+                if (setter) {
+                    setter(initialValues[key]);
+                }
+            }
+        }
+        // Store instance in the ref so animations can access it
+        instanceRef.current = instance;
+        // Call the forwarded ref if it exists
+        if (typeof forwardedRef === "function") {
+            forwardedRef(instance);
+        }
+        else if (forwardedRef) {
+            // eslint-disable-next-line react-hooks/immutability, @typescript-eslint/no-explicit-any
+            forwardedRef.current = instance;
+        }
+    }, [instanceRef, forwardedRef, initialValues]);
+    return createElement(Component, Object.assign({ ref: callbackRef }, props));
+};
+
+export { useRender };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { Vector3, Euler, Color, ReactThreeFiber } from '@react-three/fiber';
+import * as THREE from 'three';
+import { ForwardRefExoticComponent, PropsWithoutRef, RefAttributes } from 'react';
+import { MotionValue, MotionProps, ResolvedValues } from 'motion/react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type ThreeElement = InstanceType<typeof THREE.Object3D> & Record<string, unknown>;
+interface ThreeMotionProps extends Omit<MotionProps, "style" | "children"> {
+    [key: string]: unknown;
+    onInstanceUpdate?: ReactThreeFiber.ThreeElements["object3D"]["onUpdate"];
+}
+interface ThreeRenderState {
+    [key: string]: unknown;
+    latestValues?: ResolvedValues;
+}
+/**
+ * @public
+ */
+type ForwardRefComponent<T, P> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>;
+type MotionValueOrNumber = number | MotionValue<number>;
+type MotionValueVector3 = [
+    MotionValueOrNumber,
+    MotionValueOrNumber,
+    MotionValueOrNumber
+];
+type AcceptMotionValues<T> = Omit<T, "position" | "scale" | "rotation" | "color"> & {
+    position?: Vector3 | MotionValueVector3 | MotionValueOrNumber;
+    scale?: Vector3 | MotionValueVector3 | MotionValueOrNumber;
+    rotation?: Euler | MotionValueVector3 | MotionValueOrNumber;
+    color?: Color | MotionValue<string>;
+};
+/**
+ * Motion-optimised versions of React's HTML components.
+ *
+ * @public
+ */
+type ThreeMotionComponents = {
+    [K in keyof ReactThreeFiber.ThreeElements]: ForwardRefComponent<ReactThreeFiber.ThreeElements[K] extends ReactThreeFiber.ThreeElement<infer T extends new (...args: unknown[]) => THREE.Object3D> ? InstanceType<T> : THREE.Object3D, ThreeMotionProps & Omit<AcceptMotionValues<ReactThreeFiber.ThreeElements[K]>, "onUpdate" | "transition">>;
+};
+
+declare const motion: ThreeMotionComponents;
+
+interface MotionCameraProps extends ThreeMotionProps {
+    fov?: number;
+    near?: number;
+    far?: number;
+    type?: "perspective" | "orthographic";
+}
+declare const MotionCamera: (props: MotionCameraProps) => react_jsx_runtime.JSX.Element;
+
+export { MotionCamera, motion };
+export type { AcceptMotionValues, ForwardRefComponent, ThreeElement, ThreeMotionComponents, ThreeMotionProps, ThreeRenderState };

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "r3f-motion",
+  "version": "1.0.0",
+  "description": "A simple and powerful React animation library for @react-three/fiber leveraging motion.dev",
+  "main": "dist/cjs/index.js",
+  "module": "dist/es/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/es/index.mjs",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "keywords": [
+    "react animation",
+    "react-three-fiber",
+    "framer-motion-3d",
+    "react",
+    "three",
+    "3d",
+    "animation",
+    "gestures",
+    "spring",
+    "framer"
+  ],
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/couch4/r3f-motion.git"
+  },
+  "author": "Jon Couch",
+  "license": "MIT",
+  "scripts": {
+    "lint": "bun eslint src/**/*.ts",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "build": "bun clean && tsc -p . && rollup -c",
+    "dev": "bun watch",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "clean": "rm -rf types dist lib",
+    "prettier": "prettier ./src/* --write",
+    "watch": "concurrently -c blue,red -n tsc,rollup --kill-others \"tsc --watch -p . --preserveWatchOutput\" \"rollup --config --watch --no-watch.clearScreen\"",
+    "prepack": "bun run build",
+    "postpublish": "git push --tags"
+  },
+  "dependencies": {
+    "motion": "^12.29.0",
+    "react-merge-refs": "^3.0.2"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": "^9.5.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "three": "^0.182.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@react-three/test-renderer": "^9.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/react": "^10.2.0",
+    "@storybook/react-vite": "^10.2.0",
+    "@storybook/test": "^8.6.15",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.182.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/ui": "^4.0.18",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "eslint-plugin-storybook": "^10.2.0",
+    "globals": "^16.5.0",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.8.1",
+    "rollup": "^4.56.0",
+    "rollup-plugin-dts": "^6.3.0",
+    "scheduler": "^0.27.0",
+    "storybook": "^10.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.18"
+  },
+  "gitHead": "b40bbecf29630ba30d49f763642eb3314861f08c"
+}