@fluentui/react-motion 9.15.0 → 9.16.0

package/CHANGELOG.md

@@ -1,19 +1,29 @@
 # Change Log - @fluentui/react-motion
 
-This log was last generated on Thu, 23 Apr 2026 11:59:27 GMT and should not be manually modified.
+This log was last generated on Tue, 26 May 2026 09:33:47 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [9.16.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.16.0)
+
+Tue, 26 May 2026 09:33:47 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.15.0..@fluentui/react-motion_v9.16.0)
+
+### Minor changes
+
+- feat(react-motion): add replayKey prop to replay motion without remounting ([PR #36108](https://github.com/microsoft/fluentui/pull/36108) by robertpenner@microsoft.com)
+- Bump @fluentui/react-utilities to v9.26.4 ([PR #36246](https://github.com/microsoft/fluentui/pull/36246) by beachball)
+
 ## [9.15.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.15.0)
 
-Thu, 23 Apr 2026 11:59:27 GMT 
+Thu, 23 Apr 2026 14:21:02 GMT 
 [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.14.0..@fluentui/react-motion_v9.15.0)
 
 ### Minor changes
 
-- fix(react-motion): apply MotionComponent type to presence definition ([PR #35952](https://github.com/microsoft/fluentui/pull/35952) by robertpenner@microsoft.com)
 - feat: expose motion params as direct props on motion slot types ([PR #36011](https://github.com/microsoft/fluentui/pull/36011) by robertpenner@microsoft.com)
-- Bump @fluentui/react-utilities to v9.26.3 ([PR #35996](https://github.com/microsoft/fluentui/pull/35996) by beachball)
+- fix(react-motion): apply MotionComponent type to presence definition ([PR #35952](https://github.com/microsoft/fluentui/pull/35952) by robertpenner@microsoft.com)
+- Bump @fluentui/react-utilities to v9.26.3 ([PR #36035](https://github.com/microsoft/fluentui/pull/36035) by beachball)
 
 ## [9.14.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.14.0)
 

package/README.md

@@ -1,5 +1,63 @@
 # @fluentui/react-motion
 
-**React Motions components for [Fluent UI React](https://react.fluentui.dev/)**
+**React Motion components for [Fluent UI React](https://react.fluentui.dev/)**
 
-These are not production-ready components and **should never be used in product**. This space is useful for testing new components whose APIs might change before final release.
+A lightweight, performant animation library for React that brings Fluent UI experiences to life using the Web Animations API (WAAPI).
+
+## Features
+
+- ⚡ **Performance** — Animations run on the compositor thread for smooth 60fps motion
+- 📦 **Lightweight** — ~3KB gzipped, leverages native browser capabilities
+- 🎯 **Simple by default** — Common UI animations with minimal code
+- 🔧 **Powerful on demand** — Full customization with keyframes, timing, and callbacks
+
+## Installation
+
+```bash
+npm install @fluentui/react-motion
+# or
+yarn add @fluentui/react-motion
+```
+
+## Quick Start
+
+```tsx
+import { createPresenceComponent, motionTokens } from '@fluentui/react-motion';
+
+// Create a custom fade presence component
+const Fade = createPresenceComponent({
+  enter: {
+    keyframes: [{ opacity: 0 }, { opacity: 1 }],
+    duration: motionTokens.durationNormal,
+  },
+  exit: {
+    keyframes: [{ opacity: 1 }, { opacity: 0 }],
+    duration: motionTokens.durationFast,
+  },
+});
+
+// Use it in your app
+function App() {
+  const [visible, setVisible] = useState(true);
+
+  return (
+    <Fade visible={visible}>
+      <div>Animated content</div>
+    </Fade>
+  );
+}
+```
+
+## Documentation
+
+📚 **[Full documentation](https://react.fluentui.dev/?path=/docs/motion-introduction--docs)**
+
+- [Introduction](https://react.fluentui.dev/?path=/docs/motion-introduction--docs) — Overview and key concepts
+- [createPresenceComponent](https://react.fluentui.dev/?path=/docs/motion-apis-createpresencecomponent--docs) — Two-way enter/exit animations
+- [createMotionComponent](https://react.fluentui.dev/?path=/docs/motion-apis-createmotioncomponent--docs) — One-way animations
+- [Motion Tokens](https://react.fluentui.dev/?path=/docs/motion-tokens--docs) — Duration and easing values
+- [Migration Guide](https://react.fluentui.dev/?path=/docs/motion-migration--docs) — Coming from Framer Motion, GSAP, etc.
+
+## Pre-built Components
+
+For ready-to-use motion components (Fade, Scale, Slide, Collapse, etc.), see **[@fluentui/react-motion-components-preview](https://www.npmjs.com/package/@fluentui/react-motion-components-preview)**.

package/dist/index.d.ts

@@ -123,6 +123,30 @@ export declare type MotionComponentProps = {
      * so the callback is triggered with "null".
      */
     onMotionStart?: (ev: null) => void;
+    /**
+     * When this value changes, the animation replays from the start on the same DOM element,
+     * cancelling any in-progress animation, without remounting the component or its children.
+     *
+     * **Why not just use a React `key`?** Changing a React `key` forces a full unmount and
+     * remount of the subtree: DOM nodes are destroyed and recreated, focus is lost, and any
+     * child state is reset. `replayKey` avoids all of that — only the animation effect reruns
+     * while the DOM and component state remain intact.
+     *
+     * Use this when you want to retrigger a motion in response to a state change (e.g. a user
+     * action or a data update) while preserving DOM continuity. It is the declarative equivalent
+     * of calling `imperativeRef.current.play()` but driven by a prop rather than a ref call.
+     *
+     * @example
+     * ```tsx
+     * // Replay a Fade.In each time the user clicks "Refresh"
+     * const [replayKey, setReplayKey] = React.useState(0);
+     * <Fade.In replayKey={replayKey}>
+     *   <div>Content</div>
+     * </Fade.In>
+     * <button onClick={() => setReplayKey(k => k + 1)}>Refresh</button>
+     * ```
+     */
+    replayKey?: string | number;
 };
 
 export declare type MotionImperativeRef = {

package/lib/factories/createMotionComponent.js

@@ -18,10 +18,11 @@ import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
  */ export function createMotionComponent(value) {
     const Atom = (props)=>{
         'use no memo';
-        const { children, imperativeRef, onMotionFinish: onMotionFinishProp, onMotionStart: onMotionStartProp, onMotionCancel: onMotionCancelProp, ..._rest } = props;
+        const { children, imperativeRef, onMotionFinish: onMotionFinishProp, onMotionStart: onMotionStartProp, onMotionCancel: onMotionCancelProp, replayKey, ..._rest } = props;
         const params = _rest;
         const [child, childRef] = useChildElement(children);
         const handleRef = useMotionImperativeRef(imperativeRef);
+        const isInitialRender = React.useRef(true);
         const skipMotions = useMotionBehaviourContext() === 'skip';
         const optionsRef = React.useRef({
             skipMotions,
@@ -38,6 +39,21 @@ import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
         const onMotionCancel = useEventCallback(()=>{
             onMotionCancelProp === null || onMotionCancelProp === void 0 ? void 0 : onMotionCancelProp(null);
         });
+        // Stable callback (all deps are refs or useEventCallback) that activates a handle for a new playback cycle.
+        //
+        // TODO: consider moving the cancel+play+rewire sequence into a handle.replay() method on AnimationHandle,
+        // keeping pure animation sequencing on the handle and React callbacks here in the component.
+        const activateAnimationHandle = React.useCallback((handle)=>{
+            onMotionStart();
+            handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);
+            if (optionsRef.current.skipMotions) {
+                handle.finish();
+            }
+        }, [
+            onMotionStart,
+            onMotionFinish,
+            onMotionCancel
+        ]);
         useIsomorphicLayoutEffect(()=>{
             // Heads up!
             // We store the params in a ref to avoid re-rendering the component when the params change.
@@ -53,15 +69,11 @@ import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
                     element,
                     ...optionsRef.current.params
                 }) : value;
-                onMotionStart();
                 const handle = animateAtoms(element, atoms, {
                     isReducedMotion: isReducedMotion()
                 });
                 handleRef.current = handle;
-                handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);
-                if (optionsRef.current.skipMotions) {
-                    handle.finish();
-                }
+                activateAnimationHandle(handle);
                 return ()=>{
                     handle.cancel();
                 };
@@ -71,10 +83,30 @@ import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
             childRef,
             handleRef,
             isReducedMotion,
-            onMotionFinish,
-            onMotionStart,
-            onMotionCancel
+            activateAnimationHandle
+        ]);
+        // Skips initial mount; on replayKey changes, reuses existing Animation objects via cancel+play
+        // rather than recreating them, preserving DOM continuity.
+        useIsomorphicLayoutEffect(()=>{
+            if (isInitialRender.current) {
+                return;
+            }
+            const handle = handleRef.current;
+            if (handle) {
+                handle.cancel();
+                handle.play();
+                activateAnimationHandle(handle);
+            }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- replayKey is intentionally the only trigger; other deps are stable refs/callbacks
+        }, [
+            replayKey
         ]);
+        useIsomorphicLayoutEffect(()=>{
+            isInitialRender.current = false;
+            return ()=>{
+                isInitialRender.current = true;
+            };
+        }, []);
         return child;
     };
     return Object.assign(Atom, {

package/lib/factories/createMotionComponent.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/factories/createMotionComponent.ts"],"sourcesContent":["'use client';\n\nimport type { JSXElement } from '@fluentui/react-utilities';\nimport { useEventCallback, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\nimport { useAnimateAtoms } from '../hooks/useAnimateAtoms';\nimport { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';\nimport { useIsReducedMotion } from '../hooks/useIsReducedMotion';\nimport { useChildElement } from '../utils/useChildElement';\nimport type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef } from '../types';\nimport { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';\n\n/**\n * A private symbol to store the motion definition on the component for variants.\n *\n * @internal\n */\nexport const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');\n\nexport type MotionComponentProps = {\n  children: JSXElement;\n\n  /** Provides imperative controls for the animation. */\n  imperativeRef?: React.Ref<MotionImperativeRef | undefined>;\n\n  /**\n   * Callback that is called when the whole motion finishes.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"finish\" events. The callback is\n   * triggered once all animations have finished with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionFinish?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion is cancelled.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"cancel\" events. The callback is\n   * triggered once all animations have been cancelled with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionCancel?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion starts.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"start\" events. The callback is\n   * triggered when the first animation is started. There is no official \"start\" event with the Web Animations API.\n   * so the callback is triggered with \"null\".\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionStart?: (ev: null) => void;\n};\n\nexport type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React.FC<\n  MotionComponentProps & MotionParams\n> & {\n  [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;\n};\n\n/**\n * Creates a component that will animate the children using the provided motion.\n *\n * @param value - A motion definition.\n */\nexport function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(\n  value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>,\n): MotionComponent<MotionParams> {\n  const Atom: React.FC<MotionComponentProps & MotionParams> = props => {\n    'use no memo';\n\n    const {\n      children,\n      imperativeRef,\n      onMotionFinish: onMotionFinishProp,\n      onMotionStart: onMotionStartProp,\n      onMotionCancel: onMotionCancelProp,\n      ..._rest\n    } = props;\n    const params = _rest as Exclude<typeof props, MotionComponentProps>;\n    const [child, childRef] = useChildElement(children);\n\n    const handleRef = useMotionImperativeRef(imperativeRef);\n    const skipMotions = useMotionBehaviourContext() === 'skip';\n    const optionsRef = React.useRef<{ skipMotions: boolean; params: MotionParams }>({\n      skipMotions,\n      params,\n    });\n\n    const animateAtoms = useAnimateAtoms();\n    const isReducedMotion = useIsReducedMotion();\n\n    const onMotionStart = useEventCallback(() => {\n      onMotionStartProp?.(null);\n    });\n\n    const onMotionFinish = useEventCallback(() => {\n      onMotionFinishProp?.(null);\n    });\n\n    const onMotionCancel = useEventCallback(() => {\n      onMotionCancelProp?.(null);\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      // Heads up!\n      // We store the params in a ref to avoid re-rendering the component when the params change.\n      optionsRef.current = { skipMotions, params };\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      const element = childRef.current;\n\n      if (element) {\n        const atoms = typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : value;\n\n        onMotionStart();\n        const handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });\n        handleRef.current = handle;\n        handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);\n\n        if (optionsRef.current.skipMotions) {\n          handle.finish();\n        }\n\n        return () => {\n          handle.cancel();\n        };\n      }\n    }, [animateAtoms, childRef, handleRef, isReducedMotion, onMotionFinish, onMotionStart, onMotionCancel]);\n\n    return child;\n  };\n\n  return Object.assign(Atom, {\n    // Heads up!\n    // Always normalize it to a function to simplify types\n    [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,\n  });\n}\n"],"names":["useEventCallback","useIsomorphicLayoutEffect","React","useAnimateAtoms","useMotionImperativeRef","useIsReducedMotion","useChildElement","useMotionBehaviourContext","MOTION_DEFINITION","Symbol","createMotionComponent","value","Atom","props","children","imperativeRef","onMotionFinish","onMotionFinishProp","onMotionStart","onMotionStartProp","onMotionCancel","onMotionCancelProp","_rest","params","child","childRef","handleRef","skipMotions","optionsRef","useRef","animateAtoms","isReducedMotion","current","element","atoms","handle","setMotionEndCallbacks","finish","cancel","Object","assign"],"mappings":"AAAA;AAGA,SAASA,gBAAgB,EAAEC,yBAAyB,QAAQ,4BAA4B;AACxF,YAAYC,WAAW,QAAQ;AAE/B,SAASC,eAAe,QAAQ,2BAA2B;AAC3D,SAASC,sBAAsB,QAAQ,kCAAkC;AACzE,SAASC,kBAAkB,QAAQ,8BAA8B;AACjE,SAASC,eAAe,QAAQ,2BAA2B;AAE3D,SAASC,yBAAyB,QAAQ,qCAAqC;AAE/E;;;;CAIC,GACD,OAAO,MAAMC,oBAAoBC,OAAO,qBAAqB;AA2C7D;;;;CAIC,GACD,OAAO,SAASC,sBACdC,KAA6D;IAE7D,MAAMC,OAAsDC,CAAAA;QAC1D;QAEA,MAAM,EACJC,QAAQ,EACRC,aAAa,EACbC,gBAAgBC,kBAAkB,EAClCC,eAAeC,iBAAiB,EAChCC,gBAAgBC,kBAAkB,EAClC,GAAGC,OACJ,GAAGT;QACJ,MAAMU,SAASD;QACf,MAAM,CAACE,OAAOC,SAAS,GAAGnB,gBAAgBQ;QAE1C,MAAMY,YAAYtB,uBAAuBW;QACzC,MAAMY,cAAcpB,gCAAgC;QACpD,MAAMqB,aAAa1B,MAAM2B,MAAM,CAAiD;YAC9EF;YACAJ;QACF;QAEA,MAAMO,eAAe3B;QACrB,MAAM4B,kBAAkB1B;QAExB,MAAMa,gBAAgBlB,iBAAiB;YACrCmB,8BAAAA,wCAAAA,kBAAoB;QACtB;QAEA,MAAMH,iBAAiBhB,iBAAiB;YACtCiB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,MAAMG,iBAAiBpB,iBAAiB;YACtCqB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEApB,0BAA0B;YACxB,YAAY;YACZ,2FAA2F;YAC3F2B,WAAWI,OAAO,GAAG;gBAAEL;gBAAaJ;YAAO;QAC7C;QAEAtB,0BAA0B;YACxB,MAAMgC,UAAUR,SAASO,OAAO;YAEhC,IAAIC,SAAS;gBACX,MAAMC,QAAQ,OAAOvB,UAAU,aAAaA,MAAM;oBAAEsB;oBAAS,GAAGL,WAAWI,OAAO,CAACT,MAAM;gBAAC,KAAKZ;gBAE/FO;gBACA,MAAMiB,SAASL,aAAaG,SAASC,OAAO;oBAAEH,iBAAiBA;gBAAkB;gBACjFL,UAAUM,OAAO,GAAGG;gBACpBA,OAAOC,qBAAqB,CAACpB,gBAAgBI;gBAE7C,IAAIQ,WAAWI,OAAO,CAACL,WAAW,EAAE;oBAClCQ,OAAOE,MAAM;gBACf;gBAEA,OAAO;oBACLF,OAAOG,MAAM;gBACf;YACF;QACF,GAAG;YAACR;YAAcL;YAAUC;YAAWK;YAAiBf;YAAgBE;YAAeE;SAAe;QAEtG,OAAOI;IACT;IAEA,OAAOe,OAAOC,MAAM,CAAC5B,MAAM;QACzB,YAAY;QACZ,sDAAsD;QACtD,CAACJ,kBAAkB,EAAE,OAAOG,UAAU,aAAaA,QAAQ,IAAMA;IACnE;AACF"}
+{"version":3,"sources":["../src/factories/createMotionComponent.ts"],"sourcesContent":["'use client';\n\nimport type { JSXElement } from '@fluentui/react-utilities';\nimport { useEventCallback, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\nimport { useAnimateAtoms } from '../hooks/useAnimateAtoms';\nimport { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';\nimport { useIsReducedMotion } from '../hooks/useIsReducedMotion';\nimport { useChildElement } from '../utils/useChildElement';\nimport type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef, AnimationHandle } from '../types';\nimport { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';\n\n/**\n * A private symbol to store the motion definition on the component for variants.\n *\n * @internal\n */\nexport const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');\n\nexport type MotionComponentProps = {\n  children: JSXElement;\n\n  /** Provides imperative controls for the animation. */\n  imperativeRef?: React.Ref<MotionImperativeRef | undefined>;\n\n  /**\n   * Callback that is called when the whole motion finishes.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"finish\" events. The callback is\n   * triggered once all animations have finished with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionFinish?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion is cancelled.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"cancel\" events. The callback is\n   * triggered once all animations have been cancelled with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionCancel?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion starts.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"start\" events. The callback is\n   * triggered when the first animation is started. There is no official \"start\" event with the Web Animations API.\n   * so the callback is triggered with \"null\".\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionStart?: (ev: null) => void;\n\n  /**\n   * When this value changes, the animation replays from the start on the same DOM element,\n   * cancelling any in-progress animation, without remounting the component or its children.\n   *\n   * **Why not just use a React `key`?** Changing a React `key` forces a full unmount and\n   * remount of the subtree: DOM nodes are destroyed and recreated, focus is lost, and any\n   * child state is reset. `replayKey` avoids all of that — only the animation effect reruns\n   * while the DOM and component state remain intact.\n   *\n   * Use this when you want to retrigger a motion in response to a state change (e.g. a user\n   * action or a data update) while preserving DOM continuity. It is the declarative equivalent\n   * of calling `imperativeRef.current.play()` but driven by a prop rather than a ref call.\n   *\n   * @example\n   * ```tsx\n   * // Replay a Fade.In each time the user clicks \"Refresh\"\n   * const [replayKey, setReplayKey] = React.useState(0);\n   * <Fade.In replayKey={replayKey}>\n   *   <div>Content</div>\n   * </Fade.In>\n   * <button onClick={() => setReplayKey(k => k + 1)}>Refresh</button>\n   * ```\n   */\n  replayKey?: string | number;\n};\n\nexport type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React.FC<\n  MotionComponentProps & MotionParams\n> & {\n  [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;\n};\n\n/**\n * Creates a component that will animate the children using the provided motion.\n *\n * @param value - A motion definition.\n */\nexport function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(\n  value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>,\n): MotionComponent<MotionParams> {\n  const Atom: React.FC<MotionComponentProps & MotionParams> = props => {\n    'use no memo';\n\n    const {\n      children,\n      imperativeRef,\n      onMotionFinish: onMotionFinishProp,\n      onMotionStart: onMotionStartProp,\n      onMotionCancel: onMotionCancelProp,\n      replayKey,\n      ..._rest\n    } = props;\n    const params = _rest as Exclude<typeof props, MotionComponentProps>;\n    const [child, childRef] = useChildElement(children);\n\n    const handleRef = useMotionImperativeRef(imperativeRef);\n    const isInitialRender = React.useRef(true);\n    const skipMotions = useMotionBehaviourContext() === 'skip';\n    const optionsRef = React.useRef<{ skipMotions: boolean; params: MotionParams }>({\n      skipMotions,\n      params,\n    });\n\n    const animateAtoms = useAnimateAtoms();\n    const isReducedMotion = useIsReducedMotion();\n\n    const onMotionStart = useEventCallback(() => {\n      onMotionStartProp?.(null);\n    });\n\n    const onMotionFinish = useEventCallback(() => {\n      onMotionFinishProp?.(null);\n    });\n\n    const onMotionCancel = useEventCallback(() => {\n      onMotionCancelProp?.(null);\n    });\n\n    // Stable callback (all deps are refs or useEventCallback) that activates a handle for a new playback cycle.\n    //\n    // TODO: consider moving the cancel+play+rewire sequence into a handle.replay() method on AnimationHandle,\n    // keeping pure animation sequencing on the handle and React callbacks here in the component.\n    const activateAnimationHandle = React.useCallback(\n      (handle: AnimationHandle) => {\n        onMotionStart();\n        handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);\n        if (optionsRef.current.skipMotions) {\n          handle.finish();\n        }\n      },\n      [onMotionStart, onMotionFinish, onMotionCancel],\n    );\n\n    useIsomorphicLayoutEffect(() => {\n      // Heads up!\n      // We store the params in a ref to avoid re-rendering the component when the params change.\n      optionsRef.current = { skipMotions, params };\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      const element = childRef.current;\n\n      if (element) {\n        const atoms = typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : value;\n\n        const handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });\n        handleRef.current = handle;\n        activateAnimationHandle(handle);\n\n        return () => {\n          handle.cancel();\n        };\n      }\n    }, [animateAtoms, childRef, handleRef, isReducedMotion, activateAnimationHandle]);\n\n    // Skips initial mount; on replayKey changes, reuses existing Animation objects via cancel+play\n    // rather than recreating them, preserving DOM continuity.\n    useIsomorphicLayoutEffect(() => {\n      if (isInitialRender.current) {\n        return;\n      }\n\n      const handle = handleRef.current;\n      if (handle) {\n        handle.cancel();\n        handle.play();\n        activateAnimationHandle(handle);\n      }\n      // eslint-disable-next-line react-hooks/exhaustive-deps -- replayKey is intentionally the only trigger; other deps are stable refs/callbacks\n    }, [replayKey]);\n\n    useIsomorphicLayoutEffect(() => {\n      isInitialRender.current = false;\n\n      return () => {\n        isInitialRender.current = true;\n      };\n    }, []);\n\n    return child;\n  };\n\n  return Object.assign(Atom, {\n    // Heads up!\n    // Always normalize it to a function to simplify types\n    [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,\n  });\n}\n"],"names":["useEventCallback","useIsomorphicLayoutEffect","React","useAnimateAtoms","useMotionImperativeRef","useIsReducedMotion","useChildElement","useMotionBehaviourContext","MOTION_DEFINITION","Symbol","createMotionComponent","value","Atom","props","children","imperativeRef","onMotionFinish","onMotionFinishProp","onMotionStart","onMotionStartProp","onMotionCancel","onMotionCancelProp","replayKey","_rest","params","child","childRef","handleRef","isInitialRender","useRef","skipMotions","optionsRef","animateAtoms","isReducedMotion","activateAnimationHandle","useCallback","handle","setMotionEndCallbacks","current","finish","element","atoms","cancel","play","Object","assign"],"mappings":"AAAA;AAGA,SAASA,gBAAgB,EAAEC,yBAAyB,QAAQ,4BAA4B;AACxF,YAAYC,WAAW,QAAQ;AAE/B,SAASC,eAAe,QAAQ,2BAA2B;AAC3D,SAASC,sBAAsB,QAAQ,kCAAkC;AACzE,SAASC,kBAAkB,QAAQ,8BAA8B;AACjE,SAASC,eAAe,QAAQ,2BAA2B;AAE3D,SAASC,yBAAyB,QAAQ,qCAAqC;AAE/E;;;;CAIC,GACD,OAAO,MAAMC,oBAAoBC,OAAO,qBAAqB;AAoE7D;;;;CAIC,GACD,OAAO,SAASC,sBACdC,KAA6D;IAE7D,MAAMC,OAAsDC,CAAAA;QAC1D;QAEA,MAAM,EACJC,QAAQ,EACRC,aAAa,EACbC,gBAAgBC,kBAAkB,EAClCC,eAAeC,iBAAiB,EAChCC,gBAAgBC,kBAAkB,EAClCC,SAAS,EACT,GAAGC,OACJ,GAAGV;QACJ,MAAMW,SAASD;QACf,MAAM,CAACE,OAAOC,SAAS,GAAGpB,gBAAgBQ;QAE1C,MAAMa,YAAYvB,uBAAuBW;QACzC,MAAMa,kBAAkB1B,MAAM2B,MAAM,CAAC;QACrC,MAAMC,cAAcvB,gCAAgC;QACpD,MAAMwB,aAAa7B,MAAM2B,MAAM,CAAiD;YAC9EC;YACAN;QACF;QAEA,MAAMQ,eAAe7B;QACrB,MAAM8B,kBAAkB5B;QAExB,MAAMa,gBAAgBlB,iBAAiB;YACrCmB,8BAAAA,wCAAAA,kBAAoB;QACtB;QAEA,MAAMH,iBAAiBhB,iBAAiB;YACtCiB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,MAAMG,iBAAiBpB,iBAAiB;YACtCqB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,4GAA4G;QAC5G,EAAE;QACF,0GAA0G;QAC1G,6FAA6F;QAC7F,MAAMa,0BAA0BhC,MAAMiC,WAAW,CAC/C,CAACC;YACClB;YACAkB,OAAOC,qBAAqB,CAACrB,gBAAgBI;YAC7C,IAAIW,WAAWO,OAAO,CAACR,WAAW,EAAE;gBAClCM,OAAOG,MAAM;YACf;QACF,GACA;YAACrB;YAAeF;YAAgBI;SAAe;QAGjDnB,0BAA0B;YACxB,YAAY;YACZ,2FAA2F;YAC3F8B,WAAWO,OAAO,GAAG;gBAAER;gBAAaN;YAAO;QAC7C;QAEAvB,0BAA0B;YACxB,MAAMuC,UAAUd,SAASY,OAAO;YAEhC,IAAIE,SAAS;gBACX,MAAMC,QAAQ,OAAO9B,UAAU,aAAaA,MAAM;oBAAE6B;oBAAS,GAAGT,WAAWO,OAAO,CAACd,MAAM;gBAAC,KAAKb;gBAE/F,MAAMyB,SAASJ,aAAaQ,SAASC,OAAO;oBAAER,iBAAiBA;gBAAkB;gBACjFN,UAAUW,OAAO,GAAGF;gBACpBF,wBAAwBE;gBAExB,OAAO;oBACLA,OAAOM,MAAM;gBACf;YACF;QACF,GAAG;YAACV;YAAcN;YAAUC;YAAWM;YAAiBC;SAAwB;QAEhF,+FAA+F;QAC/F,0DAA0D;QAC1DjC,0BAA0B;YACxB,IAAI2B,gBAAgBU,OAAO,EAAE;gBAC3B;YACF;YAEA,MAAMF,SAAST,UAAUW,OAAO;YAChC,IAAIF,QAAQ;gBACVA,OAAOM,MAAM;gBACbN,OAAOO,IAAI;gBACXT,wBAAwBE;YAC1B;QACA,4IAA4I;QAC9I,GAAG;YAACd;SAAU;QAEdrB,0BAA0B;YACxB2B,gBAAgBU,OAAO,GAAG;YAE1B,OAAO;gBACLV,gBAAgBU,OAAO,GAAG;YAC5B;QACF,GAAG,EAAE;QAEL,OAAOb;IACT;IAEA,OAAOmB,OAAOC,MAAM,CAACjC,MAAM;QACzB,YAAY;QACZ,sDAAsD;QACtD,CAACJ,kBAAkB,EAAE,OAAOG,UAAU,aAAaA,QAAQ,IAAMA;IACnE;AACF"}

package/lib/hooks/useMountedState.js

@@ -20,6 +20,7 @@ import * as React from 'react';
             mountedRef.current = visible;
         }
     });
+    // eslint-disable-next-line react-hooks/refs
     return [
         visible || mountedRef.current,
         setMounted

package/lib/hooks/useMountedState.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks/useMountedState.ts"],"sourcesContent":["'use client';\n\nimport { useForceUpdate } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\n/**\n * This hook manages the mounted state of a component, based on the \"visible\" and \"unmountOnExit\" props.\n * It simulates the behavior of getDerivedStateFromProps(), which is not available in functional components.\n */\nexport function useMountedState(\n  visible: boolean = false,\n  unmountOnExit: boolean = false,\n): [boolean, (value: boolean) => void] {\n  const mountedRef = React.useRef<boolean>(unmountOnExit ? visible : true);\n  const forceUpdate = useForceUpdate();\n\n  const setMounted = React.useCallback(\n    (newValue: boolean) => {\n      if (mountedRef.current !== newValue) {\n        mountedRef.current = newValue;\n        forceUpdate();\n      }\n    },\n    [forceUpdate],\n  );\n\n  React.useEffect(() => {\n    if (visible) {\n      mountedRef.current = visible;\n    }\n  });\n\n  return [visible || mountedRef.current, setMounted];\n}\n"],"names":["useForceUpdate","React","useMountedState","visible","unmountOnExit","mountedRef","useRef","forceUpdate","setMounted","useCallback","newValue","current","useEffect"],"mappings":"AAAA;AAEA,SAASA,cAAc,QAAQ,4BAA4B;AAC3D,YAAYC,WAAW,QAAQ;AAE/B;;;CAGC,GACD,OAAO,SAASC,gBACdC,UAAmB,KAAK,EACxBC,gBAAyB,KAAK;IAE9B,MAAMC,aAAaJ,MAAMK,MAAM,CAAUF,gBAAgBD,UAAU;IACnE,MAAMI,cAAcP;IAEpB,MAAMQ,aAAaP,MAAMQ,WAAW,CAClC,CAACC;QACC,IAAIL,WAAWM,OAAO,KAAKD,UAAU;YACnCL,WAAWM,OAAO,GAAGD;YACrBH;QACF;IACF,GACA;QAACA;KAAY;IAGfN,MAAMW,SAAS,CAAC;QACd,IAAIT,SAAS;YACXE,WAAWM,OAAO,GAAGR;QACvB;IACF;IAEA,OAAO;QAACA,WAAWE,WAAWM,OAAO;QAAEH;KAAW;AACpD"}
+{"version":3,"sources":["../src/hooks/useMountedState.ts"],"sourcesContent":["'use client';\n\nimport { useForceUpdate } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\n/**\n * This hook manages the mounted state of a component, based on the \"visible\" and \"unmountOnExit\" props.\n * It simulates the behavior of getDerivedStateFromProps(), which is not available in functional components.\n */\nexport function useMountedState(\n  visible: boolean = false,\n  unmountOnExit: boolean = false,\n): [boolean, (value: boolean) => void] {\n  const mountedRef = React.useRef<boolean>(unmountOnExit ? visible : true);\n  const forceUpdate = useForceUpdate();\n\n  const setMounted = React.useCallback(\n    (newValue: boolean) => {\n      if (mountedRef.current !== newValue) {\n        mountedRef.current = newValue;\n        forceUpdate();\n      }\n    },\n    [forceUpdate],\n  );\n\n  React.useEffect(() => {\n    if (visible) {\n      mountedRef.current = visible;\n    }\n  });\n\n  // eslint-disable-next-line react-hooks/refs\n  return [visible || mountedRef.current, setMounted];\n}\n"],"names":["useForceUpdate","React","useMountedState","visible","unmountOnExit","mountedRef","useRef","forceUpdate","setMounted","useCallback","newValue","current","useEffect"],"mappings":"AAAA;AAEA,SAASA,cAAc,QAAQ,4BAA4B;AAC3D,YAAYC,WAAW,QAAQ;AAE/B;;;CAGC,GACD,OAAO,SAASC,gBACdC,UAAmB,KAAK,EACxBC,gBAAyB,KAAK;IAE9B,MAAMC,aAAaJ,MAAMK,MAAM,CAAUF,gBAAgBD,UAAU;IACnE,MAAMI,cAAcP;IAEpB,MAAMQ,aAAaP,MAAMQ,WAAW,CAClC,CAACC;QACC,IAAIL,WAAWM,OAAO,KAAKD,UAAU;YACnCL,WAAWM,OAAO,GAAGD;YACrBH;QACF;IACF,GACA;QAACA;KAAY;IAGfN,MAAMW,SAAS,CAAC;QACd,IAAIT,SAAS;YACXE,WAAWM,OAAO,GAAGR;QACvB;IACF;IAEA,4CAA4C;IAC5C,OAAO;QAACA,WAAWE,WAAWM,OAAO;QAAEH;KAAW;AACpD"}

package/lib-commonjs/factories/createMotionComponent.js

@@ -29,10 +29,11 @@ const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');
 function createMotionComponent(value) {
     const Atom = (props)=>{
         'use no memo';
-        const { children, imperativeRef, onMotionFinish: onMotionFinishProp, onMotionStart: onMotionStartProp, onMotionCancel: onMotionCancelProp, ..._rest } = props;
+        const { children, imperativeRef, onMotionFinish: onMotionFinishProp, onMotionStart: onMotionStartProp, onMotionCancel: onMotionCancelProp, replayKey, ..._rest } = props;
         const params = _rest;
         const [child, childRef] = (0, _useChildElement.useChildElement)(children);
         const handleRef = (0, _useMotionImperativeRef.useMotionImperativeRef)(imperativeRef);
+        const isInitialRender = _react.useRef(true);
         const skipMotions = (0, _MotionBehaviourContext.useMotionBehaviourContext)() === 'skip';
         const optionsRef = _react.useRef({
             skipMotions,
@@ -49,6 +50,21 @@ function createMotionComponent(value) {
         const onMotionCancel = (0, _reactutilities.useEventCallback)(()=>{
             onMotionCancelProp === null || onMotionCancelProp === void 0 ? void 0 : onMotionCancelProp(null);
         });
+        // Stable callback (all deps are refs or useEventCallback) that activates a handle for a new playback cycle.
+        //
+        // TODO: consider moving the cancel+play+rewire sequence into a handle.replay() method on AnimationHandle,
+        // keeping pure animation sequencing on the handle and React callbacks here in the component.
+        const activateAnimationHandle = _react.useCallback((handle)=>{
+            onMotionStart();
+            handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);
+            if (optionsRef.current.skipMotions) {
+                handle.finish();
+            }
+        }, [
+            onMotionStart,
+            onMotionFinish,
+            onMotionCancel
+        ]);
         (0, _reactutilities.useIsomorphicLayoutEffect)(()=>{
             // Heads up!
             // We store the params in a ref to avoid re-rendering the component when the params change.
@@ -64,15 +80,11 @@ function createMotionComponent(value) {
                     element,
                     ...optionsRef.current.params
                 }) : value;
-                onMotionStart();
                 const handle = animateAtoms(element, atoms, {
                     isReducedMotion: isReducedMotion()
                 });
                 handleRef.current = handle;
-                handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);
-                if (optionsRef.current.skipMotions) {
-                    handle.finish();
-                }
+                activateAnimationHandle(handle);
                 return ()=>{
                     handle.cancel();
                 };
@@ -82,10 +94,30 @@ function createMotionComponent(value) {
             childRef,
             handleRef,
             isReducedMotion,
-            onMotionFinish,
-            onMotionStart,
-            onMotionCancel
+            activateAnimationHandle
+        ]);
+        // Skips initial mount; on replayKey changes, reuses existing Animation objects via cancel+play
+        // rather than recreating them, preserving DOM continuity.
+        (0, _reactutilities.useIsomorphicLayoutEffect)(()=>{
+            if (isInitialRender.current) {
+                return;
+            }
+            const handle = handleRef.current;
+            if (handle) {
+                handle.cancel();
+                handle.play();
+                activateAnimationHandle(handle);
+            }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- replayKey is intentionally the only trigger; other deps are stable refs/callbacks
+        }, [
+            replayKey
         ]);
+        (0, _reactutilities.useIsomorphicLayoutEffect)(()=>{
+            isInitialRender.current = false;
+            return ()=>{
+                isInitialRender.current = true;
+            };
+        }, []);
         return child;
     };
     return Object.assign(Atom, {

package/lib-commonjs/factories/createMotionComponent.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/factories/createMotionComponent.ts"],"sourcesContent":["'use client';\n\nimport type { JSXElement } from '@fluentui/react-utilities';\nimport { useEventCallback, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\nimport { useAnimateAtoms } from '../hooks/useAnimateAtoms';\nimport { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';\nimport { useIsReducedMotion } from '../hooks/useIsReducedMotion';\nimport { useChildElement } from '../utils/useChildElement';\nimport type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef } from '../types';\nimport { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';\n\n/**\n * A private symbol to store the motion definition on the component for variants.\n *\n * @internal\n */\nexport const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');\n\nexport type MotionComponentProps = {\n  children: JSXElement;\n\n  /** Provides imperative controls for the animation. */\n  imperativeRef?: React.Ref<MotionImperativeRef | undefined>;\n\n  /**\n   * Callback that is called when the whole motion finishes.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"finish\" events. The callback is\n   * triggered once all animations have finished with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionFinish?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion is cancelled.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"cancel\" events. The callback is\n   * triggered once all animations have been cancelled with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionCancel?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion starts.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"start\" events. The callback is\n   * triggered when the first animation is started. There is no official \"start\" event with the Web Animations API.\n   * so the callback is triggered with \"null\".\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionStart?: (ev: null) => void;\n};\n\nexport type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React.FC<\n  MotionComponentProps & MotionParams\n> & {\n  [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;\n};\n\n/**\n * Creates a component that will animate the children using the provided motion.\n *\n * @param value - A motion definition.\n */\nexport function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(\n  value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>,\n): MotionComponent<MotionParams> {\n  const Atom: React.FC<MotionComponentProps & MotionParams> = props => {\n    'use no memo';\n\n    const {\n      children,\n      imperativeRef,\n      onMotionFinish: onMotionFinishProp,\n      onMotionStart: onMotionStartProp,\n      onMotionCancel: onMotionCancelProp,\n      ..._rest\n    } = props;\n    const params = _rest as Exclude<typeof props, MotionComponentProps>;\n    const [child, childRef] = useChildElement(children);\n\n    const handleRef = useMotionImperativeRef(imperativeRef);\n    const skipMotions = useMotionBehaviourContext() === 'skip';\n    const optionsRef = React.useRef<{ skipMotions: boolean; params: MotionParams }>({\n      skipMotions,\n      params,\n    });\n\n    const animateAtoms = useAnimateAtoms();\n    const isReducedMotion = useIsReducedMotion();\n\n    const onMotionStart = useEventCallback(() => {\n      onMotionStartProp?.(null);\n    });\n\n    const onMotionFinish = useEventCallback(() => {\n      onMotionFinishProp?.(null);\n    });\n\n    const onMotionCancel = useEventCallback(() => {\n      onMotionCancelProp?.(null);\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      // Heads up!\n      // We store the params in a ref to avoid re-rendering the component when the params change.\n      optionsRef.current = { skipMotions, params };\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      const element = childRef.current;\n\n      if (element) {\n        const atoms = typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : value;\n\n        onMotionStart();\n        const handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });\n        handleRef.current = handle;\n        handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);\n\n        if (optionsRef.current.skipMotions) {\n          handle.finish();\n        }\n\n        return () => {\n          handle.cancel();\n        };\n      }\n    }, [animateAtoms, childRef, handleRef, isReducedMotion, onMotionFinish, onMotionStart, onMotionCancel]);\n\n    return child;\n  };\n\n  return Object.assign(Atom, {\n    // Heads up!\n    // Always normalize it to a function to simplify types\n    [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,\n  });\n}\n"],"names":["MOTION_DEFINITION","createMotionComponent","Symbol","value","Atom","props","children","imperativeRef","onMotionFinish","onMotionFinishProp","onMotionStart","onMotionStartProp","onMotionCancel","onMotionCancelProp","_rest","params","child","childRef","useChildElement","handleRef","useMotionImperativeRef","skipMotions","useMotionBehaviourContext","optionsRef","React","useRef","animateAtoms","useAnimateAtoms","isReducedMotion","useIsReducedMotion","useEventCallback","useIsomorphicLayoutEffect","current","element","atoms","handle","setMotionEndCallbacks","finish","cancel","Object","assign"],"mappings":"AAAA;;;;;;;;;;;;IAkBaA,iBAAiB;eAAjBA;;IAgDGC,qBAAqB;eAArBA;;;;gCA/D4C;iEACrC;iCAES;wCACO;oCACJ;iCACH;wCAEU;AAOnC,MAAMD,oBAAoBE,OAAO;AAgDjC,SAASD,sBACdE,KAA6D;IAE7D,MAAMC,OAAsDC,CAAAA;QAC1D;QAEA,MAAM,EACJC,QAAQ,EACRC,aAAa,EACbC,gBAAgBC,kBAAkB,EAClCC,eAAeC,iBAAiB,EAChCC,gBAAgBC,kBAAkB,EAClC,GAAGC,OACJ,GAAGT;QACJ,MAAMU,SAASD;QACf,MAAM,CAACE,OAAOC,SAAS,GAAGC,IAAAA,gCAAe,EAACZ;QAE1C,MAAMa,YAAYC,IAAAA,8CAAsB,EAACb;QACzC,MAAMc,cAAcC,IAAAA,iDAAyB,QAAO;QACpD,MAAMC,aAAaC,OAAMC,MAAM,CAAiD;YAC9EJ;YACAN;QACF;QAEA,MAAMW,eAAeC,IAAAA,gCAAe;QACpC,MAAMC,kBAAkBC,IAAAA,sCAAkB;QAE1C,MAAMnB,gBAAgBoB,IAAAA,gCAAgB,EAAC;YACrCnB,8BAAAA,wCAAAA,kBAAoB;QACtB;QAEA,MAAMH,iBAAiBsB,IAAAA,gCAAgB,EAAC;YACtCrB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,MAAMG,iBAAiBkB,IAAAA,gCAAgB,EAAC;YACtCjB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEAkB,IAAAA,yCAAyB,EAAC;YACxB,YAAY;YACZ,2FAA2F;YAC3FR,WAAWS,OAAO,GAAG;gBAAEX;gBAAaN;YAAO;QAC7C;QAEAgB,IAAAA,yCAAyB,EAAC;YACxB,MAAME,UAAUhB,SAASe,OAAO;YAEhC,IAAIC,SAAS;gBACX,MAAMC,QAAQ,OAAO/B,UAAU,aAAaA,MAAM;oBAAE8B;oBAAS,GAAGV,WAAWS,OAAO,CAACjB,MAAM;gBAAC,KAAKZ;gBAE/FO;gBACA,MAAMyB,SAAST,aAAaO,SAASC,OAAO;oBAAEN,iBAAiBA;gBAAkB;gBACjFT,UAAUa,OAAO,GAAGG;gBACpBA,OAAOC,qBAAqB,CAAC5B,gBAAgBI;gBAE7C,IAAIW,WAAWS,OAAO,CAACX,WAAW,EAAE;oBAClCc,OAAOE,MAAM;gBACf;gBAEA,OAAO;oBACLF,OAAOG,MAAM;gBACf;YACF;QACF,GAAG;YAACZ;YAAcT;YAAUE;YAAWS;YAAiBpB;YAAgBE;YAAeE;SAAe;QAEtG,OAAOI;IACT;IAEA,OAAOuB,OAAOC,MAAM,CAACpC,MAAM;QACzB,YAAY;QACZ,sDAAsD;QACtD,CAACJ,kBAAkB,EAAE,OAAOG,UAAU,aAAaA,QAAQ,IAAMA;IACnE;AACF"}
+{"version":3,"sources":["../src/factories/createMotionComponent.ts"],"sourcesContent":["'use client';\n\nimport type { JSXElement } from '@fluentui/react-utilities';\nimport { useEventCallback, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\nimport { useAnimateAtoms } from '../hooks/useAnimateAtoms';\nimport { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';\nimport { useIsReducedMotion } from '../hooks/useIsReducedMotion';\nimport { useChildElement } from '../utils/useChildElement';\nimport type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef, AnimationHandle } from '../types';\nimport { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';\n\n/**\n * A private symbol to store the motion definition on the component for variants.\n *\n * @internal\n */\nexport const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');\n\nexport type MotionComponentProps = {\n  children: JSXElement;\n\n  /** Provides imperative controls for the animation. */\n  imperativeRef?: React.Ref<MotionImperativeRef | undefined>;\n\n  /**\n   * Callback that is called when the whole motion finishes.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"finish\" events. The callback is\n   * triggered once all animations have finished with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionFinish?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion is cancelled.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"cancel\" events. The callback is\n   * triggered once all animations have been cancelled with \"null\" instead of an event object to avoid ambiguity.\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionCancel?: (ev: null) => void;\n\n  /**\n   * Callback that is called when the whole motion starts.\n   *\n   * A motion definition can contain multiple animations and therefore multiple \"start\" events. The callback is\n   * triggered when the first animation is started. There is no official \"start\" event with the Web Animations API.\n   * so the callback is triggered with \"null\".\n   */\n  // eslint-disable-next-line @nx/workspace-consistent-callback-type -- EventHandler<T> does not support \"null\"\n  onMotionStart?: (ev: null) => void;\n\n  /**\n   * When this value changes, the animation replays from the start on the same DOM element,\n   * cancelling any in-progress animation, without remounting the component or its children.\n   *\n   * **Why not just use a React `key`?** Changing a React `key` forces a full unmount and\n   * remount of the subtree: DOM nodes are destroyed and recreated, focus is lost, and any\n   * child state is reset. `replayKey` avoids all of that — only the animation effect reruns\n   * while the DOM and component state remain intact.\n   *\n   * Use this when you want to retrigger a motion in response to a state change (e.g. a user\n   * action or a data update) while preserving DOM continuity. It is the declarative equivalent\n   * of calling `imperativeRef.current.play()` but driven by a prop rather than a ref call.\n   *\n   * @example\n   * ```tsx\n   * // Replay a Fade.In each time the user clicks \"Refresh\"\n   * const [replayKey, setReplayKey] = React.useState(0);\n   * <Fade.In replayKey={replayKey}>\n   *   <div>Content</div>\n   * </Fade.In>\n   * <button onClick={() => setReplayKey(k => k + 1)}>Refresh</button>\n   * ```\n   */\n  replayKey?: string | number;\n};\n\nexport type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React.FC<\n  MotionComponentProps & MotionParams\n> & {\n  [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;\n};\n\n/**\n * Creates a component that will animate the children using the provided motion.\n *\n * @param value - A motion definition.\n */\nexport function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(\n  value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>,\n): MotionComponent<MotionParams> {\n  const Atom: React.FC<MotionComponentProps & MotionParams> = props => {\n    'use no memo';\n\n    const {\n      children,\n      imperativeRef,\n      onMotionFinish: onMotionFinishProp,\n      onMotionStart: onMotionStartProp,\n      onMotionCancel: onMotionCancelProp,\n      replayKey,\n      ..._rest\n    } = props;\n    const params = _rest as Exclude<typeof props, MotionComponentProps>;\n    const [child, childRef] = useChildElement(children);\n\n    const handleRef = useMotionImperativeRef(imperativeRef);\n    const isInitialRender = React.useRef(true);\n    const skipMotions = useMotionBehaviourContext() === 'skip';\n    const optionsRef = React.useRef<{ skipMotions: boolean; params: MotionParams }>({\n      skipMotions,\n      params,\n    });\n\n    const animateAtoms = useAnimateAtoms();\n    const isReducedMotion = useIsReducedMotion();\n\n    const onMotionStart = useEventCallback(() => {\n      onMotionStartProp?.(null);\n    });\n\n    const onMotionFinish = useEventCallback(() => {\n      onMotionFinishProp?.(null);\n    });\n\n    const onMotionCancel = useEventCallback(() => {\n      onMotionCancelProp?.(null);\n    });\n\n    // Stable callback (all deps are refs or useEventCallback) that activates a handle for a new playback cycle.\n    //\n    // TODO: consider moving the cancel+play+rewire sequence into a handle.replay() method on AnimationHandle,\n    // keeping pure animation sequencing on the handle and React callbacks here in the component.\n    const activateAnimationHandle = React.useCallback(\n      (handle: AnimationHandle) => {\n        onMotionStart();\n        handle.setMotionEndCallbacks(onMotionFinish, onMotionCancel);\n        if (optionsRef.current.skipMotions) {\n          handle.finish();\n        }\n      },\n      [onMotionStart, onMotionFinish, onMotionCancel],\n    );\n\n    useIsomorphicLayoutEffect(() => {\n      // Heads up!\n      // We store the params in a ref to avoid re-rendering the component when the params change.\n      optionsRef.current = { skipMotions, params };\n    });\n\n    useIsomorphicLayoutEffect(() => {\n      const element = childRef.current;\n\n      if (element) {\n        const atoms = typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : value;\n\n        const handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });\n        handleRef.current = handle;\n        activateAnimationHandle(handle);\n\n        return () => {\n          handle.cancel();\n        };\n      }\n    }, [animateAtoms, childRef, handleRef, isReducedMotion, activateAnimationHandle]);\n\n    // Skips initial mount; on replayKey changes, reuses existing Animation objects via cancel+play\n    // rather than recreating them, preserving DOM continuity.\n    useIsomorphicLayoutEffect(() => {\n      if (isInitialRender.current) {\n        return;\n      }\n\n      const handle = handleRef.current;\n      if (handle) {\n        handle.cancel();\n        handle.play();\n        activateAnimationHandle(handle);\n      }\n      // eslint-disable-next-line react-hooks/exhaustive-deps -- replayKey is intentionally the only trigger; other deps are stable refs/callbacks\n    }, [replayKey]);\n\n    useIsomorphicLayoutEffect(() => {\n      isInitialRender.current = false;\n\n      return () => {\n        isInitialRender.current = true;\n      };\n    }, []);\n\n    return child;\n  };\n\n  return Object.assign(Atom, {\n    // Heads up!\n    // Always normalize it to a function to simplify types\n    [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,\n  });\n}\n"],"names":["MOTION_DEFINITION","createMotionComponent","Symbol","value","Atom","props","children","imperativeRef","onMotionFinish","onMotionFinishProp","onMotionStart","onMotionStartProp","onMotionCancel","onMotionCancelProp","replayKey","_rest","params","child","childRef","useChildElement","handleRef","useMotionImperativeRef","isInitialRender","React","useRef","skipMotions","useMotionBehaviourContext","optionsRef","animateAtoms","useAnimateAtoms","isReducedMotion","useIsReducedMotion","useEventCallback","activateAnimationHandle","useCallback","handle","setMotionEndCallbacks","current","finish","useIsomorphicLayoutEffect","element","atoms","cancel","play","Object","assign"],"mappings":"AAAA;;;;;;;;;;;;IAkBaA,iBAAiB;eAAjBA;;IAyEGC,qBAAqB;eAArBA;;;;gCAxF4C;iEACrC;iCAES;wCACO;oCACJ;iCACH;wCAEU;AAOnC,MAAMD,oBAAoBE,OAAO;AAyEjC,SAASD,sBACdE,KAA6D;IAE7D,MAAMC,OAAsDC,CAAAA;QAC1D;QAEA,MAAM,EACJC,QAAQ,EACRC,aAAa,EACbC,gBAAgBC,kBAAkB,EAClCC,eAAeC,iBAAiB,EAChCC,gBAAgBC,kBAAkB,EAClCC,SAAS,EACT,GAAGC,OACJ,GAAGV;QACJ,MAAMW,SAASD;QACf,MAAM,CAACE,OAAOC,SAAS,GAAGC,IAAAA,gCAAe,EAACb;QAE1C,MAAMc,YAAYC,IAAAA,8CAAsB,EAACd;QACzC,MAAMe,kBAAkBC,OAAMC,MAAM,CAAC;QACrC,MAAMC,cAAcC,IAAAA,iDAAyB,QAAO;QACpD,MAAMC,aAAaJ,OAAMC,MAAM,CAAiD;YAC9EC;YACAT;QACF;QAEA,MAAMY,eAAeC,IAAAA,gCAAe;QACpC,MAAMC,kBAAkBC,IAAAA,sCAAkB;QAE1C,MAAMrB,gBAAgBsB,IAAAA,gCAAgB,EAAC;YACrCrB,8BAAAA,wCAAAA,kBAAoB;QACtB;QAEA,MAAMH,iBAAiBwB,IAAAA,gCAAgB,EAAC;YACtCvB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,MAAMG,iBAAiBoB,IAAAA,gCAAgB,EAAC;YACtCnB,+BAAAA,yCAAAA,mBAAqB;QACvB;QAEA,4GAA4G;QAC5G,EAAE;QACF,0GAA0G;QAC1G,6FAA6F;QAC7F,MAAMoB,0BAA0BV,OAAMW,WAAW,CAC/C,CAACC;YACCzB;YACAyB,OAAOC,qBAAqB,CAAC5B,gBAAgBI;YAC7C,IAAIe,WAAWU,OAAO,CAACZ,WAAW,EAAE;gBAClCU,OAAOG,MAAM;YACf;QACF,GACA;YAAC5B;YAAeF;YAAgBI;SAAe;QAGjD2B,IAAAA,yCAAyB,EAAC;YACxB,YAAY;YACZ,2FAA2F;YAC3FZ,WAAWU,OAAO,GAAG;gBAAEZ;gBAAaT;YAAO;QAC7C;QAEAuB,IAAAA,yCAAyB,EAAC;YACxB,MAAMC,UAAUtB,SAASmB,OAAO;YAEhC,IAAIG,SAAS;gBACX,MAAMC,QAAQ,OAAOtC,UAAU,aAAaA,MAAM;oBAAEqC;oBAAS,GAAGb,WAAWU,OAAO,CAACrB,MAAM;gBAAC,KAAKb;gBAE/F,MAAMgC,SAASP,aAAaY,SAASC,OAAO;oBAAEX,iBAAiBA;gBAAkB;gBACjFV,UAAUiB,OAAO,GAAGF;gBACpBF,wBAAwBE;gBAExB,OAAO;oBACLA,OAAOO,MAAM;gBACf;YACF;QACF,GAAG;YAACd;YAAcV;YAAUE;YAAWU;YAAiBG;SAAwB;QAEhF,+FAA+F;QAC/F,0DAA0D;QAC1DM,IAAAA,yCAAyB,EAAC;YACxB,IAAIjB,gBAAgBe,OAAO,EAAE;gBAC3B;YACF;YAEA,MAAMF,SAASf,UAAUiB,OAAO;YAChC,IAAIF,QAAQ;gBACVA,OAAOO,MAAM;gBACbP,OAAOQ,IAAI;gBACXV,wBAAwBE;YAC1B;QACA,4IAA4I;QAC9I,GAAG;YAACrB;SAAU;QAEdyB,IAAAA,yCAAyB,EAAC;YACxBjB,gBAAgBe,OAAO,GAAG;YAE1B,OAAO;gBACLf,gBAAgBe,OAAO,GAAG;YAC5B;QACF,GAAG,EAAE;QAEL,OAAOpB;IACT;IAEA,OAAO2B,OAAOC,MAAM,CAACzC,MAAM;QACzB,YAAY;QACZ,sDAAsD;QACtD,CAACJ,kBAAkB,EAAE,OAAOG,UAAU,aAAaA,QAAQ,IAAMA;IACnE;AACF"}

package/lib-commonjs/hooks/useMountedState.js

@@ -28,6 +28,7 @@ function useMountedState(visible = false, unmountOnExit = false) {
             mountedRef.current = visible;
         }
     });
+    // eslint-disable-next-line react-hooks/refs
     return [
         visible || mountedRef.current,
         setMounted

package/lib-commonjs/hooks/useMountedState.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks/useMountedState.ts"],"sourcesContent":["'use client';\n\nimport { useForceUpdate } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\n/**\n * This hook manages the mounted state of a component, based on the \"visible\" and \"unmountOnExit\" props.\n * It simulates the behavior of getDerivedStateFromProps(), which is not available in functional components.\n */\nexport function useMountedState(\n  visible: boolean = false,\n  unmountOnExit: boolean = false,\n): [boolean, (value: boolean) => void] {\n  const mountedRef = React.useRef<boolean>(unmountOnExit ? visible : true);\n  const forceUpdate = useForceUpdate();\n\n  const setMounted = React.useCallback(\n    (newValue: boolean) => {\n      if (mountedRef.current !== newValue) {\n        mountedRef.current = newValue;\n        forceUpdate();\n      }\n    },\n    [forceUpdate],\n  );\n\n  React.useEffect(() => {\n    if (visible) {\n      mountedRef.current = visible;\n    }\n  });\n\n  return [visible || mountedRef.current, setMounted];\n}\n"],"names":["useMountedState","visible","unmountOnExit","mountedRef","React","useRef","forceUpdate","useForceUpdate","setMounted","useCallback","newValue","current","useEffect"],"mappings":"AAAA;;;;;+BASgBA;;;eAAAA;;;;gCAPe;iEACR;AAMhB,SAASA,gBACdC,UAAmB,KAAK,EACxBC,gBAAyB,KAAK;IAE9B,MAAMC,aAAaC,OAAMC,MAAM,CAAUH,gBAAgBD,UAAU;IACnE,MAAMK,cAAcC,IAAAA,8BAAc;IAElC,MAAMC,aAAaJ,OAAMK,WAAW,CAClC,CAACC;QACC,IAAIP,WAAWQ,OAAO,KAAKD,UAAU;YACnCP,WAAWQ,OAAO,GAAGD;YACrBJ;QACF;IACF,GACA;QAACA;KAAY;IAGfF,OAAMQ,SAAS,CAAC;QACd,IAAIX,SAAS;YACXE,WAAWQ,OAAO,GAAGV;QACvB;IACF;IAEA,OAAO;QAACA,WAAWE,WAAWQ,OAAO;QAAEH;KAAW;AACpD"}
+{"version":3,"sources":["../src/hooks/useMountedState.ts"],"sourcesContent":["'use client';\n\nimport { useForceUpdate } from '@fluentui/react-utilities';\nimport * as React from 'react';\n\n/**\n * This hook manages the mounted state of a component, based on the \"visible\" and \"unmountOnExit\" props.\n * It simulates the behavior of getDerivedStateFromProps(), which is not available in functional components.\n */\nexport function useMountedState(\n  visible: boolean = false,\n  unmountOnExit: boolean = false,\n): [boolean, (value: boolean) => void] {\n  const mountedRef = React.useRef<boolean>(unmountOnExit ? visible : true);\n  const forceUpdate = useForceUpdate();\n\n  const setMounted = React.useCallback(\n    (newValue: boolean) => {\n      if (mountedRef.current !== newValue) {\n        mountedRef.current = newValue;\n        forceUpdate();\n      }\n    },\n    [forceUpdate],\n  );\n\n  React.useEffect(() => {\n    if (visible) {\n      mountedRef.current = visible;\n    }\n  });\n\n  // eslint-disable-next-line react-hooks/refs\n  return [visible || mountedRef.current, setMounted];\n}\n"],"names":["useMountedState","visible","unmountOnExit","mountedRef","React","useRef","forceUpdate","useForceUpdate","setMounted","useCallback","newValue","current","useEffect"],"mappings":"AAAA;;;;;+BASgBA;;;eAAAA;;;;gCAPe;iEACR;AAMhB,SAASA,gBACdC,UAAmB,KAAK,EACxBC,gBAAyB,KAAK;IAE9B,MAAMC,aAAaC,OAAMC,MAAM,CAAUH,gBAAgBD,UAAU;IACnE,MAAMK,cAAcC,IAAAA,8BAAc;IAElC,MAAMC,aAAaJ,OAAMK,WAAW,CAClC,CAACC;QACC,IAAIP,WAAWQ,OAAO,KAAKD,UAAU;YACnCP,WAAWQ,OAAO,GAAGD;YACrBJ;QACF;IACF,GACA;QAACA;KAAY;IAGfF,OAAMQ,SAAS,CAAC;QACd,IAAIX,SAAS;YACXE,WAAWQ,OAAO,GAAGV;QACvB;IACF;IAEA,4CAA4C;IAC5C,OAAO;QAACA,WAAWE,WAAWQ,OAAO;QAAEH;KAAW;AACpD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentui/react-motion",
-  "version": "9.15.0",
+  "version": "9.16.0",
   "description": "A package with utilities & motion definitions using Web Animations API",
   "main": "lib-commonjs/index.js",
   "module": "lib/index.js",
@@ -19,7 +19,7 @@
   "license": "MIT",
   "dependencies": {
     "@fluentui/react-shared-contexts": "^9.26.2",
-    "@fluentui/react-utilities": "^9.26.3",
+    "@fluentui/react-utilities": "^9.26.4",
     "@swc/helpers": "^0.5.1"
   },
   "peerDependencies": {