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' });

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 });

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.

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".

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.