feat(motion): add Rotate presence motion component

change/@fluentui-react-motion-components-preview-32aac0a2-6998-44d1-a90e-ea35ad4f9e92.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat(motion): add Rotate presence motion component",
+  "packageName": "@fluentui/react-motion-components-preview",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -9,6 +9,11 @@ import { PresenceComponent } from '@fluentui/react-motion';
 // @public
 export const Blur: PresenceComponent<BlurParams>;
 
+// @public (undocumented)
+export type BlurParams = PresenceDuration & PresenceEasing & AnimateOpacity & {
+    fromRadius?: string;
+};
+
 // @public
 export const Collapse: PresenceComponent<CollapseParams>;
 
@@ -30,6 +35,16 @@ export const FadeRelaxed: PresenceComponent<FadeParams>;
 // @public (undocumented)
 export const FadeSnappy: PresenceComponent<FadeParams>;
 
+// @public (undocumented)
+export const Rotate: PresenceComponent<RotateParams>;
+
+// @public (undocumented)
+export type RotateParams = PresenceDuration & PresenceEasing & AnimateOpacity & {
+    axis?: Axis3D;
+    angle?: number;
+    exitAngle?: number;
+};
+
 // @public
 export const Scale: PresenceComponent<ScaleParams>;
 

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

@@ -0,0 +1,129 @@
+import { motionTokens } from '@fluentui/react-motion';
+import { rotateAtom } from './rotate-atom';
+
+describe('rotateAtom', () => {
+  it('creates enter keyframes with rotation from angle to 0', () => {
+    const atom = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      easing: motionTokens.curveEasyEase,
+      angle: -90,
+    });
+
+    expect(atom).toMatchObject({
+      duration: 300,
+      easing: motionTokens.curveEasyEase,
+      keyframes: [{ rotate: 'y -90deg' }, { rotate: 'y 0deg' }],
+    });
+  });
+
+  it('creates exit keyframes with rotation from 0 to exitAngle', () => {
+    const atom = rotateAtom({
+      direction: 'exit',
+      duration: 250,
+      easing: motionTokens.curveAccelerateMin,
+      exitAngle: 90,
+    });
+
+    expect(atom).toMatchObject({
+      duration: 250,
+      easing: motionTokens.curveAccelerateMin,
+      keyframes: [{ rotate: 'y 0deg' }, { rotate: 'y 90deg' }],
+    });
+  });
+
+  it('uses default angle when not provided', () => {
+    const atom = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+    });
+
+    expect(atom.keyframes).toEqual([{ rotate: 'y -90deg' }, { rotate: 'y 0deg' }]);
+  });
+
+  it('uses default easing when not provided', () => {
+    const atom = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      angle: 45,
+    });
+
+    expect(atom.easing).toBe(motionTokens.curveLinear);
+  });
+
+  it('uses default axis when not provided', () => {
+    const atom = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      angle: 180,
+    });
+
+    expect(atom.keyframes[0]).toEqual({ rotate: 'y 180deg' });
+    expect(atom.keyframes[1]).toEqual({ rotate: 'y 0deg' });
+  });
+
+  it('handles different rotation axes', () => {
+    const atomX = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      axis: 'x',
+      angle: 45,
+    });
+
+    const atomY = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      axis: 'y',
+      angle: 45,
+    });
+
+    const atomZ = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      axis: 'z',
+      angle: 45,
+    });
+
+    expect(atomX.keyframes[0]).toEqual({ rotate: 'x 45deg' });
+    expect(atomY.keyframes[0]).toEqual({ rotate: 'y 45deg' });
+    expect(atomZ.keyframes[0]).toEqual({ rotate: 'z 45deg' });
+  });
+
+  it('uses exitAngle when direction is exit', () => {
+    const atom = rotateAtom({
+      direction: 'exit',
+      duration: 300,
+      angle: -90,
+      exitAngle: 45,
+    });
+
+    expect(atom.keyframes).toEqual([{ rotate: 'y 0deg' }, { rotate: 'y 45deg' }]);
+  });
+
+  it('uses negated angle as default exitAngle', () => {
+    const atom = rotateAtom({
+      direction: 'exit',
+      duration: 300,
+      angle: -90,
+    });
+
+    expect(atom.keyframes).toEqual([{ rotate: 'y 0deg' }, { rotate: 'y 90deg' }]);
+  });
+
+  it('handles positive and negative angle values', () => {
+    const atomPositive = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      angle: 90,
+    });
+
+    const atomNegative = rotateAtom({
+      direction: 'enter',
+      duration: 300,
+      angle: -45,
+    });
+
+    expect(atomPositive.keyframes[0]).toEqual({ rotate: 'y 90deg' });
+    expect(atomNegative.keyframes[0]).toEqual({ rotate: 'y -45deg' });
+  });
+});

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

@@ -0,0 +1,51 @@
+import { AtomMotion, PresenceDirection, motionTokens } from '@fluentui/react-motion';
+import type { RotateParams } from '../components/Rotate/rotate-types';
+
+type Axis3D = NonNullable<RotateParams['axis']>;
+
+interface RotateAtomParams {
+  direction: PresenceDirection;
+  duration: number;
+  easing?: string;
+  axis?: Axis3D;
+  angle?: number;
+  exitAngle?: number;
+}
+
+const createRotateValue = (axis: Axis3D, angle: number): string => {
+  return `${axis.toLowerCase()} ${angle}deg`;
+};
+
+/**
+ * Generates a motion atom object for a rotation around a single axis.
+ * @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 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`.
+ * @returns A motion atom object with rotate keyframes and the supplied duration and easing.
+ */
+export const rotateAtom = ({
+  direction,
+  duration,
+  easing = motionTokens.curveLinear,
+  axis = 'y',
+  angle = -90,
+  exitAngle = -angle,
+}: RotateAtomParams): AtomMotion => {
+  let fromAngle = angle;
+  let toAngle = 0;
+
+  if (direction === 'exit') {
+    fromAngle = 0;
+    toAngle = exitAngle;
+  }
+  const keyframes = [{ rotate: createRotateValue(axis, fromAngle) }, { rotate: createRotateValue(axis, toAngle) }];
+
+  return {
+    keyframes,
+    duration,
+    easing,
+  };
+};

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

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

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

@@ -0,0 +1,62 @@
+import { AtomMotion, createPresenceComponent, motionTokens, PresenceMotionFn } from '@fluentui/react-motion';
+import { fadeAtom } from '../../atoms/fade-atom';
+import { rotateAtom } from '../../atoms/rotate-atom';
+import { RotateParams } from './rotate-types';
+
+/**
+ * Define a presence motion for rotate in/out
+ *
+ * @param duration - Time (ms) for the enter transition (rotate-in). Defaults to the `durationGentle` value.
+ * @param easing - Easing curve for the enter transition (rotate-in). Defaults to the `curveDecelerateMax` value.
+ * @param exitDuration - Time (ms) for the exit transition (rotate-out). Defaults to the `duration` param for symmetry.
+ * @param exitEasing - Easing curve for the exit transition (rotate-out). Defaults to the `curveAccelerateMax` value.
+ * @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 animateOpacity - Whether to animate the opacity during the rotation. Defaults to `true`.
+ */
+const rotatePresenceFn: PresenceMotionFn<RotateParams> = ({
+  axis = 'y',
+  angle = -90,
+  exitAngle = -angle,
+  duration = motionTokens.durationGentle,
+  exitDuration = duration,
+  easing = motionTokens.curveDecelerateMax,
+  exitEasing = motionTokens.curveAccelerateMax,
+  animateOpacity = true,
+}: RotateParams) => {
+  const enterAtoms: AtomMotion[] = [
+    rotateAtom({
+      direction: 'enter',
+      duration,
+      easing,
+      axis,
+      angle,
+      exitAngle,
+    }),
+  ];
+
+  const exitAtoms: AtomMotion[] = [
+    rotateAtom({
+      direction: 'exit',
+      duration: exitDuration,
+      easing: exitEasing,
+      axis,
+      angle,
+      exitAngle,
+    }),
+  ];
+
+  if (animateOpacity) {
+    enterAtoms.push(fadeAtom({ direction: 'enter', duration, easing }));
+    exitAtoms.push(fadeAtom({ direction: 'exit', duration: exitDuration, easing: exitEasing }));
+  }
+
+  return {
+    enter: enterAtoms,
+    exit: exitAtoms,
+  };
+};
+
+// Create a presence motion component to rotate an element around a single axis (x, y, or z).
+export const Rotate = createPresenceComponent(rotatePresenceFn);

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

@@ -0,0 +1,2 @@
+export { Rotate } from './Rotate';
+export type { RotateParams } from './rotate-types';

packages/react-components/react-motion-components-preview/library/src/components/Rotate/rotate-types.ts

@@ -0,0 +1,25 @@
+import type { PresenceDuration, PresenceEasing, AnimateOpacity } from '../../types';
+
+type Axis3D = 'x' | 'y' | 'z';
+
+export type RotateParams = PresenceDuration &
+  PresenceEasing &
+  AnimateOpacity & {
+    /**
+     * The axis of rotation: 'x', 'y', or 'z'.
+     * Defaults to 'y'.
+     */
+    axis?: Axis3D;
+
+    /**
+     * The starting rotation angle in degrees.
+     * Defaults to -90.
+     */
+    angle?: number;
+
+    /**
+     * The ending rotation angle in degrees.
+     * Defaults to the negation of `angle`.
+     */
+    exitAngle?: number;
+  };

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

@@ -2,4 +2,5 @@ export { Collapse, CollapseSnappy, CollapseRelaxed, CollapseDelayed } from './co
 export { Fade, FadeSnappy, FadeRelaxed } from './components/Fade';
 export { Scale, ScaleSnappy, ScaleRelaxed } from './components/Scale';
 export { Slide, SlideSnappy, SlideRelaxed } from './components/Slide';
-export { Blur } from './components/Blur';
+export { Blur, type BlurParams } from './components/Blur';
+export { Rotate, type RotateParams } from './components/Rotate';