docs(react-avatar): Adding readme and migration guide for AvatarGroup

change/@fluentui-react-avatar-398ce0cf-a9ba-4202-bc72-488f974333c9.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: Adding readme and migration guide for AvatarGroup.",
+  "packageName": "@fluentui/react-avatar",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/react-components/react-avatar/MIGRATION-AvatarGroup.md

@@ -0,0 +1,35 @@
+# AvatarGroup Migration
+
+## Migration from v0
+
+`v0` does not have a component similar to `AvatarGroup`.
+
+## Migration from v8
+
+AvatarGroup and Facepile have similar APIs, but the main difference is how they interact with AvatarGroupItem/Persona. AvatarGroup receives AvatarGroupItems as children and places them in their respective place, this means AvatarGroup has no control over AvatarGroupItem. `size` is the only property of AvatarGroupItem that is modified by AvatarGroup to make all AvatarGroupItems the same size. Face adding functionality is not supported.
+
+Avatars must not be used inside an AvatarGroup, instead AvatarGroupItems are used since it has extra functionality used only in AvatarGroups. This includes adding a label when the AvatarGroupItem is rendered in the overflow Popover and specific styling for each layout.
+
+AvatarGroup has extra functionality that Facepile does not have, this includes:
+ - When the AvatarGroupItems are overflowing, a Popover is rendered that contains all the overflowed AvatarGroupItems. The Popover is triggered when the overflow button is clicked.
+ - AvatarGroup supports three layouts: `spread` (default), `stack`, and `pie`.
+
+## Property mapping
+
+| v8 `Facepile`            | v9 `AvatarGroup`                                         |
+| ------------------------ | -------------------------------------------------------- |
+| `personas`               | `children`                                               |
+| `addButtonProps`         | -                                                        |
+| `className`              | `className`                                              |
+| `getPersonaProps`        | `AvatarGroupItem`'s props                                |
+| `maxDisplayablePersonas` | `maxAvatars`                                             |
+| `onRenderPersona`        | Render function for the AvatarGroupItem                  |
+| `onRenderPersonaCoin`    | Render function for the `avatar` slot in AvatarGroupItem |
+| `onRenderPersonaWrapper` | -                                                        |
+| `overflowButtonProps`    | `overflowButton` slot props                              |
+| `overflowButtonType`     | `overflowIndicator`                                      |
+| `overflowPersonas`       | -                                                        |
+| `personaSize`            | `size`                                                   |
+| `showAddButton`          | -                                                        |
+| `showTooltip`            | -                                                        |
+| `styles`                 | (theme)                                                  |

packages/react-components/react-avatar/README-AvatarGroup.md

@@ -0,0 +1,39 @@
+# @fluentui/react-avatar
+
+**React AvatarGroup component for [Fluent UI](https://dev.microsoft.com/fluentui)**
+
+The AvatarGroup component represents a group of multiple people or entities by taking care of the arrangement of individual Avatars in a spread, stack, or pie layout.
+
+## STATUS: WIP 🚧
+
+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 AvatarGroup and AvatarGroupItem:
+
+```js
+import { AvatarGroup, AvatarGroupItem } from '@fluentui/react-avatar';
+```
+
+Once the AvatarGroup component graduates to a production release, the component will be available at:
+
+```js
+import { AvatarGroup, AvatarGroupItem } from '@fluentui/react-components';
+```
+
+### Examples
+
+```jsx
+<AvatarGroup>
+  <AvatarGroupItem name="Katri Athokas" />
+  <AvatarGroupItem name="Elvia Atkins" />
+  <AvatarGroupItem name="Cameron Evans" />
+  <AvatarGroupItem name="Wanda Howard" />
+  <AvatarGroupItem name="Mona Kane" />
+  <AvatarGroupItem name="Allan Munger" />
+  <AvatarGroupItem name="Daisy Phillips" />
+  <AvatarGroupItem name="Robert Tolbert" />
+  <AvatarGroupItem name="Kevin Sturgis" />
+</AvatarGroup>
+```