@fluentui/react-avatar 9.2.4 → 9.2.6

package/SPEC-AvatarGroup.md

@@ -1,203 +0,0 @@
-# AvatarGroup Spec
-
-## Background
-
-AvatarGroup represents a group of multiple people or entities by taking care of the arrangement of individual Avatars in a spread, stack, or pie layout.
-
-## Prior Art
-
-### OpenUI
-
-There's no current research in OpenUI's website.
-
-| Library                                                                               | Name         | Notes                                                                                         |
-| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
-| [Fluent UI v8](https://developer.microsoft.com/en-us/fluentui#/controls/web/facepile) | Facepile     | Receives list of `IFacepilePersona` to represent each avatar.                                 |
-| [Attlassian](https://atlassian.design/components/avatar-group/examples)               | Avatar group | Component uses data prop, which is a list of "entries" to represent each avatar in the group. |
-| [Ant Design](https://ant.design/components/avatar/)                                   | Avatar.Group | Uses subcomponent `<Avatar.Group>` to group the avatars given as children.                    |
-| [Primer React](https://primer.style/react/AvatarStack)                                | AvatarStack  | Acts similar to a FlexBox, avatars are given as children and grouped.                         |
-
-### Comparison v8 and v0
-
-There's only one existent component similar to AvatarGroup in v8 `Facepile`. v0 doesn't have an equivalent of this component.
-
-- v8 [Facepile](https://developer.microsoft.com/en-us/fluentui#/controls/web/facepile): Only offers spread layout and offers three overflow indicator styles.
-
-## Epic issue: [#22240](https://github.com/microsoft/fluentui/issues/22240)
-
-## Sample Code
-
-```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>
-  );
-};
-```
-
-## Variants
-
-There are three layout variants in AvatarGroup:
-
-- Spread layout (Default): Avatars are spaced evenly.
-- Stack layout: Avatars are overlapped evenly.
-- 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), [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.
-- `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 AvatarGroupItem will have a `darkRed` color, while all the other Avatars have their color assigned by Avatar.
-
-```jsx
-<AvatarGroup>
-  <AvatarGroupItem color="darkRed" name="Katri Athokas" />
-  <AvatarGroupItem name="Elvia Atkins" />
-  <AvatarGroupItem name="Cameron Evans" />
-  <AvatarGroupItem name="Wanda Howard" />
-  <AvatarGroupItem name="Mona Kane" />
-</AvatarGroup>
-```
-
-## Structure
-
-- _**Public**_
-
-```jsx
-<AvatarGroup layout="spread" size={32}>
-  <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}>
-  <slots.avatar {...slotProps.avatar} />
-  {state.isOverflowItem && <slots.overflowLabel {...slotProps.overflowLabel} />}
-</slots.root>
-```
-
-- _**DOM** - how the component will be rendered as HTML elements_
-
-```html
-<div className="fui-AvatarGroup" role="group">
-  <div class="fui-AvatarGroupItem">
-    <Avatar />
-  </div>
-  <div class="fui-AvatarGroupItem">
-    <Avatar />
-  </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 [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:_
-
-- _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_:
-    - 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
-
-Base accessibility information is included in the design document. After the spec is filled and reviewed, outcomes from it need to be communicated to design and incorporated in the design document.
-
-- There's no native element for this component.
-
-- `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 `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.

package/SPEC.md

@@ -1,172 +0,0 @@
-# Avatar
-
-**GitHub Epic issue** - [Avatar Convergence #16373](https://github.com/microsoft/fluentui/issues/16373)
-
-## Background
-
-The Avatar component represents a person or entity. It displays the person's image, initials, or an icon, and can be either circular or square.
-
-Note: The Avatar control has been mostly implemented already. Visit [Avatar Storybook Examples](https://fluentuipr.z22.web.core.windows.net/heads/master/react-components/storybook/index.html?path=/docs/components-avatar--default) to see the current state of the implementation.
-
-## Prior Art
-
-### Open UI
-
-The Open UI [Avatar Research](https://open-ui.org/components/avatar.research) page (currently in PR: https://github.com/WICG/open-ui/pull/250), shows how the Avatar component is used in UI platforms across the web. There is a good consensus about the basic features such as displaying an image, initials, or an icon; as well as the shape being either a square or circle.
-
-### Comparison of v8 and v0
-
-The existing components are:
-
-- v8 - [Persona](https://developer.microsoft.com/en-us/fluentui#/controls/web/persona)
-- v0 - [Avatar](https://fluentsite.z22.web.core.windows.net/0.51.4/components/avatar/definition)
-
-#### Display
-
-Both the v8 and v0 components support displaying an image, initials, and an icon.
-
-The v8 `Persona` also supports the full name and extra detail text to the right of the image. The extra detail text is specifically out of scope for the `Avatar` control, and may be added to a future component that makes use of Avatar.
-
-The v8 `Persona` appears to not support a custom icon, and can only show the default person icon, or a "?" icon
-
-#### Status/Presence Badge
-
-Both components support showing a badge to indicate status, but they have different APIs. The v8 `Persona` has an enum of preset options for the presence badge. The v0 `Avatar` supports rendering a `Status` component, which is more customizable and can render an icon, and specify different sizes and colors.
-
-## Sample Code
-
-Display a user's initials:
-
-```jsx
-<Avatar name="Miguel Garcia" />
-```
-
-Display a user's image:
-
-```jsx
-<Avatar size={72} name="Mona Kane" image={{ src: './MonaKane.jpg' }} />
-```
-
-Display an icon only:
-
-```jsx
-<Avatar aria-label="Team" icon={<PeopleTeamRegular />} shape="square" />
-```
-
-Display a badge:
-
-```jsx
-<Avatar name="Allan Munger" badge={{ status: 'busy' }} />
-```
-
-With active state indication:
-
-```jsx
-<Avatar name="Daisy Phillips" active={isUserActive ? 'active' : 'inactive'} activeAppearance="ring-shadow" />
-```
-
-## Variants
-
-### Color
-
-The Avatar supports color variants when displaying initials or an icon:
-
-- **Neutral** - Gray (default)
-- **Brand** - Brand colors from the theme
-- **Colorful** - Pick from a list of pre-defined Avatar colors. The color will be assigned based on a hash of the name
-  (to "randomly" assign a person a color). The color name (like `darkRed`) can also be specified explicitly in case the use case
-  requires a different algorithm to pick the color.
-
-### Shape
-
-The Avatar supports a circular and square (with rounded corners) shape.
-
-## API
-
-From [Avatar.types.tsx](https://github.com/microsoft/fluentui/blob/master/packages/react-avatar/src/components/Avatar/Avatar.types.tsx):
-
-### Slots
-
-- `root` - The root element of the Avatar.
-- `image` - The Avatar's image, if provided.
-- `initials` - The text shown when there's no image. Defaults to the initials derived from `name`.
-- `icon` - Icon displayed when there's no image or intials available.
-- `badge` - PresenceBadge to show the avatar's status.
-
-### Props
-
-See API at [Avatar.types.ts](./src/components/Avatar/Avatar.types.ts).
-
-## Structure
-
-JSX Tree:
-
-```jsx
-<slots.root {...slotProps.root}>
-  {slots.initials && <slots.initials {...slotProps.initials} />}
-  {slots.icon && <slots.icon {...slotProps.icon} />}
-  {slots.image && <slots.image {...slotProps.image} />}
-  {slots.badge && <slots.badge {...slotProps.badge} />}
-</slots.root>
-```
-
-Resulting HTML (in this example, "avatar-42" is an ID generated by `useId`):
-
-```html
-<span class="{root}" id="avatar-42" aria-label="Miguel Garcia" aria-labelledby="avatar-42 avatar-42__badge">
-  <!-- Only one of initials OR icon will be rendered, never both -->
-  <span class="{initials}" aria-hidden="true">MG</span>
-  <span class="{icon}" aria-hidden="true"><svg>...</svg></span>
-
-  <!-- The Image -->
-  <img class="{image}" src="..." aria-hidden="true" role="presentation" alt="" />
-
-  <!-- The PresenceBadge's HTML is rendered here -->
-  <span class="{PresenceBadge}" id="avatar-42__badge" aria-hidden="true">...</span>
-</span>
-```
-
-## Migration
-
-See [MIGRATION.md](./MIGRATION.md).
-
-## Behaviors
-
-### States
-
-- **Display** - The Avatar will use the following priority:
-
-  - The `image` property, if provided.
-  - Initials derived from the `name` property (this is always displayed, so it is visible while the image is loading, and if the image fails to load).
-  - The `icon` property, if provided.
-  - If no `image`, `icon`, or `name` is provided, the default "person" icon will be used.
-
-- **Active** - The `active` property affects the display of the avatar if set. There will be an animation when switching between active and inactive.
-  - `unset` - Display at normal size/opacity.
-  - `inactive` - Reduce to 80% opacity, and 87.5% size.
-  - `active` - Adorn with an extra visual such as a ring and/or shadow, based on the `activeAppearance` property.
-
-### Interaction
-
-The Avatar is non-interactive.
-
-- **Keyboard** - Not keyboard focusable.
-- **Mouse** - Nothing
-- **Touch** - Nothing
-
-## Accessibility
-
-The Avatar presents as a single img element to accessibility tools, regardless of what it is displaying (image, initials, or icon).
-
-- The Avatar's root has `role="img"`
-- All other slots have `aria-hidden="true"`.
-- The `<img>` additionally has `alt="" role="presentation"`
-
-The Avatar root's label is determined using the following priority:
-
-- If `aria-label` and/or `aria-labelledby` is provided on props, do not add anything else.
-- If `name` is provided, set the root's `aria-label={name}`.
-  - If a badge is present, _also_ set the root's `aria-labelledby={root.id + ' ' + badge.id}`.
-  - This means the Avatar is labelled by both its root and badge slots, and results in a label like "Miguel Garcia Busy".
-- If there's no `name`, but `initials` are provided, set the root's `aria-labelledby={initials.id}`.
-  - If a badge is present, _instead_ set the root's `aria-labelledby={initials.id + ' ' + badge.id}`.