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

package/docs/attachment.md

@@ -0,0 +1,253 @@
+<!-- index: ./index.md -->
+# attachment
+
+`data-ui="attachment"` · File that belongs to a message or record.
+
+## Import
+
+```ts
+import { provideAttachmentDefaults, SlAttachment, SlAttachmentAction, SlAttachmentActions, SlAttachmentBody, SlAttachmentDetail, SlAttachmentFilename, SlAttachmentGroup, SlAttachmentMessage, SlAttachmentPreview, SlAttachmentProgress, SlAttachmentRemove, SlAttachmentTrigger } from '@slotted/angular/attachment';
+```
+
+Selector: `[slAttachment], [slAttachmentGroup], [slAttachmentPreview], [slAttachmentBody], a[slAttachmentTrigger], button[slAttachmentTrigger], [slAttachmentFilename], [slAttachmentDetail], [slAttachmentMessage], [slAttachmentProgress], [slAttachmentActions], button[slAttachmentAction], a[slAttachmentAction], button[slAttachmentRemove]` · exportAs: `slAttachment, slAttachmentGroup, slAttachmentPreview, slAttachmentBody, slAttachmentTrigger, slAttachmentFilename, slAttachmentDetail, slAttachmentMessage, slAttachmentProgress, slAttachmentActions, slAttachmentAction, slAttachmentRemove`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<li slAttachment [file]="file" removable (remove)="drop($event.file)">
+  <span slAttachmentPreview></span>
+  <div slAttachmentBody>
+    <a slAttachmentTrigger [href]="file.url"></a>
+    <p slAttachmentDetail></p>
+  </div>
+  <div slAttachmentActions><button slAttachmentRemove></button></div>
+</li>
+```
+
+## 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 or a | no |
+| `remove` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `[file]` | `{ name: string; type?: string; size?: number }` | — | slAttachment | Required. A File already is one; a server record needs only the name |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slAttachment, slAttachmentGroup | The room the attachment gets. Falls back to the group, then the token |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slAttachment, slAttachmentGroup | A row, or a card stood on end. Falls back to the group, then the token |
+| `layout` | `'list' \| 'grid' \| 'strip'` | list | slAttachmentGroup | A column, a wrapping grid, or one line that scrolls |
+| `invalid` | `boolean` | false | slAttachment | The file failed: tinted ground, doubled edge, and the message named as the trigger description |
+| `loading` | `boolean` | false | slAttachment | aria-busy on the root and the trigger refused; remove stays operable |
+| `disabled` | `boolean` | false | slAttachment | The trigger, every action and remove are refused |
+| `removable` | `boolean` | false | slAttachment | Shows slAttachmentRemove and lets Backspace and Delete ask for removal |
+| `messages` | `Partial<AttachmentMessages>` | — | slAttachment | 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` | — | slAttachmentPreview | A thumbnail. Absent or failing, the kind tile is drawn |
+| `value` | `number \| null` | null | slAttachmentProgress | Per cent, 0 to 100; null draws the indeterminate bar |
+| `href / download` | `string` | — | a[slAttachmentTrigger], a[slAttachmentAction] | The anchor own attributes, untouched |
+| `provideAttachmentDefaults` | `{ size, orientation, layout }` | — | an injector | Sets the three once; the group and the attachment still win |
+| `exportAs` | `slAttachment and every part` | — | template reference | #attachment="slAttachment" reaches kind(), blocked() and request() |
+| `projected content` | `ng-content` | — | trigger, filename, detail, remove | Replaces the name, the size or the cross the family draws by default |
+| `static attributes` | `id, title, dir, type, aria-label, aria-describedby` | — | every part | Read with HostAttributeToken and kept; aria-describedby is joined, not replaced |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(remove)` | `{ reason: 'remove' \| 'keyboard', file: AttachmentFile, source: Event }` | 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 goes on 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.
+- A refused link is refused by slAttachment in the capture phase, so the page’s own (click) on the trigger never runs while the file is loading or unavailable.
+- 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.
+- 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.
+
+## 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
+
+```html
+<div slAttachment [file]="{ name: 'telematics-export' }">
+  <div slAttachmentBody>
+    <span slAttachmentFilename></span>
+    <p slAttachmentDetail>No preview available</p>
+  </div>
+</div>
+```
+
+### 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
+
+```html
+<div slAttachment [file]="file" size="sm"></div>
+```
+
+### 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
+
+```html
+<li slAttachment [file]="photo" orientation="vertical" removable (remove)="drop(photo)">
+  <span slAttachmentPreview [src]="photo.thumbnail"></span>
+  <div slAttachmentBody>
+    <button slAttachmentTrigger (click)="openViewer(photo)"></button>
+    <p slAttachmentDetail></p>
+  </div>
+  <div slAttachmentActions><button slAttachmentRemove></button></div>
+</li>
+```
+
+### 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
+
+```html
+<ul slAttachmentGroup aria-label="Attached to your reply" layout="strip" size="sm">
+  @for (file of files(); track file.name) {
+    <li slAttachment [file]="file" removable (remove)="drop(file)">
+      <span slAttachmentPreview></span>
+      <div slAttachmentBody>
+        <span slAttachmentFilename></span>
+        <p slAttachmentDetail></p>
+      </div>
+      <div slAttachmentActions><button slAttachmentRemove></button></div>
+    </li>
+  }
+</ul>
+```
+
+### 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
+
+```html
+<div slAttachment [file]="{ name: 'repair-estimate.xlsx', size: 86000 }">
+  <span slAttachmentPreview></span>
+  <div slAttachmentBody>
+    <span slAttachmentFilename></span>
+    <p slAttachmentDetail></p>
+  </div>
+</div>
+```
+
+### A link, or a button that opens a viewer
+
+On an a the trigger is a real anchor, so href, download and a modified click are the browser’s; on a button it 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
+
+```html
+<a slAttachmentTrigger [href]="file.url"></a>
+<button slAttachmentTrigger (click)="openViewer(file)"></button>
+```
+
+### Actions beside the file, never inside it
+
+slAttachmentAction is an inner control on the button or the a the page wrote: no frame at rest, a state layer on hover and a deeper one on press. The remove control is hidden unless the attachment is removable.
+
+Excerpt — not a complete module
+
+```html
+<div slAttachmentActions>
+  <a slAttachmentAction [href]="file.url" download [attr.aria-label]="'Download ' + file.name">
+    <span slIcon><svg slGlyph name="external"></svg></span>
+  </a>
+  <button slAttachmentRemove></button>
+</div>
+```
+
+### 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
+
+```html
+<li slAttachment [file]="file" [loading]="percent() < 100" removable (remove)="cancel()">
+  <span slAttachmentPreview></span>
+  <div slAttachmentBody>
+    <button slAttachmentTrigger></button>
+    <p slAttachmentDetail>Uploading · {{ percent() }}%</p>
+  </div>
+  <div slAttachmentProgress [value]="percent()"></div>
+  <div slAttachmentActions><button slAttachmentRemove></button></div>
+</li>
+```
+
+### 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
+
+```html
+<div slAttachment [file]="report"></div>
+```
+
+### 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. provideAttachmentDefaults sets the size once for the application; the words and the locale come from provideSlotted.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideAttachmentDefaults({ size: 'sm' })],
+});
+```
+
+### 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
+
+```html
+<li slAttachment [file]="file" removable (remove)="drop($event.file, $event.reason)"></li>
+```

package/docs/avatar-group.json

@@ -0,0 +1,208 @@
+{
+  "family": "avatar-group",
+  "ui": "avatar-group",
+  "binding": "angular",
+  "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": "slAvatarGroup",
+          "description": "stack overlaps the members; spread lays them apart and wraps"
+        },
+        {
+          "name": "max",
+          "type": "number | false",
+          "defaultValue": "5",
+          "appliesTo": "slAvatarGroup",
+          "description": "The largest number of discs the group draws, the summary included. false shows every member"
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "description": "How many members there really are, when the page renders fewer than it has"
+        },
+        {
+          "name": "overflowLabel",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "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": "slAvatarGroup",
+          "description": "Provided to every member, and the length the overlap is measured against"
+        },
+        {
+          "name": "shape",
+          "type": "'circle' | 'square'",
+          "defaultValue": "circle",
+          "appliesTo": "slAvatarGroup",
+          "description": "Provided to every member. An avatar that states its own still wins"
+        },
+        {
+          "name": "variant",
+          "type": "'soft' | 'solid'",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "description": "Provided to every member. tone is never provided: it is the member’s own identity"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "description": "BCP 47, for the digits of the summary and for joining the hidden names"
+        },
+        {
+          "name": "slAvatarGroupItem",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "li",
+          "description": "One member. Hidden when it falls past the limit, and its name is what the summary is called"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "description": "What the list is called. Native, because the element already accepts it"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slAvatarGroup'",
+          "defaultValue": "—",
+          "appliesTo": "slAvatarGroup",
+          "description": "Reaches the component instance from the template"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "There is no avatar-group pattern in the WAI-ARIA Authoring Practices. The component is written on 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 input. 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.",
+        "The summary’s accessible name is the hidden members’ names, read from the avatar inside each item and 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 member past the limit carries hidden, which takes it out of the layout and out of the accessibility tree in one attribute. Its name is not lost: the group reads it and puts it on the summary.",
+        "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. 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.",
+        "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-angular-basic",
+      "title": "A list of faces, and a summary of the rest",
+      "note": null,
+      "language": "html",
+      "source": "<ul slAvatarGroup aria-label=\"Reviewers\">\n  @for (person of reviewers(); track person.id) {\n    <li slAvatarGroupItem>\n      <span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-angular-total",
+      "title": "Three of forty, from a paged endpoint",
+      "note": null,
+      "language": "html",
+      "source": "<ul\n  slAvatarGroup\n  aria-label=\"Attendees\"\n  [total]=\"event().attendeeCount\"\n  [overflowLabel]=\"event().attendeeCount - 3 + ' more attendees'\"\n>\n  @for (person of firstAttendees(); track person.id) {\n    <li slAvatarGroupItem>\n      <span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-angular-spread",
+      "title": "Laid apart rather than stacked",
+      "note": null,
+      "language": "html",
+      "source": "<ul slAvatarGroup aria-label=\"Team\" layout=\"spread\" size=\"lg\" [max]=\"false\">\n  @for (person of team(); track person.id) {\n    <li slAvatarGroupItem>\n      <span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-angular-links",
+      "title": "Members that open a profile",
+      "note": null,
+      "language": "html",
+      "source": "<ul slAvatarGroup aria-label=\"Assignees\" size=\"sm\">\n  @for (person of assignees(); track person.id) {\n    <li slAvatarGroupItem>\n      <a\n        slAvatar\n        [name]=\"person.name\"\n        [src]=\"person.photograph\"\n        [routerLink]=\"['/people', person.id]\"\n      ></a>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "avatar-group-angular-ring",
+      "title": "A group on a coloured row",
+      "note": null,
+      "language": "html",
+      "source": "<ul\n  slAvatarGroup\n  aria-label=\"Reviewers\"\n  style=\"--slotted-avatar-ring-color: var(--slotted-surface-sunken)\"\n>\n  @for (person of reviewers(); track person.id) {\n    <li slAvatarGroupItem>\n      <span slAvatar [name]=\"person.name\" [src]=\"person.photograph\"></span>\n    </li>\n  }\n</ul>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/avatar-group.md

@@ -0,0 +1,130 @@
+<!-- index: ./index.md -->
+# avatar-group
+
+`data-ui="avatar-group"` · Overlapping avatars with an overflow count.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<ul slAvatarGroup aria-label="Reviewers">
+  @for (person of reviewers(); track person.id) {
+    <li slAvatarGroupItem>
+      <span slAvatar [name]="person.name" [src]="person.photograph"></span>
+    </li>
+  }
+</ul>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `layout` | `'stack' \| 'spread'` | stack | slAvatarGroup | stack overlaps the members; spread lays them apart and wraps |
+| `max` | `number \| false` | 5 | slAvatarGroup | The largest number of discs the group draws, the summary included. false shows every member |
+| `total` | `number` | — | slAvatarGroup | How many members there really are, when the page renders fewer than it has |
+| `overflowLabel` | `string` | — | slAvatarGroup | What the summary is called. Defaults to the hidden members’ names, joined for the locale |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | slAvatarGroup | Provided to every member, and the length the overlap is measured against |
+| `shape` | `'circle' \| 'square'` | circle | slAvatarGroup | Provided to every member. An avatar that states its own still wins |
+| `variant` | `'soft' \| 'solid'` | — | slAvatarGroup | Provided to every member. tone is never provided: it is the member’s own identity |
+| `locale` | `string` | — | slAvatarGroup | BCP 47, for the digits of the summary and for joining the hidden names |
+| `slAvatarGroupItem` | `directive` | — | li | One member. Hidden when it falls past the limit, and its name is what the summary is called |
+| `aria-label` | `string` | — | slAvatarGroup | What the list is called. Native, because the element already accepts it |
+| `exportAs` | `'slAvatarGroup'` | — | slAvatarGroup | Reaches the component instance from the template |
+
+## 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 component is written on 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 input. 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.
+- The summary’s accessible name is the hidden members’ names, read from the avatar inside each item and 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 member past the limit carries hidden, which takes it out of the layout and out of the accessibility tree in one attribute. Its name is not lost: the group reads it and puts it on the summary.
+- 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. 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.
+- 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
+
+```html
+<ul
+  slAvatarGroup
+  aria-label="Attendees"
+  [total]="event().attendeeCount"
+  [overflowLabel]="event().attendeeCount - 3 + ' more attendees'"
+>
+  @for (person of firstAttendees(); track person.id) {
+    <li slAvatarGroupItem>
+      <span slAvatar [name]="person.name" [src]="person.photograph"></span>
+    </li>
+  }
+</ul>
+```
+
+### Laid apart rather than stacked
+
+Excerpt — not a complete module
+
+```html
+<ul slAvatarGroup aria-label="Team" layout="spread" size="lg" [max]="false">
+  @for (person of team(); track person.id) {
+    <li slAvatarGroupItem>
+      <span slAvatar [name]="person.name" [src]="person.photograph"></span>
+    </li>
+  }
+</ul>
+```
+
+### Members that open a profile
+
+Excerpt — not a complete module
+
+```html
+<ul slAvatarGroup aria-label="Assignees" size="sm">
+  @for (person of assignees(); track person.id) {
+    <li slAvatarGroupItem>
+      <a
+        slAvatar
+        [name]="person.name"
+        [src]="person.photograph"
+        [routerLink]="['/people', person.id]"
+      ></a>
+    </li>
+  }
+</ul>
+```
+
+### A group on a coloured row
+
+Excerpt — not a complete module
+
+```html
+<ul
+  slAvatarGroup
+  aria-label="Reviewers"
+  style="--slotted-avatar-ring-color: var(--slotted-surface-sunken)"
+>
+  @for (person of reviewers(); track person.id) {
+    <li slAvatarGroupItem>
+      <span slAvatar [name]="person.name" [src]="person.photograph"></span>
+    </li>
+  }
+</ul>
+```