feat(react-motion): implement interruptible motions [experimental] (#33994)

Author: layershifter

change/@fluentui-react-motion-24284c59-9a62-4f23-9c8e-4aca459271e5.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: experimental createInterruptablePresence()",
+  "packageName": "@fluentui/react-motion",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-motion/library/src/factories/createPresenceComponent.ts

@@ -7,7 +7,14 @@ import { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';
 import { useMountedState } from '../hooks/useMountedState';
 import { useIsReducedMotion } from '../hooks/useIsReducedMotion';
 import { getChildElement } from '../utils/getChildElement';
-import type { MotionParam, PresenceMotion, MotionImperativeRef, PresenceMotionFn, PresenceDirection } from '../types';
+import type {
+  MotionParam,
+  PresenceMotion,
+  MotionImperativeRef,
+  PresenceMotionFn,
+  PresenceDirection,
+  AnimationHandle,
+} from '../types';
 import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
 
 /**
@@ -72,6 +79,8 @@ export type PresenceComponent<MotionParams extends Record<string, MotionParam> =
   [MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
 };
 
+const INTERRUPTABLE_MOTION_SYMBOL = Symbol.for('interruptablePresence');
+
 export function createPresenceComponent<MotionParams extends Record<string, MotionParam> = {}>(
   value: PresenceMotion | PresenceMotionFn<MotionParams>,
 ): PresenceComponent<MotionParams> {
@@ -143,8 +152,40 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
             return;
           }
 
+          let handle: AnimationHandle | undefined;
+
+          function cleanup() {
+            if (!handle) {
+              return;
+            }
+
+            // Heads up!
+            //
+            // If the animation is interruptible & is running, we don't want to cancel it as it will be reversed in
+            // the next effect.
+            if (IS_EXPERIMENTAL_INTERRUPTIBLE_MOTION && handle.isRunning()) {
+              return;
+            }
+
+            handle.cancel();
+            handleRef.current = undefined;
+          }
+
           const presenceMotion =
             typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : (value as PresenceMotion);
+          const IS_EXPERIMENTAL_INTERRUPTIBLE_MOTION = (
+            presenceMotion as PresenceMotion & { [INTERRUPTABLE_MOTION_SYMBOL]?: boolean }
+          )[INTERRUPTABLE_MOTION_SYMBOL];
+
+          if (IS_EXPERIMENTAL_INTERRUPTIBLE_MOTION) {
+            handle = handleRef.current;
+
+            if (handle && handle.isRunning()) {
+              handle.reverse();
+
+              return cleanup;
+            }
+          }
 
           const atoms = visible ? presenceMotion.enter : presenceMotion.exit;
           const direction: PresenceDirection = visible ? 'enter' : 'exit';
@@ -158,13 +199,14 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
             handleMotionStart(direction);
           }
 
-          const handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });
+          handle = animateAtoms(element, atoms, { isReducedMotion: isReducedMotion() });
 
           if (applyInitialStyles) {
             // Heads up!
             // .finish() is used in this case to skip animation and apply animation styles immediately
             handle.finish();
-            return;
+
+            return cleanup;
           }
 
           handleRef.current = handle;
@@ -177,9 +219,7 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
             handle.finish();
           }
 
-          return () => {
-            handle.cancel();
-          };
+          return cleanup;
         },
         // Excluding `isFirstMount` from deps to prevent re-triggering the animation on subsequent renders
         // eslint-disable-next-line react-hooks/exhaustive-deps

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

@@ -1,4 +1,6 @@
 import * as React from 'react';
+
+import { isAnimationRunning } from '../utils/isAnimationRunning';
 import type { AnimationHandle, AtomMotion } from '../types';
 
 export const DEFAULT_ANIMATION_OPTIONS: KeyframeEffectOptions = {
@@ -78,6 +80,9 @@ function useAnimateAtomsInSupportedEnvironment() {
               oncancel();
             });
         },
+        isRunning() {
+          return animations.some(animation => isAnimationRunning(animation));
+        },
 
         cancel: () => {
           animations.forEach(animation => {
@@ -99,6 +104,18 @@ function useAnimateAtomsInSupportedEnvironment() {
             animation.finish();
           });
         },
+        reverse: () => {
+          // Heads up!
+          //
+          // This is used for the interruptible motion. If the animation is running, we need to reverse it.
+          //
+          // TODO: what do with animations that have "delay"?
+          // TODO: what do with animations that have different "durations"?
+
+          animations.forEach(animation => {
+            animation.reverse();
+          });
+        },
       };
     },
     [SUPPORTS_PERSIST],
@@ -148,6 +165,10 @@ function useAnimateAtomsInTestEnvironment() {
         set playbackRate(rate: number) {
           /* no-op */
         },
+        isRunning() {
+          return false;
+        },
+
         cancel() {
           /* no-op */
         },
@@ -160,6 +181,9 @@ function useAnimateAtomsInTestEnvironment() {
         finish() {
           /* no-op */
         },
+        reverse() {
+          /* no-op */
+        },
       };
     },
     [realAnimateAtoms],

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

@@ -31,8 +31,9 @@ export type PresenceMotionFn<MotionParams extends Record<string, MotionParam> =
 
 // ---
 
-export type AnimationHandle = Pick<Animation, 'cancel' | 'finish' | 'pause' | 'play' | 'playbackRate'> & {
+export type AnimationHandle = Pick<Animation, 'cancel' | 'finish' | 'pause' | 'play' | 'playbackRate' | 'reverse'> & {
   setMotionEndCallbacks: (onfinish: () => void, oncancel: () => void) => void;
+  isRunning: () => boolean;
 };
 
 export type MotionImperativeRef = {

packages/react-components/react-motion/library/src/utils/isAnimationRunning.test.ts

@@ -0,0 +1,51 @@
+import { isAnimationRunning } from './isAnimationRunning';
+
+// Heads up!
+// Unit tests are funny as JSDOM doesn't support the Web Animation API
+
+function createModernAnimationMock(playState: Animation['playState'], overallProgress: number): Animation {
+  return {
+    playState,
+    overallProgress,
+  } as Partial<Animation> as Animation;
+}
+
+function createLegacyAnimationMock(
+  playState: Animation['playState'],
+  currentTime: number,
+  duration: number,
+): Animation {
+  return {
+    playState,
+    currentTime,
+    effect: {
+      getTiming: () => ({
+        duration,
+      }),
+    },
+  } as Partial<Animation> as Animation;
+}
+
+describe('isAnimationRunning', () => {
+  it('returns "true" if the animation is running & started', () => {
+    expect(isAnimationRunning(createModernAnimationMock('running', 0.5))).toBe(true);
+  });
+
+  it('returns "false" if the animation is running & not started yet', () => {
+    expect(isAnimationRunning(createModernAnimationMock('running', 0))).toBe(false);
+    expect(isAnimationRunning(createModernAnimationMock('running', 1))).toBe(false);
+  });
+
+  it('returns "false" if the animation is not running', () => {
+    expect(isAnimationRunning(createModernAnimationMock('paused', 0.5))).toBe(false);
+    expect(isAnimationRunning(createModernAnimationMock('finished', 1))).toBe(false);
+    expect(isAnimationRunning(createModernAnimationMock('idle', 0))).toBe(false);
+  });
+
+  it('fallbacks to "currentTime" is "overallProgress" is not supported', () => {
+    expect(isAnimationRunning(createLegacyAnimationMock('running', 500, 1000))).toBe(true);
+
+    expect(isAnimationRunning(createLegacyAnimationMock('running', 0, 1000))).toBe(false);
+    expect(isAnimationRunning(createLegacyAnimationMock('running', 1000, 1000))).toBe(false);
+  });
+});

packages/react-components/react-motion/library/src/utils/isAnimationRunning.ts

@@ -0,0 +1,27 @@
+/**
+ * Checks if the animation is running at the moment.
+ */
+export function isAnimationRunning(animation: Animation & { readonly overallProgress?: number | null }) {
+  if (animation.playState === 'running') {
+    // Heads up!
+    //
+    // There is an edge case where the animation is running, but the overall progress is 0 or 1. In this case, we
+    // consider the animation to be not running. If it will be reversed it will flip from 1 to 0, and we will observe a
+    // glitch.
+
+    // "overallProgress" is not supported in all browsers, so we need to check if it exists.
+    // We will fall back to the currentTime and duration if "overallProgress" is not supported.
+    if (animation.overallProgress !== undefined) {
+      const overallProgress = animation.overallProgress ?? 0;
+
+      return overallProgress > 0 && overallProgress < 1;
+    }
+
+    const currentTime = Number(animation.currentTime ?? 0);
+    const totalTime = Number(animation.effect?.getTiming().duration ?? 0);
+
+    return currentTime > 0 && currentTime < totalTime;
+  }
+
+  return false;
+}