@govbr-ds/webcomponents 2.4.0 → 2.6.0

package/dist/types/components/table/table.utils.d.ts

@@ -0,0 +1,52 @@
+import type { TableDensity } from './table.types';
+/**
+ * Mapa entre um valor semântico e seu valor CSS efetivo.
+ */
+type SemanticMap = Record<string, string>;
+/**
+ * Validador de valores CSS fornecidos pelo consumidor.
+ */
+type Validator = (value: string) => boolean;
+/**
+ * Resolve um valor semântico ou CSS validado, utilizando fallback quando inválido.
+ *
+ * @param raw Valor recebido pela API pública.
+ * @param options Mapa semântico, validadores e fallback da resolução.
+ * @returns Valor CSS seguro que pode ser aplicado ao componente.
+ */
+export declare function resolveTokenValue(raw: string | undefined, options: {
+    fallback: string;
+    semanticMap?: SemanticMap;
+    validators?: Validator[];
+}): string;
+/**
+ * Valida valores positivos expressos em pixels.
+ *
+ * @param value Valor CSS candidato.
+ * @returns `true` quando o valor utiliza `px` e é maior que zero.
+ */
+export declare const positivePxValidator: Validator;
+/**
+ * Valida valores positivos expressos como fração de grid.
+ *
+ * @param value Valor CSS candidato.
+ * @returns `true` quando o valor utiliza `fr` e é maior que zero.
+ */
+export declare const positiveFrValidator: Validator;
+/**
+ * Solicita a execução de uma função no próximo frame de animação.
+ *
+ * @returns Promise que resolve no próximo frame de animação.
+ */
+export declare const requestAnimationFramePromise: () => Promise<void>;
+/**
+ * Resolve a densidade semântica correspondente ao token CSS efetivo de uma célula.
+ */
+export declare function resolveTableDensityFromElement(element: HTMLElement | null): TableDensity;
+/**
+ * Indica se uma mutação de `class` apenas adicionou ou removeu a marca
+ * `hydrated` do Stencil, que não altera a herança de tokens da tabela.
+ * Exige `attributeOldValue` no observer.
+ */
+export declare function isHydrationClassMutation(mutation: MutationRecord): boolean;
+export {};

package/dist/types/components/table/table.virtual-list.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Controlador de janela virtual das linhas da tabela.
+ *
+ * @module table-virtual-list
+ */
+export type TableVirtualRange = {
+    start: number;
+    end: number;
+    beforeHeight: number;
+    afterHeight: number;
+};
+export type TableVirtualListOptions = {
+    /** Visão interna estável; trocar a referência ao substituir, reordenar ou recortar linhas. */
+    getRows: () => readonly HTMLBrTableRowElement[];
+    getViewport: () => HTMLElement | null;
+    getStickyHeaderHeight: () => number;
+    renderRange: (range: TableVirtualRange) => void;
+    visibleRows: () => number;
+    estimatedRowHeight: () => number;
+    estimatedExpandedHeight: () => number;
+    onAfterRender?: () => void;
+};
+/**
+ * Materializa uma quantidade estável de linhas ao redor da viewport.
+ *
+ * @remarks
+ * A quantidade de elementos montados é calculada por `visibleRows` mais um
+ * buffer interno fixo de quatro linhas. A janela é ampliada aos limites dos
+ * grupos contíguos, podendo exceder essa quantidade para manter mesclas íntegras.
+ * Linhas expandidas alteram a altura
+ * total, mas não aumentam a quantidade de `br-table-row` materializados.
+ *
+ * A janela só é reposicionada quando a área visível se aproxima de uma das
+ * bordas do buffer. Isso reduz substituições de DOM durante o scroll.
+ * As somas de alturas são reutilizadas até `reset`, `invalidateRow`, uma nova
+ * sequência lógica ou uma medição diferente. Somente a faixa montada é medida.
+ */
+export declare class TableVirtualListController {
+    private readonly options;
+    private measuredHeights;
+    private indexedRows?;
+    private prefix?;
+    private currentRange;
+    private viewport;
+    private resizeObserver?;
+    private rafId?;
+    private measurementRafId?;
+    private pendingRevealIndex?;
+    private measurementVersion;
+    constructor(options: TableVirtualListOptions);
+    connect(): void;
+    disconnect(): void;
+    reset(scrollToTop?: boolean): void;
+    invalidateRow(index: number): void;
+    /** Recalcula a área útil sem descartar alturas de linhas ou a posição do scroll. */
+    refreshViewport(): void;
+    /** Materializa o destino antes do foco; null representa o cabeçalho. */
+    revealRow(index: number | null): void;
+    sync(force?: boolean): void;
+    /**
+     * Resolve a quantidade total de linhas adicionais mantidas no pool virtual.
+     * O buffer é fixo para tornar o custo de DOM previsível durante o scroll.
+     */
+    private resolveBufferRows;
+    /** Resolve a quantidade efetiva de linhas visíveis para o dataset atual. */
+    private resolveVisibleCapacity;
+    /**
+     * Mantém a janela atual enquanto a viewport estiver dentro de sua zona
+     * segura. A troca ocorre em blocos, e não a cada nova linha visível.
+     */
+    private canKeepCurrentRange;
+    /**
+     * Mantém uma quantidade fixa de linhas materializadas para um mesmo
+     * `visibleRows`: capacidade visível + até quatro linhas de buffer.
+     */
+    private resolveRenderedRowCount;
+    /** Centraliza a faixa ao redor do início visível sem variar seu tamanho. */
+    private createStableRange;
+    /** Reutiliza as somas enquanto a sequência lógica e suas alturas permanecem válidas. */
+    private getPrefix;
+    private estimateHeight;
+    private findRowAtOffset;
+    /**
+     * Mede somente as linhas materializadas e preserva a posição visual da linha
+     * âncora caso a altura de itens anteriores seja corrigida.
+     */
+    private scheduleMeasurement;
+    private isMeasurementCurrent;
+    private applyMeasurements;
+    private updateMeasuredHeights;
+    private measureRows;
+    private scheduleSync;
+    private handleScroll;
+    private disconnectViewport;
+    private isSameRange;
+}

package/dist/types/components/tag/tag.d.ts

@@ -4,37 +4,28 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrDensity } from '../global.types';
 import type { TagShape, TagValidator, TagVariant } from './tag.types';
 /**
- * O componente `br-tag` é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.
+ * O `br-tag` categoriza, rotula ou destaca informações curtas e metadados.
  *
- * ### Para que serve
+ * Suporta modo estático informativo, modo interativo clicável com `action`, modo com botão de fechar (`closable`) e modo selecionável com `selectable`.
  *
- * - **Categorização e metadados:** Identifica o tipo, categoria ou atributos de um item (ex.: "Educação", "Tecnologia", "Urgente").
- * - **Sinalização de status:** Exibe estados operacionais de processos ou documentos através de cores semânticas e ícones (ex.: "Aprovado", "Pendente", "Cancelado").
- * - **Filtros interativos dispensáveis:** Suporta botão de fechamento (`closable`), permitindo remover filtros dinamicamente.
- * - **Tags de seleção:** Suporta modo interativo selecionável com integração nativa a formulários (`formAssociated`).
+ * ```html
+ * <br-tag>Pendente</br-tag>
+ * <br-tag status="success">Concluído</br-tag>
+ * <br-tag closable>Filtro: Brasília</br-tag>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Exibir palavras-chave associadas a um conteúdo ou cartão.
- *   - Exibir status sucinto de registros em tabelas (`br-table`) ou cabeçalhos.
- *   - Oferecer filtros aplicados que podem ser removidos com um clique.
- * - **Evite e prefira outro componente quando:**
- *   - O elemento for a ação primária ou um comando executável (prefira `br-button`).
- *   - O texto for extenso e exigir explicações detalhadas (prefira `br-message`).
+ * - Rótulos de estado, tags de categorias ou palavras-chave.
+ * - Filtros aplicados que podem ser removidos individualmente.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-tag` oferece flexibilidade estrutural:
- * - `default`: Slot principal para texto ou conteúdo livre da tag.
- * - `label`: Slot para rótulo customizado.
- * - `icon`: Slot para inserção de ícone auxiliar (`br-icon`).
- * - `close-button`: Slot para customizar o botão de remoção.
- * - `feedback`: Slot para mensagem de validação contextual.
+ * - Ações primárias ou envio de formulário: use `br-button`.
+ * - Contagem numérica pura: use `br-avatar` ou texto de badge.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tag?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tag?tab=designer).
  *
-
  * @category Conteúdo, Dados
  * @status stable
  * @slot default - Slot para inserir o conteúdo da tag, como rótulo ou ícone.
@@ -141,7 +132,7 @@ export declare class Tag {
      */
     size: string;
     /**
-     * Variante funcional canônica. Aceita `default`, `status`, `action` ou `selectable`.
+     * Variante funcional padrão. Aceita `default`, `status`, `action` ou `selectable`.
      * Valores inválidos são ignorados; nesse caso, os aliases booleanos legados
      * continuam disponíveis para manter a compatibilidade.
      */

package/dist/types/components/textarea/textarea.d.ts

@@ -3,34 +3,26 @@ import { type FormValidationState } from '../../shared/utils/form';
 import type { InputValidationChangeDetail, InputValidator } from '../input/input.types';
 import type { TextareaResize, TextareaWrap } from './textarea.types';
 /**
- * O componente `br-textarea` é o controle oficial do GovBR-DS para entrada de dados textuais em múltiplas linhas, projetado para capturar textos longos, justificativas, descrições ou observações em formulários.
+ * O `br-textarea` captura textos longos em múltiplas linhas em formulários.
  *
- * ### Para que serve
+ * Configure `label`, `placeholder`, `maxlength` e `state` para validação. Use `show-counter` para exibir o contador de caracteres restantes.
  *
- * - **Entrada de texto extenso:** Permite que a pessoa usuária digite parágrafos de texto livre com quebra de linha e rolagem vertical.
- * - **Contador regressivo de caracteres:** Exibe a quantidade de caracteres restantes em tempo real com base no limite máximo (`maxlength`), alertando visualmente quando o limite é atingido.
- * - **Integração com formulários:** É associado nativamente a formulários HTML (`formAssociated`), sincronizando valor, estado de validação e foco acessível.
- * - **Redimensionamento controlado:** Oferece opções de redimensionamento vertical, horizontal ou fixo.
+ * ```html
+ * <br-textarea label="Observações" placeholder="Digite sua mensagem" maxlength="500" show-counter></br-textarea>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, participando da validação nativa com `required`.
  *
- * - **Utilize quando:**
- *   - A entrada esperada tiver mais de uma frase ou exigir formatação multilinha (comentários, manifestações, relatórios, justificativas).
- *   - Houver restrição estrita de caracteres com necessidade de feedback quantitativo dinâmico.
- * - **Evite e prefira outro componente quando:**
- *   - O dado for curto e couber em uma única linha (como nomes, e-mails, títulos, documentos): prefira `br-input`.
- *   - For necessário um editor rico WYSIWYG com formatação em negrito, tabelas e links.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Mensagens, comentários, justificativas, descrições ou textos extensos.
  *
- * O `br-textarea` é composto pelo campo e slots de apoio:
- * - `default`: Slot para instruções adicionais ou textos de ajuda.
- * - `feedback`: Slot para mensagens de validação contextual (como `br-message`).
- * - `validation-loading`: Slot para indicador de carregamento durante validações assíncronas.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
+ * - Dados curtos de linha única (nome, CPF, e-mail): use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
  *
-
  * @category Formulários
  * @status stable
  * @slot default - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.
@@ -115,7 +107,7 @@ export declare class Textarea {
      * Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. Valores inválidos não aplicam estado.
      */
     readonly state: 'danger' | 'success' | 'warning';
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
     readonly feedbackState?: 'danger' | 'success' | 'warning';
     /**
      * Regra síncrona ou assíncrona executada no `change` ou por `validate()`.

package/dist/types/components/tooltip/tooltip.d.ts

@@ -1,32 +1,26 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TooltipDensity, TooltipPosition, TooltipState, TooltipType } from './tooltip.types';
 /**
- * O componente `br-tooltip` é a sobreposição informativa flutuante do GovBR-DS, desenvolvida para fornecer dicas breves e esclarecimentos contextuais quando o usuário foca ou posiciona o cursor sobre um elemento da interface.
+ * O `br-tooltip` exibe uma dica rápida e contextual quando o usuário foca ou passa o mouse sobre um elemento.
  *
- * ### Para que serve
+ * Coloque o texto da dica em `text` ou no slot padrão, e vincule-o ao elemento acionador através de `target` ou colocando o acionador no slot `trigger`.
  *
- * - **Esclarecimento contextual imediato:** Revela descrições sucintas para botões de ícone, termos técnicos, siglas ou campos que necessitem de auxílio extra.
- * - **Posicionamento automático:** Posiciona o balão informativo em relação ao elemento de acionamento (topo, direita, baixo, esquerda) ajustando-se dinamicamente ao espaço da tela.
- * - **Acessibilidade WAI-ARIA:** Associa o acionador ao balão com `role="tooltip"` e `aria-describedby`, exibindo-se automaticamente no foco por teclado e fechando com a tecla Escape.
+ * ```html
+ * <br-button id="btn-ajuda" shape="circle" aria-label="Ajuda">?</br-button>
+ * <br-tooltip target="#btn-ajuda" text="Clique para obter informações"></br-tooltip>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Fornecer o rótulo descritivo de um botão que contenha apenas ícone.
- *   - Explicar uma sigla ou termo abreviado na interface.
- * - **Evite e prefira outro componente quando:**
- *   - O conteúdo for extenso, contiver botões interativos ou links navegáveis (prefira `br-dropdown`, `br-modal` ou texto inline fixo, pois tooltips desaparecem ao mover o ponteiro).
- *   - A informação for indispensável para a conclusão de uma tarefa crítica (ela deve estar sempre visível na tela).
+ * - Esclarecer o significado de botões que usam apenas ícones ou rótulos abreviados.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-tooltip` é composto por acionador e conteúdo:
- * - `trigger`: Slot obrigatório onde a aplicação declara o elemento de controle gatilho (ex.: um `br-button` de ícone).
- * - `content`: Slot onde é inserido o texto ou balão de conteúdo exibido pelo tooltip.
+ * - Informações essenciais que todos os usuários precisam ler imediatamente: exiba como texto visível na página.
+ * - Conteúdos longos com links clicáveis: use `br-message` ou diálogo.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
  *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a exibição do tooltip.

package/dist/types/components/upload/upload.d.ts

@@ -5,41 +5,29 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrFeedbackState } from '../global.types';
 import type { UploadErrorDetail, UploadFileDetail, UploadHandler, UploadProgressDetail, UploadValidator } from './upload.types';
 /**
- * O componente `br-upload` é o elemento oficial do GovBR-DS para seleção, anexação e envio de arquivos em formulários, com suporte a seleção múltipla, área de arrastar-e-soltar (drag-and-drop) e acompanhamento de progresso.
+ * O `br-upload` gerencia a seleção e envio de arquivos em formulários, com suporte a arrastar e soltar (drag and drop).
  *
- * ### Para que serve
+ * Defina os tipos aceitos em `accept` e permita múltiplos arquivos com `multiple`. Use a lista de arquivos para exibir o progresso e o botão de exclusão.
  *
- * - **Seleção e anexação de arquivos:** Permite anexar documentos, planilhas, imagens ou outros formatos através do seletor nativo do sistema operacional ou por arrastar e soltar.
- * - **Validação de tipos e tamanhos:** Valida extensões permitidas (`accept`) e tamanho máximo por arquivo (`max-file-size`), informando erros de validação de forma acessível.
- * - **Listagem visual e remoção:** Exibe a lista de arquivos selecionados com nome, tamanho formatado (KB/MB), barra de progresso individual e botão de exclusão.
- * - **Integração com formulários:** Integrado nativamente via `formAssociated`, permitindo submissão tradicional de formulários ou upload assíncrono programático.
+ * ```html
+ * <br-upload label="Enviar documento" accept=".pdf,.png,.jpg" multiple></br-upload>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, enviando a lista de arquivos no submit nativo.
  *
- * - **Utilize quando:**
- *   - A pessoa usuária precisar enviar comprovantes, relatórios, fotografias ou documentos digitais.
- *   - For necessário limitar e validar os tipos de arquivo e o tamanho máximo antes do envio ao servidor.
- * - **Evite e prefira outro componente quando:**
- *   - A captura for exclusivamente de texto ou URLs externas (prefira `br-input`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Anexar comprovantes, fotos ou documentos em formulários.
  *
- * O `br-upload` possui estrutura rica com múltiplos slots:
- * - `default`: Slot para texto personalizado do botão de upload (padrão: "Selecione o arquivo").
- * - `upload-list`: Slot opcional para substituição da área padrão de listagem de arquivos.
- * - `label`: Slot para personalização do rótulo do campo.
- * - `helper`: Slot para instruções ou restrições de formato/tamanho exibidas abaixo do campo.
- * - `feedback`: Slot para mensagens de validação e erro (como `br-message`).
- * - `loading`: Slot para indicador exibido durante o envio assíncrono dos arquivos.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
+ * - Campo de texto ou URL de arquivo remoto: use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
  *
-
  * @category Formulários, Dados
  * @status stable
- * @slot default - Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão.
- *                 Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos",
- *                 "Enviar imagens", etc.
+ * @slot default - Conteúdo personalizado do botão de upload, com precedência sobre `buttonLabel` (use a prop para texto simples).
  * @slot upload-list - Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.
  * @slot label - Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.
  * @slot helper - Texto auxiliar exibido abaixo da superfície de seleção.
@@ -121,6 +109,11 @@ export declare class Upload {
      * Rótulo exibido acima do botão de upload.
      */
     label: string;
+    /**
+     * Texto do botão de seleção. Quando omitido, usa "Selecione o arquivo" ou,
+     * com `multiple`, "Selecione o(s) arquivo(s)". O slot padrão tem precedência.
+     */
+    buttonLabel?: string;
     /**
      * Lista de arquivos já enviados (para edição ou pré-visualização).
      * Pode ser uma string JSON ou um array de objetos IUploadFile. Cada item deve ter `name` não vazio e `size` numérico não negativo opcional; itens inválidos são ignorados.
@@ -162,7 +155,7 @@ export declare class Upload {
      * Estado visual: 'info', 'warning', 'danger' ou 'success'. Valores inválidos não aplicam estado.
      */
     state: BrFeedbackState;
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     feedbackState?: BrFeedbackState;
     /**
      * Indica se o componente permite a seleção de múltiplos arquivos.
@@ -221,7 +214,7 @@ export declare class Upload {
      * @deprecated Use `brUploadRemove`.
      */
     brRemove: EventEmitter<IUploadFile>;
-    /** Evento canônico emitido quando um arquivo existente é removido. */
+    /** Evento emitido quando um arquivo existente é removido. */
     brUploadRemove: EventEmitter<IUploadFile>;
     /** Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada. */
     brUploadCancel: EventEmitter<void>;

package/dist/types/components/wizard/wizard-panel/wizard-panel.d.ts

@@ -1,18 +1,8 @@
 /**
- * Subcomponente individual de `br-wizard`, responsável por encapsular o formulário, campos de entrada ou informações pertencentes a uma etapa específica do fluxo guiado.
+ * Painel de conteúdo de uma etapa individual do `br-wizard`.
  *
- * ### Papel na composição
+ * Defina o título da etapa em `title-text`. Insira os campos e conteúdos dessa fase no slot padrão.
  *
- * - Agrupa todos os campos de formulário e conteúdos daquela etapa.
- * - Informa o título e subtítulo da etapa que serão refletidos na barra de progresso do wizard.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado no slot padrão do orquestrador `br-wizard`. O componente pai é quem decide qual painel deve estar visível com base na etapa corrente, coordenando os botões de avançar e voltar. Não deve ser instanciado de forma autônoma fora de um `br-wizard`.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @slot default - Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual).
  *
  * @part panel - Wrapper do painel.

package/dist/types/components/wizard/wizard.d.ts

@@ -1,39 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrOrientation, BrProgressionType } from '../global.types';
 /**
- * O componente `br-wizard` é o orquestrador completo de fluxos passo a passo do GovBR-DS, desenvolvido para guiar a pessoa usuária através de formulários e tarefas complexas distribuídas em etapas consecutivas.
+ * O `br-wizard` conduz fluxos passo a passo divididos em telas sequenciais com botões de navegação e barra de progresso.
  *
- * ### Para que serve
+ * Insira cada tela com `br-wizard-panel` no slot padrão. Acompanhe a mudança de etapas pelo evento `brStepChange`.
  *
- * - **Condução guiada de processos:** Apresenta um formulário longo dividido em etapas menores e focadas, reduzindo a carga cognitiva e o índice de abandono.
- * - **Barra de progresso e navegação integradas:** Combina o indicador visual de etapas (`step`), os painéis de conteúdo de cada etapa (`br-wizard-panel`) e a barra de ações com botões de "Voltar", "Avançar", "Concluir" e "Cancelar".
- * - **Validação por etapa:** Permite interceptar o avanço de cada passo para validação antes de liberar o próximo painel.
+ * ```html
+ * <br-wizard>
+ *   <br-wizard-panel title-text="Identificação">
+ *     <p>Primeira etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Endereço">
+ *     <p>Segunda etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Confirmação">
+ *     <p>Revise os dados antes de enviar.</p>
+ *   </br-wizard-panel>
+ * </br-wizard>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Houver um processo de cadastro, requerimento, compra ou configuração estruturado em etapas com dependência de sequência.
- *   - For essencial oferecer navegação pré-programada de retorno e avanço com controle de estado.
- * - **Evite e prefira outro componente quando:**
- *   - O objetivo for apenas mostrar o status de um pedido já concluído (use `br-step` simples).
- *   - O usuário puder navegar em qualquer ordem entre as seções da tela (use `br-tab`).
+ * - Formulários extensos com dependência lógica entre etapas.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-wizard` | **Orquestrador principal.** Gerencia a barra de progresso, ações de navegação (voltar/avançar), botões de rodapé e controle do painel ativo. | Deve ser o contêiner raiz do fluxo. |
- * | `br-wizard-panel` | **Painel de etapa individual.** Contém os campos e formulários de uma etapa específica. | Declarado dentro do slot padrão do `br-wizard`. |
+ * - Apenas indicar o status de um pedido já realizado: use `br-step`.
+ * - Conteúdos independentes onde a ordem de preenchimento é livre: use `br-tab`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
  *
- * O `br-wizard` gerencia ativamente os elementos `br-wizard-panel` declarados em seu interior:
- * 1. O pai exibe apenas o painel correspondente à etapa atual (`activeStep`), mantendo os demais ocultos.
- * 2. Ao avançar ou retroceder, o `br-wizard` dispara eventos de validação e troca de etapa (`brStepChange`), atualizando simultaneamente o cabeçalho de progresso e as ações do rodapé.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @category Navegação, Formulários, Progresso
  * @status stable
  * @slot default - Slot para os painéis de etapa (br-wizard-panel) do wizard.