Toast de aviso

Uma pilha de avisos curtos e efêmeros, presa a um canto da tela: "relatório enviado", "link copiado", "não foi possível enviar". Cada aviso traz um ícone de tom, o texto, um botão de fechar e uma régua de tempo que encolhe — é ela que torna o desaparecimento previsível em vez de arbitrário. No máximo três ficam de pé ao mesmo tempo; o quarto empurra o mais antigo para fora, e quem sai deixa os de baixo subirem no lugar, sem salto.

É a peça mais modesta desta leva, e isso é julgamento honesto, não desleixo: ela existe para dar retorno a uma ação que não muda de página — envio de formulário, cópia de um dado, download iniciado —, e o problema editorial que resolve é justamente não ter nenhum. Um aviso de erro que ninguém lê é pior que nenhum aviso; por isso a peça pausa sozinha quando alguém está lendo, em vez de confiar que cinco segundos bastam para qualquer frase.

Quando usar

• Como confirmação de uma ação que não navega: formulário enviado, texto copiado, arquivo baixado, preferência salva.
• Quando o retorno pode ser perdido sem drama — se a pessoa piscar e não ver o aviso, a ação ainda aconteceu. Toast é reforço, não o único lugar onde a informação existe.
• Empilhado com outros: a peça já resolve até três avisos simultâneos sem que um cubra o outro.

Quando não usar

• Para erro que bloqueia o próximo passo (campo obrigatório vazio, cartão recusado). Isso é mensagem inline, ao lado do campo — a pessoa não pode precisar lembrar o que um aviso que já sumiu dizia. Ver o gotcha "Sem JavaScript", abaixo, e o .lead-ok do conversao/cta-formulario-lead.
• Para confirmação que exige uma decisão (desfazer, confirmar, escolher entre duas opções). Isso é overlay/modal-dialogo: o toast fecha sozinho, e uma decisão não pode fechar sozinha.
• Para consentimento de cookies. É overlay/aviso-cookies — parece um toast, mas não pode desaparecer por tempo nem ser um entre quatro: precisa ficar até alguém decidir.
• Mais de um aviso por ação. Se uma submissão dispara três toasts em sequência, a pessoa não sabe qual ler primeiro.

Padrão editorial

Nada de retorno prometido. "Relatório enviado" é fato; "Sua carteira vai render mais" não é o tipo de frase que cabe num toast, nem em lugar nenhum desta biblioteca. Os três textos de exemplo no markup.html são ilustrativos, como todo conteúdo desta leva.

Este componente não mostra número, comparação nem captura dado — por isso não há uma seção ## Compliance dedicada (o gatilho para ela, no contrato, é justamente esse). A única exigência que sobra é a voz do texto, coberta acima.

Especificação dos assets

Nenhum. Não há imagem: o único elemento visual além do texto é o ícone de tom, e ele já é <svg> inline no próprio markup.html — não existe arquivo para versionar nem para trocar por projeto.

Como usar

<link rel="stylesheet" href="componentes/overlay/toast-aviso/estilo.css">
<script src="componentes/overlay/toast-aviso/script.js" defer></script>

Cole o bloco da .tst-pilha uma vez, perto do fim do <body> — ela é fixa e vale para a página inteira. Depois, qualquer botão em qualquer lugar da página dispara um aviso com três atributos:

<button type="button" data-tst-dispara data-tst-tom="ok" data-tst-texto="Relatório consolidado enviado para o seu e-mail.">
  Enviar relatório
</button>

data-tst-tom aceita info (padrão), ok ou atencao. data-tst-duracao é opcional, em milissegundos (padrão 5000).

Ganchos

Variações

• Duração por tom — já usada no próprio exemplo: data-tst-duracao="7000" no botão de falha, contra os 5000 padrão dos outros dois. Não há constante fixa por tom no script; cada gatilho decide.
• Canto oposto ou barra superior — troque right/bottom por left/top em .tst-pilha. O invólucro e a régua não mudam, só a âncora.
• Aviso com ação — um segundo botão ou link dentro de .tst-linha, antes do botão de fechar ("Desfazer", "Ver relatório"). O pausar-ao-focar já cobre o elemento novo; falta decidir se clicar na ação também fecha o aviso.

Gotchas

• A pilha é position:fixed e fica fora de qualquer [data-rv], e isso não é estilo — é o blur(0) do reveal do core. [data-rv].in termina em filter:blur(0), que continua sendo um filtro: um elemento com filtro é bloco de contenção para descendente position:fixed (MANUAL §5). Uma pilha nascida dentro de uma seção revelada por data-rv prenderia o overlay dentro da seção, não da janela — o aviso "flutuante" na verdade ficaria colado a um ponto do meio da página. Por isso .tst-pilha entra como irmã da seção de exemplo no markup.html, nunca como filha de um bloco com data-rv.

• Não existe token de cor por tom, de propósito. A biblioteca só tem --accent como cor de marca; "verde de sucesso" e "vermelho de alerta" não têm token global, e --tst-ok/--tst-atencao seriam cor crua escondida atrás de um nome de variável prefixada — o que o §6.6 do contrato não distingue de uma cor solta. A diferença de tom sai por ícone (três <svg> no template, um por tom, só um display:block por vez) e por papel de acessibilidade. Efeito colateral bom: a peça é legível para quem não distingue vermelho de verde, sem precisar de modo especial nenhum. Candidato a discussão de arquitetura, relatado à parte — ver relatório final do orquestrador.

• Cada aviso é a própria região viva; não existe um contêiner de aria-live fixo na pilha. Tom info/ok nasce role="status" (implica polite); tom atencao nasce role="alert" (implica assertive). Duas regiões permanentes — uma polite, uma assertive — se atropelariam no instante em que chegasse um aviso de cada tipo ao mesmo tempo, e leitor de tela nenhum garante ordem entre duas regiões que mudam junto. Como o elemento inteiro (já com o role certo) entra pronto no DOM a partir do <template>, o leitor de tela recebe a própria inserção como o anúncio.

• A saída colapsa por grid-template-rows: 0fr -> 1fr, não por altura medida em pixel. É o mesmo problema que motivou o --perf-palco-medido do conversao/diagnostico-perfil, com a solução oposta: lá o conteúdo muda de tamanho de formas imprevisíveis e só um script medindo resolve; aqui a caixa não muda de forma, só aparece e desaparece, e o truque do grid resolve sem o script tocar em getBoundingClientRect. .tst-item é o invólucro (a linha do grid que anima); .tst-caixa é o conteúdo, com min-height:0 e overflow:hidden — as duas propriedades sem as quais o item de grid nunca encolhe abaixo do próprio conteúdo.

• .tst-item e .tst-caixa são nós diferentes pelo mesmo motivo do §5 do contrato sobre transform. Aqui não há transform de repouso disputando especificidade com o core, mas a lição é irmã: o nó que leva a transição de layout (grid-template-rows) não pode ser o mesmo que precisa de conteúdo com altura livre — juntar os dois exigiria animar max-height com um valor cravado, que é exatamente o que o truque do grid evita.

• A régua de tempo não tem transition no CSS. Ela é redesenhada por transform:scaleX() a cada quadro do requestAnimationFrame, com o valor calculado por dt (teto de 50ms). Uma transição CSS por cima brigaria com um valor que já muda a ~60× por segundo, e a régua perderia precisão — o sintoma seria uma barra que sempre "persegue" o valor real com um pequeno atraso. É também por isso que ela continua se movendo em movimento reduzido: nunca teve animação declarativa para desligar, e ela é informação (quanto tempo falta), não enfeite — a única peça do componente com essa exceção explícita. Medido: com prefers-reduced-motion:reduce, transition-duration do invólucro cai para 1e-5s e ainda assim a régua de um aviso de 900ms foi de scaleX(.9497) a scaleX(.5516) em 350ms — a mesma curva de queda de quando o movimento não está reduzido — e o aviso some sozinho no tempo certo.

• O quarto aviso empurra o mais antigo pelo MESMO caminho de qualquer fechamento, nunca por um atalho. montar() chama o mesmo fechar() que o botão e o fim do tempo chamam; é por isso que o mais antigo sai com a mesma transição, e os de baixo sobem sem salto, em vez de a pilha simplesmente cortar para três. Medido: 4 cliques no mesmo botão, esperando a saída terminar, deixam exatamente 3 .tst-item no DOM, todos com .is-shown.

• Só a primeira .tst-pilha da página é usada — de propósito, ao contrário do resto da biblioteca. O script.js faz document.querySelector (singular), não querySelectorAll. Os outros componentes autorais podem repetir na página sem colidir; um toast não ganha nada em repetir, porque duas pilhas ativas disputariam o mesmo canto ou exigiriam uma decisão de layout (qual pilha recebe qual aviso) que é da página, não do componente.

• A escuta de clique é delegada no document, não na raiz do componente — a mesma exceção que modal e drawer têm ao §7.6 do contrato. A regra "parta da raiz" existe para não colidir com uma cópia irmã; um toast não tem esse risco (só uma pilha conta, ver acima) e tem o problema oposto: o gatilho é, por definição, qualquer parte da página. Travar a escuta em pilha.contains(gatilho) exigiria que cada botão de disparo morasse dentro da pilha fixa, o que descreve nenhum uso real.

• Pausar ao focar usa focusin/focusout com checagem de relatedTarget, não só blur/focus. Um aviso com uma segunda ação (ver variação "aviso com ação") tem dois elementos tabuláveis; sem checar se o novo foco ainda está dentro do mesmo .tst-item, tabular do texto para o botão de fechar retomaria a contagem por um quadro antes de pausar de novo — pequeno, mas seria a régua "piscando" a cada Tab.

• O <button class="btn btn-ghost"> dos gatilhos de exemplo já foi um problema, e a correção está no core. A primitiva .btn não zerava background nem appearance, e com color-scheme:only light (tokens.css) o <button> pintava o cromo nativo do controle, cinza claro, sob o texto claro do tema escuro — medido em rgb(240,240,240) contra rgb(242,240,236), legenda invisível. Nunca apareceu em <a class="btn"> porque âncora não tem appearance nativo, e é por isso que passou tanto tempo despercebido. Corrigido em core/base.css em 2026-09-06, na própria regra .btn; o remendo local que este componente carregava foi removido junto. Se algum dia a legenda de um botão sumir num tema escuro, é aqui que se olha.

• O botão de fechar é um <button> de verdade, e o Esc fecha só o aviso com foco dentro — nunca a pilha inteira. Fechar três avisos de uma vez porque a pessoa quis fechar um é agressivo demais para uma peça deste tamanho; e sem foco em nenhum aviso, Esc não faz nada (não há "o" aviso ativo numa pilha — pode haver três). Medido: o botão é <button>, disabled:false, tabIndex:0 — nada no componente tira ele da ordem natural de tabulação nem simula clique com outro elemento.

• A pilha inteira é pointer-events:none; só cada .tst-item devolve auto. Sem isso, a caixa invisível da pilha (que existe só para posicionar — ela não tem fundo) bloquearia clique na página por baixo mesmo nos vãos entre avisos e abaixo do último. Medido com dois avisos empilhados: um clique no meio de um deles acha o próprio toast (elementFromPoint retorna um nó dentro do .tst-item); um clique no vão entre os dois atravessa e acha o <html> por trás — a página continua clicável ao redor da pilha.

• No celular a pilha vira faixa, e o --tst-inset é a mesma variável nos dois modos. Só left/right/width mudam na media query; o respiro até a borda é o mesmo clamp em qualquer largura, o que mantém o alinhamento visual previsível. Medido a 390px: pilha de 14px a 376px (362px de largura útil), sem estourar para nenhum lado, e sem overflow horizontal na página com um aviso aberto.

Histórico

Origem. Não há referência única e não há uma linha copiada. O padrão — avisos curtos empilhados num canto, um por ação concluída, desaparecendo sozinhos com uma régua de tempo — é praticamente universal em produto digital: notificação de sistema operacional (macOS, Windows), snackbar do Material Design, e a leva recente de bibliotecas de toast de dashboard SaaS (Stripe, Linear, Vercel). O que a biblioteca tirou dessas famílias foi a forma da tela — canto, empilhamento, régua —, nunca o código.

Decisões da tradução para o contrato:

• A régua de tempo conta por dt com teto de 50ms num requestAnimationFrame que dorme quando nenhum aviso está contando, em vez de uma animação CSS declarativa — é o que permite pausar e retomar de onde parou em vez de reiniciar, e o que respeita o §3/§7 do contrato sobre tempo, não quadro.
• O colapso de altura na saída usa grid-template-rows em vez de o script medir scrollHeight: zero JavaScript de layout, e a transição roda mesmo se o conteúdo do aviso mudar de uma linha para duas (texto mais longo num projeto futuro).
• A diferença de tom é ícone e papel de acessibilidade, nunca cor — a biblioteca não tem token semântico de sucesso/alerta, e inventar um seria cor crua disfarçada de variável prefixada.
• Cada aviso é a própria região aria-live, em vez de um contêiner permanente único: um contêiner só escolheria entre polite e assertive uma vez para a sessão inteira, e erraria toda vez que chegasse um aviso do outro tipo.
• Disparo por data-tst-dispara delegado no document: é a mesma exceção de modal e drawer ao §7.6 do contrato, porque o gatilho de um toast é, por definição, qualquer lugar da página — nunca um descendente da própria pilha.

Sem JavaScript. Sem script, o <template> nunca vira DOM e os três botões de exemplo não fazem nada — o que é honesto: um toast é o retorno de uma ação que já depende de JavaScript (enviar formulário, copiar para a área de transferência). Ele não substitui a mensagem inline de erro de um formulário; complementa. Quem precisa de retorno que sobrevive a JavaScript desligado usa mensagem inline no próprio campo, como o .lead-ok do conversao/cta-formulario-lead.