docs(react-motion): document motion slot customization APIs more thoroughly (#35922)

Author: robertpenner

change/@fluentui-react-components-d257adad-0aa3-44d8-899e-32c2dd265d42.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: re-export motionSlot and presenceMotionSlot from @fluentui/react-motion",
+  "packageName": "@fluentui/react-components",
+  "email": "robertpenner@microsoft.com",
+  "dependentChangeType": "patch"
+}

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

@@ -679,6 +679,8 @@ import { MessageBarTitleState } from '@fluentui/react-message-bar';
 import { MessageBarTransitionContextValue } from '@fluentui/react-message-bar';
 import { MotionComponentProps } from '@fluentui/react-motion';
 import { MotionImperativeRef } from '@fluentui/react-motion';
+import { motionSlot } from '@fluentui/react-motion';
+import { MotionSlotProps } from '@fluentui/react-motion';
 import { motionTokens } from '@fluentui/react-motion';
 import { Nav } from '@fluentui/react-nav';
 import { NavButtonRenderFunction } from '@fluentui/react-carousel';
@@ -834,6 +836,8 @@ import { presenceDndRegular } from '@fluentui/react-badge';
 import { PresenceGroup } from '@fluentui/react-motion';
 import { PresenceMotion } from '@fluentui/react-motion';
 import { PresenceMotionFn } from '@fluentui/react-motion';
+import { presenceMotionSlot } from '@fluentui/react-motion';
+import { PresenceMotionSlotProps } from '@fluentui/react-motion';
 import { presenceOfflineRegular } from '@fluentui/react-badge';
 import { presenceOofRegular } from '@fluentui/react-badge';
 import { presenceUnknownRegular } from '@fluentui/react-badge';
@@ -3377,6 +3381,10 @@ export { MotionComponentProps }
 
 export { MotionImperativeRef }
 
+export { motionSlot }
+
+export { MotionSlotProps }
+
 export { motionTokens }
 
 export { Nav }
@@ -3687,6 +3695,10 @@ export { PresenceMotion }
 
 export { PresenceMotionFn }
 
+export { presenceMotionSlot }
+
+export { PresenceMotionSlotProps }
+
 export { presenceOfflineRegular }
 
 export { presenceOofRegular }

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

@@ -1912,16 +1912,20 @@ export {
   createMotionComponentVariant,
   createPresenceComponent,
   createPresenceComponentVariant,
+  motionSlot,
+  presenceMotionSlot,
   PresenceGroup,
 } from '@fluentui/react-motion';
 export type {
   AtomMotion,
   AtomMotionFn,
   MotionComponentProps,
   MotionImperativeRef,
+  MotionSlotProps,
   PresenceComponent,
   PresenceMotion,
   PresenceMotionFn,
+  PresenceMotionSlotProps,
   PresenceComponentProps,
 } from '@fluentui/react-motion';
 

packages/react-components/react-dialog/stories/src/Dialog/DialogMotionCustom.stories.md

@@ -0,0 +1,9 @@
+`Dialog`'s `surfaceMotion` slot accepts `Scale` params directly, such as `duration`, `outScale`, `easing`, and `animateOpacity`. `DialogSurface`'s `backdropMotion` slot accepts `Fade` params.
+
+Both slots also support the `children` render function, which allows replacing the default motion with a custom implementation. This story demonstrates the simpler direct prop approach:
+
+```tsx
+<Dialog surfaceMotion={{ duration, outScale, easing, animateOpacity }}>
+  <DialogSurface backdropMotion={{ duration: backdropDuration }}>…</DialogSurface>
+</Dialog>
+```

packages/react-components/react-dialog/stories/src/Dialog/DialogMotionCustom.stories.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import type { JSXElement } from '@fluentui/react-components';
+import {
+  Button,
+  Dialog,
+  DialogActions,
+  DialogBody,
+  DialogContent,
+  DialogSurface,
+  DialogTitle,
+  DialogTrigger,
+  Field,
+  makeStyles,
+  motionTokens,
+  Slider,
+  Switch,
+  tokens,
+} from '@fluentui/react-components';
+import description from './DialogMotionCustom.stories.md';
+
+const useStyles = makeStyles({
+  controls: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: tokens.spacingVerticalS,
+    marginBottom: tokens.spacingVerticalL,
+    padding: tokens.spacingVerticalM,
+    border: `${tokens.strokeWidthThicker} solid ${tokens.colorNeutralForeground3}`,
+    borderRadius: tokens.borderRadiusMedium,
+  },
+});
+
+export const MotionCustom = (): JSXElement => {
+  const classes = useStyles();
+  const [duration, setDuration] = React.useState(600);
+  const [outScale, setOutScale] = React.useState(0.5);
+  const [animateOpacity, setAnimateOpacity] = React.useState(true);
+  const [backdropDuration, setBackdropDuration] = React.useState(300);
+
+  const easing = motionTokens.curveDecelerateMid;
+
+  return (
+    <>
+      <div className={classes.controls}>
+        <Field label={`Surface duration: ${duration}ms`}>
+          <Slider min={100} max={2000} step={50} value={duration} onChange={(_, data) => setDuration(data.value)} />
+        </Field>
+        <Field label={`Surface outScale: ${outScale.toFixed(2)}`}>
+          <Slider min={0} max={1} step={0.05} value={outScale} onChange={(_, data) => setOutScale(data.value)} />
+        </Field>
+        <Field label={`Backdrop duration: ${backdropDuration}ms`}>
+          <Slider
+            min={0}
+            max={1000}
+            step={50}
+            value={backdropDuration}
+            onChange={(_, data) => setBackdropDuration(data.value)}
+          />
+        </Field>
+        <Switch
+          label="Surface animateOpacity"
+          checked={animateOpacity}
+          onChange={(_, data) => setAnimateOpacity(data.checked)}
+        />
+      </div>
+
+      <Dialog surfaceMotion={{ duration, outScale, easing, animateOpacity }}>
+        <DialogTrigger disableButtonEnhancement>
+          <Button>Open Dialog</Button>
+        </DialogTrigger>
+        <DialogSurface backdropMotion={{ duration: backdropDuration }}>
+          <DialogBody>
+            <DialogTitle>Dialog with custom motion params</DialogTitle>
+            <DialogContent>
+              This dialog's surface animation is driven by direct <code>surfaceMotion</code> params (`duration`,
+              `outScale`, `easing`, `animateOpacity`). Its backdrop fade is tuned independently via{' '}
+              <code>backdropMotion</code> (`duration`).
+            </DialogContent>
+            <DialogActions>
+              <DialogTrigger disableButtonEnhancement>
+                <Button appearance="secondary">Close</Button>
+              </DialogTrigger>
+            </DialogActions>
+          </DialogBody>
+        </DialogSurface>
+      </Dialog>
+    </>
+  );
+};
+
+MotionCustom.parameters = {
+  docs: {
+    description: {
+      story: description,
+    },
+  },
+};

packages/react-components/react-dialog/stories/src/Dialog/index.stories.tsx

@@ -22,6 +22,7 @@ export { WithForm } from './DialogWithForm.stories';
 export { TitleCustomAction } from './DialogTitleCustomAction.stories';
 export { TitleNoAction } from './DialogTitleNoAction.stories';
 export { Confirmation } from './DialogConfirmation.stories';
+export { MotionCustom } from './DialogMotionCustom.stories';
 
 // Typing with Meta<typeof Dialog> generates a type error for the `subcomponents` property.
 // https://github.com/storybookjs/storybook/issues/27535

packages/react-components/react-motion/stories/src/Motion/CustomMotion.stories.md

@@ -0,0 +1,10 @@
+You can replace a component's default animation by providing a `children` render function to a motion slot. The render function receives the default motion component and its props, and you return your own animation component built with [createPresenceComponent](?path=/docs/motion-apis-createpresencecomponent--docs).
+
+**Dialog** has two customizable motion slots:
+
+- `surfaceMotion` on `<Dialog>` — the surface enter/exit animation
+- `backdropMotion` on `<DialogSurface>` — the backdrop overlay animation
+
+**Drawer** also supports this via:
+
+- `surfaceMotion` — the slide animation of the drawer panel