@fluentui/react-avatar 9.0.4 → 9.1.0

package/CHANGELOG.json

@@ -2,7 +2,182 @@
   "name": "@fluentui/react-avatar",
   "entries": [
     {
-      "date": "Wed, 03 Aug 2022 16:00:05 GMT",
+      "date": "Thu, 15 Sep 2022 09:45:10 GMT",
+      "tag": "@fluentui/react-avatar_v9.1.0",
+      "version": "9.1.0",
+      "comments": {
+        "patch": [
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "5baea110a12d6c161c36b19b5b6768eeaa8370de",
+            "comment": "chore: Change content to render as ul and list item to render as li."
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "abc61d6bf47190f96b5e32ed3b7df4b77614caaf",
+            "comment": "chore: Cleaning up use of AvatarGroup context."
+          },
+          {
+            "author": "behowell@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "e598325b985cad3e5057f00893e0176416edd292",
+            "comment": "refactor: Replace useMergedEventCallbacks utility with mergeCallbacks"
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "4de0899dd07982aabdc611b1837bf9acfca44efc",
+            "comment": "fix: Making PopoverSurface focusable, moving Overflow aria-label to PopoverSurface, and moving content styles to PopoverSurface."
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "a66448342c1f3e6a6911404486aef904529988c4",
+            "comment": "fix: Set aria-hidden to AvatarGroupItem's label."
+          },
+          {
+            "author": "olfedias@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "e610024474cfe5d45f61501a8b6a21daf4c794a2",
+            "comment": "chore: Update Griffel to latest version"
+          },
+          {
+            "author": "miroslav.stastny@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "0137f992b99b3b8ec927be8f7aef751d27cd5830",
+            "comment": "fix: Rename colorNeutralForegroundInvertedStatic token to colorNeutralForegroundStaticInverted"
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "1542e766427a7f0b1ee122d507b7f50ebcb51a3c",
+            "comment": "chore: Update tests and add e2e tests."
+          },
+          {
+            "author": "seanmonahan@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "1d0a72865a151962362aa3e5054ac9bf8178f09c",
+            "comment": "fix: update color tokens"
+          },
+          {
+            "author": "lingfangao@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "a606fbedcf7d618d1a48706a5e15c26c4cd85ba6",
+            "comment": "chore: fix no-context-default-value lint violations for cxe"
+          }
+        ],
+        "none": [
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "c5249ee380c5e17651b5122a716fcf5e4c477ad1",
+            "comment": "docs: Updating AvatarGroup's migration guide."
+          },
+          {
+            "author": "martinhochel@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "ba9444d594f3a960cc590eae5237c08bf7c5a07f",
+            "comment": "chore: consume cypress.config from it's package boundary"
+          },
+          {
+            "author": "martinhochel@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "e6cf183695d6d67a24e038c49a876224e5ed35e5",
+            "comment": "chore: update package scaffold"
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "ab54d44126b26316d662551bbdd93bf5b044b022",
+            "comment": "docs: Update spec to match implementation, add best practices, and update README."
+          },
+          {
+            "author": "martinhochel@microsoft.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "16aa65dcae8f75c6a221225fd0eb43800650ac66",
+            "comment": "docs: re-generate api.md files"
+          }
+        ],
+        "minor": [
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "66762e1ca870a21db46b72c9b0848c5b107b8e09",
+            "comment": "feat: Adding functionality to AvatarGroupOverflow and updating AvatarGroup to use AvatarGroupOverflow."
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "84e2b1a8b1e8d2e9008297b6c35c76231ae3a31c",
+            "comment": "chore: Renaming AvatarGroupOverflow to AvatarGroupPopover."
+          },
+          {
+            "author": "esteban.230@hotmail.com",
+            "package": "@fluentui/react-avatar",
+            "commit": "27a3480f5361aa5d99f8978817d8395d9037e3b7",
+            "comment": "feat: Add pie layout implementation."
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-badge to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-context-selector to v9.0.3",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-popover to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-shared-contexts to v9.0.1",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-tabster to v9.1.1",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-theme to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-tooltip to v9.0.5",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-utilities to v9.1.0",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          },
+          {
+            "author": "beachball",
+            "package": "@fluentui/react-avatar",
+            "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.13",
+            "commit": "a33448fe4a0f4117686c378f80b893d1406d95a8"
+          }
+        ]
+      }
+    },
+    {
+      "date": "Wed, 03 Aug 2022 16:03:37 GMT",
       "tag": "@fluentui/react-avatar_v9.0.4",
       "version": "9.0.4",
       "comments": {
@@ -43,31 +218,31 @@
             "author": "beachball",
             "package": "@fluentui/react-avatar",
             "comment": "Bump @fluentui/react-badge to v9.0.4",
-            "commit": "54bc6105c5c9c9023da35d4670239e44117ed4a5"
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
           },
           {
             "author": "beachball",
             "package": "@fluentui/react-avatar",
             "comment": "Bump @fluentui/react-popover to v9.0.4",
-            "commit": "54bc6105c5c9c9023da35d4670239e44117ed4a5"
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
           },
           {
             "author": "beachball",
             "package": "@fluentui/react-avatar",
             "comment": "Bump @fluentui/react-tabster to v9.1.0",
-            "commit": "54bc6105c5c9c9023da35d4670239e44117ed4a5"
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
           },
           {
             "author": "beachball",
             "package": "@fluentui/react-avatar",
             "comment": "Bump @fluentui/react-tooltip to v9.0.4",
-            "commit": "54bc6105c5c9c9023da35d4670239e44117ed4a5"
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
           },
           {
             "author": "beachball",
             "package": "@fluentui/react-avatar",
             "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.12",
-            "commit": "54bc6105c5c9c9023da35d4670239e44117ed4a5"
+            "commit": "ee4a8be0d0831a6615f878f98db6a97cc61a802d"
           }
         ]
       }

package/CHANGELOG.md

@@ -1,23 +1,56 @@
 # Change Log - @fluentui/react-avatar
 
-This log was last generated on Wed, 03 Aug 2022 16:00:05 GMT and should not be manually modified.
+This log was last generated on Thu, 15 Sep 2022 09:45:10 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## [9.1.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-avatar_v9.1.0)
+
+Thu, 15 Sep 2022 09:45:10 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-avatar_v9.0.4..@fluentui/react-avatar_v9.1.0)
+
+### Minor changes
+
+- feat: Adding functionality to AvatarGroupOverflow and updating AvatarGroup to use AvatarGroupOverflow. ([PR #24115](https://github.com/microsoft/fluentui/pull/24115) by esteban.230@hotmail.com)
+- chore: Renaming AvatarGroupOverflow to AvatarGroupPopover. ([PR #24338](https://github.com/microsoft/fluentui/pull/24338) by esteban.230@hotmail.com)
+- feat: Add pie layout implementation. ([PR #24241](https://github.com/microsoft/fluentui/pull/24241) by esteban.230@hotmail.com)
+- Bump @fluentui/react-badge to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-context-selector to v9.0.3 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-popover to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-shared-contexts to v9.0.1 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-tabster to v9.1.1 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-theme to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-tooltip to v9.0.5 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-utilities to v9.1.0 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+- Bump @fluentui/react-conformance-griffel to v9.0.0-beta.13 ([PR #24808](https://github.com/microsoft/fluentui/pull/24808) by beachball)
+
+### Patches
+
+- chore: Change content to render as ul and list item to render as li. ([PR #24347](https://github.com/microsoft/fluentui/pull/24347) by esteban.230@hotmail.com)
+- chore: Cleaning up use of AvatarGroup context. ([PR #24459](https://github.com/microsoft/fluentui/pull/24459) by esteban.230@hotmail.com)
+- refactor: Replace useMergedEventCallbacks utility with mergeCallbacks ([PR #24152](https://github.com/microsoft/fluentui/pull/24152) by behowell@microsoft.com)
+- fix: Making PopoverSurface focusable, moving Overflow aria-label to PopoverSurface, and moving content styles to PopoverSurface. ([PR #24417](https://github.com/microsoft/fluentui/pull/24417) by esteban.230@hotmail.com)
+- fix: Set aria-hidden to AvatarGroupItem's label. ([PR #24359](https://github.com/microsoft/fluentui/pull/24359) by esteban.230@hotmail.com)
+- chore: Update Griffel to latest version ([PR #24221](https://github.com/microsoft/fluentui/pull/24221) by olfedias@microsoft.com)
+- fix: Rename colorNeutralForegroundInvertedStatic token to colorNeutralForegroundStaticInverted ([PR #24611](https://github.com/microsoft/fluentui/pull/24611) by miroslav.stastny@microsoft.com)
+- chore: Update tests and add e2e tests. ([PR #24348](https://github.com/microsoft/fluentui/pull/24348) by esteban.230@hotmail.com)
+- fix: update color tokens ([PR #24027](https://github.com/microsoft/fluentui/pull/24027) by seanmonahan@microsoft.com)
+- chore: fix no-context-default-value lint violations for cxe ([PR #24277](https://github.com/microsoft/fluentui/pull/24277) by lingfangao@hotmail.com)
+
 ## [9.0.4](https://github.com/microsoft/fluentui/tree/@fluentui/react-avatar_v9.0.4)
 
-Wed, 03 Aug 2022 16:00:05 GMT 
+Wed, 03 Aug 2022 16:03:37 GMT 
 [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-avatar_v9.0.3..@fluentui/react-avatar_v9.0.4)
 
 ### Patches
 
 - bugfix: add reduced motion styles for avatar, spinner, switch, and input focus styles ([PR #23788](https://github.com/microsoft/fluentui/pull/23788) by sarah.higley@microsoft.com)
 - chore: Bump Griffel dependencies ([PR #24114](https://github.com/microsoft/fluentui/pull/24114) by miroslav.stastny@microsoft.com)
-- Bump @fluentui/react-badge to v9.0.4 ([PR #24201](https://github.com/microsoft/fluentui/pull/24201) by beachball)
-- Bump @fluentui/react-popover to v9.0.4 ([PR #24201](https://github.com/microsoft/fluentui/pull/24201) by beachball)
-- Bump @fluentui/react-tabster to v9.1.0 ([PR #24201](https://github.com/microsoft/fluentui/pull/24201) by beachball)
-- Bump @fluentui/react-tooltip to v9.0.4 ([PR #24201](https://github.com/microsoft/fluentui/pull/24201) by beachball)
-- Bump @fluentui/react-conformance-griffel to v9.0.0-beta.12 ([PR #24201](https://github.com/microsoft/fluentui/pull/24201) by beachball)
+- Bump @fluentui/react-badge to v9.0.4 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)
+- Bump @fluentui/react-popover to v9.0.4 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)
+- Bump @fluentui/react-tabster to v9.1.0 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)
+- Bump @fluentui/react-tooltip to v9.0.4 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)
+- Bump @fluentui/react-conformance-griffel to v9.0.0-beta.12 ([PR #24131](https://github.com/microsoft/fluentui/pull/24131) by beachball)
 
 ## [9.0.3](https://github.com/microsoft/fluentui/tree/@fluentui/react-avatar_v9.0.3)
 

package/README-AvatarGroup.md

@@ -1,39 +1,63 @@
-# @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>
-```
+# @fluentui/react-avatar
+
+**React AvatarGroup component for [Fluent UI](https://react.fluentui.dev)**
+
+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, AvatarGroupItem, AvatarGroupPopover, and partitionAvatarGroupItems:
+
+```js
+import { AvatarGroup, AvatarGroupItem, AvatarGroupPopover, partitionAvatarGroupItems } from '@fluentui/react-avatar';
+```
+
+Once the AvatarGroup component graduates to a production release, the component will be available at:
+
+```js
+import {
+  AvatarGroup,
+  AvatarGroupItem,
+  AvatarGroupPopover,
+  partitionAvatarGroupItems,
+} from '@fluentui/react-components';
+```
+
+### Examples
+
+```jsx
+const names = [
+  'Johnie McConnell',
+  'Allan Munger',
+  'Erik Nason',
+  'Kristin Patterson',
+  'Daisy Phillips',
+  'Carole Poland',
+  'Carlos Slattery',
+  'Robert Tolbert',
+  'Kevin Sturgis',
+  'Charlotte Waltson',
+  'Elliot Woodward',
+];
+
+const AvatarGroup = () => {
+  const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: names });
+
+  return (
+    <AvatarGroup {...props}>
+      {inlineItems.map(name => (
+        <AvatarGroupItem name={name} key={name} />
+      ))}
+      <AvatarGroupPopover>
+        {overflowItems.map(name => (
+          <AvatarGroupItem name={name} key={name} />
+        ))}
+      </AvatarGroupPopover>
+    </AvatarGroup>
+  );
+};
+```

package/SPEC-AvatarGroup.md

@@ -28,16 +28,33 @@ There's only one existent component similar to AvatarGroup in v8 `Facepile`. v0
 ## Sample Code
 
 ```jsx
-import { AvatarGroup, Avatar } from '@fluentui/react-avatar';
+const names = [
+  'Johnie McConnell',
+  'Allan Munger',
+  'Erik Nason',
+  'Kristin Patterson',
+  'Daisy Phillips',
+  'Carole Poland',
+  'Carlos Slattery',
+  'Robert Tolbert',
+  'Kevin Sturgis',
+  'Charlotte Waltson',
+  'Elliot Woodward',
+];
+
+const AvatarGroup = () => {
+  const { inlineItems, overflowItems } = partitionAvatarGroupItems({ items: names });
 
-const App = () => {
   return (
-    <AvatarGroup layout="spread" size={32}>
-      <Avatar color="colorful" name="Katri Athokas" />
-      <Avatar color="colorful" name="Elvia Atkins" />
-      <Avatar color="colorful" name="Cameron Evans" />
-      <Avatar color="colorful" name="Wanda Howard" />
-      <Avatar color="colorful" name="Mona Kane" />
+    <AvatarGroup {...props}>
+      {inlineItems.map(name => (
+        <AvatarGroupItem name={name} key={name} />
+      ))}
+      <AvatarGroupPopover>
+        {overflowItems.map(name => (
+          <AvatarGroupItem name={name} key={name} />
+        ))}
+      </AvatarGroupPopover>
     </AvatarGroup>
   );
 };
@@ -49,79 +66,77 @@ There are three layout variants in AvatarGroup:
 
 - Spread layout (Default): Avatars are spaced evenly.
 - Stack layout: Avatars are overlapped evenly.
-- Pie layout: For the pie layout there can be a minimum of two Avatars and a maximum of three. This layout does not overflow and provides a popover for more details.
-
-  - If the size of the avatar group is `36` or smaller then only the first letter of the initials will be displayed.
-  - `maxAvatars` will be ignored when using this layout.
-
-- The `spread` and `stack` layouts have a maximum of 5 avatars before overflowing by default, which can be overridden via the `maxAvatars` prop.
+- Pie layout: Avatars are "cut" in a pie design. When there are two Avatars inline, the Avatars will be cut in half and placed side by side. When there are three Avatars inline, the first Avatar will be cut in half and other two will be downscaled by 50%.
+  - The pie layout must have 3 or less Avatars inline and all Avatars must repeat in the `AvatarGroupPopover`. This is handled by `partitionAvatarGroupItems`.
+- If `partitionAvatarGroupItems` is used, the `spread` and `stack` layouts will have a maximum of 5 avatars before overflowing by default. This can be overridden via the `maxAvatars` option in `partitionAvatarGroupItems`.
 
 ## API
 
-See [AvatarGroup.types.ts](./src/components/AvatarGroup/AvatarGroup.types.ts) for more details.
+See [AvatarGroup.types.ts](./src/components/AvatarGroup/AvatarGroup.types.ts), [AvatarGroupPopover.types.ts](./src/components/AvatarGroupPopover/AvatarGroupPopover.types.ts) and [AvatarGroupItem.types.ts](./src/components/AvatarGroupItem/AvatarGroupItem.types.ts) for more details.
 
 - `size`: Group size will override the children's current size. This is to ensure that the `AvatarGroup`'s spacing is correct because it changes depending on the group size.
-- `popoverSurface`: All Avatars in `popoverSurface` will have a size of 24 and will be encased in a div to apply stylings.
-- Avatar `color`: AvatarGroup's colors will follow the order below, but they can be overriden by providing a color specific color on a given avatar.
+- `AvatarGroupPopover`: All Avatars in `AvatarGroupPopover` will have a size of 24 and have a wrapper to apply stylings.
+- AvatarGroupItem `color`: Can be overridden by providing a specific color on a given avatar.
 
 #### Color override example:
 
-In this example, the first Avatar will have a `darkRed` color, while all the other avatars will follow the default color order.
+In this example, the first AvatarGroupItem will have a `darkRed` color, while all the other Avatars have their color assigned by Avatar.
 
 ```jsx
 <AvatarGroup>
-  <Avatar color="darkRed" name="Katri Athokas" />
-  <Avatar name="Elvia Atkins" />
-  <Avatar name="Cameron Evans" />
-  <Avatar name="Wanda Howard" />
-  <Avatar name="Mona Kane" />
+  <AvatarGroupItem color="darkRed" name="Katri Athokas" />
+  <AvatarGroupItem name="Elvia Atkins" />
+  <AvatarGroupItem name="Cameron Evans" />
+  <AvatarGroupItem name="Wanda Howard" />
+  <AvatarGroupItem name="Mona Kane" />
 </AvatarGroup>
 ```
 
-#### Color order:
-
-|                       |                    |                       |
-| --------------------- | ------------------ | --------------------- |
-| Avatar 1: Red         | Avatar 2: Blue     | Avatar 3: Purple      |
-| Avatar 4: Forest      | Avatar 5: Pink     | Avatar 6: Lavender    |
-| Avatar 7: Teal        | Avatar 8: Gold     | Avatar 9: Cranberry   |
-| Avatar 10: Cornflower | Avatar 11: Lilac   | Avatar 12: Anchor     |
-| Avatar 13: Dark Green | Avatar 14: Pumpkin | Avatar 15: Dark Red   |
-| Avatar 16: Mink       | Avatar 17: Grape   | Avatar 18: Platinum   |
-| Avatar 19: Royal Blue | Avatar 20: Brown   | Avatar 21: Peach      |
-| Avatar 22: Steel      | Avatar 23: Navy    | Avatar 24: Seafoam    |
-| Avatar 25: Magenta    | Avatar 26: Beige   | Avatar 27: Light Teal |
-| Avatar 28: Gold       | Avatar 29: Plum    | Avatar 30: Marigold   |
-
 ## Structure
 
 - _**Public**_
 
 ```jsx
 <AvatarGroup layout="spread" size={32}>
-  <Avatar name="Katri Athokas" />
-  <Avatar name="Elvia Atkins" />
-  <Avatar name="Cameron Evans" />
-  <Avatar name="Wanda Howard" />
-  <Avatar name="Mona Kane" />
+  <AvatarGroupItem name="Katri Athokas" />
+  <AvatarGroupItem name="Elvia Atkins" />
+  <AvatarGroupItem name="Cameron Evans" />
+  <AvatarGroupItem name="Wanda Howard" />
+  <AvatarGroupPopover>
+    <AvatarGroupItem name="Mona Kane" />
+    <AvatarGroupItem name="Kristin Patterson" />
+    <AvatarGroupItem name="Elliot Woodward" />
+    <AvatarGroupItem name="Charlotte Waltson" />
+  </AvatarGroupPopover>
 </AvatarGroup>
 ```
 
 - _**Internal**_
 
 ```jsx
+// AvatarGroup
+<AvatarGroupProvider value={contextValues.avatarGroup}>
+  <slots.root {...slotProps.root} />
+</AvatarGroupProvider>
+
+// AvatarGroupPopover
+<slots.root {...(slotProps.root as PopoverProps)}>
+  <PopoverTrigger>
+    <slots.tooltip {...(slotProps.tooltip as TooltipProps)}>
+      <slots.triggerButton {...slotProps.triggerButton} />
+    </slots.tooltip>
+  </PopoverTrigger>
+  <slots.popoverSurface {...slotProps.popoverSurface}>
+    <AvatarGroupProvider value={contextValues.avatarGroup}>
+      <slots.content {...slotProps.content} />
+    </AvatarGroupProvider>
+  </slots.popoverSurface>
+</slots.root>
+
+// AvatarGroupItem
 <slots.root {...slotProps.root}>
-  {state.root.children}
-  {slots.popoverSurface && slots.popoverTrigger && slotProps.popoverSurface.children && (
-    <Popover trapFocus size="small">
-      <PopoverTrigger>
-        <Tooltip content={state.tooltipContent} relationship="description" appearance="inverted">
-          <slots.popoverTrigger {...slotProps.popoverTrigger} />
-        </Tooltip>
-      </PopoverTrigger>
-      <slots.popoverSurface {...slotProps.popoverSurface} />
-    </Popover>
-  )}
+  <slots.avatar {...slotProps.avatar} />
+  {state.isOverflowItem && <slots.overflowLabel {...slotProps.overflowLabel} />}
 </slots.root>
 ```
 
@@ -129,46 +144,49 @@ In this example, the first Avatar will have a `darkRed` color, while all the oth
 
 ```html
 <div className="fui-AvatarGroup" role="group">
-  <Avatar />
-  <Avatar />
-  <Avatar />
-  <Avatar />
-  <button>+1</button>
-</div>
-
-// on document.body
-<div class="fui-AvatarGroup__popoverSurface" role="complementary">
-  <div class="fui-AvatarGroup__popoverSurfaceItem">
+  <div class="fui-AvatarGroupItem">
     <Avatar />
-    <label />
   </div>
-  <!-- ... -->
-  <div class="fui-AvatarGroup__popoverSurfaceItem">
+  <div class="fui-AvatarGroupItem">
     <Avatar />
-    <label />
   </div>
+  <button>+1</button>
+</div>
+
+// on document.body
+<div class="fui-AvatarGroupPopover" role="dialog" aria-label="Overflow">
+  <ul>
+    <li class="fui-AvatarGroupItem">
+      <Avatar />
+      <label />
+    </li>
+    <li class="fui-AvatarGroupItem">
+      <Avatar />
+      <label />
+    </li>
+  </ul>
 </div>
 ```
 
 ## Migration
 
-See [MIGRATION-AvatarGroup.md](MIGRATION-AvatarGroup.md) for details.
+See [v8 to v9 migration guide](https://react.fluentui.dev/?path=/docs/concepts-upgrading-from-v8-components-avatargroup-upgrade--page) for details.
 
 ## Behaviors
 
 _Explain how the component will behave in use, including:_
 
-- _Component States_
-  - Overflowed state: When there are more Avatars than the `maxAvatars`, an overflow indicator will be rendered that can be clicked to look at the rest of the avatars.
-    - `Pie` layout: since `maxAvatars` is ignored, the overflow indicator will be rendered strictly when there's more than three avatars.
-- _Interaction_
-  - _Keyboard_: Overflow indicator can be interacted with the keyboard and when enter is pressed a popover that traps focus will be rendered.
-  - _Cursor_ and _Touch_: When overflow indicator is clicked, the popover is displayed with the avatars that overflow. When the overflow indicator is hovered, a tooltip will read the number of people overflowed (`{numOverflowAvatars} more people` by default).
+- _AvatarGroupPopover Component States_
+
+  - _Keyboard_: `triggerButton` can be interacted with the keyboard and when enter is pressed a popover that traps focus on the PopoverSurface will be rendered.
+  - _Cursor_ and _Touch_: When overflow indicator is clicked, the popover is displayed with the avatars that overflow. When the overflow indicator is hovered, a tooltip will read `View more people.`.
+  - _Screen readers_:
+    - When the `triggerButton` is focused, its content will be read.
+
+- _AvatarGroupItem Component States_
   - _Screen readers_:
-    - `Avatar`: logic is handled by `Avatar` component.
-    - `AvatarGroup`:
-      - When a label is used alongside `AvatarGroup` and focused, all Avatars are read. If the overflow indicator is rendered, the popover localized text is read.
-      - Avatars can be focused and the name will be read. To get to the Avatars in the overflow menu, the Popover must be triggered, which will in turn set focus on it and let the user traverse through the set of overflowed Avatars.
+    - When AvatarGroupItem is rendered inline, logic is handled by `Avatar` component.
+    - When AvatarGroupItem is rendered inside AvatarGroupPopover, the label is disabled via `aria-label` and `Avatar` will handle the screen reader.
 
 ## Accessibility
 
@@ -176,10 +194,10 @@ Base accessibility information is included in the design document. After the spe
 
 - There's no native element for this component.
 
-- `AvatarGroup` will have a role of `group` and slots will be handled by their respective slot type.
-- Only the overflow indicator will be focusable by the keyboard. After the overflow indicator is pressed, the popover will handle focus using the `trapFocus` prop.
+- `AvatarGroup` will have a role of `group`.
+- Only the `popoverTrigger` will be focusable by the keyboard.
 - There are no live-regions in `AvatarGroup`.
-- A Tooltip will appear when the overflow indicator is hovered or focused.
-  - Screen reader: when overflow indicator is rendered and focused, screen reader will read the content of the tooltip.
-  - Tooltip cannot be focused itself.
-- Focus will only be trapped when the overflow indicator is triggered.
+- A Tooltip will appear when the `popoverTrigger` is hovered or focused.
+- Focus will only be trapped when the `popoverTrigger` is triggered.
+- The label rendered along with the Avatar inside AvatarGroupPopover is disabled via `aria-label`.
+- A `<ul>` with role list is rendered inside the PopoverSurface.