Toast

O toast é o único componente aqui que não pode ser estático: aparece em resposta a algo que aconteceu. A página desenha uma zona vazia com toasts(), e o toast() de sitelo/ui/client acrescenta-lhe coisas.

A zona é uma região viva educada, por isso tudo o que lá for acrescentado é anunciado sem roubar o foco.

Configuração

Põe a zona em qualquer sítio do body — é de posição fixa, por isso o sítio não importa:

import { toasts } from 'sitelo/ui'

body(
  // …a página…
  toasts(),
)

Esta é a única parte do runtime que nada na página dispara por ti, por isso é a única que alcanças tu — a partir de um atributo de evento, sem nada no bundle:

button({ onclick: "import('/su/toast.js').then(m=>m.toast('Guardado.',{color:'success'}))" }, 'Guardar')

Ou a partir do teu próprio módulo, quando já houver um a correr:

import { toast } from 'sitelo/ui/client'

toast('Guardado.', { color: 'success' })

Experimenta

Esta página desenha uma zona toasts() e os botões abaixo vão buscar o runtime eles próprios, por isso produzem mesmo toasts — em baixo à direita. Nada é carregado até carregares num.

stack({ direction: 'row', gap: 'sm', wrap: true },
  button({
    variant: 'soft',
    color: 'success',
    onclick: "import('/su/toast.js').then(m=>m.toast('Guardado.',{color:'success'}))",
  }, 'Success'),
  button({
    variant: 'soft',
    color: 'warning',
    onclick: "import('/su/toast.js').then(m=>m.toast('Duas páginas não têm meta description.',{color:'warning'}))",
  }, 'Warning'),
  button({
    variant: 'soft',
    color: 'danger',
    onclick: "import('/su/toast.js').then(m=>m.toast('A construção falhou. Vê o relatório de ligações.',{color:'danger'}))",
  }, 'Danger'),
  button({
    variant: 'soft',
    color: 'neutral',
    onclick: "import('/su/toast.js').then(m=>m.toast('Este fica até o fechares.',{color:'neutral',duration:0}))",
  }, 'Até ser fechado'),
)

Opções

duration é quanto tempo o toast fica, em milissegundos; 0 mantém-no até alguém o fechar. Todos os toasts levam botão de fechar, ligado ao mesmo handler que um alerta usa.

toast('Guardado.', { color: 'success' })
toast('Ainda a trabalhar…', { color: 'neutral', duration: 0 })
toast('Publicado em 1,7 s', { color: 'success', duration: 8000 })

O que desenha

Um toast é um alert() dentro da zona de toasts — a mesma marcação, as mesmas cores, o mesmo botão de fechar. Nada de novo para aprender, e nada de extra para estilizar.

stack({ gap: 'sm', style: 'width: 100%; max-width: 24rem' },
  alert({ color: 'success', dismissible: true }, 'Guardado.'),
  alert({ color: 'danger', dismissible: true }, 'A construção falhou. Vê o relatório de ligações.'),
)

Quando usar um

Um toast serve para confirmar algo que o leitor acabou de fazer. É o sítio errado para o que ele tem de resolver ou de ler com atenção — desaparece, é fácil de perder, e num site estático a maioria das mensagens pertence à própria página, como um alert().

Props

toasts() não aceita props próprias. O toast() de sitelo/ui/client:

Devolve o elemento que acrescentou, ou null quando a página não tem zona toasts().