@fluentui/react-motion-components-preview 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,12 +1,30 @@
 # Change Log - @fluentui/react-motion-components-preview
 
-This log was last generated on Fri, 31 Oct 2025 16:17:37 GMT and should not be manually modified.
+This log was last generated on Thu, 06 Nov 2025 17:23:24 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [0.14.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion-components-preview_v0.14.0)
+
+Thu, 06 Nov 2025 17:23:24 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion-components-preview_v0.13.0..@fluentui/react-motion-components-preview_v0.14.0)
+
+### Minor changes
+
+- feat(motion): Add Stagger choreography component ([PR #34705](https://github.com/microsoft/fluentui/pull/34705) by robertpenner@microsoft.com)
+
+## [0.13.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion-components-preview_v0.13.0)
+
+Thu, 06 Nov 2025 15:01:23 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion-components-preview_v0.12.0..@fluentui/react-motion-components-preview_v0.13.0)
+
+### Minor changes
+
+- feat(motion): export standard motion atoms ([PR #35421](https://github.com/microsoft/fluentui/pull/35421) by robertpenner@microsoft.com)
+
 ## [0.12.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-motion-components-preview_v0.12.0)
 
-Fri, 31 Oct 2025 16:17:37 GMT 
+Fri, 31 Oct 2025 16:22:05 GMT 
 [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-motion-components-preview_v0.11.0..@fluentui/react-motion-components-preview_v0.12.0)
 
 ### Minor changes

package/dist/index.d.ts

@@ -1,4 +1,8 @@
+import { AtomMotion } from '@fluentui/react-motion';
 import { PresenceComponent } from '@fluentui/react-motion';
+import { PresenceComponentProps } from '@fluentui/react-motion';
+import type { PresenceDirection } from '@fluentui/react-motion';
+import * as React_2 from 'react';
 
 /**
  * Common opacity animation parameter for motion components.
@@ -10,6 +14,22 @@ declare type AnimateOpacity = {
 
 declare type Axis3D = 'x' | 'y' | 'z';
 
+declare type Axis3D_2 = NonNullable<RotateParams['axis']>;
+
+/**
+ * Common parameters shared by all atom functions.
+ */
+declare type BaseAtomParams = {
+    /** The functional direction of the motion: 'enter' or 'exit'. */
+    direction: PresenceDirection;
+    /** The duration of the motion in milliseconds. */
+    duration: number;
+    /** The easing curve for the motion. */
+    easing?: EffectTiming['easing'];
+    /** Time (ms) to delay the animation. */
+    delay?: EffectTiming['delay'];
+};
+
 /**
  * Base presence parameters combining duration, easing, and delay for motion components.
  */
@@ -18,6 +38,23 @@ declare type BasePresenceParams = PresenceDuration & PresenceEasing & PresenceDe
 /** A React component that applies blur in/out transitions to its children. */
 export declare const Blur: PresenceComponent<BlurParams>;
 
+/**
+ * Generates a motion atom object for a blur-in or blur-out.
+ * @param direction - The functional direction of the motion: 'enter' or 'exit'.
+ * @param duration - The duration of the motion in milliseconds.
+ * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
+ * @param fromRadius - The blur radius value with units (e.g., '20px', '1rem'). Defaults to '10px'.
+ * @param toRadius - The ending blur radius value with units (e.g., '0px', '5px'). Defaults to '0px'.
+ * @param delay - Time (ms) to delay the animation. Defaults to 0.
+ * @returns A motion atom object with filter blur keyframes and the supplied duration and easing.
+ */
+export declare const blurAtom: ({ direction, duration, easing, delay, fromRadius, toRadius, }: BlurAtomParams) => AtomMotion;
+
+declare interface BlurAtomParams extends BaseAtomParams {
+    fromRadius?: string;
+    toRadius?: string;
+}
+
 export declare type BlurParams = BasePresenceParams & AnimateOpacity & {
     /** The blur radius with units to animate from. Defaults to '10px'. */
     fromRadius?: string;
@@ -71,6 +108,27 @@ export declare const CollapseSnappy: PresenceComponent<CollapseParams>;
 /** A React component that applies fade in/out transitions to its children. */
 export declare const Fade: PresenceComponent<FadeParams>;
 
+/**
+ * Generates a motion atom object for a fade-in or fade-out.
+ * @param direction - The functional direction of the motion: 'enter' or 'exit'.
+ * @param duration - The duration of the motion in milliseconds.
+ * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
+ * @param delay - The delay before the motion starts. Defaults to 0.
+ * @param fromOpacity - The starting opacity value. Defaults to 0.
+ * @param toOpacity - The ending opacity value. Defaults to 1.
+ * @returns A motion atom object with opacity keyframes and the supplied duration and easing.
+ */
+export declare const fadeAtom: ({ direction, duration, easing, delay, fromOpacity, toOpacity, }: FadeAtomParams) => AtomMotion;
+
+declare interface FadeAtomParams extends BaseAtomParams {
+    /** Defines how values are applied before and after execution. Defaults to 'both'. */
+    fill?: FillMode;
+    /** The starting opacity value. Defaults to 0. */
+    fromOpacity?: number;
+    /** The ending opacity value. Defaults to 1. */
+    toOpacity?: number;
+}
+
 export declare type FadeParams = BasePresenceParams & {
     /** The starting opacity value. Defaults to 0. */
     fromOpacity?: number;
@@ -114,6 +172,25 @@ declare type PresenceEasing = {
 
 export declare const Rotate: PresenceComponent<RotateParams>;
 
+/**
+ * Generates a motion atom object for a rotation around a single axis.
+ * @param direction - The functional direction of the motion: 'enter' or 'exit'.
+ * @param duration - The duration of the motion in milliseconds.
+ * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
+ * @param axis - The axis of rotation: 'x', 'y', or 'z'. Defaults to 'y'.
+ * @param fromAngle - The starting rotation angle in degrees. Defaults to -90.
+ * @param toAngle - The ending rotation angle in degrees. Defaults to 0.
+ * @param delay - Time (ms) to delay the animation. Defaults to 0.
+ * @returns A motion atom object with rotate keyframes and the supplied duration and easing.
+ */
+export declare const rotateAtom: ({ direction, duration, easing, delay, axis, fromAngle, toAngle, }: RotateAtomParams) => AtomMotion;
+
+declare interface RotateAtomParams extends BaseAtomParams {
+    axis?: Axis3D_2;
+    fromAngle?: number;
+    toAngle?: number;
+}
+
 export declare type RotateParams = BasePresenceParams & AnimateOpacity & {
     /**
      * The axis of rotation: 'x', 'y', or 'z'.
@@ -135,6 +212,23 @@ export declare type RotateParams = BasePresenceParams & AnimateOpacity & {
 /** A React component that applies scale in/out transitions to its children. */
 export declare const Scale: PresenceComponent<ScaleParams>;
 
+/**
+ * Generates a motion atom object for a scale in or scale out.
+ * @param direction - The functional direction of the motion: 'enter' or 'exit'.
+ * @param duration - The duration of the motion in milliseconds.
+ * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
+ * @param fromScale - The starting scale value. Defaults to 0.9.
+ * @param toScale - The ending scale value. Defaults to 1.
+ * @param delay - Time (ms) to delay the animation. Defaults to 0.
+ * @returns A motion atom object with scale keyframes and the supplied duration and easing.
+ */
+export declare const scaleAtom: ({ direction, duration, easing, delay, fromScale, toScale, }: ScaleAtomParams) => AtomMotion;
+
+declare interface ScaleAtomParams extends BaseAtomParams {
+    fromScale?: number;
+    toScale?: number;
+}
+
 export declare type ScaleParams = BasePresenceParams & AnimateOpacity & {
     /** The scale value to animate from. Defaults to `0.9`. */
     fromScale?: number;
@@ -149,6 +243,27 @@ export declare const ScaleSnappy: PresenceComponent<ScaleParams>;
 /** A React component that applies slide in/out transitions to its children. */
 export declare const Slide: PresenceComponent<SlideParams>;
 
+/**
+ * Generates a motion atom object for a slide-in or slide-out.
+ * @param direction - The functional direction of the motion: 'enter' or 'exit'.
+ * @param duration - The duration of the motion in milliseconds.
+ * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
+ * @param fromX - The starting X translate value with units (e.g., '50px', '100%'). Defaults to '0px'.
+ * @param fromY - The starting Y translate value with units (e.g., '50px', '100%'). Defaults to '0px'.
+ * @param toX - The ending X translate value with units (e.g.'5px', '10%'). Defaults to '0px'.
+ * @param toY - The ending Y translate value with units (e.g., '5px', '10%'). Defaults to '0px'.
+ * @param delay - Time (ms) to delay the animation. Defaults to 0.
+ * @returns A motion atom object with translate keyframes and the supplied duration and easing.
+ */
+export declare const slideAtom: ({ direction, duration, easing, delay, fromX, fromY, toX, toY, }: SlideAtomParams) => AtomMotion;
+
+declare interface SlideAtomParams extends BaseAtomParams {
+    fromX?: string;
+    fromY?: string;
+    toX?: string;
+    toY?: string;
+}
+
 export declare type SlideParams = BasePresenceParams & AnimateOpacity & {
     /** The X translate value with units to animate from. Defaults to `'0px'`. */
     fromX?: string;
@@ -164,4 +279,119 @@ export declare const SlideRelaxed: PresenceComponent<SlideParams>;
 
 export declare const SlideSnappy: PresenceComponent<SlideParams>;
 
+/**
+ * Stagger is a component that manages the staggered entrance and exit of its children.
+ * Children are animated in sequence with configurable timing between each item.
+ * Stagger can be interactively toggled between entrance and exit animations using the `visible` prop.
+ *
+ * @param children - React elements to animate. Elements are cloned with animation props.
+ * @param visible - Controls animation direction. When `true`, the group is animating "enter" (items shown);
+ * when `false`, the group is animating "exit" (items hidden). Defaults to `false`.
+ * @param itemDelay - Milliseconds between each item's animation start.
+ * Defaults to the package's default delay (see `DEFAULT_ITEM_DELAY`).
+ * @param itemDuration - Milliseconds each item's animation lasts. Only used with `delayMode="timing"`.
+ * Defaults to the package's default item duration (see `DEFAULT_ITEM_DURATION`).
+ * @param reversed - Whether to reverse the stagger sequence (last item animates first). Defaults to `false`.
+ * @param hideMode - How children's visibility/mounting is managed. Auto-detects if not specified.
+ * @param delayMode - How staggering timing is implemented. Auto-detects if not specified.
+ * @param onMotionFinish - Callback invoked when the staggered animation sequence completes.
+ *
+ * **Auto-detection behavior:**
+ * - **hideMode**: Presence components use `'visibleProp'`, DOM elements use `'visibilityStyle'`
+ * - **delayMode**: Components with delay support use `'delayProp'` (most performant), others use `'timing'`
+ *
+ * **hideMode options:**
+ * - `'visibleProp'`: Children are presence components with `visible` prop (always rendered, visibility controlled via prop)
+ * - `'visibilityStyle'`: Children remain in DOM with inline style visibility: hidden/visible (preserves layout space)
+ * - `'unmount'`: Children are mounted/unmounted from DOM based on visibility
+ *
+ * **delayMode options:**
+ * - `'timing'`: Manages visibility over time using JavaScript timing
+ * - `'delayProp'`: Passes delay props to motion components to use native Web Animations API delays (most performant)
+ *
+ * **Static variants:**
+ * - `<Stagger.In>` - One-way stagger for entrance animations only (auto-detects optimal modes)
+ * - `<Stagger.Out>` - One-way stagger for exit animations only (auto-detects optimal modes)
+ *
+ * @example
+ * ```tsx
+ * import { Stagger, Fade, Scale, Rotate } from '@fluentui/react-motion-components-preview';
+ *
+ * // Auto-detects optimal modes for presence components (delayProp + visibleProp)
+ * <Stagger visible={isVisible} itemDelay={150}>
+ *   <Fade><div>Item 2</div></Fade>
+ *   <Scale><div>Item 1</div></Scale>
+ *   <Rotate><div>Item 3</div></Rotate>
+ * </Stagger>
+ *
+ * // Auto-detects optimal modes for motion components (delayProp + unmount)
+ * <Stagger.In itemDelay={100}>
+ *   <Scale.In><div>Item 1</div></Scale.In>
+ *   <Fade.In><div>Item 2</div></Fade.In>
+ * </Stagger.In>
+ *
+ * // Auto-detects timing mode for DOM elements (timing + visibilityStyle)
+ * <Stagger visible={isVisible} itemDelay={150} onMotionFinish={handleComplete}>
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ *   <div>Item 3</div>
+ * </Stagger>
+ *
+ * // Override auto-detection when needed
+ * <Stagger visible={isVisible} delayMode="timing" hideMode="unmount">
+ *   <CustomComponent>Item 1</CustomComponent>
+ * </Stagger>
+ * ```
+ */
+export declare const Stagger: React_2.FC<StaggerProps> & {
+    In: React_2.FC<Omit<StaggerProps, "visible">>;
+    Out: React_2.FC<Omit<StaggerProps, "visible">>;
+};
+
+/**
+ * Defines how Stagger implements the timing of staggered animations.
+ * - 'timing': Manages visibility over time using JavaScript timing (current behavior)
+ * - 'delayProp': Passes delay props to motion components to use native Web Animations API delays
+ */
+declare type StaggerDelayMode = 'timing' | 'delayProp';
+
+/**
+ * Defines how Stagger manages its children's visibility/mounting.
+ * - 'visibleProp': Children are components with a `visible` prop (e.g. motion components)
+ * - 'visibilityStyle': Children remain in DOM with inline style `visibility: hidden | visible`
+ * - 'unmount': Children are mounted/unmounted from DOM based on visibility
+ */
+declare type StaggerHideMode = 'visibleProp' | 'visibilityStyle' | 'unmount';
+
+/**
+ * Props for the Stagger component that manages staggered entrance and exit animations.
+ */
+export declare interface StaggerProps {
+    /** React elements to animate. Elements are cloned with animation props. */
+    children: React_2.ReactNode;
+    /**
+     * Controls children animation direction. When `true`, the group is animating "enter" (items shown).
+     * When `false`, the group is animating "exit" (items hidden).
+     */
+    visible?: PresenceComponentProps['visible'];
+    /** Whether to reverse the stagger sequence (last item animates first). Defaults to `false`. */
+    reversed?: boolean;
+    /**
+     * Milliseconds between each child's animation start.
+     * Defaults to the package's default delay (see `DEFAULT_ITEM_DELAY`).
+     */
+    itemDelay?: number;
+    /**
+     * Milliseconds each child's animation lasts. Only used with `delayMode="timing"`.
+     * Defaults to the package's default duration (see `DEFAULT_ITEM_DURATION`).
+     */
+    itemDuration?: number;
+    /** How children's visibility/mounting is managed. Auto-detects if not specified. */
+    hideMode?: StaggerHideMode;
+    /** How staggering timing is implemented. Defaults to 'timing'. */
+    delayMode?: StaggerDelayMode;
+    /** Callback invoked when the staggered animation sequence completes. */
+    onMotionFinish?: () => void;
+}
+
 export { }

package/lib/choreography/Stagger/Stagger.js

@@ -0,0 +1,189 @@
+'use client';
+import * as React from 'react';
+import { useStaggerItemsVisibility } from './useStaggerItemsVisibility';
+import { DEFAULT_ITEM_DURATION, DEFAULT_ITEM_DELAY, acceptsVisibleProp, acceptsDelayProps, getStaggerChildMapping } from './utils';
+/**
+ * Shared utility to detect optimal stagger modes based on children components.
+ * Consolidates the auto-detection logic used by both StaggerMain and createStaggerDirection.
+ */ const detectStaggerModes = (children, options)=>{
+    const { hideMode, delayMode, fallbackHideMode = 'visibilityStyle' } = options;
+    const childMapping = getStaggerChildMapping(children);
+    const elements = Object.values(childMapping).map((item)=>item.element);
+    const hasVisiblePropSupport = elements.every((child)=>acceptsVisibleProp(child));
+    const hasDelayPropSupport = elements.every((child)=>acceptsDelayProps(child));
+    return {
+        hideMode: hideMode !== null && hideMode !== void 0 ? hideMode : hasVisiblePropSupport ? 'visibleProp' : fallbackHideMode,
+        delayMode: delayMode !== null && delayMode !== void 0 ? delayMode : hasDelayPropSupport ? 'delayProp' : 'timing'
+    };
+};
+const StaggerOneWay = ({ children, direction, itemDelay = DEFAULT_ITEM_DELAY, itemDuration = DEFAULT_ITEM_DURATION, reversed = false, hideMode, delayMode = 'timing', onMotionFinish })=>{
+    const childMapping = React.useMemo(()=>getStaggerChildMapping(children), [
+        children
+    ]);
+    // Always call hooks at the top level, regardless of delayMode
+    const { itemsVisibility } = useStaggerItemsVisibility({
+        childMapping,
+        itemDelay,
+        itemDuration,
+        direction,
+        reversed,
+        onMotionFinish,
+        hideMode
+    });
+    // For delayProp mode, pass delay props directly to motion components
+    if (delayMode === 'delayProp') {
+        return /*#__PURE__*/ React.createElement(React.Fragment, null, Object.entries(childMapping).map(([key, { element, index }])=>{
+            const staggerIndex = reversed ? Object.keys(childMapping).length - 1 - index : index;
+            const delay = staggerIndex * itemDelay;
+            // Clone element with delay prop (for enter direction) or exitDelay prop (for exit direction)
+            const delayProp = direction === 'enter' ? {
+                delay
+            } : {
+                exitDelay: delay
+            };
+            // Only set visible prop if the component supports it
+            // Set visible based on direction: true for enter, false for exit
+            const visibleProp = acceptsVisibleProp(element) ? {
+                visible: direction === 'enter'
+            } : {};
+            return /*#__PURE__*/ React.cloneElement(element, {
+                key,
+                ...visibleProp,
+                ...delayProp
+            });
+        }));
+    }
+    // For timing mode, use the existing timing-based implementation
+    return /*#__PURE__*/ React.createElement(React.Fragment, null, Object.entries(childMapping).map(([key, { element }])=>{
+        if (hideMode === 'visibleProp') {
+            // Use a generic record type for props to avoid `any` while still allowing unknown prop shapes.
+            return /*#__PURE__*/ React.cloneElement(element, {
+                key,
+                visible: itemsVisibility[key]
+            });
+        } else if (hideMode === 'visibilityStyle') {
+            const childProps = element.props;
+            const style = {
+                ...childProps === null || childProps === void 0 ? void 0 : childProps.style,
+                visibility: itemsVisibility[key] ? 'visible' : 'hidden'
+            };
+            return /*#__PURE__*/ React.cloneElement(element, {
+                key,
+                style
+            });
+        } else {
+            // unmount mode
+            return itemsVisibility[key] ? /*#__PURE__*/ React.cloneElement(element, {
+                key
+            }) : null;
+        }
+    }));
+};
+// Shared helper for StaggerIn and StaggerOut
+const createStaggerDirection = (direction)=>{
+    const StaggerDirection = ({ hideMode, delayMode, children, ...props })=>{
+        // Auto-detect modes for better performance with motion components
+        const { hideMode: resolvedHideMode, delayMode: resolvedDelayMode } = detectStaggerModes(children, {
+            hideMode,
+            delayMode,
+            // One-way stagger falls back to visibilityStyle if it doesn't detect visibleProp support
+            fallbackHideMode: 'visibilityStyle'
+        });
+        return /*#__PURE__*/ React.createElement(StaggerOneWay, {
+            ...props,
+            children: children,
+            direction: direction,
+            hideMode: resolvedHideMode,
+            delayMode: resolvedDelayMode
+        });
+    };
+    return StaggerDirection;
+};
+const StaggerIn = createStaggerDirection('enter');
+const StaggerOut = createStaggerDirection('exit');
+// Main Stagger component with auto-detection or explicit modes
+const StaggerMain = (props)=>{
+    const { children, visible = false, hideMode, delayMode, ...rest } = props;
+    // Auto-detect modes for bidirectional stagger
+    const { hideMode: resolvedHideMode, delayMode: resolvedDelayMode } = detectStaggerModes(children, {
+        hideMode,
+        delayMode,
+        // Bidirectional stagger falls back to visibilityStyle if it doesn't detect visibleProp support
+        fallbackHideMode: 'visibilityStyle'
+    });
+    const direction = visible ? 'enter' : 'exit';
+    return /*#__PURE__*/ React.createElement(StaggerOneWay, {
+        ...rest,
+        children: children,
+        hideMode: resolvedHideMode,
+        delayMode: resolvedDelayMode,
+        direction: direction
+    });
+};
+/**
+ * Stagger is a component that manages the staggered entrance and exit of its children.
+ * Children are animated in sequence with configurable timing between each item.
+ * Stagger can be interactively toggled between entrance and exit animations using the `visible` prop.
+ *
+ * @param children - React elements to animate. Elements are cloned with animation props.
+ * @param visible - Controls animation direction. When `true`, the group is animating "enter" (items shown);
+ * when `false`, the group is animating "exit" (items hidden). Defaults to `false`.
+ * @param itemDelay - Milliseconds between each item's animation start.
+ * Defaults to the package's default delay (see `DEFAULT_ITEM_DELAY`).
+ * @param itemDuration - Milliseconds each item's animation lasts. Only used with `delayMode="timing"`.
+ * Defaults to the package's default item duration (see `DEFAULT_ITEM_DURATION`).
+ * @param reversed - Whether to reverse the stagger sequence (last item animates first). Defaults to `false`.
+ * @param hideMode - How children's visibility/mounting is managed. Auto-detects if not specified.
+ * @param delayMode - How staggering timing is implemented. Auto-detects if not specified.
+ * @param onMotionFinish - Callback invoked when the staggered animation sequence completes.
+ *
+ * **Auto-detection behavior:**
+ * - **hideMode**: Presence components use `'visibleProp'`, DOM elements use `'visibilityStyle'`
+ * - **delayMode**: Components with delay support use `'delayProp'` (most performant), others use `'timing'`
+ *
+ * **hideMode options:**
+ * - `'visibleProp'`: Children are presence components with `visible` prop (always rendered, visibility controlled via prop)
+ * - `'visibilityStyle'`: Children remain in DOM with inline style visibility: hidden/visible (preserves layout space)
+ * - `'unmount'`: Children are mounted/unmounted from DOM based on visibility
+ *
+ * **delayMode options:**
+ * - `'timing'`: Manages visibility over time using JavaScript timing
+ * - `'delayProp'`: Passes delay props to motion components to use native Web Animations API delays (most performant)
+ *
+ * **Static variants:**
+ * - `<Stagger.In>` - One-way stagger for entrance animations only (auto-detects optimal modes)
+ * - `<Stagger.Out>` - One-way stagger for exit animations only (auto-detects optimal modes)
+ *
+ * @example
+ * ```tsx
+ * import { Stagger, Fade, Scale, Rotate } from '@fluentui/react-motion-components-preview';
+ *
+ * // Auto-detects optimal modes for presence components (delayProp + visibleProp)
+ * <Stagger visible={isVisible} itemDelay={150}>
+ *   <Fade><div>Item 2</div></Fade>
+ *   <Scale><div>Item 1</div></Scale>
+ *   <Rotate><div>Item 3</div></Rotate>
+ * </Stagger>
+ *
+ * // Auto-detects optimal modes for motion components (delayProp + unmount)
+ * <Stagger.In itemDelay={100}>
+ *   <Scale.In><div>Item 1</div></Scale.In>
+ *   <Fade.In><div>Item 2</div></Fade.In>
+ * </Stagger.In>
+ *
+ * // Auto-detects timing mode for DOM elements (timing + visibilityStyle)
+ * <Stagger visible={isVisible} itemDelay={150} onMotionFinish={handleComplete}>
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ *   <div>Item 3</div>
+ * </Stagger>
+ *
+ * // Override auto-detection when needed
+ * <Stagger visible={isVisible} delayMode="timing" hideMode="unmount">
+ *   <CustomComponent>Item 1</CustomComponent>
+ * </Stagger>
+ * ```
+ */ export const Stagger = Object.assign(StaggerMain, {
+    In: StaggerIn,
+    Out: StaggerOut
+});

package/lib/choreography/Stagger/Stagger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/Stagger.tsx"],"sourcesContent":["'use client';\n\nimport * as React from 'react';\nimport { useStaggerItemsVisibility } from './useStaggerItemsVisibility';\nimport {\n  DEFAULT_ITEM_DURATION,\n  DEFAULT_ITEM_DELAY,\n  acceptsVisibleProp,\n  acceptsDelayProps,\n  getStaggerChildMapping,\n} from './utils';\nimport { StaggerOneWayProps, StaggerProps, type StaggerHideMode, type StaggerDelayMode } from './stagger-types';\n\n/**\n * Shared utility to detect optimal stagger modes based on children components.\n * Consolidates the auto-detection logic used by both StaggerMain and createStaggerDirection.\n */\nconst detectStaggerModes = (\n  children: React.ReactNode,\n  options: {\n    hideMode?: StaggerHideMode;\n    delayMode?: StaggerDelayMode;\n    fallbackHideMode?: StaggerHideMode;\n  },\n): { hideMode: StaggerHideMode; delayMode: StaggerDelayMode } => {\n  const { hideMode, delayMode, fallbackHideMode = 'visibilityStyle' } = options;\n\n  const childMapping = getStaggerChildMapping(children);\n  const elements = Object.values(childMapping).map(item => item.element);\n  const hasVisiblePropSupport = elements.every(child => acceptsVisibleProp(child));\n  const hasDelayPropSupport = elements.every(child => acceptsDelayProps(child));\n\n  return {\n    hideMode: hideMode ?? (hasVisiblePropSupport ? 'visibleProp' : fallbackHideMode),\n    delayMode: delayMode ?? (hasDelayPropSupport ? 'delayProp' : 'timing'),\n  };\n};\n\nconst StaggerOneWay: React.FC<StaggerOneWayProps> = ({\n  children,\n  direction,\n  itemDelay = DEFAULT_ITEM_DELAY,\n  itemDuration = DEFAULT_ITEM_DURATION,\n  reversed = false,\n  hideMode,\n  delayMode = 'timing',\n  onMotionFinish,\n}) => {\n  const childMapping = React.useMemo(() => getStaggerChildMapping(children), [children]);\n\n  // Always call hooks at the top level, regardless of delayMode\n  const { itemsVisibility } = useStaggerItemsVisibility({\n    childMapping,\n    itemDelay,\n    itemDuration,\n    direction,\n    reversed,\n    onMotionFinish,\n    hideMode,\n  });\n\n  // For delayProp mode, pass delay props directly to motion components\n  if (delayMode === 'delayProp') {\n    return (\n      <>\n        {Object.entries(childMapping).map(([key, { element, index }]) => {\n          const staggerIndex = reversed ? Object.keys(childMapping).length - 1 - index : index;\n          const delay = staggerIndex * itemDelay;\n\n          // Clone element with delay prop (for enter direction) or exitDelay prop (for exit direction)\n          const delayProp = direction === 'enter' ? { delay } : { exitDelay: delay };\n\n          // Only set visible prop if the component supports it\n          // Set visible based on direction: true for enter, false for exit\n          const visibleProp = acceptsVisibleProp(element) ? { visible: direction === 'enter' } : {};\n\n          return React.cloneElement(element, {\n            key,\n            ...visibleProp,\n            ...delayProp,\n          });\n        })}\n      </>\n    );\n  }\n\n  // For timing mode, use the existing timing-based implementation\n\n  return (\n    <>\n      {Object.entries(childMapping).map(([key, { element }]) => {\n        if (hideMode === 'visibleProp') {\n          // Use a generic record type for props to avoid `any` while still allowing unknown prop shapes.\n          return React.cloneElement(element, {\n            key,\n            visible: itemsVisibility[key],\n          } as Partial<Record<string, unknown>>);\n        } else if (hideMode === 'visibilityStyle') {\n          const childProps = element.props as Record<string, unknown> | undefined;\n          const style = {\n            ...(childProps?.style as Record<string, unknown> | undefined),\n            visibility: itemsVisibility[key] ? 'visible' : 'hidden',\n          };\n          return React.cloneElement(element, { key, style } as Partial<Record<string, unknown>>);\n        } else {\n          // unmount mode\n          return itemsVisibility[key] ? React.cloneElement(element, { key }) : null;\n        }\n      })}\n    </>\n  );\n};\n\n// Shared helper for StaggerIn and StaggerOut\nconst createStaggerDirection = (direction: 'enter' | 'exit') => {\n  const StaggerDirection: React.FC<Omit<StaggerProps, 'visible'>> = ({ hideMode, delayMode, children, ...props }) => {\n    // Auto-detect modes for better performance with motion components\n    const { hideMode: resolvedHideMode, delayMode: resolvedDelayMode } = detectStaggerModes(children, {\n      hideMode,\n      delayMode,\n      // One-way stagger falls back to visibilityStyle if it doesn't detect visibleProp support\n      fallbackHideMode: 'visibilityStyle',\n    });\n\n    return (\n      <StaggerOneWay\n        {...props}\n        children={children}\n        direction={direction}\n        hideMode={resolvedHideMode}\n        delayMode={resolvedDelayMode}\n      />\n    );\n  };\n\n  return StaggerDirection;\n};\n\nconst StaggerIn = createStaggerDirection('enter');\nconst StaggerOut = createStaggerDirection('exit');\n\n// Main Stagger component with auto-detection or explicit modes\nconst StaggerMain: React.FC<StaggerProps> = props => {\n  const { children, visible = false, hideMode, delayMode, ...rest } = props;\n\n  // Auto-detect modes for bidirectional stagger\n  const { hideMode: resolvedHideMode, delayMode: resolvedDelayMode } = detectStaggerModes(children, {\n    hideMode,\n    delayMode,\n    // Bidirectional stagger falls back to visibilityStyle if it doesn't detect visibleProp support\n    fallbackHideMode: 'visibilityStyle',\n  });\n\n  const direction = visible ? 'enter' : 'exit';\n\n  return (\n    <StaggerOneWay\n      {...rest}\n      children={children}\n      hideMode={resolvedHideMode}\n      delayMode={resolvedDelayMode}\n      direction={direction}\n    />\n  );\n};\n\n/**\n * Stagger is a component that manages the staggered entrance and exit of its children.\n * Children are animated in sequence with configurable timing between each item.\n * Stagger can be interactively toggled between entrance and exit animations using the `visible` prop.\n *\n * @param children - React elements to animate. Elements are cloned with animation props.\n * @param visible - Controls animation direction. When `true`, the group is animating \"enter\" (items shown);\n * when `false`, the group is animating \"exit\" (items hidden). Defaults to `false`.\n * @param itemDelay - Milliseconds between each item's animation start.\n * Defaults to the package's default delay (see `DEFAULT_ITEM_DELAY`).\n * @param itemDuration - Milliseconds each item's animation lasts. Only used with `delayMode=\"timing\"`.\n * Defaults to the package's default item duration (see `DEFAULT_ITEM_DURATION`).\n * @param reversed - Whether to reverse the stagger sequence (last item animates first). Defaults to `false`.\n * @param hideMode - How children's visibility/mounting is managed. Auto-detects if not specified.\n * @param delayMode - How staggering timing is implemented. Auto-detects if not specified.\n * @param onMotionFinish - Callback invoked when the staggered animation sequence completes.\n *\n * **Auto-detection behavior:**\n * - **hideMode**: Presence components use `'visibleProp'`, DOM elements use `'visibilityStyle'`\n * - **delayMode**: Components with delay support use `'delayProp'` (most performant), others use `'timing'`\n *\n * **hideMode options:**\n * - `'visibleProp'`: Children are presence components with `visible` prop (always rendered, visibility controlled via prop)\n * - `'visibilityStyle'`: Children remain in DOM with inline style visibility: hidden/visible (preserves layout space)\n * - `'unmount'`: Children are mounted/unmounted from DOM based on visibility\n *\n * **delayMode options:**\n * - `'timing'`: Manages visibility over time using JavaScript timing\n * - `'delayProp'`: Passes delay props to motion components to use native Web Animations API delays (most performant)\n *\n * **Static variants:**\n * - `<Stagger.In>` - One-way stagger for entrance animations only (auto-detects optimal modes)\n * - `<Stagger.Out>` - One-way stagger for exit animations only (auto-detects optimal modes)\n *\n * @example\n * ```tsx\n * import { Stagger, Fade, Scale, Rotate } from '@fluentui/react-motion-components-preview';\n *\n * // Auto-detects optimal modes for presence components (delayProp + visibleProp)\n * <Stagger visible={isVisible} itemDelay={150}>\n *   <Fade><div>Item 2</div></Fade>\n *   <Scale><div>Item 1</div></Scale>\n *   <Rotate><div>Item 3</div></Rotate>\n * </Stagger>\n *\n * // Auto-detects optimal modes for motion components (delayProp + unmount)\n * <Stagger.In itemDelay={100}>\n *   <Scale.In><div>Item 1</div></Scale.In>\n *   <Fade.In><div>Item 2</div></Fade.In>\n * </Stagger.In>\n *\n * // Auto-detects timing mode for DOM elements (timing + visibilityStyle)\n * <Stagger visible={isVisible} itemDelay={150} onMotionFinish={handleComplete}>\n *   <div>Item 1</div>\n *   <div>Item 2</div>\n *   <div>Item 3</div>\n * </Stagger>\n *\n * // Override auto-detection when needed\n * <Stagger visible={isVisible} delayMode=\"timing\" hideMode=\"unmount\">\n *   <CustomComponent>Item 1</CustomComponent>\n * </Stagger>\n * ```\n */\nexport const Stagger = Object.assign(StaggerMain, {\n  In: StaggerIn,\n  Out: StaggerOut,\n});\n"],"names":["React","useStaggerItemsVisibility","DEFAULT_ITEM_DURATION","DEFAULT_ITEM_DELAY","acceptsVisibleProp","acceptsDelayProps","getStaggerChildMapping","detectStaggerModes","children","options","hideMode","delayMode","fallbackHideMode","childMapping","elements","Object","values","map","item","element","hasVisiblePropSupport","every","child","hasDelayPropSupport","StaggerOneWay","direction","itemDelay","itemDuration","reversed","onMotionFinish","useMemo","itemsVisibility","entries","key","index","staggerIndex","keys","length","delay","delayProp","exitDelay","visibleProp","visible","cloneElement","childProps","props","style","visibility","createStaggerDirection","StaggerDirection","resolvedHideMode","resolvedDelayMode","StaggerIn","StaggerOut","StaggerMain","rest","Stagger","assign","In","Out"],"mappings":"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"}

package/lib/choreography/Stagger/index.js

@@ -0,0 +1 @@
+export { Stagger } from './Stagger';

package/lib/choreography/Stagger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/index.ts"],"sourcesContent":["export { Stagger } from './Stagger';\nexport type { StaggerProps } from './stagger-types';\n"],"names":["Stagger"],"mappings":"AAAA,SAASA,OAAO,QAAQ,YAAY"}

package/lib/choreography/Stagger/stagger-types.js

@@ -0,0 +1 @@
+import * as React from 'react';

package/lib/choreography/Stagger/stagger-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/stagger-types.ts"],"sourcesContent":["import { PresenceComponentProps, PresenceDirection } from '@fluentui/react-motion';\nimport * as React from 'react';\n\n/**\n * Defines how Stagger manages its children's visibility/mounting.\n * - 'visibleProp': Children are components with a `visible` prop (e.g. motion components)\n * - 'visibilityStyle': Children remain in DOM with inline style `visibility: hidden | visible`\n * - 'unmount': Children are mounted/unmounted from DOM based on visibility\n */\nexport type StaggerHideMode = 'visibleProp' | 'visibilityStyle' | 'unmount';\n\n/**\n * Defines how Stagger implements the timing of staggered animations.\n * - 'timing': Manages visibility over time using JavaScript timing (current behavior)\n * - 'delayProp': Passes delay props to motion components to use native Web Animations API delays\n */\nexport type StaggerDelayMode = 'timing' | 'delayProp';\n\n/**\n * Props for the Stagger component that manages staggered entrance and exit animations.\n */\nexport interface StaggerProps {\n  /** React elements to animate. Elements are cloned with animation props. */\n  children: React.ReactNode;\n\n  /**\n   * Controls children animation direction. When `true`, the group is animating \"enter\" (items shown).\n   * When `false`, the group is animating \"exit\" (items hidden).\n   */\n  visible?: PresenceComponentProps['visible'];\n\n  /** Whether to reverse the stagger sequence (last item animates first). Defaults to `false`. */\n  reversed?: boolean;\n\n  /**\n   * Milliseconds between each child's animation start.\n   * Defaults to the package's default delay (see `DEFAULT_ITEM_DELAY`).\n   */\n  itemDelay?: number;\n\n  /**\n   * Milliseconds each child's animation lasts. Only used with `delayMode=\"timing\"`.\n   * Defaults to the package's default duration (see `DEFAULT_ITEM_DURATION`).\n   */\n  itemDuration?: number;\n\n  /** How children's visibility/mounting is managed. Auto-detects if not specified. */\n  hideMode?: StaggerHideMode;\n\n  /** How staggering timing is implemented. Defaults to 'timing'. */\n  delayMode?: StaggerDelayMode;\n\n  /** Callback invoked when the staggered animation sequence completes. */\n  onMotionFinish?: () => void;\n}\n\nexport interface StaggerOneWayProps extends Omit<StaggerProps, 'visible' | 'hideMode' | 'delayMode'> {\n  /** Animation direction: 'enter' or 'exit'. */\n  direction: PresenceDirection;\n\n  /** How children's visibility/mounting is managed. Required - provided by wrapper components. */\n  hideMode: StaggerHideMode;\n\n  /** How staggering timing is implemented. Required - provided by wrapper components. */\n  delayMode: StaggerDelayMode;\n}\n"],"names":["React"],"mappings":"AACA,YAAYA,WAAW,QAAQ"}