ToastViewport
Aviso de sucesso
A área de avisos já vem montada pelo RivoProvider. A aplicação só chama o gancho.
Aviso de uma espera
Com promise, o mesmo aviso atravessa a espera e vira o resultado.
Excluir com desfazer
- Projeto Atlas
- Projeto Borealis
- Projeto Cometa
import { ToastViewport } from '@rivocode/ui'Quando usar
A área onde os avisos aparecem. Ela já vem montada dentro do RivoProvider,
então na prática o aplicativo nunca a escreve: chama useToast() e pronto.
const toast = useToast()
toast.add({ title: 'Pedido 10516 confirmado', description: 'O comprovante foi para o e-mail.' })
O gancho
useToast() devolve quatro funções, e nenhuma delas precisa de estado seu:
| Função | O que faz |
|---|---|
add(options) |
Cria o aviso e devolve o id dele |
update(id, options) |
Reescreve um aviso que ainda está na tela |
close(id) |
Tira o aviso antes da hora |
promise(promessa, estados) |
Um aviso só para as três fases de uma espera |
O options do add tem title, description, type e timeout. O type
escolhe o tom no mesmo vocabulário do Alert, info, success, warning e
danger; sem ele o aviso sai neutro, que é o padrão e o que serve para a maior
parte das confirmações. timeout: 0 deixa o aviso na tela até alguém fechar.
O tom mora no fundo e no ícone
O aviso de tom pinta o fundo tingido e põe o ícone do tom à esquerda, na cor
do tom: Info, CheckCircle2, TriangleAlert e CircleX, o mesmo par do
Alert (o error desenha o do danger). O título fica em fg e a descrição
em fg-muted, porque cor nunca é o único sinal, e o ícone carrega o tom sem
pintar o texto. O neutro e o loading saem sem ícone.
icon troca o símbolo de um aviso só, e null tira. Ele vale no add, no
update e em cada fase do promise:
toast.add({ title: 'Produto favoritado', type: 'success', icon: <Heart /> })
toast.add({ title: 'Sincronização pausada', type: 'warning', icon: null })
A borda continua neutra, e é diferente do Alert de propósito. O Alert mora
no fluxo da página, e o fundo tingido já é a borda dele; o aviso flutua sobre
qualquer coisa, com sombra, e a borda é a borda da camada, a mesma do Menu e do
Popover, que separa o aviso de um conteúdo do mesmo tom embaixo dele.
O xis de cada aviso se chama "Fechar aviso", e a região que o leitor de tela
anuncia se chama "Notificações". Para trocar o idioma, passe
toastLabels={{ dismiss: "Dismiss", region: "Notifications" }} ao
RivoProvider, que entrega o labels à área.
toast.promise(publishProduct(), {
loading: { title: 'Publicando o produto…' },
success: (code) => ({ title: `Produto ${code} publicado na loja` }),
error: { title: 'A publicação falhou' },
})
O promise existe para a espera não virar três avisos empilhados. É um aviso
só, que troca de texto e de tom conforme a promessa resolve; a alternativa,
add na saída e outro add na volta, deixa o "enviando" na tela ao lado do
"enviado".
Cabem três avisos na tela ao mesmo tempo. O quarto entra e o mais antigo sai de
vista até um dos outros fechar, e aí volta, com o xis funcionando: um aviso com
timeout: 0 continua esperando a pessoa fechar, em vez de ficar visível e sem
resposta ao clique.
O objeto que o gancho devolve tem identidade estável entre renderizações, então ele pode entrar na lista de dependências de um efeito sem laço. O gerenciador da Base UI por baixo não tem essa garantia, e absorver isso é trabalho da biblioteca, não de quem a usa.
Desfazer
A ação reversível ganha desfazer, e não confirmação: faz na hora, e o aviso
oferece a volta por alguns segundos. actionProps desenha o botão dentro do
aviso, e é quem o pede que decide o que ele faz e se o aviso fecha junto:
const toast = useToast()
function remove(project: Project) {
removeFromList(project.id)
const id = toast.add({
title: `Projeto ${project.name} excluído`,
timeout: 8000,
actionProps: {
children: 'Desfazer',
onClick: () => {
restore(project)
toast.close(id)
},
},
})
}
Dê mais tempo que o padrão ao aviso com desfazer: ler, entender e alcançar o
botão leva mais que ler um "salvo". Sem actionProps, o aviso não ganha botão
nenhum além do xis.
O botão do aviso no leitor de tela
O aviso é lido em voz alta quando entra, e o botão dele se alcança pelo
teclado: F6 leva o foco para a área de avisos, de qualquer ponto da página, e
o Tab anda entre o aviso, o botão e o xis. O xis fica escondido do leitor de
tela até a área receber foco, para o anúncio não terminar em "Fechar aviso".
priority: 'high' muda duas coisas. O anúncio passa a interromper o que o
leitor estava falando, e o aviso inteiro fica fora da leitura linha a linha
(aria-hidden) até receber foco, para não ser lido duas vezes. Quem navega
pela leitura linha a linha não acha o botão nesse caso, então o aviso urgente
com actionProps precisa do mesmo caminho fora dele, como o sino da central de
notificações ou um link na própria página. Use high só no que não pode
esperar: um pedido novo, uma sessão que vai expirar.
Onde o aviso aparece
O padrão é bottom-right, que é o canto que menos disputa com o conteúdo:
cabeçalho, título e ação principal moram em cima. Para mudar, escolha no
provider, e não com CSS por cima:
<RivoProvider toastPosition="top-center">
<App />
</RivoProvider>
Os seis cantos são top-left, top-center, top-right, bottom-left,
bottom-center e bottom-right; o tipo ToastPosition é essa união, para
quando o canto vem de uma configuração e não de uma constante.
O aviso entra sempre pela borda mais próxima do canto escolhido. Um aviso ancorado à esquerda que deslizasse da direita atravessaria a tela inteira para chegar ao lugar, e o olho seguiria o movimento errado até perceber que o texto já estava lá.
Vale sair do padrão quando o aviso responde a uma ação que acontece longe dali, ou quando aquele canto já está ocupado por outra coisa fixa, como um botão flutuante.
Barra fixa embaixo. Nos três cantos de baixo, a distância da borda é
--rc-toast-bottom (1rem sem ela) mais a área do gesto do celular. A tela que
tem uma barra presa embaixo, como a navegação do celular ou o botão de comprar,
declara a altura dela nessa variável, e o aviso aparece acima da barra em vez
de cobri-la:
@media (max-width: 767px) {
:root {
--rc-toast-bottom: calc(4.5rem + 0.5rem);
}
}
O foco depois de fechar
Fechar um aviso pelo teclado não joga o foco para o começo da página. Ele vai para o aviso vizinho quando há outro na pilha, e, fechado o último, volta para onde estava antes de entrar nos avisos. Sem esse lugar, fica na região dos avisos, e o próximo Tab segue dali. O xis tem 22 pixels desenhados e área de toque de 30.
Quando não usar
Aviso é para o que já aconteceu, e o que já aconteceu não precisa de resposta.
Se a pessoa tem de decidir algo, use AlertDialog. Se a informação precisa
ficar na tela enquanto ela trabalha, use Alert, que mora no fluxo da página e
não some sozinho.
Erro de formulário também não é aviso: ele pertence ao campo que errou, via
FieldError, onde a pessoa está olhando e pode corrigir.
No React Native
No React Native esta peça é useToast - não se monta nada: o RivoProvider já traz a fiação, e o hook é o mesmo, com as quatro funções: add devolve o id, type escolhe o tom no vocabulário do Alert, timeout: 0 deixa o aviso até o close(id), e update e promise reescrevem o aviso que está na tela. Aqui o title e a description são string, porque o aviso é lido em voz alta, e não há xis: o aviso sem botão não recebe toque, então o que fica sai pelo close. Sem timeout, ele sai em 4 segundos, e não nos 5 do web. O actionProps do web, que põe o desfazer dentro do aviso, existe aqui com onPress no lugar do onClick ({ children: "Desfazer", onPress }), e só o aviso com botão recebe toque. O aviso sobe e desce com as durações do web, e aparece parado quando o sistema pede para reduzir movimento. O tom fica no fundo, sem borda saturada, como no Alert nativo, e o aviso de tom pousa sobre a surface-raised, para o que está embaixo não aparecer através dele. O pacote não traz ícone, então não há o símbolo do tom por padrão: icon aceita um nó ou a função ({ color, size }) => <CircleX color={color} size={size} />, que recebe a cor do tom, e só com ele o título passa a fg; sem ícone, o título continua na cor do tom, porque é o único sinal além do fundo. No web o ícone do tom vem por padrão, e o título é sempre fg. O aviso aparece por cima do Modal aberto da casa (Dialog, AlertDialog, Sheet, Tour e ImageViewer): o Modal do React Native é uma janela própria e cobriria a raiz, então o aviso passa a morar no Modal de cima enquanto ele está aberto, uma vez só, e volta para a raiz quando ele fecha. Modal escrito à mão no app não leva o aviso. A tabela de paridade tem o resto do catálogo.
API
| Prop | Tipo | Padrão |
|---|---|---|
containerobrigatória0.4.0Onde o portal ancora. | HTMLElement | null | sem padrão |
labelsOs textos da peca, para trocar o idioma: `dismiss` e o nome do xis de cada aviso, "Fechar aviso" sem ele; `region` e o nome da regiao que o leitor de tela anuncia, "Notificações" sem ele. | Partial<ToastLabels> | sem padrão |
position0.4.0Onde os avisos aparecem. | ToastPosition | "bottom-right" |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ToastViewportState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.