react-avatar: Adding initial implementation of AvatarGroup.

change/@fluentui-react-avatar-32be9545-3830-48b3-bca7-aa6f556ad333.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Adding initial implementation of AvatarGroup",
+  "packageName": "@fluentui/react-avatar",
+  "email": "email not defined",
+  "dependentChangeType": "none"
+}

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

@@ -30,24 +30,34 @@ export const AvatarGroup: ForwardRefComponent<AvatarGroupProps>;
 // @public (undocumented)
 export const avatarGroupClassNames: SlotClassNames<AvatarGroupSlots>;
 
+// @public (undocumented)
+export type AvatarGroupContextValue = Pick<AvatarGroupProps, 'size' | 'layout'> & {
+    color?: AvatarProps['color'];
+};
+
+// @public (undocumented)
+export type AvatarGroupContextValues = {
+    avatarGroup: AvatarGroupContextValue;
+};
+
 // @public
-export type AvatarGroupProps = ComponentProps<AvatarGroupSlots> & {
+export type AvatarGroupProps = ComponentProps<Partial<AvatarGroupSlots>> & {
     layout?: 'spread' | 'stack' | 'pie';
     maxAvatars?: number;
-    overflowIndicator?: 'number-overflowed' | 'icon';
+    overflowIndicator?: 'count' | 'icon';
     size?: AvatarSizes;
-    strings?: AvatarGroupStrings;
 };
 
 // @public (undocumented)
 export type AvatarGroupSlots = {
-    root: Slot<'div'>;
-    popoverTrigger?: Slot<typeof Button>;
-    popoverSurface?: Slot<typeof PopoverSurface>;
+    root: NonNullable<Slot<'div'>>;
+    popoverTrigger: NonNullable<Slot<typeof Button>>;
+    popoverSurface: NonNullable<Slot<typeof PopoverSurface>>;
 };
 
 // @public
-export type AvatarGroupState = ComponentState<AvatarGroupSlots> & {
+export type AvatarGroupState = ComponentState<AvatarGroupSlots> & Required<Pick<AvatarGroupProps, 'layout' | 'maxAvatars' | 'size' | 'overflowIndicator'>> & {
+    hasOverflow: boolean;
     tooltipContent: TooltipProps['content'];
 };
 
@@ -92,7 +102,7 @@ export function getInitials(displayName: string | undefined | null, isRtl: boole
 export const renderAvatar_unstable: (state: AvatarState) => JSX.Element;
 
 // @public
-export const renderAvatarGroup_unstable: (state: AvatarGroupState) => JSX.Element;
+export const renderAvatarGroup_unstable: (state: AvatarGroupState, contextValues: AvatarGroupContextValues) => JSX.Element;
 
 // @public (undocumented)
 export const useAvatar_unstable: (props: AvatarProps, ref: React_2.Ref<HTMLElement>) => AvatarState;

packages/react-components/react-avatar/package.json

@@ -35,7 +35,9 @@
   "dependencies": {
     "@fluentui/react-badge": "9.0.0-rc.8",
     "@fluentui/react-button": "9.0.0-rc.9",
+    "@fluentui/react-context-selector": "9.0.0-rc.8",
     "@fluentui/react-icons": "^2.0.166-rc.3",
+    "@fluentui/react-label": "9.0.0-rc.1",
     "@fluentui/react-popover": "9.0.0-rc.9",
     "@fluentui/react-tooltip": "9.0.0-rc.9",
     "@fluentui/react-theme": "9.0.0-rc.7",

packages/react-components/react-avatar/src/components/Avatar/useAvatar.tsx

@@ -4,13 +4,19 @@ import { getInitials } from '../../utils/index';
 import type { AvatarNamedColor, AvatarProps, AvatarState } from './Avatar.types';
 import { PersonRegular } from '@fluentui/react-icons';
 import { PresenceBadge } from '@fluentui/react-badge';
+import { AvatarGroupContext } from '../../contexts/AvatarGroupContext';
+import { useContextSelector } from '@fluentui/react-context-selector';
 import { useFluent } from '@fluentui/react-shared-contexts';
 import { useMergedEventCallbacks } from '@fluentui/react-utilities';
 
 export const useAvatar_unstable = (props: AvatarProps, ref: React.Ref<HTMLElement>): AvatarState => {
   const { dir } = useFluent();
-  const { name, size = 32, shape = 'circular', active = 'unset', activeAppearance = 'ring', idForColor } = props;
-  let { color = 'neutral' } = props;
+  const contextColor = useContextSelector(AvatarGroupContext, ctx => ctx.color);
+  const avatarGroupLayout = useContextSelector(AvatarGroupContext, ctx => ctx.layout);
+  const size = useContextSelector(AvatarGroupContext, ctx => ctx.size) ?? props.size ?? 32;
+
+  const { name, shape = 'circular', active = 'unset', activeAppearance = 'ring', idForColor } = props;
+  let color = props.color ?? contextColor ?? 'neutral';
 
   // Resolve 'colorful' to a specific color name
   if (color === 'colorful') {
@@ -31,11 +37,13 @@ export const useAvatar_unstable = (props: AvatarProps, ref: React.Ref<HTMLElemen
     /* excludedPropNames: */ ['name'],
   );
 
+  const firstInitialOnly = size <= 16 || (avatarGroupLayout === 'pie' && size < 40);
+
   // Resolve the initials slot, defaulted to getInitials.
   let initials: AvatarState['initials'] = resolveShorthand(props.initials, {
     required: true,
     defaultProps: {
-      children: getInitials(name, dir === 'rtl', { firstInitialOnly: size <= 16 }),
+      children: getInitials(name, dir === 'rtl', { firstInitialOnly }),
       'aria-hidden': true,
     },
   });

packages/react-components/react-avatar/src/components/Avatar/useAvatarStyles.ts

@@ -216,7 +216,7 @@ const useStyles = makeStyles({
   icon48: { fontSize: '48px' },
 });
 
-const useSizeStyles = makeStyles({
+export const useSizeStyles = makeStyles({
   16: { width: '16px', height: '16px' },
   20: { width: '20px', height: '20px' },
   24: { width: '24px', height: '24px' },

packages/react-components/react-avatar/src/components/AvatarGroup/AvatarGroup.test.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { render } from '@testing-library/react';
 import { AvatarGroup } from './AvatarGroup';
 import { isConformant } from '../../common/isConformant';
+import { Avatar } from '../Avatar';
 
 describe('AvatarGroup', () => {
   // TODO: Remove component-has-static-classnames-object from disabled tests.
@@ -18,7 +19,19 @@ describe('AvatarGroup', () => {
   // TODO add more tests here, and create visual regression tests in /apps/vr-tests
 
   it('renders a default state', () => {
-    const result = render(<AvatarGroup>Default AvatarGroup</AvatarGroup>);
+    const result = render(
+      <AvatarGroup>
+        <Avatar name="Katri Athokas" />
+        <Avatar name="Elvia Atkins" />
+        <Avatar name="Cameron Evans" />
+        <Avatar name="Wanda Howard" />
+        <Avatar name="Mona Kane" />
+        <Avatar name="Allan Munger" />
+        <Avatar name="Daisy Phillips" />
+        <Avatar name="Robert Tolbert" />
+        <Avatar name="Kevin Sturgis" />
+      </AvatarGroup>,
+    );
     expect(result.container).toMatchSnapshot();
   });
 });

packages/react-components/react-avatar/src/components/AvatarGroup/AvatarGroup.tsx

@@ -4,15 +4,18 @@ import { renderAvatarGroup_unstable } from './renderAvatarGroup';
 import { useAvatarGroupStyles_unstable } from './useAvatarGroupStyles';
 import type { AvatarGroupProps } from './AvatarGroup.types';
 import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import { useAvatarGroupContextValues } from '../../contexts/useAvatarGroupContextValues';
 
 /**
- * AvatarGroup component - TODO: add more docs
+ * 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.
  */
 export const AvatarGroup: ForwardRefComponent<AvatarGroupProps> = React.forwardRef((props, ref) => {
   const state = useAvatarGroup_unstable(props, ref);
+  const contextValues = useAvatarGroupContextValues(state);
 
   useAvatarGroupStyles_unstable(state);
-  return renderAvatarGroup_unstable(state);
+  return renderAvatarGroup_unstable(state, contextValues);
 });
 
 AvatarGroup.displayName = 'AvatarGroup';

packages/react-components/react-avatar/src/components/AvatarGroup/AvatarGroup.types.ts

@@ -1,27 +1,27 @@
-import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
-import { PopoverSurface } from '@fluentui/react-popover';
-import { AvatarSizes } from '../Avatar/Avatar.types';
+import { AvatarProps, AvatarSizes } from '../Avatar/Avatar.types';
 import { Button } from '@fluentui/react-button';
+import { PopoverSurface } from '@fluentui/react-popover';
 import { TooltipProps } from '@fluentui/react-tooltip';
+import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
 
 export type AvatarGroupSlots = {
-  root: Slot<'div'>;
+  root: NonNullable<Slot<'div'>>;
 
   /**
    * Popover trigger slot that can be used to change the overflow indicator.
    */
-  popoverTrigger?: Slot<typeof Button>;
+  popoverTrigger: NonNullable<Slot<typeof Button>>;
 
   /**
    * Popover surface that will be displayed when the popover is triggered.
    */
-  popoverSurface?: Slot<typeof PopoverSurface>;
+  popoverSurface: NonNullable<Slot<typeof PopoverSurface>>;
 };
 
 /**
  * AvatarGroup Props
  */
-export type AvatarGroupProps = ComponentProps<AvatarGroupSlots> & {
+export type AvatarGroupProps = ComponentProps<Partial<AvatarGroupSlots>> & {
   /**
    * Layout the Avatars should be displayed as.
    * @default spread
@@ -37,33 +37,38 @@ export type AvatarGroupProps = ComponentProps<AvatarGroupSlots> & {
 
   /**
    * Whether the overflow indicator should render an icon instead of the number of overflowed avatars.
-   * @default false
+   * @default count
    */
-  overflowIndicator?: 'number-overflowed' | 'icon';
+  overflowIndicator?: 'count' | 'icon';
 
   /**
    * Size of the avatars.
    * @default 32
    */
   size?: AvatarSizes;
-
-  /**
-   * Strings for localizing text in the tooltip.
-   */
-  strings?: AvatarGroupStrings;
 };
 
 /**
  * State used in rendering AvatarGroup
  */
-export type AvatarGroupState = ComponentState<AvatarGroupSlots> & {
-  tooltipContent: TooltipProps['content'];
+export type AvatarGroupState = ComponentState<AvatarGroupSlots> &
+  Required<Pick<AvatarGroupProps, 'layout' | 'maxAvatars' | 'size' | 'overflowIndicator'>> & {
+    /**
+     * Whether there are more Avatars than `maxAvatars`.
+     * @default false
+     */
+    hasOverflow: boolean;
+
+    /**
+     * Tooltip content for the overflow indicator.
+     */
+    tooltipContent: TooltipProps['content'];
+  };
+
+export type AvatarGroupContextValue = Pick<AvatarGroupProps, 'size' | 'layout'> & {
+  color?: AvatarProps['color'];
 };
 
-export type AvatarGroupStrings = {
-  /**
-   * Text applied to the overflow indicator's tooltip.
-   * Can include the token "\{numOverflowedAvatars\}" which will be replaced with the number of overflowed avatars.
-   */
-  tooltipContent: string;
+export type AvatarGroupContextValues = {
+  avatarGroup: AvatarGroupContextValue;
 };

packages/react-components/react-avatar/src/components/AvatarGroup/__snapshots__/AvatarGroup.test.tsx.snap

@@ -4,8 +4,86 @@ exports[`AvatarGroup renders a default state 1`] = `
 <div>
   <div
     class="fui-AvatarGroup"
+    id="avatarGroup-7"
+    role="group"
   >
-    Default AvatarGroup
+    <span
+      aria-label="Katri Athokas"
+      class="fui-Avatar"
+      id="avatar-8"
+      role="img"
+    >
+      <span
+        aria-hidden="true"
+        class="fui-Avatar__initials"
+      >
+        KA
+      </span>
+    </span>
+    <span
+      aria-label="Elvia Atkins"
+      class="fui-Avatar"
+      id="avatar-9"
+      role="img"
+    >
+      <span
+        aria-hidden="true"
+        class="fui-Avatar__initials"
+      >
+        EA
+      </span>
+    </span>
+    <span
+      aria-label="Cameron Evans"
+      class="fui-Avatar"
+      id="avatar-10"
+      role="img"
+    >
+      <span
+        aria-hidden="true"
+        class="fui-Avatar__initials"
+      >
+        CE
+      </span>
+    </span>
+    <span
+      aria-label="Wanda Howard"
+      class="fui-Avatar"
+      id="avatar-11"
+      role="img"
+    >
+      <span
+        aria-hidden="true"
+        class="fui-Avatar__initials"
+      >
+        WH
+      </span>
+    </span>
+    <span
+      aria-label="Mona Kane"
+      class="fui-Avatar"
+      id="avatar-12"
+      role="img"
+    >
+      <span
+        aria-hidden="true"
+        class="fui-Avatar__initials"
+      >
+        MK
+      </span>
+    </span>
+    <button
+      aria-describedby="tooltip-14"
+      aria-haspopup="dialog"
+      class="fui-Button fui-AvatarGroup__popoverTrigger"
+      data-tabster="{\\"deloser\\":{}}"
+      type="button"
+    >
+      +4
+    </button>
+    <span
+      hidden=""
+    />
   </div>
 </div>
 `;

packages/react-components/react-avatar/src/components/AvatarGroup/renderAvatarGroup.tsx

@@ -1,13 +1,31 @@
 import * as React from 'react';
+import { Popover, PopoverTrigger } from '@fluentui/react-popover';
+import { Tooltip } from '@fluentui/react-tooltip';
 import { getSlots } from '@fluentui/react-utilities';
-import type { AvatarGroupState, AvatarGroupSlots } from './AvatarGroup.types';
+import type { AvatarGroupState, AvatarGroupSlots, AvatarGroupContextValues } from './AvatarGroup.types';
+import { AvatarGroupContext } from '../../contexts/AvatarGroupContext';
 
 /**
  * Render the final JSX of AvatarGroup
  */
-export const renderAvatarGroup_unstable = (state: AvatarGroupState) => {
+export const renderAvatarGroup_unstable = (state: AvatarGroupState, contextValues: AvatarGroupContextValues) => {
   const { slots, slotProps } = getSlots<AvatarGroupSlots>(state);
 
-  // TODO Add additional slots in the appropriate place
-  return <slots.root {...slotProps.root} />;
+  return (
+    <AvatarGroupContext.Provider value={contextValues.avatarGroup}>
+      <slots.root {...slotProps.root}>
+        {state.root.children}
+        {state.hasOverflow && (
+          <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.root>
+    </AvatarGroupContext.Provider>
+  );
 };