# ResumoDeErros

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

O resumo de erros do padrão GOV.UK, no topo do formulário: um título que diz quantos problemas há e um link para cada campo com erro. Recebe o foco quando o envio falha — quem usa leitor de tela ouve o resumo uma vez, em vez de um alerta por campo — e cada link leva o foco ao campo.

- Função: Formulário e ação
- Também chamado de: resumo de erros, lista de erros, error summary, erros do formulário
- Mora em: `app/components/molecules/ResumoDeErros.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/ResumoDeErros](https://phorte-design-system.vercel.app/styleguide/peca/ResumoDeErros)
- Ficha no Storybook: [components-complex-resumodeerros](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-resumodeerros--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/ResumoDeErros/0](https://phorte-design-system.vercel.app/previa/ResumoDeErros/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 { ResumoDeErros } from '@/app/components/molecules/ResumoDeErros';

<ResumoDeErros erros={…}>…</ResumoDeErros>
```

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

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/ResumoDeErros/0)
2. [Um erro](https://phorte-design-system.vercel.app/previa/ResumoDeErros/1)
3. [No formulário](https://phorte-design-system.vercel.app/previa/ResumoDeErros/2)

Em formulário com mais de um campo que pode dar erro ao enviar: contato, inscrição, matrícula.

### Quando não usar

Em formulário de um campo só (a Newsletter): o erro do FormField, anunciado na hora, basta. Para uma mensagem sobre a página, não sobre campos, use o Alert.

### Faça

- Passe os `erros` na ordem dos campos na tela, cada um com o `idDoCampo` e a mensagem que diz como acertar.
- Aumente a `tentativa` a cada envio que falha: é ela que manda o foco para o resumo.
- Nos FormField do mesmo formulário, passe `anunciarErro={false}`: o resumo é o alerta; o erro continua ligado ao campo.
- Acerte o `nivelDoTitulo` conforme a página (padrão `h2`).

### Evite

- Mostrar o resumo antes do primeiro envio: ele responde a uma tentativa, não à digitação.
- Mensagem diferente no resumo e no campo: a pessoa lê uma e procura a outra.

### Anatomia

1. **Caixa** — Borda de 2px `--destructive` e fundo `--destructive-subtle`; recebe o foco e interrompe o leitor: `<div role="alert" tabIndex={-1}>`.
2. **Título** — "Há um problema no formulário" ou "Há N problemas no formulário", com o ícone de alerta; nomeia a caixa.
3. **Links** — Um por erro, com a mensagem do campo; levam o foco a ele.

### Estados

| Estado | O que muda |
| --- | --- |
| Sem erro | Não aparece (e o título da página volta ao normal). |
| Um erro | Título no singular. |
| Vários erros | Título com a contagem e a lista. |
| Foco | O anel de foco do sistema na caixa, depois do envio. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Envio que falha | Com a `tentativa` nova, o resumo recebe o foco — testado na ficha. |
| Link de um erro | O foco vai para o campo, e a página rola até ele — testado na ficha. Sem JavaScript, o `href` leva até lá. |
| Título da página | Com `prefixarTituloDaPagina` (padrão), ganha "Erro: " enquanto houver erro, e volta ao normal depois — testado na ficha. |

### Relacionados

- [FormField](https://phorte-design-system.vercel.app/styleguide/md/FormField.md) — O erro de cada campo, com `anunciarErro`.
- [ContactForm](https://phorte-design-system.vercel.app/styleguide/md/ContactForm.md) — O formulário onde ele nasceu.
- [Alert](https://phorte-design-system.vercel.app/styleguide/md/Alert.md) — Mensagem sobre a página, não sobre campos.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `erros` | `ErroDoFormulario[]` | — | sim | Os erros, na ordem dos campos na tela. Sem erro, o resumo não aparece. |
| `tentativa` | `number` | `0` | não | Muda a cada envio que falha (um contador serve). O resumo recebe o foco quando ela muda e há erro — e não ao montar, para não roubar o foco de quem só abriu a página. |
| `nivelDoTitulo` | `'h2' \| 'h3' \| 'h4'` | `'h2'` | não | Nível do título (padrão `h2`). Acerte conforme a página. |
| `prefixarTituloDaPagina` | `boolean` | `true` | não | Põe "Erro: " na frente do título da página enquanto houver erro (padrão GOV.UK): é a primeira coisa que o leitor de tela diz ao voltar à aba. Desligue quando a página já cuida do próprio título. |

Aceita também: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--destructive` | #BA0517 | `border-destructive` |
| `--destructive-strong` | #BA0517 | `text-destructive-strong` |
| `--destructive-subtle` | #F9EBEC | `bg-destructive-subtle` |

## Acessibilidade

### Teclado

| Tecla | Faz |
| --- | --- |
| Tab | Do resumo com foco, passa pelos links dos erros, na ordem dos campos. |
| Enter | Num link, leva o foco ao campo do erro. |

### Leitor de tela

- Um anúncio por envio: o resumo tem o foco e é lido; os campos, com `anunciarErro={false}`, não disparam alertas próprios.
- O erro do campo continua na descrição dele, com "Erro:" na frente (`sr-only`), lido quando o foco chega.

### O que sustenta o estado

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

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/ResumoDeErros.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-resumodeerros--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/ResumoDeErros.tsx