fokus-styles 2.3.0 → 2.5.0

package/docs/components/alert.md

@@ -1,42 +1,89 @@
 # Alert
 
-Mensagem de estado (sucesso, erro, aviso, informação) com destaque visual —
-fundo tintado, texto com contraste garantido, barra lateral colorida.
+Mensagem contextual persistente para informar, confirmar, orientar ou explicar
+um erro relacionado à região da página. Alert é CSS-only; para feedback
+transitório controlado por JavaScript, use [Toast](toast.md).
 
-## Visão geral
+## Uso mínimo
 
 ```html
-<div class="fs-alert">Alerta neutro, sem cor de estado.</div>
 <div class="fs-alert fs-alert-success">Operação concluída com sucesso.</div>
 ```
 
-## Anatomia
+O uso antigo continua válido. Variantes: `.fs-alert-primary`,
+`.fs-alert-secondary`, `.fs-alert-success`, `.fs-alert-warning`,
+`.fs-alert-danger` e `.fs-alert-info`.
+
+## Visão geral
 
-Um único elemento, `.fs-alert` — sem marcação interna obrigatória.
+Alert permanece visível no contexto da página até que a aplicação resolva a
+condição ou faça seu fechamento manual. Não é substituto de Toast nem de
+Alert Dialog.
 
-## Variações
+## Anatomia opcional
 
-Cor: `.fs-alert-{primary|secondary|success|warning|danger|info}`. Sem
-modificador, usa borda/texto neutros. Sem tamanhos (`-sm`/`-lg`) — Alert é
-sempre o mesmo `padding`.
+Os slots abaixo são opcionais. O ícone deve ser decorativo quando o texto já
+comunica o estado.
 
 ```html
-<div class="fs-alert fs-alert-danger">Ocorreu um erro ao processar a solicitação.</div>
-<div class="fs-alert fs-alert-warning">Atenção: essa ação não pode ser desfeita.</div>
+<div class="fs-alert fs-alert-danger" role="alert">
+  <span class="fs-alert-icon" aria-hidden="true"><svg class="fs-icon" aria-hidden="true"><!-- ícone --></svg></span>
+  <div class="fs-alert-content">
+    <h3 class="fs-alert-heading">Não foi possível salvar</h3>
+    <p class="fs-alert-text">Verifique os campos destacados e tente novamente.</p>
+    <div class="fs-alert-actions">
+      <button type="button" class="fs-btn fs-btn-danger fs-btn-sm">Tentar novamente</button>
+      <a class="fs-alert-link" href="#detalhes">Ver detalhes</a>
+    </div>
+  </div>
+  <button type="button" class="fs-btn-close fs-alert-close" aria-label="Fechar aviso"></button>
+</div>
 ```
 
+Classes: `.fs-alert-icon`, `.fs-alert-content`, `.fs-alert-heading`,
+`.fs-alert-text`, `.fs-alert-actions`, `.fs-alert-link` e `.fs-alert-close`.
+O fechamento é apenas composição visual; a aplicação liga sua própria lógica.
+
+Para mensagens relacionadas, use `.fs-alert-group` no contêiner. A variante
+`.fs-alert-inline` reduz a densidade para mensagens próximas a campos ou
+regiões compactas. Para operações assíncronas, aplique `aria-busy="true"` e
+componha um `.fs-spinner` decorativo; o Alert não desabilita ações nem gerencia
+o término da operação automaticamente.
+
 ## Estados
 
-Nenhum — elemento estático. Para um alerta dispensável, monte você mesmo
-com um `.fs-btn-close` (ver [Toast](toast.md) para o padrão de dispensa com
-JS, caso precise).
+Não há estados JavaScript próprios. Links, botões e o fechamento visual usam
+seus estados nativos de foco, hover e ativação.
+
+## Layout e tokens
+
+O acabamento usa raio médio, borda estrutural neutra e barra semântica em
+`border-inline-start`, funcionando em RTL. Textos longos quebram sem overflow
+e ações usam flex-wrap em telas estreitas.
+
+Tokens locais sobrescrevíveis: `--fs-alert-padding-block`,
+`--fs-alert-padding-inline`, `--fs-alert-gap`, `--fs-alert-radius`,
+`--fs-alert-border-width`, `--fs-alert-accent-width`, `--fs-alert-icon-size`,
+`--fs-alert-heading-gap` e `--fs-alert-actions-gap`.
+
+```html
+<div class="fs-alert fs-alert-danger">Ocorreu um erro ao processar a solicitação.</div>
+<div class="fs-alert fs-alert-warning">Atenção: essa ação não pode ser desfeita.</div>
+```
 
 ## A11y
 
-Para alertas que aparecem dinamicamente (não já presentes no HTML da
-carga), adicione `role="alert"` (ou `role="status"` para os menos urgentes)
-no elemento, pra leitores de tela anunciarem automaticamente — o framework
-não injeta esse atributo.
+O framework não injeta ARIA, não cria ícones automaticamente e não move foco.
+Use `role="status"` para atualização não urgente e `role="alert"` somente
+quando a mensagem precisar ser anunciada imediatamente. O significado deve
+continuar compreensível sem cor, ícone ou borda. Ícones decorativos usam
+`aria-hidden="true"`; informação adicional precisa de texto equivalente.
+
+Links e botões mantêm foco visível. Para decisão crítica use [Alert Dialog](alert-dialog.md);
+para mensagem breve use Toast.
+
+Em `forced-colors: active`, a borda semântica usa as cores do sistema e o
+conteúdo continua legível sem depender do fundo tintado.
 
 ## API JS
 
@@ -44,10 +91,8 @@ Nenhuma — 100% CSS.
 
 ## Tokens
 
-`--fs-alert-{nome}-bg`/`-text` (fundo tintado e texto, calculados por
-`tint-color()`/`shade-color()` a partir do primitivo — ver
-[`docs/reference/design-tokens.md`](../reference/design-tokens.md)),
-`--fs-color-border`. Alerts usam `border-radius: 0`.
+`--fs-alert-{nome}-bg`/`-text` (fundo tintado e texto) e `--fs-color-border`.
+Os tokens locais acima permitem ajuste por instância.
 
 ## Exemplo
 
@@ -56,4 +101,4 @@ Nenhuma — 100% CSS.
 <div class="fs-alert fs-alert-danger" role="alert">Erro ao salvar as alterações.</div>
 ```
 
-Mockup: [laboratório do componente](../../mockup/feedback-actions.html#alert).
+Mockup: [laboratório do componente](../../mockup/examples/alerts.html).

package/docs/components/badge.md

@@ -26,8 +26,15 @@ Um único elemento, `.fs-badge` — sem marcação interna obrigatória.
   metadados e filtros. As variantes sólidas permanecem para destaque alto.
 - **Tamanho**: `.fs-badge-sm` (18px), `.fs-badge-lg` (26px); sem sufixo =
   22px (padrão).
+- **Acabamento**: usa `--fs-radius-sm` (4px) por padrão, mantendo cantos
+  levemente arredondados sem transformar o badge em uma pílula.
+- **Densidade**: `--fs-badge-padding-inline`,
+  `--fs-badge-padding-block-start` e `--fs-badge-padding-block-end` permitem
+  ajustar o espaço interno localmente sem substituir o componente inteiro.
 - **Padrões**: `.fs-badge-dot` adiciona um indicador circular antes do texto;
-  `.fs-badge-count` estabiliza contagens com algarismos tabulares.
+  `.fs-badge-count` estabiliza contagens com algarismos tabulares e
+  `.fs-badge-count-circle` cria um indicador circular para contagens curtas,
+  preferencialmente de um único dígito.
 - **Split**: `.fs-badge-split` reúne um rótulo e um valor em segmentos
   conectados. Use `.fs-badge-split-{nome}` para colorir o valor; os elementos
   internos obrigatórios são `.fs-badge-split-label` e
@@ -64,10 +71,13 @@ Nenhuma — 100% CSS.
 Usa os tokens de cor de tema (`--fs-color-{nome}`, ver
 [`docs/reference/design-tokens.md`](../reference/design-tokens.md)) e expõe
 `--fs-badge-color`, `--fs-badge-bg`, `--fs-badge-border`,
-`--fs-badge-height` e `--fs-badge-radius` (0 por padrão) para
-personalização localizada. Split também expõe
+`--fs-badge-height` e `--fs-badge-radius` (`var(--fs-radius-sm)` por padrão)
+para personalização localizada. A densidade também pode ser ajustada com
+`--fs-badge-padding-inline`, `--fs-badge-padding-block-start` e
+`--fs-badge-padding-block-end`. Split também expõe
 `--fs-badge-split-{label|value}-{bg|color}`, `--fs-badge-split-height` e
-`--fs-badge-split-radius`.
+`--fs-badge-split-radius` (`var(--fs-radius-sm)` por padrão), aplicado ao
+contêiner externo que conecta o rótulo e o valor.
 
 ## Exemplo
 
@@ -77,6 +87,15 @@ personalização localizada. Split também expõe
 <span class="fs-badge fs-badge-warning fs-badge-sm">Pendente</span>
 <span class="fs-badge fs-badge-soft-success fs-badge-dot">Online</span>
 <span class="fs-badge fs-badge-count fs-badge-danger">12</span>
+<span class="fs-badge fs-badge-count fs-badge-count-circle fs-badge-danger" aria-label="1 notificação não lida">1</span>
 ```
 
+## Composição e contraste
+
+Mantenha o badge próximo do título, status ou contagem que ele qualifica e
+não use a cor como única indicação de estado. Para filtros ou ações, use um
+botão ou Tag, não um badge estático. Em temas e marcas customizadas, valide
+as variantes `soft` e `outline` com `npm run contrast:check` e confirme que o
+texto continua legível nos temas claro e escuro.
+
 Mockup: [laboratório do componente](../../mockup/feedback-actions.html#badge).

package/docs/components/checkbox.md

@@ -51,6 +51,10 @@ o preenchimento fica mais intenso para confirmar o clique.
   versão atenuada de `primary`, em vez de reduzir a opacidade do controle todo.
 - **Foco**: `:focus-visible` no input desenha o anel sobre a caixa
   (`::before` da label), não sobre o texto.
+- **Hover/active**: superfície e borda confirmam a interação sem depender
+  apenas da cor do texto.
+- **RTL e movimento**: propriedades lógicas acompanham `dir="rtl"` e as
+  transições são desativadas em `prefers-reduced-motion: reduce`.
 
 ```html
 <input type="checkbox" class="fs-check-input is-invalid" id="c1">
@@ -69,6 +73,9 @@ document.getElementById("c2").indeterminate = true;
 - Sempre associe `label` via `for`/`id` — não use só `aria-label` no input
   se houver texto visível ao lado (duplica a leitura ou some com o clique
   no texto).
+- Para grupos relacionados, use `fieldset`/`legend`. Associe ajuda ou erro
+  com `aria-describedby` e indique erro com `aria-invalid="true"` quando
+  aplicável.
 
 ## API JS
 
@@ -77,9 +84,15 @@ Nenhuma — 100% CSS. `indeterminate` é uma propriedade do DOM nativo do
 
 ## Tokens
 
-Sem tokens de componente próprios — usa `--fs-color-primary` (caixa
-marcada), `--fs-color-border`/`--fs-color-surface` (caixa vazia),
-`--fs-color-success`/`--fs-color-danger` (validação), `--fs-radius-sm`.
+Tokens de componente podem ser sobrescritos por instância sem `!important`:
+
+| Token | Fallback | Uso |
+|---|---|---|
+| `--fs-check-size` | `18px` | Caixa visual |
+| `--fs-check-border-width` | `--fs-border-width` | Borda |
+| `--fs-check-radius` | `--fs-radius-sm` | Raio |
+| `--fs-check-gap` | `--fs-space-2` | Distância até o texto |
+| `--fs-check-mark-color` | `--fs-color-on-primary` | Marca |
 
 ## Exemplo
 

package/docs/components/popover.md

@@ -19,9 +19,10 @@ aparência de card de superfície em vez do chip escuro.
 ## Anatomia
 
 Gatilho (qualquer elemento) + `.fs-popover` > `.fs-popover-header`
-(opcional) + `.fs-popover-body` + `.fs-popover-footer` (opcional, ações
-alinhadas à direita). A seta (`.fs-popover-arrow`) é gerada
-automaticamente.
+(opcional) + `.fs-popover-body` + `.fs-popover-footer` (opcional). Slots
+aditivos incluem `.fs-popover-icon`, `.fs-popover-heading`,
+`.fs-popover-title`, `.fs-popover-meta`, `.fs-popover-text` e
+`.fs-popover-close`. A seta (`.fs-popover-arrow`) é posicionada junto ao painel.
 
 ## Variações
 
@@ -52,7 +53,9 @@ automaticamente.
 
 ## Estados
 
-`.is-open` — controlado pelo JS.
+`.is-open` — controlado pelo JS. Escape, clique externo (trigger click) e
+`data-fs-dismiss="popover"` fecham conforme o tipo de gatilho. Popover não é
+modal: não bloqueia scroll nem cria focus trap.
 
 ## A11y
 
@@ -63,6 +66,12 @@ clique fora fecha. Um elemento dentro do popover com
 `data-fs-dismiss="popover"` fecha ao ser clicado (útil pra um botão "OK"
 no footer).
 
+Ao abrir outro Popover, o painel anterior é fechado para evitar sobreposição.
+O posicionamento testa alternativas quando o lado solicitado não cabe na
+viewport, e a seta acompanha o alinhamento do gatilho. Para conteúdo carregado
+de forma assíncrona, use `aria-busy="true"` e componha um `.fs-spinner` com
+texto de carregamento.
+
 ## API JS
 
 Auto-init via `data-fs="popover"`. `Popover.getInstance(el)` (`el` é o
@@ -83,7 +92,12 @@ Auto-init via `data-fs="popover"`. `Popover.getInstance(el)` (`el` é o
 ## Tokens
 
 `--fs-color-border`, `--fs-color-surface`, `--fs-color-subtle` (header),
-`--fs-color-text`, `--fs-radius-md`, `--fs-shadow-md`.
+`--fs-color-text`, `--fs-radius-md`, `--fs-shadow-md` e os tokens locais
+`--fs-popover-width`, `--fs-popover-max-width`, `--fs-popover-padding-block`,
+`--fs-popover-padding-inline`, `--fs-popover-gap`, `--fs-popover-radius`,
+`--fs-popover-shadow`, `--fs-popover-icon-size`, `--fs-popover-heading-gap`,
+`--fs-popover-footer-gap`, `--fs-popover-arrow-size` e
+`--fs-popover-border-width`.
 
 ## Exemplo
 
@@ -101,5 +115,4 @@ Auto-init via `data-fs="popover"`. `Popover.getInstance(el)` (`el` é o
 </div>
 ```
 
-Mockup: [laboratório do componente](../../mockup/overlays-commands.html#popover),
-[`mockup/overlays-commands.html#hover-card`](../../mockup/overlays-commands.html#popover).
+Mockup: [laboratório independente do componente](../../mockup/examples/popover.html).

package/docs/components/radio.md

@@ -36,6 +36,9 @@ Tamanho: `.fs-radio-sm`, `.fs-radio-lg` no wrapper.
 - **checked**, **disabled**, validação (`.is-valid`/`.is-invalid`) e foco —
   mesmo padrão do [Checkbox](checkbox.md). Não existe `indeterminate` para
   radio.
+- Hover e active também alteram a superfície do círculo vazio e selecionado.
+- O controle acompanha `dir="rtl"`, `prefers-reduced-motion` e
+  `forced-colors: active`.
 
 ## A11y
 
@@ -45,6 +48,8 @@ Tamanho: `.fs-radio-sm`, `.fs-radio-lg` no wrapper.
   `Tab`/`Shift+Tab` entram/saem do grupo de uma vez (o item selecionado, ou
   o primeiro se nenhum estiver selecionado, é o único no fluxo de tab).
 - Sempre associe `label` via `for`/`id`.
+- Agrupe opções relacionadas com `fieldset`/`legend` e associe instruções ou
+  erros por `aria-describedby`.
 
 ## API JS
 
@@ -52,7 +57,12 @@ Nenhuma — 100% CSS.
 
 ## Tokens
 
-Mesmos do [Checkbox](checkbox.md) — sem tokens próprios.
+| Token | Fallback | Uso |
+|---|---|---|
+| `--fs-radio-size` | `18px` | Círculo externo |
+| `--fs-radio-dot-size` | `8px` | Ponto selecionado |
+| `--fs-radio-radius` | `50%` | Forma circular |
+| `--fs-radio-gap` | `--fs-space-2` | Distância até o texto |
 
 ## Exemplo
 

package/docs/components/responsive.md

@@ -0,0 +1,19 @@
+# Responsive
+
+## Visão geral
+
+Os utilitários `.fs-stack`, `.fs-cluster`, `.fs-stack-md-row` e
+`.fs-table-responsive` compõem layouts que se adaptam ao espaço disponível.
+O comportamento usa propriedades lógicas e funciona com `dir="rtl"`.
+
+## Estados
+
+Em telas estreitas, grupos responsivos ocupam toda a largura e tabelas passam
+a permitir rolagem horizontal. O layout continua funcional em zoom de 200% e
+em orientação portrait ou landscape.
+
+## A11y
+
+O componente não altera a ordem semântica do conteúdo. Para tabelas largas,
+mantenha uma legenda (`caption`) e forneça uma indicação textual quando a
+rolagem horizontal for necessária.

package/docs/components/switch.md

@@ -18,7 +18,7 @@ design deliberada (nada circular no framework além de radio/spinner).
 
 `.fs-switch` (wrapper) > `.fs-switch-input` (oculto via clip) +
 `.fs-switch-label` (`<label for="...">`, desenha o trilho via `::before` e
-o knob via `::after`, que desliza com `left` + `transition`).
+o knob via `::after`, que desliza com propriedades lógicas e `transition`).
 
 ## Variações
 
@@ -26,9 +26,11 @@ Tamanho: `.fs-switch-sm`, `.fs-switch-lg` no wrapper.
 
 ## Estados
 
-checked/disabled/foco — mesmo padrão do [Checkbox](checkbox.md). Sem
-`indeterminate` nem validação (switch não é um campo de formulário
-validável, é um controle de preferência/estado).
+checked/disabled/foco — mesmo padrão do [Checkbox](checkbox.md). O switch
+também possui hover com halo sutil, active com redução discreta do thumb,
+valid/invalid opcional para uso em formulário, forced colors e redução de
+movimento. O trilho desligado usa superfície neutra e o thumb possui contraste
+e elevação próprios. Não há `indeterminate`.
 
 ## A11y
 
@@ -40,6 +42,8 @@ validável, é um controle de preferência/estado).
 - Quando não houver texto visível ao lado (ex.: dentro de um
   [Tile](tile.md), como no exemplo abaixo), use `aria-label` no `<input>`
   em vez de deixar a `<label>` vazia.
+- O Fokus Styles não injeta `role="switch"`: o contrato oficial continua
+  sendo o checkbox nativo, com `Space` e anúncio de marcado/desmarcado.
 
 ```html
 <div class="fs-switch">
@@ -54,9 +58,27 @@ Nenhuma — 100% CSS.
 
 ## Tokens
 
-Sem tokens de componente próprios — usa `--fs-color-primary` (trilho
-ligado), `--fs-color-border` (knob desligado), `--fs-radius-md` (trilho),
-`--fs-radius-sm` (knob).
+| Token | Fallback | Uso |
+|---|---|---|
+| `--fs-switch-track-width` | `40px` | Largura do trilho |
+| `--fs-switch-track-height` | `24px` | Altura do trilho |
+| `--fs-switch-thumb-width` | `18px` | Largura do knob |
+| `--fs-switch-thumb-height` | `18px` | Altura do knob |
+| `--fs-switch-thumb-offset` | `3px` | Posição desligada |
+| `--fs-switch-on-offset` | `19px` | Posição ligada |
+| `--fs-switch-radius` | `--fs-radius-md` | Raio do trilho |
+| `--fs-switch-thumb-radius` | `--fs-radius-sm` | Raio do knob |
+| `--fs-switch-gap` | `--fs-space-2` | Distância até o texto |
+| `--fs-switch-track-bg` | `--fs-color-subtle` | Fundo desligado |
+| `--fs-switch-track-border` | `--fs-color-border-default` | Borda do trilho |
+| `--fs-switch-track-checked-bg` | `--fs-color-primary` | Fundo ligado |
+| `--fs-switch-thumb-bg` | `--fs-color-surface` | Fundo do knob |
+| `--fs-switch-thumb-border` | `--fs-color-border-default` | Borda do knob |
+| `--fs-switch-thumb-shadow` | `--fs-shadow-sm` | Elevação do knob |
+| `--fs-switch-track-shadow` | Sombra interna sutil | Profundidade do trilho desligado |
+| `--fs-switch-hover-ring` | Mistura de primary com transparente | Halo de hover |
+| `--fs-switch-hover-shadow` | Halo baseado em `--fs-switch-hover-ring` | Sombra de hover |
+| `--fs-switch-active-scale` | `0.92` | Escala do knob durante active |
 
 ## Exemplo
 
@@ -71,5 +93,5 @@ ligado), `--fs-color-border` (knob desligado), `--fs-radius-md` (trilho),
 </div>
 ```
 
-Mockup: [laboratório do componente](../../mockup/content-data.html#tile).
+Mockup: [laboratório do componente](../../mockup/forms.html#check-radio-switch).
 Uso combinado com Tile: [laboratório de conteúdo e dados](../../mockup/content-data.html#tile).

package/docs/components/tag.md

@@ -24,9 +24,14 @@ Badge, não um componente separado) contendo texto + `.fs-btn-close` com
 - **Tamanho**: apenas o tamanho padrão. Tags são controles compactos de
   remoção; usar uma única densidade evita variações de alvo e de texto em
   filtros e formulários.
-- **Ícone inicial**: envolva um SVG de `fokus-styles/icons` em `.fs-tag-icon` antes
-  de `.fs-tag-label`. O ícone é decorativo (`aria-hidden="true"`) quando o
-  texto já descreve a tag.
+- **Ícones**: envolva um SVG de `fokus-styles/icons` em `.fs-tag-icon` antes
+  de `.fs-tag-label` para ícone inicial ou use `.fs-tag-icon-end` depois do
+  texto para indicar um estado. O contêiner do ícone usa a mesma dimensão
+  visual do botão de fechamento; `--fs-tag-icon-size`,
+  `--fs-tag-icon-glyph-size`, `--fs-tag-icon-gap` e `--fs-tag-icon-color`
+  permitem ajustes locais. O
+  ícone é decorativo (`aria-hidden="true"`) quando o texto já descreve a tag;
+  nunca use uma Tag somente com ícone como padrão.
 - **Texto longo**: use `.fs-tag-truncate` na tag e `.fs-tag-label` no texto.
   Defina `--fs-tag-max-inline-size` conforme o contexto; o texto integral
   continua no DOM e pode ser exposto em `title` como apoio visual.
@@ -44,6 +49,9 @@ Badge, não um componente separado) contendo texto + `.fs-btn-close` com
   Conecte-o a um popover ou a uma lista expandida e mantenha `aria-expanded`
   sincronizado com essa interface.
 
+O botão de fechamento usa `--fs-tag-close-size` e `--fs-tag-close-gap`, herda
+o raio do Badge e é a única ação de remoção. A Tag inteira não é um botão.
+
 ```html
 <div class="fs-tag-group">
   <span class="fs-badge fs-tag" data-fs="tag">Design<button type="button" class="fs-btn-close" data-fs-dismiss="tag" aria-label="Remover"></button></span>
@@ -69,6 +77,11 @@ remoção é desabilitado até que o estado seja removido.
   Frontend", não só "Remover") — é um botão só-ícone.
 - A remoção só acontece ao clicar no botão de fechar, nunca ao clicar na
   tag inteira — evita remoção acidental.
+- Se o botão de fechar estiver focado quando a Tag for removida, o foco vai
+  para a próxima Tag do mesmo grupo; se não houver, vai para a anterior.
+  Remoções programáticas sem foco no botão não movem o foco.
+- Ícones com significado próprio precisam ser acompanhados por texto ou
+  descrição acessível; não dependa apenas do desenho ou da cor.
 - Para tags truncadas, mantenha a string completa dentro de `.fs-tag-label`;
   ela continua disponível para tecnologias assistivas. `title` é apenas uma
   ajuda adicional para ponteiro.
@@ -91,7 +104,9 @@ Auto-init via `data-fs="tag"`. `Tag.getInstance(el)`.
 
 ## Tokens
 
-Usa os tokens de [Badge](badge.md). Sem tokens de componente próprios.
+Usa os tokens de [Badge](badge.md) e expõe tokens locais para composição:
+`--fs-tag-icon-size`, `--fs-tag-icon-glyph-size`, `--fs-tag-icon-gap`, `--fs-tag-icon-color`,
+`--fs-tag-close-size` e `--fs-tag-close-gap`.
 
 ## Exemplo
 

package/docs/components/toast.md

@@ -1,15 +1,14 @@
 # Toast
 
-Notificação temporária, empilhada num canto da tela, com dispensa manual
-ou automática por tempo. Base do [Notification Center](notification-center.md).
+Notificação flutuante e temporária para confirmar uma ação não bloqueante.
+Para mensagens persistentes no contexto da página use [Alert](alert.md); para
+histórico e revisão posterior use [Notification Center](notification-center.md).
 
 ## Visão geral
 
 ```html
-<button type="button" class="fs-btn fs-btn-primary" id="btn-toast">Mostrar toast</button>
-
 <div class="fs-toast-container">
-  <div class="fs-toast fs-toast-success" data-fs="toast" id="meuToast" data-delay="4000">
+  <div class="fs-toast fs-toast-success" data-fs="toast" data-delay="4000">
     <div class="fs-toast-header">
       <span>Sucesso</span>
       <button type="button" class="fs-btn-close" data-fs-dismiss="toast" aria-label="Fechar"></button>
@@ -19,77 +18,91 @@ ou automática por tempo. Base do [Notification Center](notification-center.md).
 </div>
 ```
 
-```js
-document.getElementById("btn-toast").addEventListener("click", () => {
-  FokusStyles.Toast.getInstance(document.getElementById("meuToast")).show();
-});
-```
-
-Ao contrário de Modal/Offcanvas, o Toast **não** abre sozinho ao clicar num
-gatilho com `data-fs-target` — ele é mostrado programaticamente via
-`.show()`, porque geralmente é disparado por um evento da sua aplicação
-(sucesso de uma requisição, etc.), não diretamente por um clique.
+O Toast é inicializado pelo atributo `data-fs="toast"`, mas só aparece quando
+`.show()` é chamado. O container é fixo, empilha mensagens e usa propriedades
+lógicas para funcionar em RTL e respeitar áreas seguras móveis.
 
 ## Anatomia
 
-`.fs-toast-container` (posição fixa num canto — um só por página,
-compartilhado por todos os toasts) > `.fs-toast` (`data-fs="toast"`) >
-`.fs-toast-header` (título + `.fs-btn-close`) + `.fs-toast-body`.
+`.fs-toast-container` contém um ou mais `.fs-toast`. Dentro dele, os slots
+opcionais são `.fs-toast-header`, `.fs-toast-icon`, `.fs-toast-heading`,
+`.fs-toast-title`, `.fs-toast-meta`, `.fs-toast-body`, `.fs-toast-actions`,
+`.fs-toast-link`, `.fs-toast-close` e `.fs-toast-progress`.
+
+```html
+<div class="fs-toast fs-toast-success" data-fs="toast" data-delay="5000" data-toast-progress="true">
+  <div class="fs-toast-header">
+    <span class="fs-toast-icon" aria-hidden="true">✓</span>
+    <div class="fs-toast-heading">
+      <strong class="fs-toast-title">Arquivo salvo</strong>
+      <span class="fs-toast-meta">Agora</span>
+    </div>
+    <button type="button" class="fs-btn-close fs-toast-close" data-fs-dismiss="toast" aria-label="Fechar aviso de arquivo salvo"></button>
+  </div>
+  <div class="fs-toast-body">O documento foi salvo com sucesso.</div>
+  <div class="fs-toast-actions">
+    <button type="button" class="fs-btn fs-btn-sm fs-btn-success">Desfazer</button>
+    <a href="#detalhes" class="fs-toast-link">Ver detalhes</a>
+  </div>
+  <div class="fs-toast-progress" aria-hidden="true"></div>
+</div>
+```
+
+O ícone é fornecido pelo consumidor e deve ser decorativo quando o texto já
+explicar o estado. Ações usam Button; o fechamento continua sendo o único
+controle obrigatório da dispensa.
 
-## Variações
+## Variações e estados
 
-Cor: `.fs-toast-{primary|secondary|success|warning|danger|info}` no
-`.fs-toast` — tinge só o header.
+Variantes: `.fs-toast-primary`, `.fs-toast-secondary`, `.fs-toast-success`,
+`.fs-toast-warning`, `.fs-toast-danger` e `.fs-toast-info`.
 
-## Estados
+- `data-delay="4000"` define o tempo de auto-dismiss em milissegundos;
+- `data-autohide="false"` mantém o Toast aberto;
+- `data-toast-progress="true"` exibe a barra de tempo quando o auto-dismiss está ativo;
+- hover, foco e interação pausam o timer e a barra de progresso;
+- `prefers-reduced-motion` elimina a animação contínua do progresso.
 
-`.is-open` — controlado pelo JS (o toast começa com `display: none`
-inline até a primeira `show()`).
+## Estados
 
-- `data-delay` (ms, padrão `4000`) — tempo até auto-esconder.
-- `data-autohide="false"` — desativa o auto-esconder; só fecha pelo
-  `.fs-btn-close` ou `.hide()` programático.
+O Toast começa oculto, entra em `.is-open` durante a exibição e pode ser
+pausado por hover ou foco. `hide()` e auto-dismiss cancelam o timer e ocultam
+o elemento sem transferir foco.
 
 ## A11y
 
-`role="status"` + `aria-live="polite"` aplicados automaticamente — leitor
-de tela anuncia o conteúdo ao aparecer, sem interromper o que está sendo
-lido (diferente de `aria-live="assertive"`, que interromperia).
+O JavaScript aplica `role="status"` e `aria-live="polite"`. O Toast não move
+foco automaticamente e não deve usar `aria-live="assertive"` por padrão.
+Botões de fechamento precisam de `aria-label` específico; links e ações devem
+ter nomes compreensíveis. Ícones decorativos usam `aria-hidden="true"` e não
+substituem texto.
 
-## API JS
+Use `data-autohide="false"` para erros que exigem ação. Não use Toast para
+decisões críticas, conteúdo extenso ou mensagens que precisam permanecer no
+contexto da região afetada.
 
-Auto-init via `data-fs="toast"` (registra a instância, mas **não** mostra
-automaticamente). `Toast.getInstance(el)`.
+## API JS
 
-| Método | Descrição |
-|---|---|
-| `show()` | Mostra (anima expansão), inicia o temporizador de auto-esconder se `autohide` estiver ativo. |
-| `hide()` | Esconde (anima recolhimento), cancela o temporizador. |
-| `toggle()` | Alterna. |
-| `dispose()` | Cancela o temporizador, remove listeners, desregistra a instância. |
+```js
+const toast = FokusStyles.Toast.getInstance(document.querySelector(".fs-toast"));
+toast.show();
+toast.hide();
+toast.toggle();
+toast.dispose();
+```
 
-| Evento | Cancelável | Quando |
-|---|---|---|
-| `fs:toast:shown` | Não | Depois que a animação de mostrar termina. |
-| `fs:toast:hidden` | Não | Depois que a animação de esconder termina (inclusive auto-hide). |
+Eventos preservados: `fs:toast:shown` e `fs:toast:hidden`. O componente pausa
+o auto-dismiss durante hover e foco, sem transferir foco para outro Toast.
 
 ## Tokens
 
-`--fs-color-border`, `--fs-color-surface`, `--fs-alert-{nome}-bg`/`-text`
-(header colorido), `--fs-radius-md`, `--fs-shadow-md`.
+Container: `--fs-toast-offset`, `--fs-toast-gap`, `--fs-toast-width` e
+`--fs-toast-max-width`. Instância: `--fs-toast-padding-block`,
+`--fs-toast-padding-inline`, `--fs-toast-gap`, `--fs-toast-radius`,
+`--fs-toast-shadow`, `--fs-toast-icon-size`, `--fs-toast-title-gap`,
+`--fs-toast-actions-gap`, `--fs-toast-border-width` e
+`--fs-toast-progress-height`.
 
-## Exemplo
-
-```html
-<div class="fs-toast-container">
-  <div class="fs-toast fs-toast-danger" data-fs="toast" id="erroToast" data-autohide="false">
-    <div class="fs-toast-header">
-      <span>Erro</span>
-      <button type="button" class="fs-btn-close" data-fs-dismiss="toast" aria-label="Fechar"></button>
-    </div>
-    <div class="fs-toast-body">Falha ao salvar. Tente novamente.</div>
-  </div>
-</div>
-```
+## Mockup
 
-Mockup: [laboratório do componente](../../mockup/overlays-commands.html#toast).
+[Laboratório independente do Toast](../../mockup/examples/toast.html).