r3f-motion 1.0.0 → 1.0.1

package/dist/cjs/index.js

@@ -9,14 +9,16 @@ var fiber = require('@react-three/fiber');
 var three = require('three');
 
 const useRender = (Component, props, forwardedRef, instanceRef, initialValues) => {
+    const initialValuesAppliedRef = react.useRef(false);
     /**
      * 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) {
+        // Apply initial values immediately to prevent FOUC - but only once
+        if (initialValues && !initialValuesAppliedRef.current) {
+            initialValuesAppliedRef.current = true;
             // Property mapping configuration
             const propertyMap = {
                 x: (val) => instance.position && (instance.position.x = val),
@@ -225,17 +227,66 @@ function useTap(isStatic, props, options) {
     };
 }
 
+function createAnimationState() {
+    return {
+        hasStarted: false,
+        completedCount: 0,
+        totalAnimations: [],
+        latestValues: {},
+    };
+}
+function createCallbackOptions(baseOpts, callbacks, state, variant, propertyKey) {
+    if (!callbacks)
+        return baseOpts;
+    const { onAnimationUpdate, onAnimationStart, onAnimationComplete } = callbacks;
+    const variantString = typeof variant === "string" ? variant : undefined;
+    return Object.assign(Object.assign({}, baseOpts), { onUpdate: onAnimationUpdate
+            ? (latest) => {
+                // Fire onAnimationStart once on first update
+                if (!state.hasStarted && onAnimationStart) {
+                    state.hasStarted = true;
+                    onAnimationStart(variantString);
+                }
+                // Accumulate values by property key
+                if (propertyKey) {
+                    state.latestValues[propertyKey] = latest;
+                }
+                // Pass accumulated values object to user callback
+                onAnimationUpdate(state.latestValues, variantString);
+            }
+            : onAnimationStart
+                ? () => {
+                    // If only onAnimationStart is provided, still fire it
+                    if (!state.hasStarted) {
+                        state.hasStarted = true;
+                        onAnimationStart(variantString);
+                    }
+                }
+                : undefined, onComplete: () => {
+            state.completedCount++;
+            if (state.completedCount === state.totalAnimations.length &&
+                onAnimationComplete) {
+                onAnimationComplete(variantString);
+            }
+        } });
+}
+function registerAnimation(state) {
+    state.totalAnimations.push(1);
+}
+
 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 animStateRef = react.useRef(createAnimationState());
+        const callbacksRef = react.useRef(undefined);
         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 _a = props, { initial: initialProp, animate: animateProp, transition, variants, custom, inherit = true, children, onAnimationUpdate, onAnimationStart, onAnimationComplete } = _a, restProps = tslib.__rest(_a, ["initial", "animate", "transition", "variants", "custom", "inherit", "children", "onAnimationUpdate", "onAnimationStart", "onAnimationComplete"]);
         const initial = initialProp !== undefined
             ? initialProp
             : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.initial);
@@ -244,6 +295,23 @@ function custom(Component) {
             : 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;
+        // Update callbacks ref on every render
+        if (onAnimationUpdate || onAnimationStart || onAnimationComplete) {
+            const typedCallbacks = {};
+            if (onAnimationUpdate) {
+                typedCallbacks.onAnimationUpdate = onAnimationUpdate;
+            }
+            if (onAnimationStart) {
+                typedCallbacks.onAnimationStart = onAnimationStart;
+            }
+            if (onAnimationComplete) {
+                typedCallbacks.onAnimationComplete = onAnimationComplete;
+            }
+            callbacksRef.current = typedCallbacks;
+        }
+        else {
+            callbacksRef.current = undefined;
+        }
         const resolveVariant = react.useCallback((variantKey) => {
             if (!effectiveVariants || !variantKey)
                 return null;
@@ -283,12 +351,19 @@ function custom(Component) {
             rotateZ: capturedState.rotation.z,
             scale: capturedState.scale.x,
         }), []);
-        const animateToTarget = react.useCallback((targetValues, options) => {
+        const animateToTarget = react.useCallback((targetValues, options, useCallbacks = false) => {
             var _a;
             const instance = instanceRef.current;
             if (!instance || !targetValues)
                 return;
             (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+            // Reset animation state when using callbacks
+            if (useCallbacks) {
+                animStateRef.current = createAnimationState();
+            }
+            const animState = animStateRef.current;
+            const callbacks = useCallbacks ? callbacksRef.current : undefined;
+            const animateVariant = animate;
             const convertOptions = (opts) => {
                 if (!opts)
                     return { type: "tween" };
@@ -330,42 +405,52 @@ function custom(Component) {
                 scaleZ: { target: instance.scale, prop: "z" },
             };
             const animations = [];
-            const animateColor = (target, value, opts) => {
+            // Helper to create animation with optional callbacks
+            const createAnimation = (target, props, opts, propertyKey) => {
+                const animOpts = callbacks
+                    ? createCallbackOptions(opts, callbacks, animState, animateVariant, propertyKey)
+                    : opts;
+                animations.push(motion$1.animate(target, props, animOpts));
+                if (callbacks) {
+                    registerAnimation(animState);
+                }
+            };
+            const animateColor = (target, value, opts, key) => {
                 const ColorConstructor = target.constructor;
                 const tempColor = new ColorConstructor(value);
-                ["r", "g", "b"].forEach((channel) => animations.push(motion$1.animate(target, { [channel]: tempColor[channel] }, opts)));
+                ["r", "g", "b"].forEach((channel) => createAnimation(target, { [channel]: tempColor[channel] }, opts, key));
             };
             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)));
+                        ["x", "y", "z"].forEach((axis) => createAnimation(mapping.target, { [axis]: value }, opts, key));
                     }
                     else {
-                        animations.push(motion$1.animate(mapping.target, { [mapping.prop]: value }, opts));
+                        createAnimation(mapping.target, { [mapping.prop]: value }, opts, key);
                     }
                 }
                 else if (key === "color" && instance.color) {
-                    animateColor(instance.color, value, opts);
+                    animateColor(instance.color, value, opts, key);
                 }
                 else if (key === "emissive" && instance.emissive) {
-                    animateColor(instance.emissive, value, opts);
+                    animateColor(instance.emissive, value, opts, key);
                 }
                 else if (key === "opacity" && instance.opacity !== undefined) {
-                    animations.push(motion$1.animate(instance, { opacity: value }, opts));
+                    createAnimation(instance, { opacity: value }, opts, key);
                 }
                 else if (key === "emissiveIntensity" &&
                     instance.emissiveIntensity !== undefined) {
-                    animations.push(motion$1.animate(instance, { emissiveIntensity: value }, opts));
+                    createAnimation(instance, { emissiveIntensity: value }, opts, key);
                 }
                 else if (key === "roughness" &&
                     instance.roughness !== undefined) {
-                    animations.push(motion$1.animate(instance, { roughness: value }, opts));
+                    createAnimation(instance, { roughness: value }, opts, key);
                 }
                 else if (key === "metalness" &&
                     instance.metalness !== undefined) {
-                    animations.push(motion$1.animate(instance, { metalness: value }, opts));
+                    createAnimation(instance, { metalness: value }, opts, key);
                 }
             });
             animationRef.current = {
@@ -388,16 +473,10 @@ function custom(Component) {
                     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);
+            animateToTarget(targetValues, effectiveTransition, true);
             return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
-        }, [
-            animate,
-            transition,
-            resolveVariant,
-            animateToTarget,
-            childIndex,
-            parentContext,
-        ]);
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [animate]);
         const gestureProps = {
             captureInstanceState,
             buildTargetFromState,
@@ -427,7 +506,7 @@ function custom(Component) {
         return element;
     });
     MotionComponent.displayName = `Motion(${Component})`;
-    return MotionComponent;
+    return react.memo(MotionComponent);
 }
 const componentCache = new Map();
 const motion = new Proxy(custom, {

package/dist/es/render/events/index.mjs

@@ -0,0 +1,49 @@
+"use client";
+function createAnimationState() {
+    return {
+        hasStarted: false,
+        completedCount: 0,
+        totalAnimations: [],
+        latestValues: {},
+    };
+}
+function createCallbackOptions(baseOpts, callbacks, state, variant, propertyKey) {
+    if (!callbacks)
+        return baseOpts;
+    const { onAnimationUpdate, onAnimationStart, onAnimationComplete } = callbacks;
+    const variantString = typeof variant === "string" ? variant : undefined;
+    return Object.assign(Object.assign({}, baseOpts), { onUpdate: onAnimationUpdate
+            ? (latest) => {
+                // Fire onAnimationStart once on first update
+                if (!state.hasStarted && onAnimationStart) {
+                    state.hasStarted = true;
+                    onAnimationStart(variantString);
+                }
+                // Accumulate values by property key
+                if (propertyKey) {
+                    state.latestValues[propertyKey] = latest;
+                }
+                // Pass accumulated values object to user callback
+                onAnimationUpdate(state.latestValues, variantString);
+            }
+            : onAnimationStart
+                ? () => {
+                    // If only onAnimationStart is provided, still fire it
+                    if (!state.hasStarted) {
+                        state.hasStarted = true;
+                        onAnimationStart(variantString);
+                    }
+                }
+                : undefined, onComplete: () => {
+            state.completedCount++;
+            if (state.completedCount === state.totalAnimations.length &&
+                onAnimationComplete) {
+                onAnimationComplete(variantString);
+            }
+        } });
+}
+function registerAnimation(state) {
+    state.totalAnimations.push(1);
+}
+
+export { createAnimationState, createCallbackOptions, registerAnimation };

package/dist/es/render/motion.mjs

@@ -1,10 +1,11 @@
 "use client";
 import { __rest } from 'tslib';
-import { createContext, forwardRef, useRef, useContext, useMemo, useCallback, useEffect, createElement } from 'react';
+import { createContext, forwardRef, useRef, useContext, useMemo, useCallback, useEffect, createElement, memo } 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';
+import { createAnimationState, createCallbackOptions, registerAnimation } from './events/index.mjs';
 
 const MotionContext = createContext(null);
 function custom(Component) {
@@ -12,11 +13,13 @@ function custom(Component) {
         const instanceRef = useRef(null);
         const animationRef = useRef(null);
         const childIndexCounterRef = useRef(0);
+        const animStateRef = useRef(createAnimationState());
+        const callbacksRef = useRef(undefined);
         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 _a = props, { initial: initialProp, animate: animateProp, transition, variants, custom, inherit = true, children, onAnimationUpdate, onAnimationStart, onAnimationComplete } = _a, restProps = __rest(_a, ["initial", "animate", "transition", "variants", "custom", "inherit", "children", "onAnimationUpdate", "onAnimationStart", "onAnimationComplete"]);
         const initial = initialProp !== undefined
             ? initialProp
             : inherit && (parentContext === null || parentContext === void 0 ? void 0 : parentContext.initial);
@@ -25,6 +28,23 @@ function custom(Component) {
             : 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;
+        // Update callbacks ref on every render
+        if (onAnimationUpdate || onAnimationStart || onAnimationComplete) {
+            const typedCallbacks = {};
+            if (onAnimationUpdate) {
+                typedCallbacks.onAnimationUpdate = onAnimationUpdate;
+            }
+            if (onAnimationStart) {
+                typedCallbacks.onAnimationStart = onAnimationStart;
+            }
+            if (onAnimationComplete) {
+                typedCallbacks.onAnimationComplete = onAnimationComplete;
+            }
+            callbacksRef.current = typedCallbacks;
+        }
+        else {
+            callbacksRef.current = undefined;
+        }
         const resolveVariant = useCallback((variantKey) => {
             if (!effectiveVariants || !variantKey)
                 return null;
@@ -64,12 +84,19 @@ function custom(Component) {
             rotateZ: capturedState.rotation.z,
             scale: capturedState.scale.x,
         }), []);
-        const animateToTarget = useCallback((targetValues, options) => {
+        const animateToTarget = useCallback((targetValues, options, useCallbacks = false) => {
             var _a;
             const instance = instanceRef.current;
             if (!instance || !targetValues)
                 return;
             (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+            // Reset animation state when using callbacks
+            if (useCallbacks) {
+                animStateRef.current = createAnimationState();
+            }
+            const animState = animStateRef.current;
+            const callbacks = useCallbacks ? callbacksRef.current : undefined;
+            const animateVariant = animate$1;
             const convertOptions = (opts) => {
                 if (!opts)
                     return { type: "tween" };
@@ -111,42 +138,52 @@ function custom(Component) {
                 scaleZ: { target: instance.scale, prop: "z" },
             };
             const animations = [];
-            const animateColor = (target, value, opts) => {
+            // Helper to create animation with optional callbacks
+            const createAnimation = (target, props, opts, propertyKey) => {
+                const animOpts = callbacks
+                    ? createCallbackOptions(opts, callbacks, animState, animateVariant, propertyKey)
+                    : opts;
+                animations.push(animate(target, props, animOpts));
+                if (callbacks) {
+                    registerAnimation(animState);
+                }
+            };
+            const animateColor = (target, value, opts, key) => {
                 const ColorConstructor = target.constructor;
                 const tempColor = new ColorConstructor(value);
-                ["r", "g", "b"].forEach((channel) => animations.push(animate(target, { [channel]: tempColor[channel] }, opts)));
+                ["r", "g", "b"].forEach((channel) => createAnimation(target, { [channel]: tempColor[channel] }, opts, key));
             };
             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)));
+                        ["x", "y", "z"].forEach((axis) => createAnimation(mapping.target, { [axis]: value }, opts, key));
                     }
                     else {
-                        animations.push(animate(mapping.target, { [mapping.prop]: value }, opts));
+                        createAnimation(mapping.target, { [mapping.prop]: value }, opts, key);
                     }
                 }
                 else if (key === "color" && instance.color) {
-                    animateColor(instance.color, value, opts);
+                    animateColor(instance.color, value, opts, key);
                 }
                 else if (key === "emissive" && instance.emissive) {
-                    animateColor(instance.emissive, value, opts);
+                    animateColor(instance.emissive, value, opts, key);
                 }
                 else if (key === "opacity" && instance.opacity !== undefined) {
-                    animations.push(animate(instance, { opacity: value }, opts));
+                    createAnimation(instance, { opacity: value }, opts, key);
                 }
                 else if (key === "emissiveIntensity" &&
                     instance.emissiveIntensity !== undefined) {
-                    animations.push(animate(instance, { emissiveIntensity: value }, opts));
+                    createAnimation(instance, { emissiveIntensity: value }, opts, key);
                 }
                 else if (key === "roughness" &&
                     instance.roughness !== undefined) {
-                    animations.push(animate(instance, { roughness: value }, opts));
+                    createAnimation(instance, { roughness: value }, opts, key);
                 }
                 else if (key === "metalness" &&
                     instance.metalness !== undefined) {
-                    animations.push(animate(instance, { metalness: value }, opts));
+                    createAnimation(instance, { metalness: value }, opts, key);
                 }
             });
             animationRef.current = {
@@ -169,16 +206,10 @@ function custom(Component) {
                     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);
+            animateToTarget(targetValues, effectiveTransition, true);
             return () => { var _a; return (_a = animationRef.current) === null || _a === void 0 ? void 0 : _a.stop(); };
-        }, [
-            animate$1,
-            transition,
-            resolveVariant,
-            animateToTarget,
-            childIndex,
-            parentContext,
-        ]);
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [animate$1]);
         const gestureProps = {
             captureInstanceState,
             buildTargetFromState,
@@ -208,7 +239,7 @@ function custom(Component) {
         return element;
     });
     MotionComponent.displayName = `Motion(${Component})`;
-    return MotionComponent;
+    return memo(MotionComponent);
 }
 const componentCache = new Map();
 const motion = new Proxy(custom, {

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

@@ -1,15 +1,17 @@
 "use client";
-import { useCallback, createElement } from 'react';
+import { useRef, useCallback, createElement } from 'react';
 
 const useRender = (Component, props, forwardedRef, instanceRef, initialValues) => {
+    const initialValuesAppliedRef = useRef(false);
     /**
      * 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) {
+        // Apply initial values immediately to prevent FOUC - but only once
+        if (initialValues && !initialValuesAppliedRef.current) {
+            initialValuesAppliedRef.current = true;
             // Property mapping configuration
             const propertyMap = {
                 x: (val) => instance.position && (instance.position.x = val),

package/dist/index.d.ts

@@ -5,9 +5,12 @@ 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"> {
+interface ThreeMotionProps extends Omit<MotionProps, "style" | "children" | "onUpdate" | "onAnimationStart" | "onAnimationComplete"> {
     [key: string]: unknown;
     onInstanceUpdate?: ReactThreeFiber.ThreeElements["object3D"]["onUpdate"];
+    onUpdate?: (values: Record<string, unknown>, animationVariant?: string) => void;
+    onAnimationStart?: (values: Record<string, unknown>, animationVariant?: string) => void;
+    onAnimationComplete?: (values: Record<string, unknown>, animationVariant?: string) => void;
 }
 interface ThreeRenderState {
     [key: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "r3f-motion",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",
@@ -55,8 +55,8 @@
   },
   "peerDependencies": {
     "@react-three/fiber": "^9.5.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "three": "^0.182.0"
   },
   "devDependencies": {
@@ -67,8 +67,6 @@
     "@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",