feat(motion): add createMotionComponentVariant factory (microsoft#35149)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: robertpenner <[email protected]>

Author: robertpenner

change/@fluentui-react-components-3226277d-e60b-4fd4-8a20-810e4ddd0f41.json

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

change/@fluentui-react-motion-8a2ef634-4d5e-447f-9f09-345e38c0b53c.json

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

packages/react-components/react-components/etc/react-components.api.md

@@ -284,6 +284,7 @@ import { CreateFocusOutlineStyleOptions } from '@fluentui/react-tabster';
 import { createHighContrastTheme } from '@fluentui/react-theme';
 import { createLightTheme } from '@fluentui/react-theme';
 import { createMotionComponent } from '@fluentui/react-motion';
+import { createMotionComponentVariant } from '@fluentui/react-motion';
 import { createPresenceComponent } from '@fluentui/react-motion';
 import { createPresenceComponentVariant } from '@fluentui/react-motion';
 import { createTableColumn } from '@fluentui/react-table';
@@ -2580,6 +2581,8 @@ export { createLightTheme }
 
 export { createMotionComponent }
 
+export { createMotionComponentVariant }
+
 export { createPresenceComponent }
 
 export { createPresenceComponentVariant }

packages/react-components/react-components/src/index.ts

@@ -1904,6 +1904,7 @@ export type {
 export {
   motionTokens,
   createMotionComponent,
+  createMotionComponentVariant,
   createPresenceComponent,
   createPresenceComponentVariant,
   PresenceGroup,

packages/react-components/react-motion-components-preview/library/src/testing/testUtils.ts

@@ -1,10 +1,10 @@
 import type { PresenceComponent, PresenceMotionFn } from '@fluentui/react-motion';
 
-function getMotionFunction(component: PresenceComponent): PresenceMotionFn | null {
+function getPresenceMotionFunction(component: PresenceComponent): PresenceMotionFn | null {
   const symbols = Object.getOwnPropertySymbols(component);
 
   for (const symbol of symbols) {
-    if (symbol.toString() === 'Symbol(MOTION_DEFINITION)') {
+    if (symbol.toString() === 'Symbol(PRESENCE_MOTION_DEFINITION)') {
       // @ts-expect-error symbol can't be used as an index there, type casting is also not possible
       return component[symbol];
     }
@@ -14,7 +14,7 @@ function getMotionFunction(component: PresenceComponent): PresenceMotionFn | nul
 }
 
 export function expectPresenceMotionObject(component: PresenceComponent): void {
-  const presenceMotionFn = getMotionFunction(component);
+  const presenceMotionFn = getPresenceMotionFunction(component);
 
   expect(
     presenceMotionFn?.({
@@ -39,7 +39,7 @@ export function expectPresenceMotionObject(component: PresenceComponent): void {
 }
 
 export function expectPresenceMotionArray(component: PresenceComponent): void {
-  const presenceMotionFn = getMotionFunction(component);
+  const presenceMotionFn = getPresenceMotionFunction(component);
 
   // eslint-disable-next-line @nx/workspace-no-restricted-globals
   expect(presenceMotionFn?.({ element: document.createElement('div') })).toMatchObject({
@@ -63,7 +63,7 @@ export function expectPresenceMotionArray(component: PresenceComponent): void {
 }
 
 export function expectPresenceMotionFunction(PresenceComponent: PresenceComponent): void {
-  const presenceMotionFn = getMotionFunction(PresenceComponent);
+  const presenceMotionFn = getPresenceMotionFunction(PresenceComponent);
 
   expect(presenceMotionFn).toBeInstanceOf(Function);
 }

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

@@ -21,7 +21,10 @@ export type AtomMotionFn<MotionParams extends Record<string, MotionParam> = {}>
 } & MotionParams) => AtomMotion | AtomMotion[];
 
 // @public
-export function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>): React_2.FC<MotionComponentProps & MotionParams>;
+export function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>): MotionComponent<MotionParams>;
+
+// @public
+export function createMotionComponentVariant<MotionParams extends Record<string, MotionParam> = {}>(component: MotionComponent<MotionParams>, variantParams: Partial<MotionParams>): MotionComponent<MotionParams>;
 
 // @public (undocumented)
 export function createPresenceComponent<MotionParams extends Record<string, MotionParam> = {}>(value: PresenceMotion | PresenceMotionFn<MotionParams>): PresenceComponent<MotionParams>;
@@ -57,6 +60,11 @@ export const durations: {
 // @public (undocumented)
 export const MotionBehaviourProvider: React_2.Provider<MotionBehaviourType | undefined>;
 
+// @public (undocumented)
+export type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React_2.FC<MotionComponentProps & MotionParams> & {
+    [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;
+};
+
 // @public (undocumented)
 export type MotionComponentProps = {
     children: JSXElement;
@@ -99,7 +107,7 @@ export const motionTokens: {
 // @public (undocumented)
 export type PresenceComponent<MotionParams extends Record<string, MotionParam> = {}> = React_2.FC<PresenceComponentProps & MotionParams> & {
     (props: PresenceComponentProps & MotionParams): JSXElement | null;
-    [MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
+    [PRESENCE_MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
     In: React_2.FC<MotionComponentProps & MotionParams>;
     Out: React_2.FC<MotionComponentProps & MotionParams>;
 };

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

@@ -9,6 +9,11 @@ import { useChildElement } from '../utils/useChildElement';
 import type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef } from '../types';
 import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
 
+/**
+ * @internal A private symbol to store the motion definition on the component for variants.
+ */
+export const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');
+
 export type MotionComponentProps = {
   children: JSXElement;
 
@@ -44,14 +49,20 @@ export type MotionComponentProps = {
   onMotionStart?: (ev: null) => void;
 };
 
+export type MotionComponent<MotionParams extends Record<string, MotionParam> = {}> = React.FC<
+  MotionComponentProps & MotionParams
+> & {
+  [MOTION_DEFINITION]: AtomMotionFn<MotionParams>;
+};
+
 /**
  * Creates a component that will animate the children using the provided motion.
  *
  * @param value - A motion definition.
  */
 export function createMotionComponent<MotionParams extends Record<string, MotionParam> = {}>(
   value: AtomMotion | AtomMotion[] | AtomMotionFn<MotionParams>,
-): React.FC<MotionComponentProps & MotionParams> {
+): MotionComponent<MotionParams> {
   const Atom: React.FC<MotionComponentProps & MotionParams> = props => {
     'use no memo';
 
@@ -118,5 +129,9 @@ export function createMotionComponent<MotionParams extends Record<string, Motion
     return child;
   };
 
-  return Atom;
+  return Object.assign(Atom, {
+    // Heads up!
+    // Always normalize it to a function to simplify types
+    [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,
+  });
 }

packages/react-components/react-motion/library/src/factories/createMotionComponentVariant.test.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { render } from '@testing-library/react';
+
+import type { AtomMotionFn } from '../types';
+import { createMotionComponent } from './createMotionComponent';
+import { createMotionComponentVariant } from './createMotionComponentVariant';
+
+jest.mock('./createMotionComponent', () => {
+  const module = jest.requireActual('./createMotionComponent');
+
+  return {
+    ...module,
+    createMotionComponent: jest.fn().mockImplementation(module.createMotionComponent),
+  };
+});
+
+const MOTION_FUNCTION: AtomMotionFn<{ opacity?: number; duration?: number; easing?: string }> = ({
+  opacity = 0,
+  duration = 1000,
+  easing = 'linear',
+}) => ({
+  keyframes: [{ opacity }, { opacity: 1 }],
+  duration,
+  easing,
+});
+const MOTION_COMPONENT = createMotionComponent(MOTION_FUNCTION);
+
+const MOTION_PARAMS = {
+  element: document.createElement('div'),
+};
+
+describe('createMotionComponentVariant', () => {
+  it('overrides motion parameters used within motion function', () => {
+    // variant params overriding the default motion params
+    const opacity = 0.3;
+    const duration = 500;
+    const easing = 'ease-in-out';
+
+    const MotionVariant = createMotionComponentVariant(MOTION_COMPONENT, {
+      opacity,
+      duration,
+      easing,
+    });
+    const overrideFn = (createMotionComponent as jest.Mock).mock.calls[0][0];
+
+    const { getByText } = render(
+      <MotionVariant>
+        <div>Hello world!</div>
+      </MotionVariant>,
+    );
+
+    expect(MotionVariant).not.toBe(MOTION_COMPONENT);
+    expect(getByText('Hello world!')).toBeInTheDocument();
+
+    expect(createMotionComponent).toHaveBeenCalledTimes(1);
+    expect(createMotionComponent).toHaveBeenCalledWith(expect.any(Function));
+
+    expect(overrideFn).toBeInstanceOf(Function);
+    expect(overrideFn(MOTION_PARAMS)).toEqual({
+      keyframes: [{ opacity }, { opacity: 1 }],
+      duration,
+      easing,
+    });
+  });
+});

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

@@ -0,0 +1,37 @@
+import type { MotionParam, AtomMotionFn } from '../types';
+import { MOTION_DEFINITION, createMotionComponent, MotionComponent } from './createMotionComponent';
+
+/**
+ * @internal
+ *
+ * Create a variant function that wraps a motion function to customize it.
+ * The new motion function has the supplied variant params as defaults,
+ * but these can still be overridden by runtime params when the new function is called.
+ */
+export function createMotionFnVariant<MotionParams extends Record<string, MotionParam> = {}>(
+  motionFn: AtomMotionFn<MotionParams>,
+  variantParams: Partial<MotionParams>,
+): typeof motionFn {
+  const variantFn: typeof motionFn = runtimeParams => motionFn({ ...variantParams, ...runtimeParams });
+  return variantFn;
+}
+
+/**
+ * Create a new motion component based on another motion component,
+ * using the provided variant parameters as defaults.
+ *
+ * @param component - A component created by `createMotionComponent`.
+ * @param variantParams - An object containing the variant parameters to be used as defaults.
+ * The variant parameters should match the type of the component's motion parameters.
+ * @returns A new motion component that uses the provided variant parameters as defaults.
+ * The new component can still accept runtime parameters that override the defaults.
+ */
+export function createMotionComponentVariant<MotionParams extends Record<string, MotionParam> = {}>(
+  component: MotionComponent<MotionParams>,
+  variantParams: Partial<MotionParams>,
+): MotionComponent<MotionParams> {
+  const originalFn = component[MOTION_DEFINITION];
+  // The variant params become new defaults, but they can still be overridden by runtime params.
+  const variantFn = createMotionFnVariant(originalFn, variantParams);
+  return createMotionComponent(variantFn);
+}

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

@@ -22,7 +22,7 @@ import { createMotionComponent, MotionComponentProps } from './createMotionCompo
 /**
  * @internal A private symbol to store the motion definition on the component for variants.
  */
-export const MOTION_DEFINITION = Symbol('MOTION_DEFINITION');
+export const PRESENCE_MOTION_DEFINITION = Symbol('PRESENCE_MOTION_DEFINITION');
 
 export type PresenceComponentProps = {
   /**
@@ -80,7 +80,7 @@ export type PresenceComponent<MotionParams extends Record<string, MotionParam> =
   PresenceComponentProps & MotionParams
 > & {
   (props: PresenceComponentProps & MotionParams): JSXElement | null;
-  [MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
+  [PRESENCE_MOTION_DEFINITION]: PresenceMotionFn<MotionParams>;
   In: React.FC<MotionComponentProps & MotionParams>;
   Out: React.FC<MotionComponentProps & MotionParams>;
 };
@@ -248,7 +248,7 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
     {
       // Heads up!
       // Always normalize it to a function to simplify types
-      [MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,
+      [PRESENCE_MOTION_DEFINITION]: typeof value === 'function' ? value : () => value,
     },
     {
       // Wrap `enter` in its own motion component as a static method, e.g. <Fade.In>