# AvatarGroup

> Componentes / Conteúdo · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Avatares sobrepostos em fila, com um círculo "+N" para os que passam do limite — prova social ("e mais 250 mil formados"). É um grupo com o total para quem ouve: "6 participantes".

- Função: Conteúdo
- Também chamado de: grupo de avatares, pilha de fotos, prova social
- Mora em: `app/components/molecules/AvatarGroup.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/AvatarGroup](https://phorte-design-system.vercel.app/styleguide/peca/AvatarGroup)
- Ficha no Storybook: [components-complex-avatargroup](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-avatargroup--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/AvatarGroup/0](https://phorte-design-system.vercel.app/previa/AvatarGroup/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { AvatarGroup } from '@/app/components/molecules/AvatarGroup';

<AvatarGroup avatars={…}>…</AvatarGroup>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/AvatarGroup/0)
2. [Com Excedente](https://phorte-design-system.vercel.app/previa/AvatarGroup/1)
3. [Tamanhos](https://phorte-design-system.vercel.app/previa/AvatarGroup/2)
4. [Um só](https://phorte-design-system.vercel.app/previa/AvatarGroup/3)
5. [Com rótulo](https://phorte-design-system.vercel.app/previa/AvatarGroup/4)
6. [Com adicionar](https://phorte-design-system.vercel.app/previa/AvatarGroup/5)
7. [Com presença](https://phorte-design-system.vercel.app/previa/AvatarGroup/6)

Para mostrar que várias pessoas participam — alunos, palestrantes, inscritos — sem listar todas.

### Quando não usar

Para uma pessoa só, use o Avatar. Para apresentar pessoas com nome e cargo, o EventSpeaker ou o TeamGrid.

### Faça

- Escreva ao lado o que o grupo significa ("+ de 250.000 alunos") — o grupo sozinho não diz.
- Dê o `name` completo de cada pessoa (E64): é o nome do avatar e a fonte das iniciais.
- Ajuste `max` ao espaço: quatro por padrão. Use menos quando a fila divide a linha com texto.
- Troque o `rotulo` quando "participantes" não disser quem são: "6 palestrantes".
- Passe `onAdicionar` para o botão de convidar (E116), com um `rotuloDoAdicionar` que diga a ação ("Convidar para o grupo de estudo").

### Evite

- Esperar que o "+N" diga de quê: o leitor ouve "e mais 3 pessoas", mas o que o grupo significa ("formados", "inscritos") precisa estar escrito ao lado.
- Usar para logotipos de parceiros: é só para pessoas (a nota do SLDS registra esse erro).

### Nota de uso

**Só para pessoas** (E64) — logotipos de parceiros vão numa faixa de logos, não aqui. Passe o `name` completo em cada avatar; o grupo anuncia o total ("6 participantes", ou o `rotulo`), e o contador diz "e mais 2 pessoas". Use `max` para caber no espaço, e escreva ao lado o que o grupo significa. O salto no hover saiu: o avatar não é clicável.

### Anatomia

1. **Avatares** — Até `max`, sobrepostos (o primeiro por cima), com borda da cor do fundo.
2. **Contador** — Círculo `--muted` com "+N", do mesmo tamanho dos avatares.
3. **Adicionar** — Com `onAdicionar`: círculo tracejado `--border-interactive` com o sinal de mais, 12px depois da fila, do tamanho dos avatares; área de toque de 44px pela utilidade `area-de-toque` (pseudo-elemento).

### Estados

| Estado | O que muda |
| --- | --- |
| Padrão | Avatares sobrepostos, `md` por padrão. |
| Excedente | Com mais pessoas que `max`, aparece o "+N". |
| Com adicionar | O botão tracejado ao lado; no hover e no foco, borda e sinal em `--primary`. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Mais pessoas que `max` | Mostra as primeiras `max` e o "+N" com o resto. |
| Foto que falha | Cada Avatar troca pelas iniciais do `name` (ou do `fallback`). |
| Hover | Nada (E64): o salto de 4px saiu — movimento em avatar que não é clicável prometia uma ação que não existe. |
| "Adicionar" acionado | Chama `onAdicionar`; quem chama abre o convite (um Modal, uma Gaveta) — testado na ficha, pelo teclado. |

### Relacionados

- [Avatar](https://phorte-design-system.vercel.app/styleguide/md/Avatar.md) — Uma pessoa.
- [EventSpeaker](https://phorte-design-system.vercel.app/styleguide/md/EventSpeaker.md) — Pessoas com foto, nome e cargo.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | não | Variante do `cva`. |
| `avatars` | `{ src?: string; name?: string; alt?: string; fallback?: string; presenca?: 'disponivel' \| 'ausente' }[]` | — | sim | Uma pessoa por item. O `name` completo vai em cada avatar (E64). |
| `max` | `number` | `4` | não |  |
| `rotulo` | `string` | — | não | Nome do grupo para quem ouve (E64). Padrão: o total, "6 participantes". Diga quem são quando o contexto não disser: "6 palestrantes". |
| `onAdicionar` | `() => void` | — | não | Mostra o botão "Adicionar" depois dos avatares (E116) — convidar alguém para a turma, para o grupo de estudo. Sem a prop, o botão não aparece. |
| `rotuloDoAdicionar` | `string` | `'Adicionar pessoa'` | não | O nome do botão (padrão "Adicionar pessoa"). |

Aceita também: `React.HTMLAttributes<HTMLDivElement>`.

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Sobreposição, `md` | −12px | `-space-x-3` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--primary` | #D42B2B | `border-primary`, `text-primary` |
| `--background` | #FAFAFA | `border-background` |
| `--border-interactive` | #8C8C8C | `border-border-interactive` |
| `--card` | #FFFFFF | `bg-card` |
| `--muted` | #F4F6F9 | `bg-muted` |
| `--muted-foreground` | #595959 | `text-muted-foreground` |

## Acessibilidade

### Teclado

| Tecla | Faz |
| --- | --- |
| Tab | Com `onAdicionar`, chega ao botão de adicionar; os avatares não recebem foco. |
| Enter / Espaço | Aciona o "Adicionar". |

### Leitor de tela

- `role="group"` com o total ("6 participantes", ou o `rotulo`), conferido no teste da ficha — antes quem ouvia recebia quatro nomes e "e mais 2", sem saber que eram seis.
- Cada avatar é lido pelo `name`; o contador é lido como "e mais 2 pessoas" (o "+2" visível é `aria-hidden`).
- O "Adicionar" é um botão com nome ("Adicionar pessoa", ou o `rotuloDoAdicionar`), dentro do grupo.

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/AvatarGroup.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-avatargroup--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `0298af8` 2026-09-30 — E147: fechamento da Entrega 11 — REPORT.md, verificação cross-agent e o gate estático estrito
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/AvatarGroup.tsx