Progress documentation (microsoft#25194)

* (chore): Update README and add MIGRATION.md to react-progress * change files * Apply suggestions from code review Co-authored-by: Ben Howell <[email protected]> Co-authored-by: Ben Howell <[email protected]>
NotWoods · Nov 18, 2022 · 3d25e10 · 3d25e10
1 parent c7201c4
commit 3d25e10
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 0 deletions.
diff --git a/change/@fluentui-react-progress-c2e92a72-c8c9-4de6-8329-7e686f950e0c.json b/change/@fluentui-react-progress-c2e92a72-c8c9-4de6-8329-7e686f950e0c.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Add documentation",
+  "packageName": "@fluentui/react-progress",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/react-components/react-progress/MIGRATION.md b/packages/react-components/react-progress/MIGRATION.md
@@ -0,0 +1,26 @@
+# Progress Migration
+
+## Migration from v8
+
+v8 offers a component equivalent to v9's `Progress`. However, the API is slightly different. The main difference is that v9's `Progress` does not have the `label` or `description` props. Instead, the `label` and `hint` are located in the `ProgressField` that can be used in conjunction with `Progress`.
+
+Here's how the API of v8's `Progress` compares to the one from v9's `Progress` component:
+
+- `className` => `className`
+- `description` => Use `ProgressField` to use the `hint` prop
+- `label` => Use `ProgressField` to use the `label` prop
+- `onRenderProgress` => NOT SUPPORTED
+- `percentComplete` => Use the `value` prop
+- `progressHidden` => NOT SUPPORTED
+- `styles` => Use style customization through `className` instead
+
+## Property Mapping
+
+| v8 `ProgressIndicator` | v9 `Progress`                   |
+| ---------------------- | ------------------------------- |
+| `barHeight`            | `thickness`                     |
+| `className`            | `className`                     |
+| `componentRef`         | `ref`                           |
+| `description`          | use `ProgressField` hint |
+| `label`                | use `ProgressField` label       |
+| `percentComplete`      | `value`                         |
diff --git a/packages/react-components/react-progress/README.md b/packages/react-components/react-progress/README.md
@@ -3,3 +3,48 @@
 **React Progress components for [Fluent UI React](https://react.fluentui.dev/)**
 
 These are not production-ready components and **should never be used in product**. This space is useful for testing new components whose APIs might change before final release.
+
+## Usage
+
+To import `Progress`:
+
+```js
+import { Progress } from '@fluentui/react-progress';
+```
+
+Once the Progress component graduates to a production release, the component will be available at:
+
+```js
+import { Progress } from '@fluentui/react-components';
+```
+
+### Examples
+
+```jsx
+const ProgressExample = () => {
+  return <Progress thickness="large" value={0.5} />;
+};
+```
+
+#### Using ProgressField
+
+The `ProgressField` component is a wrapper around the `Progress` component that allows the user to add a `label`, `hint`, `validationMessage`, and `validationState` to the `Progress` component. You can pass these props, as well as the regular `Progress` props to a `ProgressField` component.
+
+To import `ProgressField`:
+
+```js
+import { ProgressField } from '@fluentui/react-field';
+```
+
+```jsx
+const ProgressFieldExample = () => {
+  return (
+    <ProgressField
+      label="Determinate Progress"
+      hint="This is a determinate Progress with description"
+      value={0.5}
+      validationState="warning"
+    />
+  );
+};
+```