feat(react-headless-components-preview): add AvatarGroup component (#36350)

Author: dmytrokirpa

change/@fluentui-react-headless-components-preview-48da31d5-627a-41b6-a90b-014c11660079.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add AvatarGroup, AvatarGroupItem, and AvatarGroupPopover components",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "dmytrokirpa@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-headless-components-preview/library/bundle-size/AllComponents.fixture.js

@@ -1,5 +1,6 @@
 import * as Accordion from '@fluentui/react-headless-components-preview/accordion';
 import * as Avatar from '@fluentui/react-headless-components-preview/avatar';
+import * as AvatarGroup from '@fluentui/react-headless-components-preview/avatar-group';
 import * as Badge from '@fluentui/react-headless-components-preview/badge';
 import * as Breadcrumb from '@fluentui/react-headless-components-preview/breadcrumb';
 import * as Button from '@fluentui/react-headless-components-preview/button';
@@ -48,6 +49,7 @@ import * as Tooltip from '@fluentui/react-headless-components-preview/tooltip';
 console.log({
   Accordion,
   Avatar,
+  AvatarGroup,
   Badge,
   Breadcrumb,
   Button,

packages/react-components/react-headless-components-preview/library/etc/avatar-group.api.md

@@ -0,0 +1,116 @@
+## API Report File for "@fluentui/react-headless-components-preview"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { AvatarGroupContextValue } from '@fluentui/react-avatar';
+import { AvatarGroupContextValues } from '@fluentui/react-avatar';
+import type { AvatarGroupItemBaseProps } from '@fluentui/react-avatar';
+import { AvatarGroupItemSlots } from '@fluentui/react-avatar';
+import { AvatarGroupItemBaseState as AvatarGroupItemState } from '@fluentui/react-avatar';
+import { AvatarGroupBaseProps as AvatarGroupProps } from '@fluentui/react-avatar';
+import type { AvatarGroupProps as AvatarGroupProps_2 } from '@fluentui/react-avatar';
+import { AvatarGroupSlots } from '@fluentui/react-avatar';
+import { AvatarGroupBaseState as AvatarGroupState } from '@fluentui/react-avatar';
+import type { ComponentProps } from '@fluentui/react-utilities';
+import type { ComponentState } from '@fluentui/react-utilities';
+import type { EventData } from '@fluentui/react-utilities';
+import type { EventHandler } from '@fluentui/react-utilities';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import type { JSXElement } from '@fluentui/react-utilities';
+import { PartitionAvatarGroupItems } from '@fluentui/react-avatar';
+import { partitionAvatarGroupItems } from '@fluentui/react-avatar';
+import { PartitionAvatarGroupItemsOptions } from '@fluentui/react-avatar';
+import { PositioningShorthand } from '@fluentui/react-positioning';
+import type * as React_2 from 'react';
+import { renderAvatarGroup_unstable as renderAvatarGroup } from '@fluentui/react-avatar';
+import { renderAvatarGroupItem_unstable as renderAvatarGroupItem } from '@fluentui/react-avatar';
+import type { Slot } from '@fluentui/react-utilities';
+import type { TooltipBaseProps } from '@fluentui/react-tooltip';
+
+// @public
+export const AvatarGroup: ForwardRefComponent<AvatarGroupProps>;
+
+export { AvatarGroupContextValue }
+
+export { AvatarGroupContextValues }
+
+// @public
+export const AvatarGroupItem: ForwardRefComponent<AvatarGroupItemProps>;
+
+// @public
+export type AvatarGroupItemProps = Omit<AvatarGroupItemBaseProps, 'color' | 'idForColor'>;
+
+export { AvatarGroupItemSlots }
+
+export { AvatarGroupItemState }
+
+// @public
+export const AvatarGroupPopover: {
+    (props: AvatarGroupPopoverProps): JSXElement;
+    displayName: string;
+};
+
+// @public
+export type AvatarGroupPopoverPopoverProps = Pick<PopoverProps, 'open' | 'defaultOpen' | 'onOpenChange' | 'openOnHover' | 'openOnContext' | 'mouseLeaveDelay' | 'positioning' | 'withArrow' | 'trapFocus'>;
+
+// @public
+export type AvatarGroupPopoverProps = Omit<ComponentProps<Partial<AvatarGroupPopoverSlots>>, 'children'> & AvatarGroupPopoverPopoverProps & {
+    indicator?: 'count' | 'icon';
+    count?: number;
+    children: React_2.ReactNode;
+};
+
+// @public (undocumented)
+export type AvatarGroupPopoverSlots = {
+    triggerButton: NonNullable<Slot<'button'>>;
+    tooltip: NonNullable<Slot<typeof Tooltip>>;
+    content: NonNullable<Slot<'ul'>>;
+    popoverSurface: NonNullable<Slot<typeof PopoverSurface>>;
+};
+
+// @public
+export type AvatarGroupPopoverState = ComponentState<AvatarGroupPopoverSlots> & Required<Pick<AvatarGroupPopoverProps, 'count' | 'indicator'>> & {
+    popoverOpen: boolean;
+    layout: AvatarGroupProps_2['layout'];
+    popover: AvatarGroupPopoverPopoverProps;
+};
+
+export { AvatarGroupProps }
+
+export { AvatarGroupSlots }
+
+export { AvatarGroupState }
+
+export { PartitionAvatarGroupItems }
+
+export { partitionAvatarGroupItems }
+
+export { PartitionAvatarGroupItemsOptions }
+
+export { renderAvatarGroup }
+
+export { renderAvatarGroupItem }
+
+// @public
+export const renderAvatarGroupPopover: (state: AvatarGroupPopoverState, contextValues: AvatarGroupContextValues) => JSXElement;
+
+// @public
+export const useAvatarGroup: (props: AvatarGroupProps, ref: React_2.Ref<HTMLElement>) => AvatarGroupState;
+
+// @public
+export const useAvatarGroupContextValues: (state: AvatarGroupState) => AvatarGroupContextValues;
+
+// @public
+export const useAvatarGroupItem: (props: AvatarGroupItemProps, ref: React_2.Ref<HTMLElement>) => AvatarGroupItemState;
+
+// @public
+export const useAvatarGroupPopover: (props: AvatarGroupPopoverProps) => AvatarGroupPopoverState;
+
+// @public
+export const useAvatarGroupPopoverContextValues: (state: AvatarGroupPopoverState) => AvatarGroupContextValues;
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/react-components/react-headless-components-preview/library/package.json

@@ -87,6 +87,12 @@
       "import": "./lib/avatar.js",
       "require": "./lib-commonjs/avatar.js"
     },
+    "./avatar-group": {
+      "types": "./dist/avatar-group.d.ts",
+      "node": "./lib-commonjs/avatar-group.js",
+      "import": "./lib/avatar-group.js",
+      "require": "./lib-commonjs/avatar-group.js"
+    },
     "./badge": {
       "types": "./dist/badge.d.ts",
       "node": "./lib-commonjs/badge.js",

packages/react-components/react-headless-components-preview/library/src/avatar-group.ts

@@ -0,0 +1,30 @@
+export {
+  AvatarGroup,
+  renderAvatarGroup,
+  useAvatarGroup,
+  useAvatarGroupContextValues,
+  AvatarGroupItem,
+  renderAvatarGroupItem,
+  useAvatarGroupItem,
+  AvatarGroupPopover,
+  renderAvatarGroupPopover,
+  useAvatarGroupPopover,
+  useAvatarGroupPopoverContextValues,
+} from './components/AvatarGroup/index';
+export type {
+  AvatarGroupSlots,
+  AvatarGroupProps,
+  AvatarGroupState,
+  AvatarGroupContextValue,
+  AvatarGroupContextValues,
+  AvatarGroupItemSlots,
+  AvatarGroupItemProps,
+  AvatarGroupItemState,
+  AvatarGroupPopoverSlots,
+  AvatarGroupPopoverProps,
+  AvatarGroupPopoverState,
+  AvatarGroupPopoverPopoverProps,
+} from './components/AvatarGroup/index';
+
+export { partitionAvatarGroupItems } from '@fluentui/react-avatar';
+export type { PartitionAvatarGroupItems, PartitionAvatarGroupItemsOptions } from '@fluentui/react-avatar';

packages/react-components/react-headless-components-preview/library/src/components/AvatarGroup/AvatarGroup.test.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { render } from '@testing-library/react';
+import { isConformant } from '../../testing/isConformant';
+import { AvatarGroup } from './AvatarGroup';
+import { AvatarGroupItem } from './AvatarGroupItem/AvatarGroupItem';
+
+describe('AvatarGroup', () => {
+  isConformant({
+    Component: AvatarGroup,
+    displayName: 'AvatarGroup',
+  });
+
+  it('renders a default state', () => {
+    const { getByRole } = render(
+      <AvatarGroup>
+        <AvatarGroupItem name="John Doe" />
+      </AvatarGroup>,
+    );
+
+    expect(getByRole('group')).toBeInTheDocument();
+  });
+
+  it('renders its AvatarGroupItem children', () => {
+    const { getAllByRole } = render(
+      <AvatarGroup>
+        <AvatarGroupItem name="John Doe" />
+        <AvatarGroupItem name="Jane Smith" />
+      </AvatarGroup>,
+    );
+
+    expect(getAllByRole('img')).toHaveLength(2);
+  });
+
+  it('forwards the layout prop through context to its items', () => {
+    const { getByRole } = render(
+      <AvatarGroup layout="stack">
+        <AvatarGroupItem name="John Doe" />
+      </AvatarGroup>,
+    );
+
+    // The group renders as a `role="group"` container regardless of layout.
+    expect(getByRole('group')).toBeInTheDocument();
+  });
+});

packages/react-components/react-headless-components-preview/library/src/components/AvatarGroup/AvatarGroup.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import * as React from 'react';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+
+import type { AvatarGroupProps } from './AvatarGroup.types';
+import { useAvatarGroup } from './useAvatarGroup';
+import { useAvatarGroupContextValues } from './useAvatarGroupContextValues';
+import { renderAvatarGroup } from './renderAvatarGroup';
+
+/**
+ * The AvatarGroup component displays a group of Avatars, each represented as an AvatarGroupItem.
+ */
+export const AvatarGroup: ForwardRefComponent<AvatarGroupProps> = React.forwardRef((props, ref) => {
+  const state = useAvatarGroup(props, ref);
+  const contextValues = useAvatarGroupContextValues(state);
+
+  return renderAvatarGroup(state, contextValues);
+});
+
+AvatarGroup.displayName = 'AvatarGroup';

packages/react-components/react-headless-components-preview/library/src/components/AvatarGroup/AvatarGroup.types.ts

@@ -0,0 +1,7 @@
+export type {
+  AvatarGroupBaseProps as AvatarGroupProps,
+  AvatarGroupBaseState as AvatarGroupState,
+  AvatarGroupContextValue,
+  AvatarGroupContextValues,
+  AvatarGroupSlots,
+} from '@fluentui/react-avatar';

packages/react-components/react-headless-components-preview/library/src/components/AvatarGroup/AvatarGroupItem/AvatarGroupItem.test.tsx

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import { render, screen } from '@testing-library/react';
+import { isConformant } from '../../../testing/isConformant';
+import { AvatarGroup } from '../AvatarGroup';
+import { AvatarGroupPopover } from '../AvatarGroupPopover/AvatarGroupPopover';
+import { AvatarGroupItem } from './AvatarGroupItem';
+
+describe('AvatarGroupItem', () => {
+  isConformant({
+    Component: AvatarGroupItem,
+    displayName: 'AvatarGroupItem',
+    disabledTests: ['has-top-level-file-extra', 'component-has-root-ref'],
+  });
+
+  it('renders the headless Avatar with computed initials', () => {
+    render(
+      <AvatarGroup>
+        <AvatarGroupItem name="John Doe" />
+      </AvatarGroup>,
+    );
+
+    expect(screen.getByRole('img', { name: 'John Doe' })).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveTextContent('JD');
+  });
+
+  it('renders as a non-overflow item (div) by default', () => {
+    const { container } = render(
+      <AvatarGroup>
+        <AvatarGroupItem name="John Doe" />
+      </AvatarGroup>,
+    );
+
+    // The item root is a `div` when not inside an AvatarGroupPopover.
+    expect(container.querySelector('li')).not.toBeInTheDocument();
+  });
+
+  it('renders as an overflow item (li) with a name label inside the popover', () => {
+    render(
+      <AvatarGroup>
+        <AvatarGroupPopover defaultOpen>
+          <AvatarGroupItem name="Jane Smith" />
+        </AvatarGroupPopover>
+      </AvatarGroup>,
+    );
+
+    const listItem = screen.getByRole('listitem', { hidden: true });
+    expect(listItem.tagName).toBe('LI');
+    // The overflow label echoes the avatar name and is hidden from AT (avatar already labels it).
+    const label = screen.getByText('Jane Smith');
+    expect(label).toHaveAttribute('aria-hidden', 'true');
+  });
+});

packages/react-components/react-headless-components-preview/library/src/components/AvatarGroup/AvatarGroupItem/AvatarGroupItem.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import * as React from 'react';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+
+import type { AvatarGroupItemProps } from './AvatarGroupItem.types';
+import { useAvatarGroupItem } from './useAvatarGroupItem';
+import { renderAvatarGroupItem } from './renderAvatarGroupItem';
+
+/**
+ * An AvatarGroupItem represents a single Avatar inside an AvatarGroup. When rendered
+ * inside an AvatarGroupPopover it is displayed as an overflow item with its name label.
+ */
+export const AvatarGroupItem: ForwardRefComponent<AvatarGroupItemProps> = React.forwardRef((props, ref) => {
+  const state = useAvatarGroupItem(props, ref);
+
+  return renderAvatarGroupItem(state);
+});
+
+AvatarGroupItem.displayName = 'AvatarGroupItem';