Toast

O mk-toast exibe notificações temporárias via função imperativa toast(). Ele aparece brevemente na interface — geralmente no canto da tela — para comunicar feedback imediato sem interromper o fluxo do usuário. Não bloqueia a interface, dispensa-se automaticamente após o tempo configurado e pausa o timer ao passar o mouse. Cada estado semântico (sucesso, erro, aviso, informação) usa cor e ícone distintos para comunicar a natureza da mensagem de forma imediata.

Quando usar

Use o mk-toast para situações em que o usuário precisa de um retorno rápido do sistema sem ser interrompido em sua tarefa atual.

• Uma ação foi concluída e o usuário precisa de confirmação rápida ("Salvo com sucesso").
• Ocorreu um erro não bloqueante que o usuário deve conhecer.
• O sistema precisa comunicar um evento sem interromper o que o usuário está fazendo.

• A mensagem exigir uma decisão do usuário — use um Dialog.
• O erro for crítico e bloquear o uso da funcionalidade — use uma mensagem inline no formulário.
• A informação precisar ficar visível por tempo indeterminado — use um banner de alerta fixo.

Anatomia

O toast é composto por uma borda lateral colorida (indicador semântico) e uma área de conteúdo.

Variantes

Cada variante comunica a natureza semântica da mensagem por meio de cor de borda e ícone específicos. Use success para confirmar ações concluídas, warning para situações que merecem atenção mas não bloqueiam o fluxo, info para comunicados neutros sobre o sistema e error para falhas que o usuário precisa conhecer.

import { toast } from '@db1/makuco-ui-core';

toast({ variant: 'success', message: 'Salvo com sucesso', description: 'As alterações foram aplicadas.' });
toast({ variant: 'error',   message: 'Erro ao salvar' });
toast({ variant: 'warning', message: 'Atenção' });
toast({ variant: 'info',    message: 'Informação' });

import { toast } from '@db1/makuco-ui-core';

toast({ variant: 'success', message: 'Salvo com sucesso', description: 'As alterações foram aplicadas.' });
toast({ variant: 'error',   message: 'Erro ao salvar' });
toast({ variant: 'warning', message: 'Atenção' });
toast({ variant: 'info',    message: 'Informação' });

Posições

toast({ message: 'Aviso', description: 'Toast posicionado no topo ao centro.', position: 'top-center' });
toast({ message: 'Aviso', description: 'Toast posicionado no canto inferior esquerdo.', position: 'bottom-left' });

toast({ message: 'Aviso', description: 'Toast posicionado no topo ao centro.', position: 'top-center' });
toast({ message: 'Aviso', description: 'Toast posicionado no canto inferior esquerdo.', position: 'bottom-left' });

Afastamento da borda

Os contêineres ficam rente às bordas da viewport. Para afastá-los de uma barra fixa, como um rodapé, defina os ganchos de CSS no :root:

• --mk-toast-offset-bottom: afasta as posições bottom-* da borda inferior.
• --mk-toast-offset-top: afasta as posições top-* da borda superior.

O valor soma-se ao espaçamento interno do contêiner. Sem os ganchos, nada muda.

:root {
  --mk-toast-offset-bottom: 64px; /* altura do rodapé fixo */
}

Sem ícone e sem fechar

toast({ variant: 'info', message: 'Sem ícone',        description: 'O ícone da variante está oculto.',       showIcon: false });
toast({ variant: 'info', message: 'Sem botão fechar', description: 'Este toast só fecha pelo temporizador.', closable: false });

toast({ variant: 'info', message: 'Sem ícone',        description: 'O ícone da variante está oculto.',       showIcon: false });
toast({ variant: 'info', message: 'Sem botão fechar', description: 'Este toast só fecha pelo temporizador.', closable: false });

Duração

toast({ message: 'Rápido', description: 'Este toast fecha automaticamente em 5s.',  duration: 5000  });
toast({ message: 'Médio',  description: 'Este toast fecha automaticamente em 7s.',  duration: 7000  });
toast({ message: 'Longo',  description: 'Este toast fecha automaticamente em 10s.', duration: 10000 });

toast({ message: 'Rápido', description: 'Este toast fecha automaticamente em 5s.',  duration: 5000  });
toast({ message: 'Médio',  description: 'Este toast fecha automaticamente em 7s.',  duration: 7000  });
toast({ message: 'Longo',  description: 'Este toast fecha automaticamente em 10s.', duration: 10000 });

Persistente

duration: 0 mantém o toast na tela até o usuário fechar (WCAG 2.2.1). Combine com closable.

toast({ variant: 'warning', message: 'Sessão expirando', duration: 0, closable: true });

toast({ variant: 'warning', message: 'Sessão expirando', duration: 0, closable: true });

Idioma

locale (pt, es, en) traduz o botão de fechar e o rótulo da região de notificações. Sem valor, usa o lang do ancestral mais próximo, depois <html lang>, e por fim pt-BR.

toast({ message: 'Saved', locale: 'en' });

toast({ message: 'Saved', locale: 'en' });

Comportamento

O toast é acionado de forma imperativa pela função toast(), que insere o elemento na interface sem bloquear a interação do usuário. Ao ser exibido, um temporizador é iniciado automaticamente e, ao expirar, o componente executa a animação de saída e se remove do DOM.

O timer é pausado quando o usuário posiciona o cursor sobre o toast, permitindo a leitura completa da mensagem. Ao mover o cursor para fora, o temporizador retoma de onde parou.

Quando o botão de fechar (closable) está disponível, o usuário pode dispensar o toast manualmente a qualquer momento, independentemente do tempo restante. O evento mkToastDismiss é emitido após a animação de saída ser concluída, tanto no fechamento manual quanto no automático.

Composição

O toast não possui elementos filhos configuráveis via slots — todo o conteúdo é passado como opções para a função toast(). A mensagem principal (message) é obrigatória e aparece em destaque; a descrição (description) é opcional e fornece contexto adicional abaixo da mensagem.

Múltiplos toasts podem ser exibidos simultaneamente e são empilhados na posição configurada. Cada chamada a toast() cria uma instância independente com seu próprio temporizador e ciclo de vida.

Fechar por código

toast() devolve um controle com id e dismiss(). Ele continua sendo uma Promise: await toast() resolve quando o toast é exibido, não quando é removido.

import { dismissAll, toast } from '@db1/makuco-ui-core';

const salvando = toast({ message: 'Salvando…', duration: 0, closable: false });
// ...
salvando.dismiss();      // fecha com a animação de saída

toast({ id: 'sync', message: 'Sincronizando…', duration: 0 });
toast({ id: 'sync', message: 'Sincronizado' }); // substitui o toast aberto com o mesmo id

dismissAll();            // fecha todos os toasts abertos

id identifica o toast: um toast aberto com o mesmo id é substituído, sem empilhar duplicado, e pode mudar de posição. Sem id, o serviço gera um, disponível em handle.id. dismissAll() fecha todos os toasts abertos e remove os contêineres vazios. O dismiss() de um handle fecha só o toast que ele criou: se um toast com o mesmo id o substituiu, o handle antigo não tem efeito sobre o novo.

API — toast(options)

Eventos

Acessibilidade

• Variantes error e warning usam role="alert" com aria-live="assertive" — leitores de tela anunciam imediatamente.
• Variantes success e info usam role="status" com aria-live="polite" — anunciam na próxima pausa.
• O timer é pausado ao passar o mouse, permitindo leitura completa sem perder a mensagem.
• O container de toasts recebe role="region" e aria-label="Notificações". O botão de fechar e o rótulo da região seguem locale.
• Com duration: 0 o toast permanece até o usuário fechar (WCAG 2.2.1).

Não dependa só da cor: cada variante usa cor e ícone juntos para comunicar o estado — nunca use cor como único indicador, pois usuários com daltonismo podem não distinguir os tipos.

Tempo de exibição: toasts que desaparecem automaticamente devem dar tempo suficiente para leitura (mínimo 5 segundos para mensagens curtas). O botão de fechar manual garante controle ao usuário mesmo quando o timer ainda está ativo.