@govbr-ds/webcomponents 2.1.2 → 2.2.0

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

@@ -1,11 +1,36 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
 import type { InputValidationChangeDetail, InputValidator } from '../input/input.types';
+import type { TextareaResize, TextareaWrap } from './textarea.types';
 /**
- * ## Design System
+ * 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.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
+ * ### Para que serve
  *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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.
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
  * @category Formulários
  * @status stable
  * @slot default - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.
@@ -75,10 +100,11 @@ export declare class Textarea {
     readonly required: boolean;
     /** Impede edição sem remover o campo do envio do formulário. */
     readonly readonly: boolean;
-    /** Número mínimo de caracteres necessário para o valor ser válido. */
+    /** Número mínimo de caracteres necessário para o valor ser válido. Deve ser um inteiro não negativo; valores inválidos usam 0. */
     readonly minlength: number;
     /**
      * Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite.
+     * Deve ser um inteiro não negativo; valores inválidos usam 0.
      */
     readonly maxlength: number;
     /**
@@ -86,19 +112,27 @@ export declare class Textarea {
      */
     readonly showCounter: boolean;
     /**
-     * Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'.
+     * 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`. */
+    /** Estado de feedback canônico. 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()`.
      * Pode consultar um serviço remoto; o componente controla apenas loading,
      * validade e a precedência do resultado mais recente.
+     *
+     * @example
+     * ```js
+     * const textarea = document.querySelector('br-textarea');
+     * textarea.validator = (value) =>
+     *   value.trim().length >= 20 ? null : 'Informe pelo menos 20 caracteres';
+     * ```
      */
     readonly validator?: InputValidator | string;
     /**
      * Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'.
+     * Valores inválidos usam `medium`.
      */
     readonly density: 'small' | 'medium' | 'large';
     /**
@@ -111,14 +145,36 @@ export declare class Textarea {
     /**
      * Número de linhas visíveis no textarea.
      * Define a altura do componente em relação ao número de linhas de texto exibidas.
+     * Deve ser um inteiro positivo; valores inválidos são ignorados.
      */
     readonly rows: number;
     /**
      * Número de colunas (caracteres) visíveis no textarea.
      * Define a largura do componente em relação ao número de caracteres por linha.
+     * Deve ser um inteiro positivo; valores inválidos são ignorados.
      */
     readonly cols: number;
+    /**
+     * Ajusta automaticamente a altura ao conteúdo sem exibir rolagem vertical.
+     * Quando ativo, o componente controla a dimensão vertical; `resize="vertical"`
+     * e `resize="both"` passam a se comportar como `none`, enquanto
+     * `resize="horizontal"` continua disponível.
+     */
+    readonly autoGrow: boolean;
+    /**
+     * Define os eixos que a pessoa usuária pode redimensionar manualmente.
+     * Quando omitida, preserva o comportamento nativo atual do navegador.
+     * Valores inválidos são ignorados.
+     */
+    readonly resize?: TextareaResize;
+    /**
+     * Encaminha a política nativa de quebra de linha ao `<textarea>` interno.
+     * Quando omitida, o navegador usa o comportamento nativo `soft`.
+     * Valores inválidos são ignorados.
+     */
+    readonly wrap?: TextareaWrap;
     valueChanged(): void;
+    autoGrowChanged(): void;
     /**
      * Valor atualizado do textarea
      * @deprecated Use o evento nativo `input` e leia `event.target.value`.
@@ -131,6 +187,8 @@ export declare class Textarea {
     brTextareaValidationChange: EventEmitter<InputValidationChangeDetail>;
     componentWillLoad(): void;
     componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
     /**
      * Retorna `true` se o valor do textarea for válido, caso contrário `false`.
      * Se o textarea for inválido, dispara um evento 'invalid'.
@@ -165,10 +223,15 @@ export declare class Textarea {
      * Referência nativa do textarea para acessar a API de validação
      */
     private nativeTextarea?;
+    private autoGrowResizeObserver?;
+    private autoGrowObservedWidth?;
     private initialValue;
     private manualValidationMessage;
     private validationRunId;
     private syncProgrammaticValue;
+    private readonly setNativeTextarea;
+    private syncAutoGrowObservation;
+    private syncAutoGrowHeight;
     private syncFormState;
     private isDisabled;
     private updateValidity;
@@ -192,5 +255,12 @@ export declare class Textarea {
      */
     private getAccessibilityLabel;
     private getCssClassMap;
+    private get effectiveState();
+    private get effectiveMinLength();
+    private get effectiveMaxLength();
+    private get effectiveRows();
+    private get effectiveCols();
+    private get effectiveResize();
+    private get effectiveWrap();
     render(): any;
 }

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

@@ -1 +1,5 @@
 export type TextareaState = 'danger' | 'success' | 'warning';
+/** Políticas de redimensionamento aceitas pelo textarea nativo. */
+export type TextareaResize = 'none' | 'vertical' | 'horizontal' | 'both';
+/** Modos nativos de quebra de linha encaminhados ao textarea interno. */
+export type TextareaWrap = 'soft' | 'hard';

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

@@ -1,9 +1,33 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TooltipDensity, TooltipPosition, TooltipState, TooltipType } from './tooltip.types';
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
+ * 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.
  *
- * @category Feedback
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @category Feedback, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a exibição do tooltip.
  * @slot content - Slot para o conteúdo exibido no tooltip.
@@ -46,15 +70,15 @@ export declare class Tooltip {
      */
     ariaLabel: string | null;
     /**
-     * Posição do tooltip em relação ao acionador.
+     * Posição do tooltip em relação ao acionador. Valores inválidos usam `top`.
      */
     position: TooltipPosition;
     /**
-     * Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação).
+     * Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação). Valores inválidos usam `standard`.
      */
     type: TooltipType;
     /**
-     * Modo de interação para exibição do tooltip: 'hover' ou 'click'.
+     * Modo de interação para exibição do tooltip: 'hover' ou 'click'. Valores inválidos usam `hover`.
      */
     interaction: 'hover' | 'click';
     /**
@@ -64,10 +88,11 @@ export declare class Tooltip {
      * - `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.
      * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
      *
+     * Valores inválidos usam `medium`.
      */
     density: TooltipDensity;
     /**
-     * Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'.
+     * Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'. Valores inválidos usam `info`.
      */
     state: TooltipState;
     /**
@@ -75,19 +100,32 @@ export declare class Tooltip {
      */
     isAutoVisible: boolean;
     /**
-     * Atraso em milissegundos antes de exibir.
+     * Faz o conteúdo acompanhar a largura do acionador enquanto estiver visível.
+     * O valor padrão `false` preserva a largura determinada pelo conteúdo.
+     */
+    matchTriggerWidth: boolean;
+    /**
+     * Atraso em milissegundos antes de exibir. Valores negativos usam `0`.
      */
     showDelay: number | null;
     /**
-     * Atraso em milissegundos antes de ocultar.
+     * Atraso em milissegundos antes de ocultar. Valores negativos usam `0`.
      */
     hideDelay: number | null;
+    private get effectiveShowDelay();
+    private get effectiveHideDelay();
+    private get effectivePosition();
+    private get effectiveType();
+    private get effectiveInteraction();
+    private get effectiveState();
     /**
      * Watcher para monitorar alterações na propriedade `isVisible`.
      * @param visible boolean
      * @returns void
      */
     handleVisibilityChange(visible: boolean): void;
+    /** Recalcula a superfície visível quando a política de largura muda. */
+    handleMatchTriggerWidthChange(): void;
     /**
      * Emitido quando o tooltip abre.
      */

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

@@ -5,9 +5,37 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrFeedbackState } from '../global.types';
 import type { UploadErrorDetail, UploadFileDetail, UploadHandler, UploadProgressDetail, UploadValidator } from './upload.types';
 /**
- * ## Design System
+ * 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.
  *
- * @category Formulários
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+ * @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",
@@ -85,7 +113,7 @@ export declare class Upload {
      */
     accept: string;
     /**
-     * Sugere a câmera usada na captura de imagem ou vídeo.
+     * Sugere a câmera usada na captura de imagem ou vídeo. Valores inválidos são ignorados.
      * O navegador pode ignorar a preferência conforme dispositivo e permissões.
      */
     capture?: '' | 'user' | 'environment';
@@ -95,11 +123,31 @@ export declare class Upload {
     label: string;
     /**
      * Lista de arquivos já enviados (para edição ou pré-visualização).
-     * Pode ser uma string JSON ou um array de objetos IUploadFile.
+     * 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.
+     *
+     * @example
+     * ```html
+     * <!-- Compatibilidade legada; prefira existing-files. -->
+     * <br-upload upload-files='[{"name":"relatorio.pdf","size":204800}]'></br-upload>
+     * ```
+     * @deprecated Use `existingFiles`.
      */
-    /** @deprecated Use `existingFiles`. */
     uploadFiles: string | IUploadFile[];
-    /** Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`. */
+    /**
+     * Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`.
+     * Cada item deve ter `name` não vazio e `size` numérico não negativo opcional.
+     * Use JSON no atributo HTML ou um array por property binding.
+     *
+     * @example
+     * ```html
+     * <br-upload existing-files='[{"name":"relatorio.pdf","size":204800}]'></br-upload>
+     * ```
+     * @example
+     * ```js
+     * const upload = document.querySelector('br-upload');
+     * upload.existingFiles = [{ name: 'relatorio.pdf', size: 204800 }];
+     * ```
+     */
     existingFiles?: string | IUploadFile[];
     /**
      * Desabilita a interação com o componente.
@@ -111,7 +159,7 @@ export declare class Upload {
      */
     readonly required: boolean;
     /**
-     * Estado visual: 'info', 'warning', 'danger' ou 'success'.
+     * 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`. */
@@ -121,16 +169,23 @@ export declare class Upload {
      * Quando definido como `true`, o usuário pode selecionar mais de um arquivo para upload.
      */
     multiple: boolean;
-    /** Quantidade mínima de arquivos, incluindo arquivos já enviados. */
+    /** Quantidade mínima de arquivos, incluindo arquivos já enviados. Deve ser um inteiro não negativo; valores inválidos usam `0`. */
     minFiles: number;
-    /** Quantidade máxima de arquivos. Zero significa sem limite. */
+    /** Quantidade máxima de arquivos. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam `0`. */
     maxFiles: number;
-    /** Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite. */
+    /** Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam `0`. */
     maxFileSize: number;
     /**
      * Regra síncrona ou assíncrona aplicada à lista de arquivos selecionados.
      * O componente valida `File[]`, mas não envia arquivos nem interpreta a
      * resposta do servidor.
+     *
+     * @example
+     * ```js
+     * const upload = document.querySelector('br-upload');
+     * upload.validator = (files) =>
+     *   files.every((file) => file.size <= 5_000_000) ? null : 'Cada arquivo deve ter até 5 MB';
+     * ```
      */
     readonly validator?: UploadValidator;
     /**
@@ -138,6 +193,13 @@ export declare class Upload {
      *
      * O componente fornece o arquivo, um `AbortSignal` e uma função de progresso,
      * mas não conhece endpoint, autenticação nem formato de resposta.
+     *
+     * @example
+     * ```js
+     * const upload = document.querySelector('br-upload');
+     * upload.uploadHandler = ({ file, signal, onProgress }) =>
+     *   enviarArquivo({ file, signal, onProgress });
+     * ```
      */
     readonly uploadHandler?: UploadHandler;
     /** Lista de arquivos selecionados, equivalente a `HTMLInputElement.files`. */
@@ -146,6 +208,7 @@ export declare class Upload {
     protected uploadFilesHandler(newValue: string | IUploadFile[]): void;
     protected existingFilesHandler(newValue?: string | IUploadFile[]): void;
     private parseExistingFiles;
+    private normalizeExistingFiles;
     protected filesSelectedHandler(): void;
     /**
      * Emitido quando a lista de arquivos selecionados muda.
@@ -214,6 +277,11 @@ export declare class Upload {
     private updateValidity;
     private isAcceptedFile;
     private getCssClassMap;
+    private get effectiveCapture();
+    private get effectiveState();
+    private get effectiveMinFiles();
+    private get effectiveMaxFiles();
+    private get effectiveMaxFileSize();
     private handleRemoveFileSelection;
     private renderFilesUploaded;
     private getFileKey;

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

@@ -1,7 +1,18 @@
 /**
- * Wizard Panel (Painel de etapa do Wizard)
- * Representa uma etapa individual dentro do br-wizard.
+ * 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.
  *
+ * ### Papel na composiçã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.
@@ -36,5 +47,12 @@ export declare class WizardPanel {
      * @internal Método interno para o wizard pai consultar o estado
      */
     isActive(): Promise<boolean>;
+    /**
+     * Move o foco para o primeiro controle interativo do conteúdo do painel.
+     * O wizard usa este método para manter o encapsulamento do Shadow DOM.
+     * @internal
+     * @returns `true` quando um elemento recebeu foco.
+     */
+    focusFirst(): Promise<boolean>;
     render(): any;
 }

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

@@ -1,9 +1,40 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrOrientation, BrProgressionType } from '../global.types';
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
+ * 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.
  *
- * @category Navegação
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | 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`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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.
  * @slot cancel-button - Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão "Cancelar" é substituído.
@@ -51,10 +82,11 @@ export declare class Wizard {
      * Índice da etapa inicial do wizard.
      * Define qual etapa será exibida ao carregar o componente.
      * A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).
+     * Valores inválidos usam 1.
      * @deprecated Use `initialIndex`.
      */
     initialStep: number;
-    /** Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`. */
+    /** Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`; valores inválidos usam 0. */
     initialIndex?: number;
     /** Índice atual zero-based para controle externo opcional. */
     currentIndex?: number;
@@ -77,6 +109,10 @@ export declare class Wizard {
      *
      */
     customId: string;
+    private get effectiveOrientation();
+    private get effectiveProgressionType();
+    private get effectiveInitialIndex();
+    private get effectiveInitialStep();
     /**
      * Observa mudanças no tipo de progressão.
      * Atualiza a navegação dos painéis quando muda entre linear/nonlinear.
@@ -241,10 +277,6 @@ export declare class Wizard {
      * Tempo de espera para limpar mensagens aria-live (em ms).
      */
     private ARIA_LIVE_CLEANUP_DELAY;
-    /**
-     * Seletor de elementos focáveis dentro dos painéis.
-     */
-    private FOCUSABLE_SELECTOR;
     /**
      * Método privado central que gerencia toda a navegação com validação.
      *
@@ -269,6 +301,11 @@ export declare class Wizard {
      * @param slot - Elemento slot do shadow DOM
      */
     private discoverPanelsFromSlot;
+    /**
+     * Atualiza a lista de painéis somente quando a composição realmente mudou.
+     * Evita uma re-renderização redundante durante `componentDidLoad()`.
+     */
+    private setPanels;
     /**
      * Atualiza estados de todos os painéis.
      * Define o índice e o estado ativo de cada painel.