@govbr-ds/webcomponents 2.4.0 → 2.6.0

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

@@ -1,29 +1,34 @@
 import type { IconFlip, IconRotate, IconSource } from './icon.types';
 /**
- * O componente `br-icon` é o elemento oficial do GovBR-DS para renderização dinâmica e padronizada de ícones vetoriais. Ele suporta a família tipográfica Font Awesome e ícones utilitários do governo, garantindo contraste, escalabilidade e acessibilidade visual.
+ * O `br-icon` exibe um ícone com tamanho e alinhamento padronizados. O ícone vem da sua aplicação, de uma destas formas:
  *
- * ### Para que serve
+ * ```html
+ * <!-- Arquivo ou URL -->
+ * <br-icon src="/icones/busca.svg"></br-icon>
  *
- * - **Comunicação visual imediata:** Fornece apoio gráfico rápido para ações em botões, links, cartões, menus e alertas contextuais.
- * - **Acessibilidade nativa:** Gerencia automaticamente a visibilidade para leitores de tela: ícones decorativos recebem `aria-hidden="true"`, enquanto ícones informativos recebem nome acessível via `aria-label`.
- * - **Flexibilidade dimensional e cromática:** Permite personalizar tamanho, cor através de tokens CSS do GovBR-DS, rotação e efeitos de espelhamento.
+ * <!-- SVG no próprio código -->
+ * <br-icon svg='<svg viewBox="0 0 24 24"><path d="…" fill="currentColor"/></svg>'></br-icon>
  *
- * ### Quando utilizar
+ * <!-- Outra biblioteca, como Font Awesome -->
+ * <br-icon><i class="fas fa-search"></i></br-icon>
+ * ```
  *
- * - **Utilize quando:**
- *   - For necessário reforçar o significado de um texto ou ação com uma representação gráfica familiar.
- *   - Criar controles compactos com ícone acompanhado de descrição acessível.
- * - **Evite e prefira outro componente quando:**
- *   - For necessária uma imagem fotográfica ou ilustração visual ampla com detalhes cromáticos complexos (prefira tags HTML `<img>` ou SVG ilustrativo).
+ * Sem `label`, o ícone é decorativo e ignorado por leitores de tela. Quando o ícone transmite informação sozinho, descreva-o em `label`:
  *
- * ### Estrutura e Slots
+ * ```html
+ * <br-icon src="/icones/alerta.svg" label="Atenção"></br-icon>
+ * ```
  *
- * O `br-icon` renderiza um elemento vetorial direto com base no atributo `name` informado ou através de classes utilitárias.
+ * O tamanho padrão é 16 × 16 px; ajuste com `width` e `height`, em qualquer unidade CSS. Use `rotate` e `flip` para girar ou espelhar.
  *
- * 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/icon?tab=designer).
+ * Se mais de uma forma for informada, vale nesta ordem: conteúdo, `svg`, `src` e, por último, `icon-name` (depreciado). Para fixar uma delas, use `source`.
+ *
+ * ### Quando evitar
+ *
+ * - Fotos e ilustrações: use `<img>`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/icon?tab=designer).
  *
-
-
  * @category Identidade
  * @status stable
  * @slot - Conteúdo customizado do ícone. Pode receber elementos como `<i>`, `<svg>` ou componentes de outras bibliotecas.
@@ -43,9 +48,8 @@ export declare class Icon {
     /** Texto alternativo para ícones informativos. Sem label, o ícone é decorativo. */
     label?: string;
     /**
-     * Identificador legado do ícone. Identificadores que pertencem ao registro local são
-     * renderizados como SVG empacotado; nomes desconhecidos continuam disponíveis via Iconify
-     * somente para compatibilidade.
+     * Identificador legado do ícone. Nomes no cache local são renderizados como SVG empacotado;
+     * em `source="auto"`, nomes ausentes usam Iconify como fallback. `source="iconify"` força essa origem.
      *
      * @deprecated Use `src` com um asset controlado pela aplicação, `svg` ou o slot padrão.
      */
@@ -73,9 +77,10 @@ export declare class Icon {
     svg?: string;
     /**
      * Define explicitamente a origem do ícone.
-     * Quando `auto`, o componente prioriza slot, SVG inline e imagem por URL.
-     * Iconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada.
+     * Quando `auto`, o componente prioriza slot, SVG inline, imagem por URL e o cache local Font Awesome 5 Free.
+     * Se `iconName` não estiver no cache, usa Iconify como fallback. `iconify` força essa origem mesmo para nomes presentes no cache.
      * Aceita `auto`, `iconify`, `image`, `svg` ou `slot`; valores inválidos usam `auto`.
+     * @remarks Os componentes do Design System usam identificadores presentes no cache local; Iconify atende nomes ausentes e usos explícitos.
      */
     source: IconSource;
     /**
@@ -134,7 +139,7 @@ export declare class Icon {
      *
      * Comportamento:
      * - Padrão (propriedade não definida): carregamento imediato aplicando `noobserver` para evitar problemas de layout shift
-     * - `lazy={true}`: ativa o carregamento tardio nativo para imagens em `src` e o observer do Iconify no fallback legado
+     * - `lazy={true}`: ativa o carregamento tardio nativo para imagens em `src`
      * - `lazy={false}`: carregamento imediato
      *
      * **Nota**: O padrão foi alterado para carregamento imediato para resolver problemas de deslocamento de layout

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

@@ -1,7 +1,7 @@
 export declare function sanitizeSvgMarkup(markup: string): string;
 /**
  * Indica se um valor de ícone é uma lista de classes CSS (ex.: `fas fa-bell`), e não um
- * identificador Iconify (`fa6-solid:bell`). Classes CSS não funcionam dentro do Shadow DOM,
+ * identificador Font Awesome 5 Free presente no cache local (`fa-solid:bell`). Classes CSS não funcionam dentro do Shadow DOM,
  * porque os estilos globais do Font Awesome não o atravessam; nesses casos use um slot.
  */
 export declare function isIconClassList(value: string | null | undefined): boolean;

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

@@ -1,34 +1,30 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
-import type { InputActionClickDetail, InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from './input.types';
+import type { InputActionClickDetail, InputComboboxState, InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from './input.types';
 /**
- * O componente `br-input` é o controle padrão do GovBR-DS para entrada de dados textuais em linha única. Totalmente integrado à validação nativa de formulários HTML via `ElementInternals` (`formAssociated`), ele suporta múltiplos tipos de entrada, máscaras e formatação.
+ * O `br-input` captura dados de texto em linha única, como nomes, e-mails, números ou senhas.
  *
- * ### Para que serve
+ * Configure `label`, `placeholder` e o tipo em `type` (como `text`, `email`, `password`, `number`). Use `state` (`success`, `danger`, `info`, `warning`) para indicar validação.
  *
- * - **Captura de dados curtos em formulários:** Entrada de textos, senhas, endereços de e-mail, números, telefones, documentos e termos de busca.
- * - **Alternância de visualização de senha:** No tipo `type="password"`, oferece botão embutido para alternar entre texto visível e caracteres mascarados com feedback acessível.
- * - **Validação e mensagens contextuais:** Comunica valor, validade e mensagens de erro ou orientação diretamente ao formulário HTML e leitores de tela.
- * - **Densidade e ícones de apoio:** Suporta diferentes densidades visuais (alta, média e baixa) e ícones prefixados ou sufixados para enriquecer a experiência.
+ * ```html
+ * <br-input label="E-mail" type="email" placeholder="nome@exemplo.com"></br-input>
+ * <br-input label="Senha" type="password"></br-input>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se nativamente via `ElementInternals`, participando do submit e da validação nativa com `required`.
  *
- * - **Utilize quando:**
- *   - A informação digitada couber em uma única linha (ex.: nome, CPF, e-mail, valor monetário, busca).
- * - **Evite e prefira outro componente quando:**
- *   - O texto for extenso ou exigir múltiplas linhas (prefira `br-textarea`).
- *   - A escolha for feita a partir de uma lista pré-determinada de opções (prefira `br-select`, `br-radio` ou `br-checkbox`).
- *   - O valor for uma data ou hora estruturada (prefira `br-datetime-picker`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Entrada de texto curto que cabe em uma única linha (nome, CPF, e-mail, telefone).
+ * - Campo de busca ou senha com alternância de visualização.
  *
- * O `br-input` é composto pelo campo de entrada e slots de apoio:
- * - `icon`: Slot para ícone de apoio visual (prefixado ou sufixado ao campo de digitação).
- * - `feedback`: Slot para exibição de mensagens de validação contextual (como `br-message`).
+ * ### 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/input?tab=designer).
+ * - Textos longos ou com quebra de linha: use `br-textarea`.
+ * - Escolha entre opções pré-definidas: use `br-select` ou `br-radio`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/input?tab=designer).
  *
-
  * @category Formulários
  * @status stable
  * @slot action - Botão à direita do input.
@@ -44,6 +40,7 @@ import type { InputActionClickDetail, InputDensity, InputState, InputToggle, Inp
  * @part icon - Contêiner do slot de ícone.
  * @part action - Botão de ação lateral.
  * @part action-button - Botão interno reexportado do br-button da ação.
+ * @part clear - Botão de limpar exibido com `clearable` enquanto há texto editável.
  * @part help-text - Texto de ajuda ou slot de ajuda.
  * @part feedback - Slot de feedback.
  */
@@ -103,7 +100,7 @@ export declare class Input {
      * O estado é propagado para o slot de feedback, mas também pode ser controlado diretamente pelo conteúdo do slot.
      */
     readonly state?: InputState;
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     readonly feedbackState?: InputState;
     /**
      * Texto exibido como rótulo do input.
@@ -243,6 +240,14 @@ export declare class Input {
      * Aceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.
      */
     readonly actionTabIndex?: number;
+    /**
+     * Exibe um botão para limpar o texto enquanto o campo tem valor e aceita edição.
+     * O botão fica à esquerda do botão de ação, quando houver. Ao ser acionado,
+     * limpa o valor, emite `input` uma única vez e `brClear`, e devolve o foco ao campo.
+     * Não é exibido com `disabled` ou `readonly`.
+     * @default false
+     */
+    readonly clearable: boolean;
     protected handleValueChange(newValue: string): void;
     protected handleMaskChange(): void;
     protected handleStateChange(): void;
@@ -253,7 +258,10 @@ export declare class Input {
      * @deprecated Use o evento nativo `input` e leia `event.target.value`.
      */
     valueChange: EventEmitter<string>;
-    /** Emitted when the input clear button action is triggered. */
+    /**
+     * Emitido quando o usuário aciona o botão de limpar (`clearable`), depois que o
+     * valor foi limpo e o evento `input` foi disparado.
+     */
     brClear: EventEmitter<void>;
     /**
      * Notifica a ativação do botão do slot `action` por clique ou teclado.
@@ -272,7 +280,7 @@ export declare class Input {
     componentDidLoad(): void;
     disconnectedCallback(): void;
     componentDidUpdate(): void;
-    componentShouldUpdate(_newValue: unknown, _oldValue: unknown, propName: string): boolean;
+    componentShouldUpdate(newValue: unknown, oldValue: unknown, propName: string): boolean;
     componentDidRender(): void;
     /**
      * Retorna `true` se o valor do input for válido, caso contrário `false`.
@@ -378,6 +386,12 @@ export declare class Input {
      * que receber o foco durante o envio.
      */
     private handleKeyDown;
+    private comboboxState?;
+    private accessibleList?;
+    private accessibleStatus?;
+    private accessibleDescription?;
+    handleComboboxSync(event: CustomEvent<InputComboboxState>): void;
+    private applyComboboxState;
     private readonly renderInput;
     /**
      * Renderiza o texto de ajuda do input, considerando se está definido como string ou slot.
@@ -399,6 +413,15 @@ export declare class Input {
      * @returns JSX.Element representando o slot de ícone.
      */
     private renderIconSlot;
+    private isClearButtonVisible;
+    /** Mantém o foco no campo ao clicar no botão de limpar, como o "x" de um campo de busca nativo. */
+    private readonly keepInputFocus;
+    private readonly handleClearClick;
+    /**
+     * Renderiza o botão de limpar quando `clearable` está ativo e há texto editável.
+     * @returns JSX.Element do botão ou `null`.
+     */
+    private renderClearButton;
     private handleActionClick;
     /**
      * Renderiza o botão de ação do input, considerando o tipo de input e slots disponíveis.

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

@@ -15,3 +15,21 @@ export interface InputValidationChangeDetail {
     valid: boolean | null;
     message: string | null;
 }
+/** Estado de uma lista de sugestões vinculada ao campo. */
+export interface InputComboboxState {
+    options: Array<{
+        value: string;
+        label?: string;
+        group?: string;
+        selected?: boolean;
+        disabled?: boolean;
+    }>;
+    activeIndex: number;
+    expanded: boolean;
+    multiple: boolean;
+    label: string;
+    loading: boolean;
+    required: boolean;
+    invalid: boolean;
+    errorMessage: string;
+}

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

@@ -2,31 +2,27 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrButtonType, BrDensity, BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { ItemSelectDetail } from './item.types';
 /**
- * O componente `br-item` é o elemento flexível e padronizado do GovBR-DS para construção de linhas navegáveis, selecionáveis ou de exibição em listas, menus contextuais e painéis suspensos.
+ * O `br-item` padroniza uma linha de conteúdo, ação ou link dentro de listas, menus ou agrupamentos verticais.
  *
- * ### Para que serve
+ * Coloque o texto ou elementos no slot padrão. Use `interactive` para habilitar efeito de clique e foco, ou `href` para transformá-lo em link navegável. Para destacar um item escolhido, use `selected`.
  *
- * - **Padronização de linhas interativas:** Garante espaçamento, tipografia, contraste e efeitos de estado (hover, foco visível, seleção e desativação) em conformidade com os tokens do design system.
- * - **Polimorfismo semântico:** Pode renderizar internamente um botão interativo (`<button>`), um hiperlink navegável (`<a>`) ou uma divisão semântica (`<div>`) dependendo dos atributos fornecidos (`href`, `clickable`).
- * - **Suporte a seleção visual:** Oferece suporte a estados de seleção (`selected`), marcas de verificação e densidades ajustáveis.
+ * ```html
+ * <br-item interactive>Item de ação</br-item>
+ * <br-item href="/perfil">Meu Perfil</br-item>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Estiver montando linhas de conteúdo em listas (`br-list`), painéis flutuantes (`br-dropdown`) ou agrupamentos verticais.
- *   - Cada entrada representar um item de dado ou uma ação com estilo homogêneo.
- * - **Evite e prefira outro componente quando:**
- *   - O item pertencer especificamente à navegação de abas (use `br-tab-item`), etapas de fluxo (use `br-step-item`) ou seleção em formulário (use `br-select-option`).
+ * - Linhas de dados em listas (`br-list`) ou painéis verticais.
+ * - Linhas com foco, hover e seleção consistentes com o design system.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-item` é um componente estrutural direto:
- * - `default`: Slot para inserção do conteúdo livre da linha (textos, ícones, badges ou metadados).
+ * - Itens específicos de navegação estruturada: use `br-breadcrumb-item`, `br-tab-item` ou `br-step-item`.
+ * - Opções de seleção em formulário: use `br-select-option`.
  *
- * 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/item?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/item?tab=designer).
  *
-
-
  * @slot default - Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.).
  *
  * @slot start - Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.
@@ -80,7 +76,7 @@ export declare class Item {
      * @deprecated Use `active`.
      */
     isActive: boolean;
-    /** Estado ativo canônico. Quando informado, tem precedência sobre `isActive`. */
+    /** Estado ativo atual. Quando informado, tem precedência sobre `isActive`. */
     active?: boolean;
     /**
      * Indica se o item está no estado selecionado.
@@ -88,7 +84,7 @@ export declare class Item {
      * @deprecated Use `selected`.
      */
     isSelected: boolean;
-    /** Estado selecionado canônico. Em itens interativos, também é atualizado pelo acionamento. */
+    /** Estado selecionado. Em itens interativos, também é atualizado pelo acionamento. */
     selected?: boolean;
     /**
      * Marca o item como interativo, permitindo que toda a superfície do item seja clicável.
@@ -158,7 +154,7 @@ export declare class Item {
      */
     /** @deprecated Use `brItemClick`. */
     brDidClick: EventEmitter;
-    /** Evento canônico emitido quando o item com comportamento de botão é acionado. */
+    /** Evento emitido quando o item com comportamento de botão é acionado. */
     brItemClick: EventEmitter<void>;
     /**
      * Evento customizado aplicável para todos os tipos de elementos (`div`, `button`, `a`), emitido quando a seleção do item interativo ou botão muda.
@@ -167,7 +163,7 @@ export declare class Item {
      */
     /** @deprecated Use `brItemSelect`. */
     brDidSelect: EventEmitter<ItemSelectDetail>;
-    /** Evento canônico emitido quando a seleção muda. */
+    /** Evento emitido quando a seleção muda. */
     brItemSelect: EventEmitter<ItemSelectDetail>;
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.

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

@@ -1,30 +1,26 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../global.types';
 /**
- * O componente `br-link` é o controle oficial de hiperlink do GovBR-DS, projetado para orientar e conduzir a pessoa usuária em navegações internas entre páginas ou encaminhamentos para destinos externos.
+ * O `br-link` conduz a pessoa usuária a outra página, arquivo para download ou seção externa.
  *
- * ### Para que serve
+ * Coloque o texto ou ícone no slot padrão e aponte o destino em `href`. Para destinos externos ou abas novas, use `target="_blank"`. Para integração com roteadores de SPA, use `navigation-mode="event"` e ouça o evento `brNavigate`.
  *
- * - **Navegação estruturada:** Conduz o usuário para novas URLs, rotas de aplicação, âncoras dentro da mesma página ou arquivos para download.
- * - **Identificação de links externos:** Permite sinalizar visualmente que o link aponta para um domínio externo ou abre em nova aba/janela, adicionando os atributos de segurança e acessibilidade necessários (`target="_blank"`, `rel="noopener noreferrer"`).
- * - **Estilos inline e de bloco:** Adapta-se ao fluxo de leitura textual em parágrafos ou como elemento de navegação isolado com suporte a ícones.
+ * ```html
+ * <br-link href="/servicos">Serviços disponíveis</br-link>
+ * <br-link href="https://www.gov.br" target="_blank">Portal Gov.br</br-link>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - A ação resultar na alteração da URL do navegador, navegação para outra página ou download de arquivo.
- * - **Evite e prefira outro componente quando:**
- *   - A ação disparar um comportamento na interface sem alterar a URL (como abrir modal, submeter formulário ou acionar filtro): prefira `br-button`.
+ * - Navegar para outra página, rota ou domínio.
+ * - Fazer download de arquivos ou saltar para âncoras na mesma página.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-link` é um componente autônomo:
- * - `default`: Slot para o texto do link, ícones auxiliares ou elementos combinados.
+ * - Executar uma ação na página atual (salvar, abrir diálogo): use `br-button`.
  *
- * 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/link?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/link?tab=designer).
  *
-
-
  * @category Navegação, Ações
  * @status stable
  * @slot default - Conteúdo do link (texto, ícones ou outros elementos).
@@ -96,7 +92,7 @@ export declare class Link {
      * @deprecated Use `ariaExpanded`.
      */
     readonly linkAriaExpanded?: string;
-    /** Valor canônico de `aria-expanded`. */
+    /** Valor de `aria-expanded`. */
     readonly ariaExpanded: string | null;
     /**
      * Encaminhamento de `aria-selected` para o elemento âncora interno.
@@ -104,7 +100,7 @@ export declare class Link {
      * @deprecated Use `ariaSelected`.
      */
     readonly linkAriaSelected?: string;
-    /** Valor canônico de `aria-selected`. */
+    /** Valor de `aria-selected`. */
     readonly ariaSelected: string | null;
     /**
      * Encaminhamento de `aria-haspopup` para o elemento âncora interno.
@@ -112,7 +108,7 @@ export declare class Link {
      * @deprecated Use `ariaHasPopup`.
      */
     readonly linkAriaHaspopup?: string;
-    /** Valor canônico de `aria-haspopup`. */
+    /** Valor de `aria-haspopup`. */
     readonly ariaHasPopup: string | null;
     /**
      * Encaminhamento de `aria-current` para o elemento âncora interno.
@@ -123,7 +119,7 @@ export declare class Link {
      * @deprecated Use `ariaCurrent`.
      */
     readonly linkAriaCurrent?: string;
-    /** Valor canônico de `aria-current`. */
+    /** Valor de `aria-current`. */
     readonly ariaCurrent: string | null;
     /**
      * Encaminhamento de `aria-label` para o elemento âncora interno.
@@ -133,7 +129,7 @@ export declare class Link {
      * @deprecated Use `ariaLabel`.
      */
     readonly linkAriaLabel?: string;
-    /** Valor canônico de `aria-label`. */
+    /** Valor de `aria-label`. */
     readonly ariaLabel: string | null;
     /**
      * Encaminhamento de `aria-describedby` para o elemento âncora interno.
@@ -142,7 +138,7 @@ export declare class Link {
      * @deprecated Use `ariaDescribedBy`.
      */
     readonly linkAriaDescribedby?: string;
-    /** Valor canônico de `aria-describedby`. */
+    /** Valor de `aria-describedby`. */
     readonly ariaDescribedBy: string | null;
     private get effectiveTarget();
     private get effectiveNavigationMode();

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

@@ -1,31 +1,27 @@
 /**
- * O componente `br-list` é o contêiner estrutural do GovBR-DS desenvolvido para apresentar coleções verticais de itens homogêneos ou relacionados de forma organizada, fácil de percorrer visualmente e acessível.
+ * O `br-list` organiza coleções verticais de itens homogêneos ou relacionados, como listas de contatos, tarefas ou configurações.
  *
- * ### Para que serve
+ * Adicione os itens (como `br-item`) no slot padrão. Se precisar de um título ou ações no topo da lista, use o slot `header` ou a propriedade `title`.
  *
- * - **Apresentação sequencial de informações:** Organiza listagens de dados, tarefas, configurações, opções de navegação ou mensagens.
- * - **Cabeçalho e ações integradas:** Suporta cabeçalho contextual (`header`) para exibição de título da lista, contadores de itens ou botões de ação em lote.
- * - **Composição com itens padronizados:** Integra-se perfeitamente com elementos `br-item` e divisores `br-divider`, mantendo ritmo visual e alinhamento consistentes.
+ * ```html
+ * <br-list title="Configurações">
+ *   <br-item interactive>Notificações</br-item>
+ *   <br-item interactive>Segurança</br-item>
+ * </br-list>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Desejar exibir uma sequência vertical de itens que compartilham a mesma estrutura ou propósito.
- *   - O conteúdo favorecer leitura linear ou seleção de uma linha e precisar ser percorrido visualmente com rapidez.
- * - **Evite e prefira outro componente quando:**
- *   - As informações forem tabulares com múltiplas colunas e necessidade de ordenação por coluna (prefira `br-table`).
- *   - A lista representar o menu principal de navegação do sistema (prefira `br-menu`).
+ * - Sequências verticais de itens com leitura linear.
+ * - Listas de opções simples ou links agrupados.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-list` atua como contêiner de itens:
- * - `header`: Slot opcional para cabeçalho da lista (título, filtros ou ações globais).
- * - `default`: Slot principal onde são inseridos os elementos filhos (como `br-item` ou divs semânticas).
+ * - Dados em linhas e colunas com ordenação: use `br-table`.
+ * - Menu lateral de navegação da página: use `br-menu`.
  *
- * 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/list?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/list?tab=designer).
  *
-
-
  * @category Conteúdo, Layout
  * @status stable
  * @see br-item
@@ -53,7 +49,7 @@ export declare class List {
      * @deprecated Use `orientation`.
      */
     isHorizontal: boolean;
-    /** Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`; valores inválidos usam `vertical`. */
+    /** Orientação padrão. Quando informada, tem precedência sobre `isHorizontal`; valores inválidos usam `vertical`. */
     orientation?: 'horizontal' | 'vertical';
     /**
      * Identificador único do componente.

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

@@ -1,34 +1,27 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { LoadingChangeDetail, LoadingCompleteDetail, LoadingCompletionBehavior, LoadingIndeterminateStateDetail, LoadingLabelPosition, LoadingMode, LoadingSize, LoadingSpeed, LoadingValueDetail } from './loading.types';
 /**
- * O componente `br-loading` é o indicador de carregamento e progresso do GovBR-DS, utilizado para informar visualmente e de forma acessível que uma operação assíncrona está em execução no sistema.
+ * O `br-loading` indica visualmente que uma operação assíncrona está em andamento.
  *
- * ### Para que serve
+ * Suporta o modo circular padrão (indeterminado) ou o modo determinístico com barra e percentual via `progress`. Para adicionar uma mensagem explicativa, informe `label`.
  *
- * - **Feedback de processamento:** Alerta a pessoa usuária de que uma requisição, cálculo ou carregamento de dados está ocorrendo, evitando múltiplos cliques acidentais.
- * - **Modo spinner (indeterminado):** Indicador circular contínuo para operações de duração imprevisível.
- * - **Modo progress (determinado):** Indicador com percentual explícito (0 a 100%) para downloads, uploads ou tarefas com progresso mensurável, suportando ação de cancelamento.
- * - **Acessibilidade para tecnologias assistivas:** Comunica o estado de carregamento através de regiões acessíveis (`aria-live="polite"` e papéis `progressbar` ou `status`).
+ * ```html
+ * <br-loading label="Carregando dados..."></br-loading>
+ * <br-loading progress="60" label="Enviando arquivo..."></br-loading>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Uma operação assíncrona demorar mais de 300 a 500 milissegundos para responder.
- *   - Durante o envio de formulários volumosos, processamento de arquivos ou transição de telas pesadas.
- * - **Evite e prefira outro componente quando:**
- *   - A resposta for quase instantânea (menos de 300ms), para evitar piscamento rápido de tela que cause desconforto visual.
- *   - A espera ocorrer dentro de um botão durante o clique (use a prop `loading` do próprio `br-button`).
+ * - Operações que demoram mais de 300 ms (carregamento de dados, envio de formulário).
+ * - Downloads ou uploads com percentual de progresso mensurável.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-loading` oferece slots para personalização:
- * - `label`: Slot para rótulo ou mensagem descritiva do carregamento (substitui a prop `label`).
- * - `cancel-button`: Slot para botão customizado de cancelamento no modo `progress`.
+ * - Operações instantâneas (menos de 300 ms).
+ * - Carregamento interno em botão: use a propriedade `loading` do `br-button`.
  *
- * 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/loading?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/loading?tab=designer).
  *
-
-
  * @category Feedback, Progresso
  * @status stable
  * @slot label - Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.
@@ -76,7 +69,7 @@ export declare class Loading {
      */
     size: LoadingSize;
     /**
-     * Densidade visual canônica. Quando informada, tem precedência sobre `size`.
+     * Densidade visual. Quando informada, tem precedência sobre `size`.
      * Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
      */
     density?: LoadingSize;
@@ -180,7 +173,7 @@ export declare class Loading {
      * Payload: `void`.
      */
     brDidShow: EventEmitter<void>;
-    /** Evento canônico emitido quando o loading é exibido. */
+    /** Evento emitido quando o loading é exibido. */
     brLoadingShow: EventEmitter<void>;
     /**
      * Notifica que o componente foi ocultado.
@@ -188,7 +181,7 @@ export declare class Loading {
      * Payload: `void`.
      */
     brDidHide: EventEmitter<void>;
-    /** Evento canônico emitido quando o loading é ocultado. */
+    /** Evento emitido quando o loading é ocultado. */
     brLoadingHide: EventEmitter<void>;
     /**
      * Etapa do ciclo de vida: desmontagem do componente.

package/dist/types/components/magic-button/magic-button.d.ts

@@ -1,32 +1,25 @@
 import type { BrDensity } from '../global.types';
 /**
- * O componente `br-magic-button` é o botão de ação flutuante (Floating Action Button - FAB) do GovBR-DS, projetado para destacar a ação primária ou mais relevante da tela, mantendo-se acessível e visível durante a navegação.
+ * O `br-magic-button` é o botão de ação flutuante (FAB) que destaca a ação primária ou mais frequente da tela.
  *
- * ### Para que serve
+ * Pode ser exibido apenas com ícone (formato circular) ou expandido com texto descritivo.
  *
- * - **Destaque da ação principal:** Cria um ponto focal imediato para a ação central de uma tela (ex.: "Nova mensagem", "Criar solicitação", "Adicionar item").
- * - **Posicionamento persistente ou integrado:** Pode ser fixado em um canto da tela (em dispositivos móveis) ou posicionado no fluxo de leitura de painéis e tabelas.
- * - **Modos circular e expandido:** Suporta visual circular compacto com ícone ou versão expandida com texto explicativo.
+ * ```html
+ * <br-magic-button icon="fa-solid:plus" aria-label="Novo item"></br-magic-button>
+ * <br-magic-button icon="fa-solid:plus">Criar documento</br-magic-button>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Houver uma única ação dominante que represente o principal objetivo da pessoa usuária naquela tela.
- *   - Em aplicações móveis ou responsivas que necessitem de um atalho de fácil alcance para os polegares.
- * - **Evite e prefira outro componente quando:**
- *   - Houver múltiplas ações de importância equivalente (prefira uma barra de botões com `br-button`).
- *   - A ação for secundária, destrutiva ou de cancelamento.
+ * - Ação principal e dominante da tela em dispositivos móveis ou interfaces focadas em uma tarefa única.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-magic-button` é um controle direto:
- * - `default`: Slot para rótulo de texto ou conteúdo interno do botão.
- * - `icon`: Slot para personalização do ícone de ação (como `br-icon`).
+ * - Múltiplas ações de mesma importância: use `br-button`.
+ * - Ações secundárias ou destrutivas.
  *
- * 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/magic-button?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/magic-button?tab=designer).
  *
-
-
  * @category Ações
  * @status stable
  * @slot default - Conteúdo interno do botão (texto ou ícone).
@@ -56,8 +49,8 @@ export declare class MagicButton {
      */
     label: string;
     /**
-     * Ícone como identificador Iconify (ex.: `fa6-solid:star`) ou nome simples (ex.: `question`,
-     * resolvido como `fa6-solid:question` no registro SVG local), renderizado pelo `br-icon`.
+     * Ícone como identificador Font Awesome 5 Free do cache local (ex.: `fa-solid:star`) ou nome simples
+     * (ex.: `question`, resolvido como `fa-solid:question`), renderizado pelo `br-icon`.
      * Para classes CSS (ex.: Font Awesome) ou SVGs personalizados, use o slot `icon`, a forma preferida.
      * Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-star`) não são exibidas no Shadow DOM
      * e geram aviso.
@@ -99,12 +92,11 @@ export declare class MagicButton {
      */
     private getLabelIconClass;
     /**
-     * Mantém a API legada `icon="question"` sem transformar o valor em uma
-     * requisição implícita ao Iconify. Identificadores sem coleção usam o
-     * registro local Font Awesome 6; valores já qualificados continuam intactos.
+     * Mantém a API legada `icon="question"` no cache local. Identificadores sem
+     * coleção usam Font Awesome 5 Free; valores já qualificados continuam intactos.
      */
     private getIconName;
-    /** Fallback do slot `icon`: somente identificadores Iconify; classes CSS geram aviso. */
+    /** Fallback para identificadores do cache local; classes CSS geram aviso. */
     private renderIconFallback;
     /**
      * Renderiza o componente.