feat(Rotate): implement rotateAtom for single-axis rotation and update Rotate component to use new parameters

Author: robertpenner

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

@@ -0,0 +1,50 @@
+import { AtomMotion, PresenceDirection, motionTokens } from '@fluentui/react-motion';
+
+export type Axis3D = 'x' | 'y' | 'z';
+
+interface RotateAtomParams {
+  direction: PresenceDirection;
+  duration: number;
+  easing?: string;
+  axis?: Axis3D;
+  enterAngle?: number;
+  exitAngle?: number;
+}
+
+const createRotateValue = (axis: Axis3D, angle: number): string => {
+  return `${axis} ${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 enterAngle - The starting rotation angle in degrees. Defaults to -90.
+ * @param exitAngle - The ending rotation angle in degrees. Defaults to the negation of `enterAngle`.
+ * @returns A motion atom object with rotate keyframes and the supplied duration and easing.
+ */
+export const rotateAtom = ({
+  direction,
+  duration,
+  easing = motionTokens.curveLinear,
+  axis = 'y',
+  enterAngle = -90,
+  exitAngle = -enterAngle,
+}: RotateAtomParams): AtomMotion => {
+  let fromAngle = enterAngle;
+  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.ts

@@ -1,5 +1,6 @@
 import { AtomMotion, createPresenceComponent, motionTokens, PresenceMotionFn } from '@fluentui/react-motion';
 import { fadeAtom } from '../../atoms/fade-atom';
+import { rotateAtom, Axis3D } from '../../atoms/rotate-atom';
 
 /**
  * Parameters for configuring the Rotate motion.
@@ -30,40 +31,22 @@ export type RotateParams = {
   exitEasing?: string;
 
   /**
-   * The starting X-axis rotation angle, in degrees.
-   * Defaults to 0.
+   * The axis of rotation: 'X', 'Y', or 'Z'.
+   * Defaults to 'Y'.
    */
-  fromX?: number;
+  axis?: Axis3D;
 
   /**
-   * The starting Y-axis rotation angle, in degrees.
+   * The starting rotation angle in degrees.
    * Defaults to -90.
    */
-  fromY?: number;
+  enterAngle?: number;
 
   /**
-   * The starting Z-axis rotation angle, in degrees.
-   * Defaults to 0.
+   * The ending rotation angle in degrees.
+   * Defaults to the negation of `enterAngle`.
    */
-  fromZ?: number;
-
-  /**
-   * The ending X-axis rotation angle, in degrees.
-   * Defaults to the negation of `fromX`.
-   */
-  toX?: number;
-
-  /**
-   * The ending Y-axis rotation angle, in degrees.
-   * Defaults to the negation of `fromY`.
-   */
-  toY?: number;
-
-  /**
-   * The ending Z-axis rotation angle, in degrees.
-   * Defaults to the negation of `fromZ`.
-   */
-  toZ?: number;
+  exitAngle?: number;
 
   /**
    * Whether to animate the opacity during the rotation.
@@ -72,50 +55,36 @@ export type RotateParams = {
   animateOpacity?: boolean;
 };
 
-const createRotateValue = (x: number, y: number, z: number): string => {
-  const rotations = [];
-
-  if (x !== 0) {
-    rotations.push(`x ${x}deg`);
-  }
-  if (y !== 0) {
-    rotations.push(`y ${y}deg`);
-  }
-  if (z !== 0) {
-    rotations.push(`z ${z}deg`);
-  }
-
-  return rotations.length > 0 ? rotations.join(' ') : '0deg';
-};
-
 const rotatePresenceFn: PresenceMotionFn<RotateParams> = ({
-  // element,
-  fromX = 0,
-  fromY = -90,
-  fromZ = 0,
-  toX = -fromX,
-  toY = -fromY,
-  toZ = -fromZ,
+  axis = 'y',
+  enterAngle = -90,
+  exitAngle = -enterAngle,
   duration = motionTokens.durationGentle,
   exitDuration = duration,
   easing = motionTokens.curveDecelerateMax,
   exitEasing = motionTokens.curveAccelerateMax,
   animateOpacity = true,
 }: RotateParams) => {
   const enterAtoms: AtomMotion[] = [
-    {
-      keyframes: [{ rotate: createRotateValue(fromX, fromY, fromZ) }, { rotate: createRotateValue(0, 0, 0) }],
+    rotateAtom({
+      direction: 'enter',
       duration,
       easing,
-    },
+      axis,
+      enterAngle,
+      exitAngle,
+    }),
   ];
 
   const exitAtoms: AtomMotion[] = [
-    {
-      keyframes: [{ rotate: createRotateValue(0, 0, 0) }, { rotate: createRotateValue(toX, toY, toZ) }],
+    rotateAtom({
+      direction: 'exit',
       duration: exitDuration,
       easing: exitEasing,
-    },
+      axis,
+      enterAngle,
+      exitAngle,
+    }),
   ];
 
   if (animateOpacity) {
@@ -129,5 +98,5 @@ const rotatePresenceFn: PresenceMotionFn<RotateParams> = ({
   };
 };
 
-// Create a presence motion component to rotate an element around the X, Y, and/or Z axes.
+// 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/stories/src/Rotate/RotateCardFlip.stories.tsx

@@ -157,8 +157,9 @@ export const CardFlip = () => {
           <div key={card.id} className={classes.cardContainer}>
             <Rotate
               visible={!flippedCards.has(card.id)}
-              fromY={0}
-              toY={180}
+              axis="Y"
+              enterAngle={0}
+              exitAngle={180}
               duration={600}
               easing="cubic-bezier(0.4, 0, 0.2, 1)"
             >
@@ -172,8 +173,9 @@ export const CardFlip = () => {
 
             <Rotate
               visible={flippedCards.has(card.id)}
-              fromY={-180}
-              toY={0}
+              axis="Y"
+              enterAngle={-180}
+              exitAngle={0}
               duration={600}
               easing="cubic-bezier(0.4, 0, 0.2, 1)"
             >

packages/react-components/react-motion-components-preview/stories/src/Rotate/RotateCommonPatterns.stories.tsx

@@ -64,7 +64,8 @@ const patterns = [
     description: 'Classic Y-axis rotation',
     icon: '↔️',
     color: tokens.colorPaletteBlueForeground2,
-    rotation: { fromY: 180 },
+    axis: 'Y' as const,
+    enterAngle: 180,
     easing: 'ease-out',
     duration: 600,
   },
@@ -74,7 +75,8 @@ const patterns = [
     description: 'X-axis rotation',
     icon: '↕️',
     color: tokens.colorPaletteGreenForeground2,
-    rotation: { fromX: 180 },
+    axis: 'X' as const,
+    enterAngle: 180,
     easing: 'ease-out',
     duration: 600,
   },
@@ -84,27 +86,19 @@ const patterns = [
     description: 'Z-axis rotation',
     icon: '🔄',
     color: tokens.colorPaletteRedForeground2,
-    rotation: { fromZ: 360 },
+    axis: 'Z' as const,
+    enterAngle: 360,
     easing: 'ease-in-out',
     duration: 800,
   },
-  {
-    id: 'tumble',
-    name: 'Tumble',
-    description: 'Multi-axis rotation',
-    icon: '🎲',
-    color: tokens.colorPalettePurpleForeground2,
-    rotation: { fromX: 180, fromY: 180 },
-    easing: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
-    duration: 1000,
-  },
   {
     id: 'wobble',
     name: 'Wobble',
     description: 'Gentle X-axis tilt',
     icon: '〰️',
     color: tokens.colorPaletteYellowForeground2,
-    rotation: { fromX: 15 },
+    axis: 'X' as const,
+    enterAngle: 15,
     easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
     duration: 400,
   },
@@ -114,7 +108,8 @@ const patterns = [
     description: 'Slight Y-axis reveal',
     icon: '👀',
     color: tokens.colorPaletteTealForeground2,
-    rotation: { fromY: -15 },
+    axis: 'Y' as const,
+    enterAngle: -15,
     easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
     duration: 400,
   },
@@ -124,20 +119,11 @@ const patterns = [
     description: 'Accordion-style fold',
     icon: '📄',
     color: tokens.colorPaletteDarkOrangeForeground2,
-    rotation: { fromX: -90 },
+    axis: 'X' as const,
+    enterAngle: -90,
     easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
     duration: 500,
   },
-  {
-    id: 'twist',
-    name: 'Twist',
-    description: 'Diagonal rotation',
-    icon: '🌪️',
-    color: tokens.colorPalettePinkForeground2,
-    rotation: { fromX: 45, fromZ: 45 },
-    easing: 'cubic-bezier(0.175, 0.885, 0.32, 1.275)',
-    duration: 700,
-  },
 ];
 
 export const CommonPatterns = () => {
@@ -199,9 +185,8 @@ export const CommonPatterns = () => {
           <div key={pattern.id}>
             <Rotate
               visible={activePatterns.has(pattern.id)}
-              fromX={pattern.rotation.fromX || 0}
-              fromY={pattern.rotation.fromY || 0}
-              fromZ={pattern.rotation.fromZ || 0}
+              axis={pattern.axis}
+              enterAngle={pattern.enterAngle}
               duration={pattern.duration}
               easing={pattern.easing}
             >
@@ -228,7 +213,7 @@ CommonPatterns.parameters = {
   docs: {
     description: {
       story:
-        'A collection of common rotation patterns that you can use as starting points for your own animations. Each pattern demonstrates different combinations of rotation axes and easing curves.',
+        'A collection of common single-axis rotation patterns that you can use as starting points for your own animations. Each pattern demonstrates rotation around a specific axis (X, Y, or Z) with different easing curves.',
     },
   },
 };