@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/attachment.md

@@ -0,0 +1,276 @@
+<!-- index: ./index.md -->
+# attachment
+
+`data-ui="attachment"` · File that belongs to a message or record.
+
+## Import
+
+```tsx
+import { Attachment, AttachmentAction, AttachmentActions, AttachmentBody, AttachmentDefaultsProvider, AttachmentDetail, AttachmentFilename, AttachmentGroup, AttachmentLink, AttachmentMessage, AttachmentPreview, AttachmentProgress, AttachmentRemove, AttachmentTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={file} onRemove={remove}>
+  <AttachmentPreview />
+  <AttachmentBody>
+    <AttachmentLink href={file.url} />
+    <AttachmentDetail />
+  </AttachmentBody>
+  <AttachmentActions>
+    <AttachmentRemove />
+  </AttachmentActions>
+</Attachment>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | li, or div alone | yes |
+| `group` | ul | no |
+| `preview` | span | no |
+| `body` | div | yes |
+| `trigger` | a or button | no |
+| `filename` | span | yes |
+| `name` | span | yes |
+| `extension` | span | no |
+| `detail` | p | no |
+| `message` | p | no |
+| `progress` | div | no |
+| `actions` | div | no |
+| `action` | button | no |
+| `remove` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `file` | `{ name: string; type?: string; size?: number }` | — | Attachment | The file. A File already is one; a server record needs only the name |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Attachment, AttachmentGroup | The room the attachment gets. Falls back to the group, then the provider |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | Attachment, AttachmentGroup | A row, or a card stood on end. Falls back to the group, then the provider |
+| `layout` | `'list' \| 'grid' \| 'strip'` | list | AttachmentGroup | A column, a wrapping grid, or one line that scrolls |
+| `invalid` | `boolean` | false | Attachment | The file failed: tinted ground, doubled edge, and the message named as the trigger description |
+| `loading` | `boolean` | false | Attachment | aria-busy on the root and the trigger refused; remove stays operable |
+| `disabled` | `boolean` | false | Attachment | The trigger, every action and remove are refused |
+| `onRemove` | `(request) => void` | — | Attachment | Makes the attachment removable: AttachmentRemove renders and Backspace and Delete answer |
+| `messages` | `Partial<AttachmentMessages>` | — | Attachment | Words laid over the language in force, key by key: the remove control name (remove, with the file name) and the tile word for a file without an extension (noExtension) |
+| `src` | `string` | — | AttachmentPreview | A thumbnail. Absent or failing, the kind tile is drawn |
+| `href / download` | `string` | — | AttachmentLink | The anchor own attributes; the platform follows and downloads |
+| `type` | `'button' \| 'submit' \| 'reset'` | button | AttachmentTrigger, AttachmentAction, AttachmentRemove | The button own type |
+| `value` | `number \| null` | null | AttachmentProgress | Per cent, 0 to 100; null draws the indeterminate bar |
+| `children` | `ReactNode` | the size | AttachmentDetail | Replaces the size with the page own line |
+| `children` | `ReactNode` | the filename | AttachmentTrigger, AttachmentLink | Replaces the name the trigger renders |
+| `render` | `(props) => ReactNode` | — | every part | Renders the wiring into another element — a router link, an anchor with download |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the native element; each part extends its own element props |
+| `AttachmentDefaultsProvider` | `{ size, orientation, layout }` | — | a subtree | Sets the three once; the group and the attachment still win |
+| `render` | `(props) => ReactNode` | — | every part | The consumer element receives data-part and the wiring; spread it |
+| `onKeyDown / onClick` | `handler` | — | root, remove | Composed: the page handler runs first and preventDefault refuses the family behaviour |
+| `aria-describedby` | `string` | — | AttachmentLink, AttachmentTrigger | Joined with the detail and message ids rather than replaced |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onRemove` | `{ reason: 'remove' \| 'keyboard', file: AttachmentFile, source: SyntheticEvent }` | The remove control was pressed, or Backspace or Delete arrived inside a removable attachment. A request: the list is the page’s, and nothing leaves until the page removes it. Not emitted while disabled, nor for a repeated key. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `layout` | `list`, `grid`, `strip` | `list` |
+
+## Rules
+
+- The set is a native ul and each attachment an li, so a reader hears the count of files; an attachment alone is a div, because a list item outside a list is an error.
+- The trigger is a real a or button whose accessible name is the file name and whose description is the detail and the message, so a failed file is heard as its name and then its reason.
+- The trigger is stretched over the attachment by a transparent pseudo-element rather than wrapping it, because interactive content may not nest inside a or button; the actions are its siblings and sit above it.
+- ARIA 1.2 deprecates aria-invalid and aria-disabled on listitem, so the three states are painted from data attributes on the root and carried by the controls: disabled on a button, aria-disabled on a link that keeps its destination.
+- The tile is aria-hidden: the name already says what the file is, and a thumbnail alt text would repeat it.
+- Backspace and Delete ask to remove a removable attachment from wherever focus is inside it; a held key does not repeat the request, and a field inside the attachment keeps its editing keys.
+- When an attachment leaves, focus goes to the control that took its place, then to the last one, then to the list, which holds tabIndex -1 for that purpose; nothing is lost to the document body.
+- The progress bar is named by the file, so a reader hears the file and the percentage together, and without a value it is announced as indeterminate.
+- A failed attachment doubles its edge as well as tinting its ground, because every tone surface is the page white in the high-contrast scheme.
+
+## Tokens
+
+`--slotted-attachment-action-radius`, `--slotted-attachment-action-size`, `--slotted-attachment-action-state-layer-active`, `--slotted-attachment-action-state-layer-hover`, `--slotted-attachment-background`, `--slotted-attachment-border-color`, `--slotted-attachment-border-width`, `--slotted-attachment-card-actions-opacity`, `--slotted-attachment-card-preview-radius`, `--slotted-attachment-card-size`, `--slotted-attachment-font-family`, `--slotted-attachment-grid-min`, `--slotted-attachment-group-gap`, `--slotted-attachment-icon-size-min`, `--slotted-attachment-line-gap`, `--slotted-attachment-name-font-weight`, `--slotted-attachment-padding-lg`, `--slotted-attachment-padding-md`, `--slotted-attachment-padding-sm`, `--slotted-attachment-preview-radius`, `--slotted-attachment-preview-size`, `--slotted-attachment-radius`, `--slotted-attachment-state-layer-active`, `--slotted-attachment-state-layer-hover`, `--slotted-attachment-strip-item-size`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-upload-kind-archive`, `--slotted-upload-kind-audio`, `--slotted-upload-kind-document`, `--slotted-upload-kind-foreground`, `--slotted-upload-kind-image`, `--slotted-upload-kind-other`, `--slotted-upload-kind-pdf`, `--slotted-upload-kind-presentation`, `--slotted-upload-kind-spreadsheet`, `--slotted-upload-kind-video`
+
+## Examples
+
+### Every part, and a file with almost none
+
+An absent part leaves no column behind: without a tile or actions the name takes the width they held. A file that cannot be opened writes its name without a trigger.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={{ name: 'telematics-export' }}>
+  <AttachmentBody>
+    <AttachmentFilename />
+    <AttachmentDetail>No preview available</AttachmentDetail>
+  </AttachmentBody>
+</Attachment>;
+```
+
+### Three sizes, one tile rule
+
+The tile is the height of the two lines beside it — 40 pixels at md — so its edges meet the name’s cap and the detail’s foot. Density shrinks all three with the fields around them.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={file} size="sm" />;
+```
+
+### A row, or a card stood on end
+
+A card is three tiles wide — 120 pixels at md — with the picture square inside it. The actions move onto the picture on a plate of their own, and a card with no picture writes its extension under the mark.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={photo} orientation="vertical" onRemove={remove}>
+  <AttachmentPreview src={photo.thumbnail} />
+  <AttachmentBody>
+    <AttachmentTrigger onClick={() => openViewer(photo)} />
+    <AttachmentDetail />
+  </AttachmentBody>
+  <AttachmentActions>
+    <AttachmentRemove />
+  </AttachmentActions>
+</Attachment>;
+```
+
+### A column, a grid, a scrolling tray
+
+The group is a native list. Grid rows share the width and never go narrower than a name; cards keep their own width so each is a whole pixel. The strip scrolls on one line and snaps to each attachment, and its ring never meets the clip.
+
+Excerpt — not a complete module
+
+```tsx
+<AttachmentGroup aria-label="Attached to your reply" layout="strip" size="sm">
+  {files.map((file) => (
+    <Attachment file={file} key={file.name} onRemove={remove}>
+      <AttachmentPreview />
+      <AttachmentBody>
+        <AttachmentFilename />
+        <AttachmentDetail />
+      </AttachmentBody>
+      <AttachmentActions>
+        <AttachmentRemove />
+      </AttachmentActions>
+    </Attachment>
+  ))}
+</AttachmentGroup>;
+```
+
+### Nine kinds, read before the name
+
+The kind comes from the media type first and the extension second, and paints the tile from the scale upload uses, so a PDF is the same red in a reply as in the upload it came from. A thumbnail replaces the tile, and falls back to it if it fails.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={{ name: 'repair-estimate.xlsx', size: 86_000 }}>
+  <AttachmentPreview />
+  <AttachmentBody>
+    <AttachmentFilename />
+    <AttachmentDetail />
+  </AttachmentBody>
+</Attachment>;
+```
+
+### A link, or a button that opens a viewer
+
+AttachmentLink is a real anchor, so href, download and a modified click are the browser’s. AttachmentTrigger is a real button for a viewer the page opens. Either one is the whole attachment’s target, and the ring goes round the attachment.
+
+Excerpt — not a complete module
+
+```tsx
+<AttachmentLink href={file.url} />;
+<AttachmentTrigger onClick={() => openViewer(file)} />;
+```
+
+### Actions beside the file, never inside it
+
+AttachmentAction is an inner control: no frame at rest, a state layer on hover and a deeper one on press. render puts it on an anchor with download. AttachmentRemove renders only when the attachment has onRemove.
+
+Excerpt — not a complete module
+
+```tsx
+<AttachmentActions>
+  <AttachmentAction
+    aria-label={`Download ${file.name}`}
+    render={({ disabled, type, ...props }) => <a {...props} download href={file.url} />}
+  >
+    <Icon>
+      <DownloadIcon />
+    </Icon>
+  </AttachmentAction>
+  <AttachmentRemove />
+</AttachmentActions>;
+```
+
+### Failed, sending, waiting, unavailable
+
+A failed file tints its ground, doubles its edge and says why in a sentence the trigger names as its description; its tile keeps the kind. A sending file carries its bar as its bottom edge and refuses its trigger but not remove.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={file} loading={percent < 100} onRemove={cancel}>
+  <AttachmentPreview />
+  <AttachmentBody>
+    <AttachmentTrigger />
+    <AttachmentDetail>Uploading · {percent}%</AttachmentDetail>
+  </AttachmentBody>
+  <AttachmentProgress value={percent} />
+  <AttachmentActions>
+    <AttachmentRemove />
+  </AttachmentActions>
+</Attachment>;
+```
+
+### Names the family did not choose
+
+The stem shrinks and the extension stays, so a sixty-character report still ends in .pdf; the whole name stays in the title. A name in Arabic keeps its own direction, and a name with no dot is one run.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment file={{ name: 'quarterly-loss-adjustment-report-consolidated-final-v7-signed.pdf' }} />;
+```
+
+### In a claim thread
+
+A message carries its files the way the product would: the group under the text, links that download, one file still sending. The provider sets the size once for the whole thread; the words come from the language in force.
+
+Excerpt — not a complete module
+
+```tsx
+<AttachmentDefaultsProvider size="sm">
+  <ClaimThread />
+</AttachmentDefaultsProvider>;
+```
+
+### Tab reaches every control; Delete asks
+
+Tab reaches the trigger, each action and remove. Backspace or Delete anywhere in a removable attachment asks to remove it, a held key is ignored, and focus moves to the attachment that took its place, then the last one, then the list.
+
+Excerpt — not a complete module
+
+```tsx
+<Attachment
+  file={file}
+  onRemove={({ reason }) => {
+    setFiles((all) => all.filter((each) => each !== file));
+    if (reason === 'keyboard') announce(`${file.name} removed`);
+  }}
+/>;
+```

package/dist/docs/avatar-group.json

@@ -0,0 +1,207 @@
+{
+  "family": "avatar-group",
+  "ui": "avatar-group",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Overlapping avatars with an overflow count."
+  },
+  "axes": {
+    "layout": [
+      "stack",
+      "spread"
+    ],
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
+    "shape": [
+      "circle",
+      "square"
+    ]
+  },
+  "members": {
+    "avatarGroup": {
+      "nativeElement": "ul",
+      "defaults": {
+        "layout": "stack",
+        "size": "md",
+        "shape": "circle",
+        "max": 5
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "shape"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible"
+      ],
+      "parts": [
+        "root",
+        "item",
+        "overflow"
+      ]
+    }
+  },
+  "docs": {
+    "avatarGroup": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "layout",
+          "type": "'stack' | 'spread'",
+          "defaultValue": "stack",
+          "appliesTo": "AvatarGroup",
+          "description": "stack overlaps the members; spread lays them apart and wraps"
+        },
+        {
+          "name": "max",
+          "type": "number | false",
+          "defaultValue": "5",
+          "appliesTo": "AvatarGroup",
+          "description": "The largest number of discs the group draws, the summary included. false shows every member"
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "How many members there really are, when the page renders fewer than it has"
+        },
+        {
+          "name": "overflowLabel",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "What the summary is called. Defaults to the hidden members’ names, joined for the locale"
+        },
+        {
+          "name": "size",
+          "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
+          "defaultValue": "md",
+          "appliesTo": "AvatarGroup",
+          "description": "Provided to every member, and the length the overlap is measured against"
+        },
+        {
+          "name": "shape",
+          "type": "'circle' | 'square'",
+          "defaultValue": "circle",
+          "appliesTo": "AvatarGroup",
+          "description": "Provided to every member. An avatar that states its own still wins"
+        },
+        {
+          "name": "variant",
+          "type": "'soft' | 'solid'",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "Provided to every member. tone is never provided: it is the member’s own identity"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "BCP 47, for the digits of the summary and for joining the hidden names"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "Renders the list into another element — an ordered list for a ranked row"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLUListElement>",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "Reaches the native element; the props type is the element’s own, extended"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "AvatarGroup",
+          "description": "What the list is called. Native, because the element already accepts it"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "There is no avatar-group pattern in the WAI-ARIA Authoring Practices. The group is a real ul whose members are real li, so assistive technology announces a list of N without the family inventing a role.",
+        "There is no label prop. The element already accepts aria-label and aria-labelledby, and a second way to name one thing is a second thing to get wrong — the decision button-group took for the same question. Name the list for what it holds: “reviewers”, “attendees”.",
+        "The summary’s accessible name is the hidden members’ names, joined with Intl.ListFormat for the locale. Atlassian’s default there is the English string “N more people”; MUI, Ant, Fluent, Chakra and HeroUI leave “+3” as the whole announcement.",
+        "A group told it stands for more members than it renders knows only the names it holds, so it names none of them rather than a third of them. Supply overflowLabel in that case.",
+        "The group has no keyboard model of its own, because it is a list rather than a composite widget. Members that are links or buttons are ordinary tab stops in document order.",
+        "In a stack each member covers the trailing edge of the one before it, so the member under the pointer or the caret is raised: without it a focus ring would be half-hidden under the next avatar. The raise is instant, and a disabled member does not rise.",
+        "The summary is not interactive here. Making it open the hidden members is a disclosure, which belongs to the popover and menu families; render on the member avatar is what turns it into your own trigger in the meantime.",
+        "An empty group takes no room at all, so a row built from a permission filter does not leave a gap nobody can see in the markup."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-avatar-group-overlap",
+    "--slotted-avatar-group-raise-lift",
+    "--slotted-avatar-size",
+    "--slotted-avatar-size-lg",
+    "--slotted-avatar-size-md",
+    "--slotted-avatar-size-sm",
+    "--slotted-avatar-size-xl",
+    "--slotted-avatar-size-xs",
+    "--slotted-border-width-thick",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-shadow-sm",
+    "--slotted-space-2",
+    "--slotted-space-4"
+  ],
+  "examples": [
+    {
+      "id": "avatar-group-react-basic",
+      "title": "A list of faces, and a summary of the rest",
+      "note": null,
+      "language": "tsx",
+      "source": "<AvatarGroup aria-label=\"Reviewers\">\n  {reviewers.map((person) => (\n    <Avatar key={person.id} name={person.name} src={person.photograph} />\n  ))}\n</AvatarGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-react-total",
+      "title": "Three of forty, from a paged endpoint",
+      "note": null,
+      "language": "tsx",
+      "source": "<AvatarGroup\n  aria-label=\"Attendees\"\n  overflowLabel={`${event.attendeeCount - 3} more attendees`}\n  total={event.attendeeCount}\n>\n  {event.firstAttendees.map((person) => (\n    <Avatar key={person.id} name={person.name} src={person.photograph} />\n  ))}\n</AvatarGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-react-spread",
+      "title": "Laid apart rather than stacked",
+      "note": null,
+      "language": "tsx",
+      "source": "<AvatarGroup aria-label=\"Team\" layout=\"spread\" max={false} size=\"lg\">\n  {team.map((person) => (\n    <Avatar key={person.id} name={person.name} src={person.photograph} />\n  ))}\n</AvatarGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-react-links",
+      "title": "Members that open a profile",
+      "note": null,
+      "language": "tsx",
+      "source": "<AvatarGroup aria-label=\"Assignees\" size=\"sm\">\n  {assignees.map((person) => (\n    <Avatar\n      key={person.id}\n      name={person.name}\n      render={(props) => <a {...props} href={`/people/${person.id}`} />}\n      src={person.photograph}\n    />\n  ))}\n</AvatarGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-react-ring",
+      "title": "A group on a coloured row",
+      "note": null,
+      "language": "tsx",
+      "source": "<div style={{ background: 'var(--slotted-surface-sunken)' }}>\n  <AvatarGroup\n    aria-label=\"Reviewers\"\n    style={{ '--slotted-avatar-ring-color': 'var(--slotted-surface-sunken)' }}\n  >\n    {reviewers.map((person) => (\n      <Avatar key={person.id} name={person.name} src={person.photograph} />\n    ))}\n  </AvatarGroup>\n</div>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/avatar-group.md

@@ -0,0 +1,119 @@
+<!-- index: ./index.md -->
+# avatar-group
+
+`data-ui="avatar-group"` · Overlapping avatars with an overflow count.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<AvatarGroup aria-label="Reviewers">
+  {reviewers.map((person) => (
+    <Avatar key={person.id} name={person.name} src={person.photograph} />
+  ))}
+</AvatarGroup>;
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `'stack' \| 'spread'` | stack | AvatarGroup | stack overlaps the members; spread lays them apart and wraps |
+| `max` | `number \| false` | 5 | AvatarGroup | The largest number of discs the group draws, the summary included. false shows every member |
+| `total` | `number` | — | AvatarGroup | How many members there really are, when the page renders fewer than it has |
+| `overflowLabel` | `string` | — | AvatarGroup | What the summary is called. Defaults to the hidden members’ names, joined for the locale |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | AvatarGroup | Provided to every member, and the length the overlap is measured against |
+| `shape` | `'circle' \| 'square'` | circle | AvatarGroup | Provided to every member. An avatar that states its own still wins |
+| `variant` | `'soft' \| 'solid'` | — | AvatarGroup | Provided to every member. tone is never provided: it is the member’s own identity |
+| `locale` | `string` | — | AvatarGroup | BCP 47, for the digits of the summary and for joining the hidden names |
+| `render` | `(props) => ReactNode` | — | AvatarGroup | Renders the list into another element — an ordered list for a ranked row |
+| `ref` | `Ref<HTMLUListElement>` | — | AvatarGroup | Reaches the native element; the props type is the element’s own, extended |
+| `aria-label` | `string` | — | AvatarGroup | What the list is called. Native, because the element already accepts it |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `layout` | `stack`, `spread` | `stack` |
+| `size` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
+| `shape` | `circle`, `square` | `circle` |
+
+## Rules
+
+- There is no avatar-group pattern in the WAI-ARIA Authoring Practices. The group is a real ul whose members are real li, so assistive technology announces a list of N without the family inventing a role.
+- There is no label prop. The element already accepts aria-label and aria-labelledby, and a second way to name one thing is a second thing to get wrong — the decision button-group took for the same question. Name the list for what it holds: “reviewers”, “attendees”.
+- The summary’s accessible name is the hidden members’ names, joined with Intl.ListFormat for the locale. Atlassian’s default there is the English string “N more people”; MUI, Ant, Fluent, Chakra and HeroUI leave “+3” as the whole announcement.
+- A group told it stands for more members than it renders knows only the names it holds, so it names none of them rather than a third of them. Supply overflowLabel in that case.
+- The group has no keyboard model of its own, because it is a list rather than a composite widget. Members that are links or buttons are ordinary tab stops in document order.
+- In a stack each member covers the trailing edge of the one before it, so the member under the pointer or the caret is raised: without it a focus ring would be half-hidden under the next avatar. The raise is instant, and a disabled member does not rise.
+- The summary is not interactive here. Making it open the hidden members is a disclosure, which belongs to the popover and menu families; render on the member avatar is what turns it into your own trigger in the meantime.
+- An empty group takes no room at all, so a row built from a permission filter does not leave a gap nobody can see in the markup.
+
+## Tokens
+
+`--slotted-avatar-group-overlap`, `--slotted-avatar-group-raise-lift`, `--slotted-avatar-size`, `--slotted-avatar-size-lg`, `--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xl`, `--slotted-avatar-size-xs`, `--slotted-border-width-thick`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-shadow-sm`, `--slotted-space-2`, `--slotted-space-4`
+
+## Examples
+
+### Three of forty, from a paged endpoint
+
+Excerpt — not a complete module
+
+```tsx
+<AvatarGroup
+  aria-label="Attendees"
+  overflowLabel={`${event.attendeeCount - 3} more attendees`}
+  total={event.attendeeCount}
+>
+  {event.firstAttendees.map((person) => (
+    <Avatar key={person.id} name={person.name} src={person.photograph} />
+  ))}
+</AvatarGroup>;
+```
+
+### Laid apart rather than stacked
+
+Excerpt — not a complete module
+
+```tsx
+<AvatarGroup aria-label="Team" layout="spread" max={false} size="lg">
+  {team.map((person) => (
+    <Avatar key={person.id} name={person.name} src={person.photograph} />
+  ))}
+</AvatarGroup>;
+```
+
+### Members that open a profile
+
+Excerpt — not a complete module
+
+```tsx
+<AvatarGroup aria-label="Assignees" size="sm">
+  {assignees.map((person) => (
+    <Avatar
+      key={person.id}
+      name={person.name}
+      render={(props) => <a {...props} href={`/people/${person.id}`} />}
+      src={person.photograph}
+    />
+  ))}
+</AvatarGroup>;
+```
+
+### A group on a coloured row
+
+Excerpt — not a complete module
+
+```tsx
+<div style={{ background: 'var(--slotted-surface-sunken)' }}>
+  <AvatarGroup
+    aria-label="Reviewers"
+    style={{ '--slotted-avatar-ring-color': 'var(--slotted-surface-sunken)' }}
+  >
+    {reviewers.map((person) => (
+      <Avatar key={person.id} name={person.name} src={person.photograph} />
+    ))}
+  </AvatarGroup>
+</div>;
+```