feat(motion): add Blur presence motion component (#34839)

Co-authored-by: Oleksandr Fediashov <alexander.mcgarret@gmail.com>

Author: robertpenner

change/@fluentui-react-motion-components-preview-bf84c59d-8c3b-455f-b611-e483dee252d9.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat(motion): add Fade presence motion component",
+  "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

@@ -6,6 +6,9 @@
 
 import { PresenceComponent } from '@fluentui/react-motion';
 
+// @public
+export const Blur: PresenceComponent<BlurParams>;
+
 // @public
 export const Collapse: PresenceComponent<CollapseParams>;
 

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

@@ -0,0 +1,70 @@
+import { motionTokens } from '@fluentui/react-motion';
+import { blurAtom } from './blur-atom';
+
+describe('blurAtom', () => {
+  it('creates enter keyframes with blur from radius to 0', () => {
+    const atom = blurAtom({
+      direction: 'enter',
+      duration: 300,
+      easing: motionTokens.curveEasyEase,
+      fromRadius: '20px',
+    });
+
+    expect(atom).toMatchObject({
+      duration: 300,
+      easing: motionTokens.curveEasyEase,
+      keyframes: [{ filter: 'blur(20px)' }, { filter: 'blur(0px)' }],
+    });
+  });
+
+  it('creates exit keyframes with blur from 0 to radius', () => {
+    const atom = blurAtom({
+      direction: 'exit',
+      duration: 250,
+      easing: motionTokens.curveAccelerateMin,
+      fromRadius: '15px',
+    });
+
+    expect(atom).toMatchObject({
+      duration: 250,
+      easing: motionTokens.curveAccelerateMin,
+      keyframes: [{ filter: 'blur(0px)' }, { filter: 'blur(15px)' }],
+    });
+  });
+
+  it('uses default fromRadius when not provided', () => {
+    const atom = blurAtom({
+      direction: 'enter',
+      duration: 300,
+    });
+
+    expect(atom.keyframes).toEqual([{ filter: 'blur(10px)' }, { filter: 'blur(0px)' }]);
+  });
+
+  it('uses default easing when not provided', () => {
+    const atom = blurAtom({
+      direction: 'enter',
+      duration: 300,
+      fromRadius: '5px',
+    });
+
+    expect(atom.easing).toBe(motionTokens.curveLinear);
+  });
+
+  it('handles different CSS units for fromRadius', () => {
+    const atomPx = blurAtom({
+      direction: 'enter',
+      duration: 300,
+      fromRadius: '8px',
+    });
+
+    const atomRem = blurAtom({
+      direction: 'enter',
+      duration: 300,
+      fromRadius: '1rem',
+    });
+
+    expect(atomPx.keyframes[0]).toEqual({ filter: 'blur(8px)' });
+    expect(atomRem.keyframes[0]).toEqual({ filter: 'blur(1rem)' });
+  });
+});

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

@@ -0,0 +1,33 @@
+import { AtomMotion, PresenceDirection, motionTokens } from '@fluentui/react-motion';
+
+interface BlurAtomParams {
+  direction: PresenceDirection;
+  duration: number;
+  easing?: string;
+  fromRadius?: string;
+}
+
+/**
+ * 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 '20px'.
+ * @returns A motion atom object with filter blur keyframes and the supplied duration and easing.
+ */
+export const blurAtom = ({
+  direction,
+  duration,
+  easing = motionTokens.curveLinear,
+  fromRadius = '10px',
+}: BlurAtomParams): AtomMotion => {
+  const keyframes = [{ filter: `blur(${fromRadius})` }, { filter: 'blur(0px)' }];
+  if (direction === 'exit') {
+    keyframes.reverse();
+  }
+  return {
+    keyframes,
+    duration,
+    easing,
+  };
+};

packages/react-components/react-motion-components-preview/library/src/components/Blur/Blur.test.ts

@@ -0,0 +1,12 @@
+import { expectPresenceMotionFunction, expectPresenceMotionArray } from '../../testing/testUtils';
+import { Blur } from './Blur';
+
+describe('Blur', () => {
+  it('stores its motion definition as a static function', () => {
+    expectPresenceMotionFunction(Blur);
+  });
+
+  it('generates a motion definition from the static function', () => {
+    expectPresenceMotionArray(Blur);
+  });
+});

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

@@ -0,0 +1,47 @@
+import { motionTokens, createPresenceComponent, PresenceMotionFn } from '@fluentui/react-motion';
+import { fadeAtom } from '../../atoms/fade-atom';
+import { blurAtom } from '../../atoms/blur-atom';
+import { BlurParams } from './blur-types';
+
+/**
+ * Define a presence motion for blur in/out
+ *
+ * @param fromRadius - The radius of pixels to blend into the blur. A length string, defaulting to '10px'.
+ * @param duration - Time (ms) for the enter transition (blur-in). Defaults to the `durationSlow` value (300 ms).
+ * @param easing - Easing curve for the enter transition (blur-in). Defaults to the `curveDecelerateMin` value.
+ * @param exitDuration - Time (ms) for the exit transition (blur-out). Defaults to the enter duration.
+ * @param exitEasing - Easing curve for the exit transition (blur-out). Defaults to the `curveAccelerateMin` value.
+ * @param animateOpacity - Whether to animate the opacity. Defaults to `true`.
+ */
+const blurPresenceFn: PresenceMotionFn<BlurParams> = ({
+  fromRadius = '10px',
+  duration = motionTokens.durationSlow,
+  easing = motionTokens.curveDecelerateMin,
+  exitDuration = duration,
+  exitEasing = motionTokens.curveAccelerateMin,
+  animateOpacity = true,
+}) => {
+  const enterAtoms = [blurAtom({ direction: 'enter', duration, easing, fromRadius })];
+  const exitAtoms = [
+    blurAtom({
+      direction: 'exit',
+      duration: exitDuration,
+      easing: exitEasing,
+      fromRadius,
+    }),
+  ];
+
+  // Only add fade atoms if animateOpacity is true.
+  if (animateOpacity) {
+    enterAtoms.push(fadeAtom({ direction: 'enter', duration, easing }));
+    exitAtoms.push(fadeAtom({ direction: 'exit', duration: exitDuration, easing: exitEasing }));
+  }
+
+  return {
+    enter: enterAtoms,
+    exit: exitAtoms,
+  };
+};
+
+/** A React component that applies blur in/out transitions to its children. */
+export const Blur = createPresenceComponent(blurPresenceFn);

packages/react-components/react-motion-components-preview/library/src/components/Blur/blur-types.ts

@@ -0,0 +1,8 @@
+import type { PresenceDuration, PresenceEasing, AnimateOpacity } from '../../types';
+
+export type BlurParams = PresenceDuration &
+  PresenceEasing &
+  AnimateOpacity & {
+    /** The radius of pixels to blend into the blur. A length string, defaulting to '20px'. */
+    fromRadius?: string;
+  };

packages/react-components/react-motion-components-preview/library/src/components/Blur/index.ts

@@ -0,0 +1,2 @@
+export { Blur } from './Blur';
+export type { BlurParams } from './blur-types';

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

@@ -69,7 +69,17 @@ function createCollapseAtoms({
   };
 }
 
-/** Define a presence motion for collapse/expand */
+/**
+ * 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,
@@ -94,7 +104,21 @@ const collapsePresenceFn: PresenceMotionFn<CollapseParams> = ({
   });
 };
 
-/** Define a presence motion for collapse/expand that can stagger the size and opacity motions by a given delay */
+/**
+ * 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,

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

@@ -1,27 +1,15 @@
+import type { PresenceDuration, PresenceEasing, AnimateOpacity } from '../../types';
+
 export type CollapseOrientation = 'horizontal' | 'vertical';
 
 /** Common properties shared by all collapse components */
-type CollapseBaseParams = {
-  /** Easing curve for the enter transition. Defaults to the `curveEasyEaseMax` value. */
-  easing?: string;
-
-  /** Easing curve for the exit transition. Defaults to the `easing` param for symmetry. */
-  exitEasing?: string;
+type CollapseBaseParams = PresenceEasing &
+  AnimateOpacity & {
+    /** The orientation of the size animation. Defaults to `'vertical'` to expand/collapse the height. */
+    orientation?: CollapseOrientation;
+  };
 
-  /** The orientation of the size animation. Defaults to `'vertical'` to expand/collapse the height. */
-  orientation?: CollapseOrientation;
-
-  /** Whether to animate the opacity. Defaults to `true`. */
-  animateOpacity?: boolean;
-};
-
-export type CollapseParams = CollapseBaseParams & {
-  /** Time (ms) for the enter transition (expand). Defaults to the `durationNormal` value (200 ms). */
-  duration?: number;
-
-  /** Time (ms) for the exit transition (collapse). Defaults to the `duration` param for symmetry. */
-  exitDuration?: number;
-};
+export type CollapseParams = CollapseBaseParams & PresenceDuration;
 
 export type CollapseDelayedParams = CollapseBaseParams & {
   /** Time (ms) for the size expand. Defaults to the `durationNormal` value (200 ms). */