@fluentui/react-motion 9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 → 9.74.3-experimental.esm.20260709-49ee7a20cf.0

package/CHANGELOG.md

@@ -1,19 +1,95 @@
 # Change Log - @fluentui/react-motion
 
-This log was last generated on Thu, 22 Jan 2026 16:12:40 GMT and should not be manually modified.
+This log was last generated on Thu, 09 Jul 2026 17:34:11 GMT and should not be manually modified.
 
 <!-- Start content -->
 
-## [9.72.9-experimental.component-base-hooks.20260122-49fc330360.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0)
+## [9.74.3-experimental.esm.20260709-49ee7a20cf.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.74.3-experimental.esm.20260709-49ee7a20cf.0)
 
-Thu, 22 Jan 2026 16:12:40 GMT 
-[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.11.5..@fluentui/react-motion_v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0)
+Thu, 09 Jul 2026 17:34:11 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.16.1..@fluentui/react-motion_v9.74.3-experimental.esm.20260709-49ee7a20cf.0)
 
 ### Changes
 
-- Release 9.72.9-experimental.component-base-hooks.20260122-49fc330360 ([commit](https://github.com/microsoft/fluentui/commit/not available) by fluentui-internal@service.microsoft.com)
-- Bump @fluentui/react-shared-contexts to v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 ([commit](https://github.com/microsoft/fluentui/commit/373001c3e19d022ef1fcf745ea96375cf4f3aff1) by beachball)
-- Bump @fluentui/react-utilities to v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 ([commit](https://github.com/microsoft/fluentui/commit/373001c3e19d022ef1fcf745ea96375cf4f3aff1) by beachball)
+- Release 9.74.3-experimental.esm.20260709-49ee7a20cf ([commit](https://github.com/microsoft/fluentui/commit/not available) by fluentui-internal@service.microsoft.com)
+- Bump @fluentui/react-shared-contexts to v9.74.3-experimental.esm.20260709-49ee7a20cf.0 ([commit](https://github.com/microsoft/fluentui/commit/175a26e0c520dd90a54578d1185a3b0b6c446e15) by beachball)
+- Bump @fluentui/react-utilities to v9.74.3-experimental.esm.20260709-49ee7a20cf.0 ([commit](https://github.com/microsoft/fluentui/commit/175a26e0c520dd90a54578d1185a3b0b6c446e15) by beachball)
+
+## [9.16.1](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.16.1)
+
+Wed, 24 Jun 2026 11:09:49 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.16.0..@fluentui/react-motion_v9.16.1)
+
+### Patches
+
+- fix: remove redundant use no memo directives, and add justification to valid ones ([PR #36224](https://github.com/microsoft/fluentui/pull/36224) by martinhochel@microsoft.com)
+- Bump @fluentui/react-utilities to v9.26.5 ([commit](https://github.com/microsoft/fluentui/commit/a4b871ca80c1f16f35ab4229def4fe02be7f30ea) by beachball)
+
+## [9.16.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.16.0)
+
+Tue, 26 May 2026 09:39:25 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 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
+
+- feat: expose motion params as direct props on motion slot types ([PR #36011](https://github.com/microsoft/fluentui/pull/36011) by robertpenner@microsoft.com)
+- 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)
+
+Mon, 30 Mar 2026 14:37:40 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.13.0..@fluentui/react-motion_v9.14.0)
+
+### Minor changes
+
+- feat: add motionSlot() as parallel to presenceMotionSlot() ([PR #35888](https://github.com/microsoft/fluentui/pull/35888) by robertpenner@microsoft.com)
+- feat: add motionSlot() as parallel to presenceMotionSlot() ([PR #35883](https://github.com/microsoft/fluentui/pull/35883) by robertpenner@microsoft.com)
+
+## [9.13.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.13.0)
+
+Tue, 03 Mar 2026 09:43:40 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.12.0..@fluentui/react-motion_v9.13.0)
+
+### Minor changes
+
+- fix: make children optional in MotionRefForwarder to resolve type issue ([PR #35763](https://github.com/microsoft/fluentui/pull/35763) by robertpenner@microsoft.com)
+
+### Patches
+
+- fix: add MotionRefForwarderReset to prevent context leaking to descendants ([PR #35807](https://github.com/microsoft/fluentui/pull/35807) by olfedias@microsoft.com)
+
+## [9.12.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.12.0)
+
+Wed, 25 Feb 2026 13:32:23 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.11.6..@fluentui/react-motion_v9.12.0)
+
+### Minor changes
+
+- feat: export MotionRefForwarder and useMotionForwardedRef for shared motion ref forwarding ([PR #35774](https://github.com/microsoft/fluentui/pull/35774) by robertpenner@microsoft.com)
+- Bump @fluentui/react-shared-contexts to v9.26.2 ([PR #35782](https://github.com/microsoft/fluentui/pull/35782) by beachball)
+- Bump @fluentui/react-utilities to v9.26.2 ([PR #35782](https://github.com/microsoft/fluentui/pull/35782) by beachball)
+
+## [9.11.6](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.11.6)
+
+Thu, 22 Jan 2026 17:06:32 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion_v9.11.5..@fluentui/react-motion_v9.11.6)
+
+### Patches
+
+- fix: cleanup animation handle on unmounted component ([PR #35617](https://github.com/microsoft/fluentui/pull/35617) by olfedias@microsoft.com)
+- Bump @fluentui/react-shared-contexts to v9.26.1 ([PR #35574](https://github.com/microsoft/fluentui/pull/35574) by beachball)
+- Bump @fluentui/react-utilities to v9.26.1 ([PR #35574](https://github.com/microsoft/fluentui/pull/35574) by beachball)
 
 ## [9.11.5](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion_v9.11.5)
 

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.cts

@@ -0,0 +1,368 @@
+import type { JSXElement } from '@fluentui/react-utilities';
+import type { JSXIntrinsicElementKeys } from '@fluentui/react-utilities';
+import * as React_2 from 'react';
+import type { SlotComponentType } from '@fluentui/react-utilities';
+import type { SlotRenderFunction } from '@fluentui/react-utilities';
+
+declare type AtomCore = {
+    keyframes: Keyframe[];
+} & KeyframeEffectOptions;
+
+export declare type AtomMotion = AtomCore & {
+    /**
+     * Allows to specify a reduced motion version of the animation. If provided, the settings will be used when the
+     * user has enabled the reduced motion setting in the operating system (i.e `prefers-reduced-motion` media query is
+     * active). If not provided, the duration of the animation will be overridden to be 1ms.
+     *
+     * Note, if `keyframes` are provided, they will be used instead of the regular `keyframes`.
+     */
+    reducedMotion?: Partial<AtomCore>;
+};
+
+export declare type AtomMotionFn<MotionParams extends Record<string, MotionParam> = {}> = (params: {
+    element: HTMLElement;
+} & MotionParams) => AtomMotion | AtomMotion[];
+
+/**
+ * Creates a component that will animate the children using the provided motion.
+ *
+ * @param value - A motion definition.
+ */
+export declare function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>): MotionComponent<MotionParams>;
+
+/**
+ * Create a new motion component based on another motion component,
+ * using the provided variant parameters as defaults.
+ *
+ * @param component - A component created by `createMotionComponent`.
+ * @param variantParams - An object containing the variant parameters to be used as defaults.
+ * The variant parameters should match the type of the component's motion parameters.
+ * @returns A new motion component that uses the provided variant parameters as defaults.
+ * The new component can still accept runtime parameters that override the defaults.
+ */
+export declare function createMotionComponentVariant<MotionParams extends Record<string, MotionParam> = {}>(component: MotionComponent<MotionParams>, variantParams: Partial<MotionParams>): MotionComponent<MotionParams>;
+
+export declare function createPresenceComponent<MotionParams extends Record<string, MotionParam> = {}>(value: PresenceMotion | PresenceMotionFn<MotionParams>): PresenceComponent<MotionParams>;
+
+/**
+ * Create a new presence component based on another presence component,
+ * using the provided variant parameters as defaults.
+ *
+ * @param component - A component created by `createPresenceComponent`.
+ * @param variantParams - An object containing the variant parameters to be used as defaults.
+ * The variant parameters should match the type of the component's motion parameters.
+ * @returns A new presence component that uses the provided variant parameters as defaults.
+ * The new component can still accept runtime parameters that override the defaults.
+ */
+export declare function createPresenceComponentVariant<MotionParams extends Record<string, MotionParam> = {}>(component: PresenceComponent<MotionParams>, variantParams: Partial<MotionParams>): PresenceComponent<MotionParams>;
+
+export declare const curves: {
+    readonly curveAccelerateMax: "cubic-bezier(0.9,0.1,1,0.2)";
+    readonly curveAccelerateMid: "cubic-bezier(1,0,1,1)";
+    readonly curveAccelerateMin: "cubic-bezier(0.8,0,0.78,1)";
+    readonly curveDecelerateMax: "cubic-bezier(0.1,0.9,0.2,1)";
+    readonly curveDecelerateMid: "cubic-bezier(0,0,0,1)";
+    readonly curveDecelerateMin: "cubic-bezier(0.33,0,0.1,1)";
+    readonly curveEasyEaseMax: "cubic-bezier(0.8,0,0.2,1)";
+    readonly curveEasyEase: "cubic-bezier(0.33,0,0.67,1)";
+    readonly curveLinear: "cubic-bezier(0,0,1,1)";
+};
+
+export declare const durations: {
+    readonly durationUltraFast: 50;
+    readonly durationFaster: 100;
+    readonly durationFast: 150;
+    readonly durationNormal: 200;
+    readonly durationGentle: 250;
+    readonly durationSlow: 300;
+    readonly durationSlower: 400;
+    readonly durationUltraSlow: 500;
+};
+
+/**
+ * A private symbol to store the motion definition on the component for variants.
+ *
+ * @internal
+ */
+declare const MOTION_DEFINITION: unique symbol;
+
+export declare const MotionBehaviourProvider: React_2.Provider<MotionBehaviourType | undefined>;
+
+/**
+ * Specifies the behaviour of child motion component under @see MotionBehaviourProvider.
+ */
+declare type MotionBehaviourType = 'skip' | 'default';
+
+export declare type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React_2.FC<MotionComponentProps & MotionParams> & {
+    [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;
+};
+
+export declare type MotionComponentProps = {
+    children: JSXElement;
+    /** Provides imperative controls for the animation. */
+    imperativeRef?: React_2.Ref<MotionImperativeRef | undefined>;
+    /**
+     * Callback that is called when the whole motion finishes.
+     *
+     * A motion definition can contain multiple animations and therefore multiple "finish" events. The callback is
+     * triggered once all animations have finished with "null" instead of an event object to avoid ambiguity.
+     */
+    onMotionFinish?: (ev: null) => void;
+    /**
+     * Callback that is called when the whole motion is cancelled.
+     *
+     * A motion definition can contain multiple animations and therefore multiple "cancel" events. The callback is
+     * triggered once all animations have been cancelled with "null" instead of an event object to avoid ambiguity.
+     */
+    onMotionCancel?: (ev: null) => void;
+    /**
+     * Callback that is called when the whole motion starts.
+     *
+     * A motion definition can contain multiple animations and therefore multiple "start" events. The callback is
+     * triggered when the first animation is started. There is no official "start" event with the Web Animations API.
+     * 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 = {
+    /** Sets the playback rate of the animation, where 1 is normal speed. */
+    setPlaybackRate: (rate: number) => void;
+    /** Sets the state of the animation to running or paused. */
+    setPlayState: (state: 'running' | 'paused') => void;
+};
+
+/**
+ * A motion param should be a primitive value that can be serialized to JSON and could be potentially used a plain
+ * dependency for React hooks.
+ */
+export declare type MotionParam = boolean | number | string;
+
+/**
+ * A component that forwards a ref to its children via a React context.
+ * This is used to pass a motion component's ref through to the actual surface element,
+ * since motion components wrap their children and the ref needs to reach the inner element.
+ *
+ * @internal
+ */
+export declare const MotionRefForwarder: React_2.ForwardRefExoticComponent<{
+    children?: React_2.ReactElement;
+} & React_2.RefAttributes<HTMLElement>>;
+
+/**
+ * Resets the MotionRefForwarder context to `undefined` for its children.
+ * Render this in components that consume `useMotionForwardedRef()` and render
+ * arbitrary user content, to prevent the context from leaking to descendants.
+ *
+ * @internal
+ */
+export declare const MotionRefForwarderReset: React_2.FC<{
+    children: React_2.ReactElement;
+}>;
+
+export declare function motionSlot<MotionParams extends Record<string, MotionParam> = {}>(motion: MotionSlotProps<MotionParams> | null | undefined, options: {
+    elementType: React_2.FC<MotionComponentProps & MotionParams>;
+    defaultProps: MotionSlotRenderProps & MotionParams;
+}): SlotComponentType<MotionSlotRenderProps & MotionParams>;
+
+export declare type MotionSlotProps<MotionParams extends Record<string, MotionParam> = {}> = Pick<MotionComponentProps, 'imperativeRef' | 'onMotionFinish' | 'onMotionStart' | 'onMotionCancel'> & Partial<MotionParams> & {
+    /**
+     * @deprecated Do not use. Motion Slots do not support intrinsic elements.
+     *
+     * If you want to override the animation, use the children render function instead.
+     */
+    as?: JSXIntrinsicElementKeys;
+    children?: SlotRenderFunction<MotionSlotRenderProps & MotionParams & {
+        children: JSXElement;
+    }>;
+};
+
+/**
+ * @internal
+ */
+declare type MotionSlotRenderProps = Pick<MotionComponentProps, 'onMotionFinish' | 'onMotionStart' | 'onMotionCancel'>;
+
+export declare const motionTokens: {
+    curveAccelerateMax: "cubic-bezier(0.9,0.1,1,0.2)";
+    curveAccelerateMid: "cubic-bezier(1,0,1,1)";
+    curveAccelerateMin: "cubic-bezier(0.8,0,0.78,1)";
+    curveDecelerateMax: "cubic-bezier(0.1,0.9,0.2,1)";
+    curveDecelerateMid: "cubic-bezier(0,0,0,1)";
+    curveDecelerateMin: "cubic-bezier(0.33,0,0.1,1)";
+    curveEasyEaseMax: "cubic-bezier(0.8,0,0.2,1)";
+    curveEasyEase: "cubic-bezier(0.33,0,0.67,1)";
+    curveLinear: "cubic-bezier(0,0,1,1)";
+    durationUltraFast: 50;
+    durationFaster: 100;
+    durationFast: 150;
+    durationNormal: 200;
+    durationGentle: 250;
+    durationSlow: 300;
+    durationSlower: 400;
+    durationUltraSlow: 500;
+};
+
+/**
+ * A private symbol to store the motion definition on the component for variants.
+ *
+ * @internal
+ */
+declare const PRESENCE_MOTION_DEFINITION: unique symbol;
+
+export declare type PresenceComponent<MotionParams extends Record<string, MotionParam> = {}> = React_2.FC<PresenceComponentProps & MotionParams> & {
+    (props: PresenceComponentProps & MotionParams): JSXElement | null;
+    [PRESENCE_MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
+    In: MotionComponent<MotionParams>;
+    Out: MotionComponent<MotionParams>;
+};
+
+export declare type PresenceComponentProps = {
+    /**
+     * By default, the child component won't execute the "enter" motion when it initially mounts, regardless of the value
+     * of "visible". If you desire this behavior, ensure both "appear" and "visible" are set to "true".
+     */
+    appear?: boolean;
+    /** A React element that will be cloned and will have motion effects applied to it. */
+    children: JSXElement;
+    /** Provides imperative controls for the animation. */
+    imperativeRef?: React_2.Ref<MotionImperativeRef | undefined>;
+    /**
+     * Callback that is called when the whole motion finishes.
+     *
+     * A motion definition can contain multiple animations and therefore multiple "finish" events. The callback is
+     * triggered once all animations have finished with "null" instead of an event object to avoid ambiguity.
+     */
+    onMotionFinish?: (ev: null, data: {
+        direction: PresenceDirection;
+    }) => void;
+    /**
+     * Callback that is called when the whole motion is cancelled. When a motion is cancelled it does not
+     * emit a finish event but a specific cancel event
+     *
+     * A motion definition can contain multiple animations and therefore multiple "finish" events. The callback is
+     * triggered once all animations have finished with "null" instead of an event object to avoid ambiguity.
+     */
+    onMotionCancel?: (ev: null, data: {
+        direction: PresenceDirection;
+    }) => void;
+    /**
+     * Callback that is called when the whole motion starts.
+     *
+     * A motion definition can contain multiple animations and therefore multiple "start" events. The callback is
+     * triggered when the first animation is started. There is no official "start" event with the Web Animations API.
+     * so the callback is triggered with "null".
+     */
+    onMotionStart?: (ev: null, data: {
+        direction: PresenceDirection;
+    }) => void;
+    /** Defines whether a component is visible; triggers the "enter" or "exit" motions. */
+    visible?: boolean;
+    /**
+     * By default, the child component remains mounted after it reaches the "finished" state. Set "unmountOnExit" if
+     * you prefer to unmount the component after it finishes exiting.
+     */
+    unmountOnExit?: boolean;
+};
+
+export declare type PresenceDirection = 'enter' | 'exit';
+
+export declare class PresenceGroup extends React_2.Component<PresenceGroupProps, PresenceGroupState> {
+    private mounted;
+    static getDerivedStateFromProps(nextProps: PresenceGroupProps, { childMapping: prevChildMapping, firstRender }: PresenceGroupState): PresenceGroupState;
+    constructor(props: PresenceGroupProps, context?: unknown);
+    private handleExit;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    render(): JSXElement;
+}
+
+declare type PresenceGroupChild = {
+    element: JSXElement;
+    appear: boolean;
+    visible: boolean;
+    unmountOnExit: boolean;
+};
+
+export declare type PresenceGroupChildContextValue = {
+    appear: boolean;
+    visible: boolean;
+    unmountOnExit: boolean;
+    onExit: () => void;
+};
+
+declare type PresenceGroupChildMapping = Record<string, PresenceGroupChild>;
+
+export declare const PresenceGroupChildProvider: React_2.Provider<PresenceGroupChildContextValue | undefined>;
+
+declare type PresenceGroupProps = {
+    children: React_2.ReactNode;
+};
+
+declare type PresenceGroupState = {
+    childMapping: PresenceGroupChildMapping;
+    firstRender: boolean;
+};
+
+export declare type PresenceMotion = Record<PresenceDirection, AtomMotion | AtomMotion[]>;
+
+export declare type PresenceMotionFn<MotionParams extends Record<string, MotionParam> = {}> = (params: {
+    element: HTMLElement;
+} & MotionParams) => PresenceMotion;
+
+export declare function presenceMotionSlot<MotionParams extends Record<string, MotionParam> = {}>(motion: PresenceMotionSlotProps<MotionParams> | null | undefined, options: {
+    elementType: React_2.FC<PresenceComponentProps & MotionParams>;
+    defaultProps: PresenceMotionSlotRenderProps & MotionParams;
+}): SlotComponentType<PresenceMotionSlotRenderProps & MotionParams>;
+
+export declare type PresenceMotionSlotProps<MotionParams extends Record<string, MotionParam> = {}> = Pick<PresenceComponentProps, 'imperativeRef' | 'onMotionFinish' | 'onMotionStart'> & Partial<MotionParams> & {
+    /**
+     * @deprecated Do not use. Presence Motion Slots do not support intrinsic elements.
+     *
+     * If you want to override the animation, use the children render function instead.
+     */
+    as?: JSXIntrinsicElementKeys;
+    children?: SlotRenderFunction<PresenceMotionSlotRenderProps & MotionParams & {
+        children: JSXElement;
+    }>;
+};
+
+/**
+ * @internal
+ */
+declare type PresenceMotionSlotRenderProps = Pick<PresenceComponentProps, 'appear' | 'onMotionFinish' | 'onMotionStart' | 'unmountOnExit' | 'visible'>;
+
+/**
+ * A hook that reads the ref forwarded by `MotionRefForwarder` from context.
+ * Used in child components to merge the motion ref into the root slot ref.
+ *
+ * @internal
+ */
+export declare function useMotionForwardedRef(): React_2.Ref<HTMLElement> | undefined;
+
+export declare const usePresenceGroupChildContext: () => PresenceGroupChildContextValue | undefined;
+
+export { }

package/dist/index.d.ts

@@ -80,7 +80,9 @@ export declare const durations: {
 };
 
 /**
- * @internal A private symbol to store the motion definition on the component for variants.
+ * A private symbol to store the motion definition on the component for variants.
+ *
+ * @internal
  */
 declare const MOTION_DEFINITION: unique symbol;
 
@@ -121,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 = {
@@ -136,6 +162,50 @@ export declare type MotionImperativeRef = {
  */
 export declare type MotionParam = boolean | number | string;
 
+/**
+ * A component that forwards a ref to its children via a React context.
+ * This is used to pass a motion component's ref through to the actual surface element,
+ * since motion components wrap their children and the ref needs to reach the inner element.
+ *
+ * @internal
+ */
+export declare const MotionRefForwarder: React_2.ForwardRefExoticComponent<{
+    children?: React_2.ReactElement;
+} & React_2.RefAttributes<HTMLElement>>;
+
+/**
+ * Resets the MotionRefForwarder context to `undefined` for its children.
+ * Render this in components that consume `useMotionForwardedRef()` and render
+ * arbitrary user content, to prevent the context from leaking to descendants.
+ *
+ * @internal
+ */
+export declare const MotionRefForwarderReset: React_2.FC<{
+    children: React_2.ReactElement;
+}>;
+
+export declare function motionSlot<MotionParams extends Record<string, MotionParam> = {}>(motion: MotionSlotProps<MotionParams> | null | undefined, options: {
+    elementType: React_2.FC<MotionComponentProps & MotionParams>;
+    defaultProps: MotionSlotRenderProps & MotionParams;
+}): SlotComponentType<MotionSlotRenderProps & MotionParams>;
+
+export declare type MotionSlotProps<MotionParams extends Record<string, MotionParam> = {}> = Pick<MotionComponentProps, 'imperativeRef' | 'onMotionFinish' | 'onMotionStart' | 'onMotionCancel'> & Partial<MotionParams> & {
+    /**
+     * @deprecated Do not use. Motion Slots do not support intrinsic elements.
+     *
+     * If you want to override the animation, use the children render function instead.
+     */
+    as?: JSXIntrinsicElementKeys;
+    children?: SlotRenderFunction<MotionSlotRenderProps & MotionParams & {
+        children: JSXElement;
+    }>;
+};
+
+/**
+ * @internal
+ */
+declare type MotionSlotRenderProps = Pick<MotionComponentProps, 'onMotionFinish' | 'onMotionStart' | 'onMotionCancel'>;
+
 export declare const motionTokens: {
     curveAccelerateMax: "cubic-bezier(0.9,0.1,1,0.2)";
     curveAccelerateMid: "cubic-bezier(1,0,1,1)";
@@ -157,15 +227,17 @@ export declare const motionTokens: {
 };
 
 /**
- * @internal A private symbol to store the motion definition on the component for variants.
+ * A private symbol to store the motion definition on the component for variants.
+ *
+ * @internal
  */
 declare const PRESENCE_MOTION_DEFINITION: unique symbol;
 
 export declare type PresenceComponent<MotionParams extends Record<string, MotionParam> = {}> = React_2.FC<PresenceComponentProps & MotionParams> & {
     (props: PresenceComponentProps & MotionParams): JSXElement | null;
     [PRESENCE_MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
-    In: React_2.FC<MotionComponentProps & MotionParams>;
-    Out: React_2.FC<MotionComponentProps & MotionParams>;
+    In: MotionComponent<MotionParams>;
+    Out: MotionComponent<MotionParams>;
 };
 
 export declare type PresenceComponentProps = {
@@ -266,7 +338,7 @@ export declare function presenceMotionSlot<MotionParams extends Record<string, M
     defaultProps: PresenceMotionSlotRenderProps & MotionParams;
 }): SlotComponentType<PresenceMotionSlotRenderProps & MotionParams>;
 
-export declare type PresenceMotionSlotProps<MotionParams extends Record<string, MotionParam> = {}> = Pick<PresenceComponentProps, 'imperativeRef' | 'onMotionFinish' | 'onMotionStart'> & {
+export declare type PresenceMotionSlotProps<MotionParams extends Record<string, MotionParam> = {}> = Pick<PresenceComponentProps, 'imperativeRef' | 'onMotionFinish' | 'onMotionStart'> & Partial<MotionParams> & {
     /**
      * @deprecated Do not use. Presence Motion Slots do not support intrinsic elements.
      *
@@ -283,6 +355,14 @@ export declare type PresenceMotionSlotProps<MotionParams extends Record<string,
  */
 declare type PresenceMotionSlotRenderProps = Pick<PresenceComponentProps, 'appear' | 'onMotionFinish' | 'onMotionStart' | 'unmountOnExit' | 'visible'>;
 
+/**
+ * A hook that reads the ref forwarded by `MotionRefForwarder` from context.
+ * Used in child components to merge the motion ref into the root slot ref.
+ *
+ * @internal
+ */
+export declare function useMotionForwardedRef(): React_2.Ref<HTMLElement> | undefined;
+
 export declare const usePresenceGroupChildContext: () => PresenceGroupChildContextValue | undefined;
 
 export { }