feat(react-motion): add useMotion hook

apps/public-docsite-v9/package.json

@@ -36,6 +36,7 @@
     "@fluentui/react-storybook-addon-codesandbox": "*",
     "@fluentui/theme-designer": "*",
     "@fluentui/react-search-preview": "*",
+    "@fluentui/react-motion-preview": "*",
     "@griffel/react": "^1.5.14",
     "react": "17.0.2",
     "react-dom": "17.0.2",

apps/public-docsite-v9/src/Utilities/Motion/useMotion/MotionExample.stories.tsx

@@ -0,0 +1,60 @@
+import * as React from 'react';
+
+import { useMotion } from '@fluentui/react-motion-preview';
+import { Button, makeStyles, mergeClasses, shorthands, tokens } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    rowGap: '24px',
+  },
+
+  rectangle: {
+    ...shorthands.borderRadius('8px'),
+
+    width: '200px',
+    height: '150px',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: tokens.colorBrandBackground2,
+    opacity: 0,
+    transform: 'translate3D(0, 0, 0) scale(0.25)',
+    transitionDuration: `${tokens.durationNormal}, ${tokens.durationNormal}, ${tokens.durationUltraSlow}`,
+    transitionDelay: `${tokens.durationFast}, 0, ${tokens.durationSlow}`,
+    transitionProperty: 'opacity, transform, background-color',
+    willChange: 'opacity, transform, background-color',
+    color: '#fff',
+  },
+
+  visible: {
+    opacity: 1,
+    transform: 'translate3D(0, 0, 0) scale(1)',
+    backgroundColor: tokens.colorBrandBackground,
+  },
+});
+
+export const MotionExample = () => {
+  const styles = useStyles();
+
+  const [open, setOpen] = React.useState(false);
+  const motion = useMotion<HTMLDivElement>(open);
+
+  return (
+    <div className={styles.root}>
+      <Button appearance="primary" onClick={() => setOpen(!open)}>
+        Toggle
+      </Button>
+
+      {motion.canRender && (
+        <div ref={motion.ref} className={mergeClasses(styles.rectangle, motion.active && styles.visible)}>
+          Lorem ipsum
+        </div>
+      )}
+    </div>
+  );
+};

apps/public-docsite-v9/src/Utilities/Motion/useMotion/index.stories.mdx

@@ -0,0 +1,83 @@
+import { Title, Subtitle, Meta, Description } from '@storybook/addon-docs';
+
+import { MotionExample } from './MotionExample.stories';
+
+<Title>useMotion</Title>
+
+<Meta title="Utilities/Motion/useMotion" />
+
+<Description>
+  A tracker hook, that monitors the state of animations and transitions for a particular element. This hook does not
+  directly create animations but instead synchronizes with CSS properties to determine the rendering status, visibility,
+  entering, leaving, and ongoing animation of a component. If any CSS changes or properties are overridden, this hook
+  will automatically adjust and stay synchronized.
+</Description>
+
+<Subtitle>Usage</Subtitle>
+
+```tsx
+import * as React from 'react';
+
+import { useMotion } from '@fluentui/react-motion-preview';
+import { Button, makeStyles, mergeClasses, shorthands, tokens } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    rowGap: '24px',
+  },
+
+  rectangle: {
+    ...shorthands.borderRadius('8px'),
+
+    width: '200px',
+    height: '150px',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: tokens.colorBrandBackground2,
+    opacity: 0,
+    transform: 'translate3D(0, 0, 0) scale(0.25)',
+    transitionDuration: `${tokens.durationNormal}, ${tokens.durationNormal}, ${tokens.durationUltraSlow}`,
+    transitionDelay: `${tokens.durationFast}, 0, ${tokens.durationSlow}`,
+    transitionProperty: 'opacity, transform, background-color',
+    willChange: 'opacity, transform, background-color',
+    color: '#fff',
+  },
+
+  visible: {
+    opacity: 1,
+    transform: 'translate3D(0, 0, 0) scale(1)',
+    backgroundColor: tokens.colorBrandBackground,
+  },
+});
+
+export const MotionExample = () => {
+  const styles = useStyles();
+
+  const [open, setOpen] = React.useState(false);
+  const motion = useMotion<HTMLDivElement>(open);
+
+  return (
+    <div className={styles.root}>
+      <Button appearance="primary" onClick={() => setOpen(!open)}>
+        Toggle
+      </Button>
+
+      {motion.canRender() && (
+        <div ref={motion.ref} className={mergeClasses(styles.rectangle, motion.isActive() && styles.visible)}>
+          Lorem ipsum
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+<Subtitle>Example</Subtitle>
+
+<MotionExample />

change/@fluentui-react-motion-preview-a0e15534-5b7d-4fb8-a6dd-f28e388add2a.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: create react-motion-preview package with useMotion hook",
+  "packageName": "@fluentui/react-motion-preview",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -4,6 +4,36 @@
 
 ```ts
 
+import * as React_2 from 'react';
+
+// @public
+export function getDefaultMotionState<Element extends HTMLElement>(): MotionState<Element>;
+
+// @public (undocumented)
+export type MotionOptions = {
+    animateOnFirstMount?: boolean;
+};
+
+// @public (undocumented)
+export type MotionShorthand<Element extends HTMLElement = HTMLElement> = MotionShorthandValue | MotionState<Element>;
+
+// @public (undocumented)
+export type MotionShorthandValue = boolean;
+
+// @public (undocumented)
+export type MotionState<Element extends HTMLElement = HTMLElement> = {
+    ref: React_2.Ref<Element>;
+    type: MotionType;
+    canRender: boolean;
+    active: boolean;
+};
+
+// @public (undocumented)
+export type MotionType = 'entering' | 'entered' | 'idle' | 'exiting' | 'exited' | 'unmounted';
+
+// @public
+export function useMotion<Element extends HTMLElement>(shorthand: MotionShorthand<Element>, options?: MotionOptions): MotionState<Element>;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/react-components/react-motion-preview/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@fluentui/react-motion-preview",
   "version": "0.0.0",
-  "private": true,
   "description": "New fluentui react package",
   "main": "lib-commonjs/index.js",
   "module": "lib/index.js",

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

@@ -0,0 +1 @@
+export * from './useMotion';