refactor(Collapse): simplify parameters and add tests (#35262)

Author: robertpenner

change/@fluentui-react-motion-components-preview-0772213f-2594-47a8-909f-f05cf42a3c3f.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "refactor(Collapse): simplify parameter types",
+  "packageName": "@fluentui/react-motion-components-preview",
+  "email": "robertpenner@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-motion-components-preview/library/etc/react-motion-components-preview.api.md

@@ -3,38 +3,38 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+
 import { PresenceComponent } from '@fluentui/react-motion';
 
 // @public
 export const Blur: PresenceComponent<BlurParams>;
 
 // @public (undocumented)
-export type BlurParams = BasePresenceParams &
-  AnimateOpacity & {
+export type BlurParams = BasePresenceParams & AnimateOpacity & {
     fromRadius?: string;
-  };
+};
 
 // @public
 export const Collapse: PresenceComponent<CollapseParams>;
 
 // @public
-export const CollapseDelayed: PresenceComponent<CollapseDelayedParams>;
+export const CollapseDelayed: PresenceComponent<CollapseParams>;
 
-// @public (undocumented)
-export type CollapseDelayedParams = CollapseBaseParams & {
-  sizeDuration?: number;
-  opacityDuration?: number;
-  exitSizeDuration?: number;
-  exitOpacityDuration?: number;
-  delay?: number;
-  exitDelay?: number;
+// @public
+export type CollapseDurations = {
+    sizeDuration?: number;
+    opacityDuration?: number;
+    exitSizeDuration?: number;
+    exitOpacityDuration?: number;
 };
 
 // @public (undocumented)
-export type CollapseParams = BasePresenceParams &
-  AnimateOpacity & {
+export type CollapseParams = BasePresenceParams & AnimateOpacity & CollapseDurations & {
     orientation?: CollapseOrientation;
-  };
+    fromSize?: string;
+    staggerDelay?: number;
+    exitStaggerDelay?: number;
+};
 
 // @public (undocumented)
 export const CollapseRelaxed: PresenceComponent<CollapseParams>;
@@ -58,21 +58,19 @@ export const FadeSnappy: PresenceComponent<BasePresenceParams>;
 export const Rotate: PresenceComponent<RotateParams>;
 
 // @public (undocumented)
-export type RotateParams = BasePresenceParams &
-  AnimateOpacity & {
+export type RotateParams = BasePresenceParams & AnimateOpacity & {
     axis?: Axis3D;
     angle?: number;
     exitAngle?: number;
-  };
+};
 
 // @public
 export const Scale: PresenceComponent<ScaleParams>;
 
 // @public (undocumented)
-export type ScaleParams = BasePresenceParams &
-  AnimateOpacity & {
+export type ScaleParams = BasePresenceParams & AnimateOpacity & {
     fromScale?: number;
-  };
+};
 
 // @public (undocumented)
 export const ScaleRelaxed: PresenceComponent<ScaleParams>;
@@ -84,11 +82,10 @@ export const ScaleSnappy: PresenceComponent<ScaleParams>;
 export const Slide: PresenceComponent<SlideParams>;
 
 // @public (undocumented)
-export type SlideParams = BasePresenceParams &
-  AnimateOpacity & {
+export type SlideParams = BasePresenceParams & AnimateOpacity & {
     fromX?: string;
     fromY?: string;
-  };
+};
 
 // @public (undocumented)
 export const SlideRelaxed: PresenceComponent<SlideParams>;
@@ -97,4 +94,5 @@ export const SlideRelaxed: PresenceComponent<SlideParams>;
 export const SlideSnappy: PresenceComponent<SlideParams>;
 
 // (No @packageDocumentation comment for this package)
+
 ```

packages/react-components/react-motion-components-preview/library/src/atoms/blur-atom.ts

@@ -11,6 +11,7 @@ interface BlurAtomParams extends BaseAtomParams {
  * @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 '20px'.
+ * @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 const blurAtom = ({

packages/react-components/react-motion-components-preview/library/src/atoms/rotate-atom.ts

@@ -22,6 +22,7 @@ const createRotateValue = (axis: Axis3D, angle: number): string => {
  * @param axis - The axis of rotation: 'x', 'y', or 'z'. Defaults to 'y'.
  * @param angle - The starting rotation angle in degrees. Defaults to -90.
  * @param exitAngle - The ending rotation angle in degrees. Defaults to the negation of `angle`.
+ * @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 const rotateAtom = ({

packages/react-components/react-motion-components-preview/library/src/atoms/scale-atom.ts

@@ -13,6 +13,7 @@ interface ScaleAtomParams extends BaseAtomParams {
  * @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 const scaleAtom = ({

packages/react-components/react-motion-components-preview/library/src/atoms/slide-atom.ts

@@ -13,6 +13,7 @@ interface SlideAtomParams extends BaseAtomParams {
  * @param easing - The easing curve for the motion. Defaults to `motionTokens.curveLinear`.
  * @param fromX - The starting X translate value with units (e.g., '0px', '100%'). Defaults to '0px'.
  * @param fromY - The starting Y translate value with units (e.g., '-20px', '100%'). 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 const slideAtom = ({

packages/react-components/react-motion-components-preview/library/src/components/Collapse/Collapse.ts

@@ -5,146 +5,101 @@ import {
   createPresenceComponentVariant,
   AtomMotion,
 } from '@fluentui/react-motion';
-import type { CollapseDelayedParams, CollapseParams } from './collapse-types';
+import type { CollapseParams } from './collapse-types';
 import { sizeEnterAtom, sizeExitAtom, whitespaceAtom } from './collapse-atoms';
 import { fadeAtom } from '../../atoms/fade-atom';
 
-/** Internal helper to create collapse atoms with shared logic */
-function createCollapseAtoms({
+/**
+ * Define a presence motion for collapse/expand
+ *
+ * @param element - The element to apply the collapse motion to
+ * @param duration - Time (ms) for the enter transition (expand). Defaults to the `durationNormal` value (200 ms)
+ * @param easing - Easing curve for the enter transition. Defaults to the `curveEasyEaseMax` value
+ * @param delay - Time (ms) to delay the entire enter transition. Defaults to 0
+ * @param exitDuration - Time (ms) for the exit transition (collapse). Defaults to the `duration` param for symmetry
+ * @param exitEasing - Easing curve for the exit transition. Defaults to the `easing` param for symmetry
+ * @param exitDelay - Time (ms) to delay the entire exit transition. Defaults to the `delay` param for symmetry
+ * @param staggerDelay - Time (ms) offset between the size and opacity animations. Defaults to 0
+ * @param exitStaggerDelay - Time (ms) offset between the size and opacity animations on exit. Defaults to the `staggerDelay` param for symmetry
+ * @param sizeDuration - Time (ms) for the size animation during enter. Defaults to `duration` for unified timing
+ * @param opacityDuration - Time (ms) for the opacity animation during enter. Defaults to `sizeDuration` for synchronized timing
+ * @param exitSizeDuration - Time (ms) for the size animation during exit. Defaults to `exitDuration` for unified timing
+ * @param exitOpacityDuration - Time (ms) for the opacity animation during exit. Defaults to `exitSizeDuration` for synchronized timing
+ * @param animateOpacity - Whether to animate the opacity. Defaults to `true`
+ * @param orientation - The orientation of the size animation. Defaults to `'vertical'` to expand/collapse the height
+ * @param fromSize - The starting size for the expand animation. Defaults to `'0px'`
+ */
+const collapsePresenceFn: PresenceMotionFn<CollapseParams> = ({
   element,
-  orientation,
-  animateOpacity,
+  // Primary duration controls (simple API)
+  duration = motionTokens.durationNormal,
+  exitDuration = duration,
 
-  // Enter params
-  sizeDuration,
+  // Granular duration controls with smart defaults (advanced API)
+  sizeDuration = duration,
   opacityDuration = sizeDuration,
-  easing,
-  delay,
-
-  // Exit params
-  exitSizeDuration,
+  exitSizeDuration = exitDuration,
   exitOpacityDuration = exitSizeDuration,
-  exitEasing,
-  exitDelay,
-}: {
-  element: HTMLElement;
-} & Required<CollapseDelayedParams>) {
+
+  // Other timing controls
+  easing = motionTokens.curveEasyEaseMax,
+  delay = 0,
+  exitEasing = easing,
+  exitDelay = delay,
+  staggerDelay = 0,
+  exitStaggerDelay = staggerDelay,
+
+  // Animation controls
+  animateOpacity = true,
+  orientation = 'vertical',
+  fromSize = '0px',
+}) => {
   // ----- ENTER -----
   // The enter transition is an array of up to 3 motion atoms: size, whitespace and opacity.
+  // For enter: size expands first, then opacity fades in after staggerDelay
   const enterAtoms: AtomMotion[] = [
-    sizeEnterAtom({ orientation, duration: sizeDuration, easing, element }),
-    whitespaceAtom({ direction: 'enter', orientation, duration: sizeDuration, easing }),
+    // Apply global delay to size atom - size expansion starts first
+    sizeEnterAtom({ orientation, duration: sizeDuration, easing, element, fromSize, delay }),
+    whitespaceAtom({ direction: 'enter', orientation, duration: sizeDuration, easing, delay }),
   ];
   // Fade in only if animateOpacity is true. Otherwise, leave opacity unaffected.
   if (animateOpacity) {
-    enterAtoms.push({
-      ...fadeAtom({ direction: 'enter', duration: opacityDuration, easing }),
-      delay,
-      fill: 'both',
-    });
+    enterAtoms.push(fadeAtom({ direction: 'enter', duration: opacityDuration, easing, delay: delay + staggerDelay }));
   }
 
   // ----- EXIT -----
   // The exit transition is an array of up to 3 motion atoms: opacity, size and whitespace.
+  // For exit: opacity fades out first, then size collapses after exitStaggerDelay
   const exitAtoms: AtomMotion[] = [];
   // Fade out only if animateOpacity is true. Otherwise, leave opacity unaffected.
   if (animateOpacity) {
-    exitAtoms.push(fadeAtom({ direction: 'exit', duration: exitOpacityDuration, easing: exitEasing }));
+    exitAtoms.push(
+      fadeAtom({ direction: 'exit', duration: exitOpacityDuration, easing: exitEasing, delay: exitDelay }),
+    );
   }
 
   exitAtoms.push(
-    sizeExitAtom({ orientation, duration: exitSizeDuration, easing: exitEasing, element, delay: exitDelay }),
+    sizeExitAtom({
+      orientation,
+      duration: exitSizeDuration,
+      easing: exitEasing,
+      element,
+      delay: exitDelay + exitStaggerDelay,
+      fromSize,
+    }),
     whitespaceAtom({
       direction: 'exit',
       orientation,
       duration: exitSizeDuration,
       easing: exitEasing,
-      delay: exitDelay,
+      delay: exitDelay + exitStaggerDelay, // Size/whitespace collapse after opacity finishes fading out
     }),
   );
 
   return {
     enter: enterAtoms,
     exit: exitAtoms,
   };
-}
-
-/**
- * Define a presence motion for collapse/expand
- *
- * @param element - The element to apply the collapse motion to
- * @param duration - Time (ms) for the enter transition (expand). Defaults to the `durationNormal` value (200 ms)
- * @param easing - Easing curve for the enter transition. Defaults to the `curveEasyEaseMax` value
- * @param exitDuration - Time (ms) for the exit transition (collapse). Defaults to the `duration` param for symmetry
- * @param exitEasing - Easing curve for the exit transition. Defaults to the `easing` param for symmetry
- * @param animateOpacity - Whether to animate the opacity. Defaults to `true`
- * @param orientation - The orientation of the size animation. Defaults to `'vertical'` to expand/collapse the height
- */
-const collapsePresenceFn: PresenceMotionFn<CollapseParams> = ({
-  element,
-  duration = motionTokens.durationNormal,
-  easing = motionTokens.curveEasyEaseMax,
-  exitDuration = duration,
-  exitEasing = easing,
-  animateOpacity = true,
-  orientation = 'vertical',
-}) => {
-  return createCollapseAtoms({
-    element,
-    orientation,
-    animateOpacity,
-    sizeDuration: duration,
-    opacityDuration: duration,
-    easing,
-    exitSizeDuration: exitDuration,
-    exitOpacityDuration: exitDuration,
-    exitEasing,
-    delay: 0,
-    exitDelay: 0,
-  });
-};
-
-/**
- * Define a presence motion for collapse/expand that can stagger the size and opacity motions by a given delay
- *
- * @param element - The element to apply the collapse motion to
- * @param sizeDuration - Time (ms) for the size expand. Defaults to the `durationNormal` value (200 ms)
- * @param opacityDuration - Time (ms) for the fade-in. Defaults to the `durationSlower` value (400 ms)
- * @param easing - Easing curve for the enter transition. Defaults to the `curveEasyEase` value
- * @param delay - Time (ms) between the size expand start and the fade-in start. Defaults to the `durationNormal` value (200 ms)
- * @param exitSizeDuration - Time (ms) for the size collapse. Defaults to the `sizeDuration` param for temporal symmetry
- * @param exitOpacityDuration - Time (ms) for the fade-out. Defaults to the `opacityDuration` param for temporal symmetry
- * @param exitEasing - Easing curve for the exit transition. Defaults to the `easing` param for symmetry
- * @param exitDelay - Time (ms) between the fade-out start and the size collapse start. Defaults to the `durationSlower` value (400 ms)
- * @param animateOpacity - Whether to animate the opacity. Defaults to `true`
- * @param orientation - The orientation of the size animation. Defaults to `'vertical'` to expand/collapse the height
- */
-const collapseDelayedPresenceFn: PresenceMotionFn<CollapseDelayedParams> = ({
-  element,
-  sizeDuration = motionTokens.durationNormal,
-  opacityDuration = motionTokens.durationSlower,
-  easing = motionTokens.curveEasyEase,
-  delay = motionTokens.durationNormal,
-  exitSizeDuration = sizeDuration,
-  exitOpacityDuration = opacityDuration,
-  exitEasing = easing,
-  exitDelay = motionTokens.durationSlower,
-  animateOpacity = true,
-  orientation = 'vertical',
-}) => {
-  return createCollapseAtoms({
-    element,
-    orientation,
-    animateOpacity,
-    sizeDuration,
-    opacityDuration,
-    easing,
-    delay,
-    exitSizeDuration,
-    exitOpacityDuration,
-    exitEasing,
-    exitDelay,
-  });
 };
 
 /** A React component that applies collapse/expand transitions to its children. */
@@ -159,4 +114,18 @@ export const CollapseRelaxed = createPresenceComponentVariant(Collapse, {
 });
 
 /** A React component that applies collapse/expand transitions with delayed fade to its children. */
-export const CollapseDelayed = createPresenceComponent(collapseDelayedPresenceFn);
+export const CollapseDelayed = createPresenceComponentVariant(Collapse, {
+  // Enter timing per motion design spec
+  sizeDuration: motionTokens.durationNormal, // 200ms
+  opacityDuration: motionTokens.durationSlower, // 400ms
+  staggerDelay: motionTokens.durationNormal, // 200ms
+
+  // Exit timing per motion design spec
+  exitSizeDuration: motionTokens.durationNormal, // 200ms
+  exitOpacityDuration: motionTokens.durationSlower, // 400ms
+  exitStaggerDelay: motionTokens.durationSlower, // 400ms
+
+  // Easing per motion design spec
+  easing: motionTokens.curveEasyEase,
+  exitEasing: motionTokens.curveEasyEase,
+});