# Qual canal de mensagem

Cada mensagem tem um lugar, e o lugar diz à pessoa o tamanho do assunto: a
mensagem da tarefa fica perto da tarefa, a da conta fica no topo, e o que é
crítico não some sozinho.

## O problema

O erro de pagamento que aparece num aviso de canto e some em cinco segundos,
enquanto a pessoa olhava para o formulário. A manutenção de amanhã escrita num
`Alert` no meio do cadastro. Três faixas empilhadas no topo, uma em cima da
outra, até ninguém ler nenhuma. Cada canal errado ou some antes da hora, ou
grita mais que o assunto.

## Quando usar

| Canal | Para quê | Onde | Some sozinho? | Exemplo |
|---|---|---|---|---|
| `Alert` | o que diz respeito a um trecho da tela ou a uma tarefa, e precisa ficar lido | junto do trecho, no topo do formulário ou no lugar do conteúdo | não; fecha só se a pessoa fechar | "Não foi possível salvar. O que você mudou continua aqui." |
| `Banner` | o que diz respeito à conta, ao produto ou à sessão inteira | faixa de largura total, no topo da área que governa | não; sai quando o motivo acaba, ou quando a pessoa dispensa | "Fatura em atraso", "Modo de teste", manutenção programada |
| Aviso do `useToast` | o retorno de uma ação pequena que deu certo, com desfazer quando cabe | o canto da tela, por cima | sim, em segundos | "Nota 4816 arquivada. Desfazer" |
| `NotificationCenter` | o que aconteceu enquanto a pessoa estava fora, e que ela lê quando quiser | o sino do cabeçalho, com a contagem | não; fica até ser lida | "Pedido 482 entregue", "Ana comentou na proposta" |
| `Result` | o desfecho de um fluxo longo, ou a página que não pode mostrar o que pediu | no lugar do formulário, ou da página inteira | não; é a tela | "Pagamento confirmado", "Você não tem acesso ao Faturamento" |

O erro de campo não é canal: mora no campo, pelo `FormField`
([erros.md](https://ds.rivocode.com.br/padroes/erros.md)).

## Quando não usar

- **Aviso que some não serve para erro que exige ação.** A pessoa estava olhando
  para outro canto, e perde. Erro de envio é `Alert`.
- **`Banner` não serve para o que é de um trecho só.** Manutenção da conta é
  faixa; o CNPJ que a Receita não achou é `Alert` junto do campo.
- **`Alert` não serve para o sucesso de uma ação pequena**: fica na tela para
  sempre dizendo "Salvo".
- **A central não serve para o que precisa de resposta agora**: a pessoa só a
  abre quando quer. O que não pode esperar é `Banner`, ou aviso com
  `priority: 'high'` e o mesmo caminho na página.
- **`Result` não serve para aviso ao lado do conteúdo**: ele toma o lugar.

## As peças

- `Alert` com `tone`, `AlertTitle`, `AlertDescription` e `onDismiss`.
- `Banner` com `tone`, `title`, `description`, `actions` e `onDismiss`, e `flush`
  quando a faixa mora dentro de um `Card`, encostada nas bordas dele.
- `useToast` com `add`, `promise`, `type`, `timeout`, `actionProps` e
  `priority`.
- `NotificationCenter` com `items`, `onMarkRead` e `onItemClick`.
- `Result` com `tone`, `illustration`, `actions` e `layout`.

## Comportamento

- **A mensagem da tarefa fica perto dela.** O erro do salvar aparece na barra
  de salvar, e não no topo da página; o erro do gráfico, no lugar do gráfico.
  Quanto mais longe da causa, mais a pessoa tem de procurar a ligação.
- **Um `Banner` por vez.** Duas razões de conta ao mesmo tempo viram uma faixa
  com a mais grave; a outra espera, ou vai para a central. Faixas empilhadas
  empurram o conteúdo para baixo da dobra e treinam a pessoa a não ler faixa.
- **O crítico não some sozinho.** Erro, risco de perda, prazo que vence e
  qualquer coisa com ação obrigatória ficam até a pessoa agir ou fechar:
  `Alert`, `Banner`, ou aviso com `timeout: 0`.
- **No máximo três avisos na tela.** O quarto espera o mais antigo sair. Muitos
  avisos em sequência são sinal de que a ação devia ser em lote, ou de que o
  sucesso devia ser calado.
- **O aviso de sucesso com desfazer fica mais tempo**: 8 segundos ou mais.
- **O que entra na central também pode ter ido a outro canal**, mas o
  contrário não: aviso de canto que some não é registro.

## Texto

- O `Alert` e o `Banner` têm título que diz o assunto e descrição que diz o que
  fazer: "Fatura em atraso. A fatura de agosto venceu há 5 dias. O acesso da
  equipe será suspenso em 10/10."
- O aviso diz o que aconteceu, com o objeto e o número: "Nota 4816 arquivada",
  e não "Sucesso!".
- A notificação da central começa pelo que aconteceu e com quem: "Ana comentou
  na proposta de maio".
- O tom do texto acompanha o tom da cor: `danger` diz o que falhou, e não
  "Atenção".

## Acessibilidade

- `Alert` e `Banner` de `danger` e `warning` saem com `role="alert"` e
  interrompem o leitor; `info` e `success` saem com `role="status"` e esperam a
  frase terminar.
- O aviso do `useToast` é lido quando entra, e `F6` leva o foco para a área de
  avisos de qualquer ponto da página. O `priority: 'high'` interrompe o leitor,
  e precisa do mesmo caminho fora do aviso, porque fica fora da leitura linha a
  linha.
- O sino da central diz a contagem no nome: "3 notificações não lidas".
- Cor nunca é o sinal sozinha: cada tom tem ícone e texto.

## No celular e no nativo

No celular o aviso sobe do pé da tela, acima da área segura, e só recebe toque
quando tem botão. A central abre como folha de baixo. O `Banner` cabe em 320px,
com as ações embaixo do texto. No `@rivocode/ui-native` todos os cinco existem:
o `Alert` com `title` em prop e o corpo como filho, o `Banner` com `title` e
`description` em texto, o aviso pelo `useToast` (o `RivoProvider` já traz a
fiação), a `NotificationCenter` numa `Sheet`, e o `Result`, que anuncia ao
montar em vez de levar o foco.

## Os blocos que o aplicam

- [Manutenção programada](https://ds.rivocode.com.br/blocos#manutencao-programada)
