feat(motion): add extended support for reduced motion

Author: layershifter

change/@fluentui-react-motion-f4c1433b-f36e-4b2c-a9bd-9b16f37489fc.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add extended support for reduced motion",
+  "packageName": "@fluentui/react-motion",
+  "email": "olfedias@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-motion/library/src/hooks/useAnimateAtoms.test.tsx

@@ -0,0 +1,84 @@
+import { renderHook } from '@testing-library/react-hooks';
+
+import type { AtomMotion } from '../types';
+import { DEFAULT_ANIMATION_OPTIONS, useAnimateAtoms } from './useAnimateAtoms';
+
+function createElementMock() {
+  const animate = jest.fn().mockReturnValue({
+    persist: jest.fn(),
+  });
+
+  return [{ animate } as unknown as HTMLElement, animate] as const;
+}
+
+const DEFAULT_KEYFRAMES = [{ transform: 'rotate(0)' }, { transform: 'rotate(180deg)' }];
+const REDUCED_MOTION_KEYFRAMES = [{ opacity: 0 }, { opacity: 1 }];
+
+describe('useAnimateAtoms', () => {
+  beforeEach(() => {
+    // We set production environment to avoid testing the mock implementation
+    process.env.NODE_ENV = 'production';
+  });
+
+  it('should return a function', () => {
+    const { result } = renderHook(() => useAnimateAtoms());
+
+    expect(result.current).toBeInstanceOf(Function);
+  });
+
+  describe('reduce motion', () => {
+    it('calls ".animate()" with regular motion', () => {
+      const { result } = renderHook(() => useAnimateAtoms());
+
+      const [element, animateMock] = createElementMock();
+      const motion: AtomMotion = { keyframes: DEFAULT_KEYFRAMES };
+
+      result.current(element, motion, { isReducedMotion: false });
+
+      expect(animateMock).toHaveBeenCalledTimes(1);
+      expect(animateMock).toHaveBeenCalledWith(DEFAULT_KEYFRAMES, { ...DEFAULT_ANIMATION_OPTIONS });
+    });
+
+    it('calls ".animate()" with shortened duration (1ms) when reduced motion is enabled', () => {
+      const { result } = renderHook(() => useAnimateAtoms());
+
+      const [element, animateMock] = createElementMock();
+      const motion: AtomMotion = { keyframes: DEFAULT_KEYFRAMES };
+
+      result.current(element, motion, { isReducedMotion: true });
+
+      expect(animateMock).toHaveBeenCalledTimes(1);
+      expect(animateMock).toHaveBeenCalledWith(DEFAULT_KEYFRAMES, { ...DEFAULT_ANIMATION_OPTIONS, duration: 1 });
+    });
+
+    it('calls ".animate()" with specified reduced motion params when reduced motion is enabled', () => {
+      const { result } = renderHook(() => useAnimateAtoms());
+
+      const [element, animateMock] = createElementMock();
+      const motion: AtomMotion = {
+        keyframes: DEFAULT_KEYFRAMES,
+        reducedMotion: { duration: 100 },
+      };
+
+      result.current(element, motion, { isReducedMotion: true });
+
+      expect(animateMock).toHaveBeenCalledTimes(1);
+      expect(animateMock).toHaveBeenCalledWith(DEFAULT_KEYFRAMES, { ...DEFAULT_ANIMATION_OPTIONS, duration: 100 });
+    });
+
+    it('calls ".animate()" with specified reduced motion keyframes when reduced motion is enabled', () => {
+      const { result } = renderHook(() => useAnimateAtoms());
+
+      const [element, animateMock] = createElementMock();
+      const motion: AtomMotion = {
+        keyframes: DEFAULT_KEYFRAMES,
+        reducedMotion: { keyframes: REDUCED_MOTION_KEYFRAMES },
+      };
+
+      result.current(element, motion, { isReducedMotion: true });
+
+      expect(animateMock).toHaveBeenCalledTimes(1);
+      expect(animateMock).toHaveBeenCalledWith(REDUCED_MOTION_KEYFRAMES, { ...DEFAULT_ANIMATION_OPTIONS, duration: 1 });
+    });
+  });
+});

packages/react-components/react-motion/library/src/hooks/useAnimateAtoms.ts

@@ -1,6 +1,10 @@
 import * as React from 'react';
 import type { AnimationHandle, AtomMotion } from '../types';
 
+export const DEFAULT_ANIMATION_OPTIONS: KeyframeEffectOptions = {
+  fill: 'forwards',
+};
+
 function useAnimateAtomsInSupportedEnvironment() {
   return React.useCallback(
     (
@@ -14,13 +18,19 @@ function useAnimateAtomsInSupportedEnvironment() {
       const { isReducedMotion } = options;
 
       const animations = atoms.map(motion => {
-        const { keyframes, ...params } = motion;
-        const animation = element.animate(keyframes, {
-          fill: 'forwards',
+        const { keyframes, reducedMotion, ...params } = motion;
+        const { keyframes: reducedMotionKeyframes = keyframes, ...reducedMotionParams } = reducedMotion ?? {};
 
+        const animationKeyframes: Keyframe[] = isReducedMotion ? reducedMotionKeyframes : keyframes;
+        const animationParams: KeyframeEffectOptions = {
+          ...DEFAULT_ANIMATION_OPTIONS,
           ...params,
+
           ...(isReducedMotion && { duration: 1 }),
-        });
+          ...(isReducedMotion && reducedMotionParams),
+        };
+
+        const animation = element.animate(animationKeyframes, animationParams);
 
         animation.persist();
 

packages/react-components/react-motion/library/src/types.ts

@@ -1,4 +1,15 @@
-export type AtomMotion = { keyframes: Keyframe[] } & KeyframeEffectOptions;
+export type AtomMotion = { keyframes: Keyframe[] } & KeyframeEffectOptions & {
+    /**
+     * Allows to specify a reduced motion version of the animation. If provided, the settings will be used when the
+     * user has enabled the reduced motion setting in the operating system. By default, the duration of the animation is
+     * set to 1ms.
+     *
+     * Note, if keyframes are provided, they will be used instead of the regular keyframes.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+     */
+    reducedMotion?: { keyframes?: Keyframe[] } & KeyframeEffectOptions;
+  };
 
 export type PresenceDirection = 'enter' | 'exit';
 

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentDefault.stories.tsx

@@ -41,6 +41,10 @@ const FadeEnter = createMotionComponent({
   keyframes: [{ opacity: 0 }, { opacity: 1 }],
   duration: motionTokens.durationSlow,
   iterations: Infinity,
+
+  reducedMotion: {
+    iterations: 1,
+  },
 });
 
 export const CreateMotionComponentDefault = (props: MotionComponentProps) => {

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentFactory.stories.tsx

@@ -45,6 +45,10 @@ const DropIn = createMotionComponent({
   ],
   duration: 4000,
   iterations: Infinity,
+
+  reducedMotion: {
+    iterations: 1,
+  },
 });
 
 export const CreateMotionComponentFactory = () => {

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentFunctionParams.stories.tsx

@@ -81,6 +81,10 @@ const Scale = createMotionComponent<{ startFrom?: number }>(({ startFrom = 0.5 }
     ],
     duration: motionTokens.durationUltraSlow,
     iterations: Infinity,
+
+    reducedMotion: {
+      iterations: 1,
+    },
   };
 });
 

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentFunctions.stories.tsx

@@ -68,6 +68,10 @@ const Grow = createMotionComponent(({ element }) => ({
     { opacity: 0, maxHeight: `${element.scrollHeight / 2}px` },
   ],
   iterations: Infinity,
+
+  reducedMotion: {
+    iterations: 1,
+  },
 }));
 
 export const CreateMotionComponentFunctions = () => {

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentImperativeRefPlayState.stories.tsx

@@ -66,6 +66,10 @@ const FadeEnter = createMotionComponent({
   keyframes: [{ opacity: 0 }, { opacity: 1 }],
   duration: motionTokens.durationSlow,
   iterations: Infinity,
+
+  reducedMotion: {
+    iterations: 1,
+  },
 });
 
 export const CreateMotionComponentImperativeRefPlayState = () => {

packages/react-components/react-motion/stories/src/CreateMotionComponent/CreateMotionComponentTokensUsage.stories.tsx

@@ -45,6 +45,10 @@ const BackgroundChange = createMotionComponent({
   ],
   duration: 3000,
   iterations: Infinity,
+
+  reducedMotion: {
+    iterations: 1,
+  },
 });
 
 export const CreateMotionComponentTokensUsage = () => {