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

package/CHANGELOG.md

@@ -1,12 +1,21 @@
 # Change Log - @fluentui/react-motion-components-preview
 
-This log was last generated on Thu, 06 Nov 2025 14:56:59 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 14:56:59 GMT 
+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

package/dist/index.d.ts

@@ -1,6 +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.
@@ -277,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"}

package/lib/choreography/Stagger/useStaggerItemsVisibility.js

@@ -0,0 +1,176 @@
+'use client';
+import * as React from 'react';
+import { useAnimationFrame, useEventCallback } from '@fluentui/react-utilities';
+import { staggerItemsVisibilityAtTime, DEFAULT_ITEM_DURATION } from './utils';
+/**
+ * Hook that tracks the visibility of a staggered sequence of items as time progresses.
+ *
+ * Behavior summary for all hide modes:
+ * - On the first render, items are placed in their final state (enter => visible, exit => hidden)
+ *   and no animation runs.
+ * - On subsequent renders when direction changes, items animate from the opposite state
+ *   to the final state over the stagger timeline.
+ * - Changes to the `reversed` prop do not trigger re-animation; they only affect the order
+ *   during the next direction change animation.
+ *
+ * This hook uses child key mapping instead of item count to track individual items.
+ * This allows it to correctly handle:
+ * - Items being added and removed simultaneously (when count stays the same)
+ * - Items being reordered
+ * - Individual item identity across renders
+ *
+ * @param childMapping - Mapping of child keys to elements and indices
+ * @param itemDelay - Milliseconds between the start of each item's animation
+ * @param itemDuration - Milliseconds each item's animation lasts
+ * @param direction - 'enter' (show items) or 'exit' (hide items)
+ * @param reversed - Whether to reverse the stagger order (last item first)
+ * @param onMotionFinish - Callback fired when the full stagger sequence completes
+ * @param hideMode - How children's visibility is managed: 'visibleProp', 'visibilityStyle', or 'unmount'
+ *
+ * @returns An object with `itemsVisibility: Record<string, boolean>` indicating which items are currently visible by key
+ */ export function useStaggerItemsVisibility({ childMapping, itemDelay, itemDuration = DEFAULT_ITEM_DURATION, direction, reversed = false, onMotionFinish, hideMode = 'visibleProp' }) {
+    const [requestAnimationFrame, cancelAnimationFrame] = useAnimationFrame();
+    // Stabilize the callback reference to avoid re-triggering effects on every render
+    const handleMotionFinish = useEventCallback(onMotionFinish !== null && onMotionFinish !== void 0 ? onMotionFinish : ()=>{
+        return;
+    });
+    // Track animation state independently of child changes
+    const [animationKey, setAnimationKey] = React.useState(0);
+    const prevDirection = React.useRef(direction);
+    // Only trigger new animation when direction actually changes, not when children change
+    React.useEffect(()=>{
+        if (prevDirection.current !== direction) {
+            setAnimationKey((prev)=>prev + 1);
+            prevDirection.current = direction;
+        }
+    }, [
+        direction
+    ]);
+    // State: visibility mapping for all items by key
+    const [itemsVisibility, setItemsVisibility] = React.useState(()=>{
+        const initial = {};
+        // All hide modes start in final state: visible for 'enter', hidden for 'exit'
+        const initialState = direction === 'enter';
+        Object.keys(childMapping).forEach((key)=>{
+            initial[key] = initialState;
+        });
+        return initial;
+    });
+    // Update visibility mapping when childMapping changes
+    React.useEffect(()=>{
+        setItemsVisibility((prev)=>{
+            const next = {};
+            const targetState = direction === 'enter';
+            // Add or update items from new mapping
+            Object.keys(childMapping).forEach((key)=>{
+                if (key in prev) {
+                    // Existing item - preserve its visibility state
+                    next[key] = prev[key];
+                } else {
+                    // New item - set to target state
+                    next[key] = targetState;
+                }
+            });
+            // Note: Items that were in prev but not in childMapping are automatically removed
+            // because we only iterate over keys in childMapping
+            return next;
+        });
+    }, [
+        childMapping,
+        direction
+    ]);
+    // Refs: animation timing and control
+    const startTimeRef = React.useRef(null);
+    const frameRef = React.useRef(null);
+    const finishedRef = React.useRef(false);
+    const isFirstRender = React.useRef(true);
+    // Use ref to avoid re-running the animation when child mapping changes
+    const childMappingRef = React.useRef(childMapping);
+    // Update childMapping ref whenever it changes
+    React.useEffect(()=>{
+        childMappingRef.current = childMapping;
+    }, [
+        childMapping
+    ]);
+    // Use ref for reversed to avoid re-running animation when it changes
+    const reversedRef = React.useRef(reversed);
+    // Update reversed ref whenever it changes
+    React.useEffect(()=>{
+        reversedRef.current = reversed;
+    }, [
+        reversed
+    ]);
+    // ====== ANIMATION EFFECT ======
+    React.useEffect(()=>{
+        let cancelled = false;
+        startTimeRef.current = null;
+        finishedRef.current = false;
+        // All hide modes skip animation on first render - items are already in their final state
+        if (isFirstRender.current) {
+            isFirstRender.current = false;
+            // Items are already in their final state from useState, no animation needed
+            handleMotionFinish();
+            return; // No cleanup needed for first render
+        }
+        // For animations after first render, start from the opposite of the final state
+        // - Enter animation: start hidden (false), animate to visible (true)
+        // - Exit animation: start visible (true), animate to hidden (false)
+        const startState = direction === 'exit';
+        // Use childMappingRef.current to avoid adding childMapping to dependencies
+        const initialVisibility = {};
+        Object.keys(childMappingRef.current).forEach((key)=>{
+            initialVisibility[key] = startState;
+        });
+        setItemsVisibility(initialVisibility);
+        // Animation loop: update visibility on each frame until complete
+        const tick = (now)=>{
+            if (cancelled) {
+                return;
+            }
+            if (startTimeRef.current === null) {
+                startTimeRef.current = now;
+            }
+            const elapsed = now - startTimeRef.current;
+            const childKeys = Object.keys(childMappingRef.current);
+            const itemCount = childKeys.length;
+            const result = staggerItemsVisibilityAtTime({
+                itemCount,
+                elapsed,
+                itemDelay,
+                itemDuration,
+                direction,
+                reversed: reversedRef.current
+            });
+            // Convert boolean array to keyed object
+            const nextVisibility = {};
+            childKeys.forEach((key, idx)=>{
+                nextVisibility[key] = result.itemsVisibility[idx];
+            });
+            setItemsVisibility(nextVisibility);
+            if (elapsed < result.totalDuration) {
+                frameRef.current = requestAnimationFrame(tick);
+            } else if (!finishedRef.current) {
+                finishedRef.current = true;
+                handleMotionFinish();
+            }
+        };
+        frameRef.current = requestAnimationFrame(tick);
+        return ()=>{
+            cancelled = true;
+            if (frameRef.current) {
+                cancelAnimationFrame();
+            }
+        };
+    }, [
+        animationKey,
+        itemDelay,
+        itemDuration,
+        direction,
+        requestAnimationFrame,
+        cancelAnimationFrame,
+        handleMotionFinish
+    ]);
+    return {
+        itemsVisibility
+    };
+}

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/useStaggerItemsVisibility.tsx"],"sourcesContent":["'use client';\n\nimport * as React from 'react';\nimport { useAnimationFrame, useEventCallback } from '@fluentui/react-utilities';\nimport type { StaggerProps } from './stagger-types';\nimport {\n  staggerItemsVisibilityAtTime,\n  type StaggerItemsVisibilityAtTimeParams,\n  DEFAULT_ITEM_DURATION,\n  type StaggerChildMapping,\n} from './utils';\n\nexport interface UseStaggerItemsVisibilityParams\n  extends Pick<StaggerProps, 'onMotionFinish'>,\n    Omit<StaggerItemsVisibilityAtTimeParams, 'elapsed' | 'itemCount'> {\n  hideMode: StaggerProps['hideMode'];\n  childMapping: StaggerChildMapping;\n}\n\n/**\n * Hook that tracks the visibility of a staggered sequence of items as time progresses.\n *\n * Behavior summary for all hide modes:\n * - On the first render, items are placed in their final state (enter => visible, exit => hidden)\n *   and no animation runs.\n * - On subsequent renders when direction changes, items animate from the opposite state\n *   to the final state over the stagger timeline.\n * - Changes to the `reversed` prop do not trigger re-animation; they only affect the order\n *   during the next direction change animation.\n *\n * This hook uses child key mapping instead of item count to track individual items.\n * This allows it to correctly handle:\n * - Items being added and removed simultaneously (when count stays the same)\n * - Items being reordered\n * - Individual item identity across renders\n *\n * @param childMapping - Mapping of child keys to elements and indices\n * @param itemDelay - Milliseconds between the start of each item's animation\n * @param itemDuration - Milliseconds each item's animation lasts\n * @param direction - 'enter' (show items) or 'exit' (hide items)\n * @param reversed - Whether to reverse the stagger order (last item first)\n * @param onMotionFinish - Callback fired when the full stagger sequence completes\n * @param hideMode - How children's visibility is managed: 'visibleProp', 'visibilityStyle', or 'unmount'\n *\n * @returns An object with `itemsVisibility: Record<string, boolean>` indicating which items are currently visible by key\n */\nexport function useStaggerItemsVisibility({\n  childMapping,\n  itemDelay,\n  itemDuration = DEFAULT_ITEM_DURATION,\n  direction,\n  reversed = false,\n  onMotionFinish,\n  hideMode = 'visibleProp',\n}: UseStaggerItemsVisibilityParams): { itemsVisibility: Record<string, boolean> } {\n  const [requestAnimationFrame, cancelAnimationFrame] = useAnimationFrame();\n\n  // Stabilize the callback reference to avoid re-triggering effects on every render\n  const handleMotionFinish = useEventCallback(\n    onMotionFinish ??\n      (() => {\n        return;\n      }),\n  );\n\n  // Track animation state independently of child changes\n  const [animationKey, setAnimationKey] = React.useState(0);\n  const prevDirection = React.useRef(direction);\n\n  // Only trigger new animation when direction actually changes, not when children change\n  React.useEffect(() => {\n    if (prevDirection.current !== direction) {\n      setAnimationKey(prev => prev + 1);\n      prevDirection.current = direction;\n    }\n  }, [direction]);\n\n  // State: visibility mapping for all items by key\n  const [itemsVisibility, setItemsVisibility] = React.useState<Record<string, boolean>>(() => {\n    const initial: Record<string, boolean> = {};\n    // All hide modes start in final state: visible for 'enter', hidden for 'exit'\n    const initialState = direction === 'enter';\n    Object.keys(childMapping).forEach(key => {\n      initial[key] = initialState;\n    });\n    return initial;\n  });\n\n  // Update visibility mapping when childMapping changes\n  React.useEffect(() => {\n    setItemsVisibility(prev => {\n      const next: Record<string, boolean> = {};\n      const targetState = direction === 'enter';\n\n      // Add or update items from new mapping\n      Object.keys(childMapping).forEach(key => {\n        if (key in prev) {\n          // Existing item - preserve its visibility state\n          next[key] = prev[key];\n        } else {\n          // New item - set to target state\n          next[key] = targetState;\n        }\n      });\n\n      // Note: Items that were in prev but not in childMapping are automatically removed\n      // because we only iterate over keys in childMapping\n\n      return next;\n    });\n  }, [childMapping, direction]);\n\n  // Refs: animation timing and control\n  const startTimeRef = React.useRef<number | null>(null);\n  const frameRef = React.useRef<number | null>(null);\n  const finishedRef = React.useRef(false);\n  const isFirstRender = React.useRef(true);\n\n  // Use ref to avoid re-running the animation when child mapping changes\n  const childMappingRef = React.useRef(childMapping);\n\n  // Update childMapping ref whenever it changes\n  React.useEffect(() => {\n    childMappingRef.current = childMapping;\n  }, [childMapping]);\n\n  // Use ref for reversed to avoid re-running animation when it changes\n  const reversedRef = React.useRef(reversed);\n\n  // Update reversed ref whenever it changes\n  React.useEffect(() => {\n    reversedRef.current = reversed;\n  }, [reversed]);\n\n  // ====== ANIMATION EFFECT ======\n\n  React.useEffect(() => {\n    let cancelled = false;\n    startTimeRef.current = null;\n    finishedRef.current = false;\n\n    // All hide modes skip animation on first render - items are already in their final state\n    if (isFirstRender.current) {\n      isFirstRender.current = false;\n      // Items are already in their final state from useState, no animation needed\n      handleMotionFinish();\n      return; // No cleanup needed for first render\n    }\n\n    // For animations after first render, start from the opposite of the final state\n    // - Enter animation: start hidden (false), animate to visible (true)\n    // - Exit animation: start visible (true), animate to hidden (false)\n    const startState = direction === 'exit';\n    // Use childMappingRef.current to avoid adding childMapping to dependencies\n    const initialVisibility: Record<string, boolean> = {};\n    Object.keys(childMappingRef.current).forEach(key => {\n      initialVisibility[key] = startState;\n    });\n    setItemsVisibility(initialVisibility);\n\n    // Animation loop: update visibility on each frame until complete\n    const tick = (now: number) => {\n      if (cancelled) {\n        return;\n      }\n      if (startTimeRef.current === null) {\n        startTimeRef.current = now;\n      }\n      const elapsed = now - (startTimeRef.current as number);\n\n      const childKeys = Object.keys(childMappingRef.current);\n      const itemCount = childKeys.length;\n\n      const result = staggerItemsVisibilityAtTime({\n        itemCount,\n        elapsed,\n        itemDelay,\n        itemDuration,\n        direction,\n        reversed: reversedRef.current,\n      });\n\n      // Convert boolean array to keyed object\n      const nextVisibility: Record<string, boolean> = {};\n      childKeys.forEach((key, idx) => {\n        nextVisibility[key] = result.itemsVisibility[idx];\n      });\n\n      setItemsVisibility(nextVisibility);\n\n      if (elapsed < result.totalDuration) {\n        frameRef.current = requestAnimationFrame(tick);\n      } else if (!finishedRef.current) {\n        finishedRef.current = true;\n        handleMotionFinish();\n      }\n    };\n\n    frameRef.current = requestAnimationFrame(tick);\n    return () => {\n      cancelled = true;\n      if (frameRef.current) {\n        cancelAnimationFrame();\n      }\n    };\n  }, [\n    animationKey,\n    itemDelay,\n    itemDuration,\n    direction,\n    requestAnimationFrame,\n    cancelAnimationFrame,\n    handleMotionFinish,\n  ]);\n\n  return { itemsVisibility };\n}\n"],"names":["React","useAnimationFrame","useEventCallback","staggerItemsVisibilityAtTime","DEFAULT_ITEM_DURATION","useStaggerItemsVisibility","childMapping","itemDelay","itemDuration","direction","reversed","onMotionFinish","hideMode","requestAnimationFrame","cancelAnimationFrame","handleMotionFinish","animationKey","setAnimationKey","useState","prevDirection","useRef","useEffect","current","prev","itemsVisibility","setItemsVisibility","initial","initialState","Object","keys","forEach","key","next","targetState","startTimeRef","frameRef","finishedRef","isFirstRender","childMappingRef","reversedRef","cancelled","startState","initialVisibility","tick","now","elapsed","childKeys","itemCount","length","result","nextVisibility","idx","totalDuration"],"mappings":"AAAA;AAEA,YAAYA,WAAW,QAAQ;AAC/B,SAASC,iBAAiB,EAAEC,gBAAgB,QAAQ,4BAA4B;AAEhF,SACEC,4BAA4B,EAE5BC,qBAAqB,QAEhB,UAAU;AASjB;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,SAASC,0BAA0B,EACxCC,YAAY,EACZC,SAAS,EACTC,eAAeJ,qBAAqB,EACpCK,SAAS,EACTC,WAAW,KAAK,EAChBC,cAAc,EACdC,WAAW,aAAa,EACQ;IAChC,MAAM,CAACC,uBAAuBC,qBAAqB,GAAGb;IAEtD,kFAAkF;IAClF,MAAMc,qBAAqBb,iBACzBS,2BAAAA,4BAAAA,iBACG;QACC;IACF;IAGJ,uDAAuD;IACvD,MAAM,CAACK,cAAcC,gBAAgB,GAAGjB,MAAMkB,QAAQ,CAAC;IACvD,MAAMC,gBAAgBnB,MAAMoB,MAAM,CAACX;IAEnC,uFAAuF;IACvFT,MAAMqB,SAAS,CAAC;QACd,IAAIF,cAAcG,OAAO,KAAKb,WAAW;YACvCQ,gBAAgBM,CAAAA,OAAQA,OAAO;YAC/BJ,cAAcG,OAAO,GAAGb;QAC1B;IACF,GAAG;QAACA;KAAU;IAEd,iDAAiD;IACjD,MAAM,CAACe,iBAAiBC,mBAAmB,GAAGzB,MAAMkB,QAAQ,CAA0B;QACpF,MAAMQ,UAAmC,CAAC;QAC1C,8EAA8E;QAC9E,MAAMC,eAAelB,cAAc;QACnCmB,OAAOC,IAAI,CAACvB,cAAcwB,OAAO,CAACC,CAAAA;YAChCL,OAAO,CAACK,IAAI,GAAGJ;QACjB;QACA,OAAOD;IACT;IAEA,sDAAsD;IACtD1B,MAAMqB,SAAS,CAAC;QACdI,mBAAmBF,CAAAA;YACjB,MAAMS,OAAgC,CAAC;YACvC,MAAMC,cAAcxB,cAAc;YAElC,uCAAuC;YACvCmB,OAAOC,IAAI,CAACvB,cAAcwB,OAAO,CAACC,CAAAA;gBAChC,IAAIA,OAAOR,MAAM;oBACf,gDAAgD;oBAChDS,IAAI,CAACD,IAAI,GAAGR,IAAI,CAACQ,IAAI;gBACvB,OAAO;oBACL,iCAAiC;oBACjCC,IAAI,CAACD,IAAI,GAAGE;gBACd;YACF;YAEA,kFAAkF;YAClF,oDAAoD;YAEpD,OAAOD;QACT;IACF,GAAG;QAAC1B;QAAcG;KAAU;IAE5B,qCAAqC;IACrC,MAAMyB,eAAelC,MAAMoB,MAAM,CAAgB;IACjD,MAAMe,WAAWnC,MAAMoB,MAAM,CAAgB;IAC7C,MAAMgB,cAAcpC,MAAMoB,MAAM,CAAC;IACjC,MAAMiB,gBAAgBrC,MAAMoB,MAAM,CAAC;IAEnC,uEAAuE;IACvE,MAAMkB,kBAAkBtC,MAAMoB,MAAM,CAACd;IAErC,8CAA8C;IAC9CN,MAAMqB,SAAS,CAAC;QACdiB,gBAAgBhB,OAAO,GAAGhB;IAC5B,GAAG;QAACA;KAAa;IAEjB,qEAAqE;IACrE,MAAMiC,cAAcvC,MAAMoB,MAAM,CAACV;IAEjC,0CAA0C;IAC1CV,MAAMqB,SAAS,CAAC;QACdkB,YAAYjB,OAAO,GAAGZ;IACxB,GAAG;QAACA;KAAS;IAEb,iCAAiC;IAEjCV,MAAMqB,SAAS,CAAC;QACd,IAAImB,YAAY;QAChBN,aAAaZ,OAAO,GAAG;QACvBc,YAAYd,OAAO,GAAG;QAEtB,yFAAyF;QACzF,IAAIe,cAAcf,OAAO,EAAE;YACzBe,cAAcf,OAAO,GAAG;YACxB,4EAA4E;YAC5EP;YACA,QAAQ,qCAAqC;QAC/C;QAEA,gFAAgF;QAChF,qEAAqE;QACrE,oEAAoE;QACpE,MAAM0B,aAAahC,cAAc;QACjC,2EAA2E;QAC3E,MAAMiC,oBAA6C,CAAC;QACpDd,OAAOC,IAAI,CAACS,gBAAgBhB,OAAO,EAAEQ,OAAO,CAACC,CAAAA;YAC3CW,iBAAiB,CAACX,IAAI,GAAGU;QAC3B;QACAhB,mBAAmBiB;QAEnB,iEAAiE;QACjE,MAAMC,OAAO,CAACC;YACZ,IAAIJ,WAAW;gBACb;YACF;YACA,IAAIN,aAAaZ,OAAO,KAAK,MAAM;gBACjCY,aAAaZ,OAAO,GAAGsB;YACzB;YACA,MAAMC,UAAUD,MAAOV,aAAaZ,OAAO;YAE3C,MAAMwB,YAAYlB,OAAOC,IAAI,CAACS,gBAAgBhB,OAAO;YACrD,MAAMyB,YAAYD,UAAUE,MAAM;YAElC,MAAMC,SAAS9C,6BAA6B;gBAC1C4C;gBACAF;gBACAtC;gBACAC;gBACAC;gBACAC,UAAU6B,YAAYjB,OAAO;YAC/B;YAEA,wCAAwC;YACxC,MAAM4B,iBAA0C,CAAC;YACjDJ,UAAUhB,OAAO,CAAC,CAACC,KAAKoB;gBACtBD,cAAc,CAACnB,IAAI,GAAGkB,OAAOzB,eAAe,CAAC2B,IAAI;YACnD;YAEA1B,mBAAmByB;YAEnB,IAAIL,UAAUI,OAAOG,aAAa,EAAE;gBAClCjB,SAASb,OAAO,GAAGT,sBAAsB8B;YAC3C,OAAO,IAAI,CAACP,YAAYd,OAAO,EAAE;gBAC/Bc,YAAYd,OAAO,GAAG;gBACtBP;YACF;QACF;QAEAoB,SAASb,OAAO,GAAGT,sBAAsB8B;QACzC,OAAO;YACLH,YAAY;YACZ,IAAIL,SAASb,OAAO,EAAE;gBACpBR;YACF;QACF;IACF,GAAG;QACDE;QACAT;QACAC;QACAC;QACAI;QACAC;QACAC;KACD;IAED,OAAO;QAAES;IAAgB;AAC3B"}

package/lib/choreography/Stagger/utils/constants.js

@@ -0,0 +1,5 @@
+/**
+ * Default timing constants for stagger animations (milliseconds).
+ */ import { motionTokens } from '@fluentui/react-motion';
+/** Default delay in milliseconds between each item's animation start */ export const DEFAULT_ITEM_DELAY = motionTokens.durationFaster;
+/** Default duration in milliseconds for each item's animation */ export const DEFAULT_ITEM_DURATION = motionTokens.durationNormal;

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/utils/constants.ts"],"sourcesContent":["/**\n * Default timing constants for stagger animations (milliseconds).\n */\n\nimport { motionTokens } from '@fluentui/react-motion';\n\n/** Default delay in milliseconds between each item's animation start */\nexport const DEFAULT_ITEM_DELAY = motionTokens.durationFaster;\n\n/** Default duration in milliseconds for each item's animation */\nexport const DEFAULT_ITEM_DURATION = motionTokens.durationNormal;\n"],"names":["motionTokens","DEFAULT_ITEM_DELAY","durationFaster","DEFAULT_ITEM_DURATION","durationNormal"],"mappings":"AAAA;;CAEC,GAED,SAASA,YAAY,QAAQ,yBAAyB;AAEtD,sEAAsE,GACtE,OAAO,MAAMC,qBAAqBD,aAAaE,cAAc,CAAC;AAE9D,+DAA+D,GAC/D,OAAO,MAAMC,wBAAwBH,aAAaI,cAAc,CAAC"}

package/lib/choreography/Stagger/utils/getStaggerChildMapping.js

@@ -0,0 +1,29 @@
+import * as React from 'react';
+/**
+ * Given `children`, return an object mapping key to child element and its index.
+ * This allows tracking individual items by identity (via React keys) rather than by position.
+ *
+ * Uses React.Children.toArray() which:
+ * - Automatically provides stable indices (0, 1, 2, ...)
+ * - Handles key normalization (e.g., 'a' → '.$a') consistently
+ * - Flattens fragments automatically
+ * - Generates keys for elements without explicit keys (e.g., '.0', '.1', '.2')
+ *
+ * @param children - React children to map
+ * @returns Object mapping child keys to { element, index }
+ */ // TODO: consider unifying with getChildMapping from react-motion package by making it generic
+export function getStaggerChildMapping(children) {
+    const childMapping = {};
+    if (children) {
+        React.Children.toArray(children).forEach((child, index)=>{
+            if (React.isValidElement(child)) {
+                var _child_key;
+                childMapping[(_child_key = child.key) !== null && _child_key !== void 0 ? _child_key : ''] = {
+                    element: child,
+                    index
+                };
+            }
+        });
+    }
+    return childMapping;
+}

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/choreography/Stagger/utils/getStaggerChildMapping.ts"],"sourcesContent":["import * as React from 'react';\n\nexport type StaggerChildMapping = Record<string, { element: React.ReactElement; index: number }>;\n\n/**\n * Given `children`, return an object mapping key to child element and its index.\n * This allows tracking individual items by identity (via React keys) rather than by position.\n *\n * Uses React.Children.toArray() which:\n * - Automatically provides stable indices (0, 1, 2, ...)\n * - Handles key normalization (e.g., 'a' → '.$a') consistently\n * - Flattens fragments automatically\n * - Generates keys for elements without explicit keys (e.g., '.0', '.1', '.2')\n *\n * @param children - React children to map\n * @returns Object mapping child keys to { element, index }\n */\n// TODO: consider unifying with getChildMapping from react-motion package by making it generic\nexport function getStaggerChildMapping(children: React.ReactNode | undefined): StaggerChildMapping {\n  const childMapping: StaggerChildMapping = {};\n\n  if (children) {\n    React.Children.toArray(children).forEach((child, index) => {\n      if (React.isValidElement(child)) {\n        childMapping[child.key ?? ''] = {\n          element: child,\n          index,\n        };\n      }\n    });\n  }\n\n  return childMapping;\n}\n"],"names":["React","getStaggerChildMapping","children","childMapping","Children","toArray","forEach","child","index","isValidElement","key","element"],"mappings":"AAAA,YAAYA,WAAW,QAAQ;AAI/B;;;;;;;;;;;;CAYC,GACD,8FAA8F;AAC9F,OAAO,SAASC,uBAAuBC,QAAqC;IAC1E,MAAMC,eAAoC,CAAC;IAE3C,IAAID,UAAU;QACZF,MAAMI,QAAQ,CAACC,OAAO,CAACH,UAAUI,OAAO,CAAC,CAACC,OAAOC;YAC/C,IAAIR,MAAMS,cAAc,CAACF,QAAQ;oBAClBA;gBAAbJ,YAAY,CAACI,CAAAA,aAAAA,MAAMG,GAAG,cAATH,wBAAAA,aAAa,GAAG,GAAG;oBAC9BI,SAASJ;oBACTC;gBACF;YACF;QACF;IACF;IAEA,OAAOL;AACT"}