@govbr-ds/webcomponents 2.3.0 → 2.5.0

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 { InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from './input.types';
+import type { InputActionClickDetail, 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 { InputDensity, InputState, InputToggle, InputType, InputValidationC
  * @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,8 +258,18 @@ 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.
+     * Emitido no host com `detail.originalEvent` contendo o clique original.
+     * Propaga e atravessa Shadow DOM; não é cancelável nem altera o clique nativo.
+     * Não emite para o campo textual, botão de senha, inicialização ou controle desabilitado.
+     */
+    brInputActionClick: EventEmitter<InputActionClickDetail>;
     /**
      * Informa o início e o resultado do validator, inclusive quando ele consulta
      * um serviço remoto. O `detail` contém `validating`, `valid` e `message`;
@@ -265,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`.
@@ -392,6 +407,16 @@ 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.
      * @returns JSX.Element representando o botão de ação.

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

@@ -5,6 +5,10 @@ export type InputDensity = BrDensity;
 export type InputState = BrFeedbackState;
 /** Regra de validação fornecida pelo consumidor do campo. */
 export type InputValidator = (value: string) => string | null | Promise<string | null>;
+/** Clique que ativou o botão do slot `action`, inclusive por teclado. */
+export interface InputActionClickDetail {
+    originalEvent: MouseEvent;
+}
 /** Estado observável de uma validação customizada do campo. */
 export interface InputValidationChangeDetail {
     validating: boolean;

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="fa6-solid:plus" aria-label="Novo item"></br-magic-button>
+ * <br-magic-button icon="fa6-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).

package/dist/types/components/menu/menu-group/menu-group.d.ts

@@ -1,21 +1,8 @@
 /**
- * O componente `br-menu-group` é o subcomponente do GovBR-DS que divide os itens de navegação em blocos ou agrupamentos temáticos com subtítulos.
+ * Agrupa itens de menu sob um título ou categoria comum. Use dentro do `br-menu`.
  *
- * ### Para que serve
+ * Defina o título do grupo pelo slot `label` ou pela propriedade `label`. Insira a lista de itens (`br-menu-list`) no slot padrão.
  *
- * - **Segmentação visual:** Separa blocos de links afins para facilitar a leitura.
- * - **Hierarquia clara:** Estabelece grupos com rótulos descritivos.
- *
- * ### Papel na composição
- *
- * Atua como agrupador intermediário dentro do corpo do `br-menu`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado no interior do componente `br-menu`.
- * - Contém instâncias de `br-menu-list` ou `br-menu-item`.
- *
-
  * @slot default - Itens do grupo.
  * @part container - Contêiner do agrupamento.
  * @part label - Rótulo visual do agrupamento.

package/dist/types/components/menu/menu-header/menu-header.d.ts

@@ -1,22 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-menu-header` é o subcomponente do GovBR-DS que fornece o cabeçalho superior do menu lateral, contendo o título da área e o botão de fechamento.
+ * Cabeçalho do menu lateral com título e botão de fechar. Use no slot `header` do `br-menu`.
  *
- * ### Para que serve
+ * Defina o título da área em `title-text`. O botão de fechar emite o fechamento para o `br-menu` pai.
  *
- * - **Identificação da navegação:** Exibe o título do menu ou seção atual.
- * - **Controle de fechamento:** Fornece o botão de fechar acessível que recolhe o menu.
- *
- * ### Papel na composição
- *
- * Atua como cabeçalho funcional e acessível no topo do `br-menu`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser posicionado no início do orquestrador `br-menu`.
- * - Dispara a ação de fechamento gerenciada pelo componente pai.
- *
-
  * @slot logo - Slot para logo personalizado no cabeçalho.
  * @slot signature - Slot para a assinatura personalizada do sistema.
  *

package/dist/types/components/menu/menu-info/menu-info.d.ts

@@ -1,19 +1,6 @@
 /**
- * O componente `br-menu-info` é o subcomponente do GovBR-DS destinado a exibir textos informativos, versão do sistema, status da aplicação ou informações de usuário no menu.
+ * Exibe informações de apoio (versão do sistema, dados do usuário ou licença) no menu. Use no slot `info` ou no rodapé do `br-menu`.
  *
- * ### Para que serve
- *
- * - **Informações contextuais:** Apresenta dados de apoio ao usuário sem poluir o fluxo de links.
- *
- * ### Papel na composição
- *
- * Atua como área informativa complementar no menu.
- *
- * ### Regra de uso e relacionamento
- *
- * - Posiciona-se geralmente no rodapé ou na área superior do `br-menu`.
- *
-
  * @slot default - Slot para conteúdo personalizado no lugar do texto padrão de informações.
  */
 export declare class MenuInfo {

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

@@ -2,23 +2,10 @@ import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 import type { MenuItemDisplayMode } from './menu-item.types';
 /**
- * O componente `br-menu-item` é o subcomponente interativo do GovBR-DS que representa uma opção de navegação ou gatilho para submenu na árvore de menu.
+ * Representa uma linha de navegação ou botão de submenu dentro do `br-menu-list`.
  *
- * ### Para que serve
+ * Coloque um `br-menu-link` ou texto no slot padrão. Para submenus multiníveis, adicione a lista filha no interior do item.
  *
- * - **Opção de rota ou submenu:** Funciona como link direto para uma página ou como nó que abre um próximo nível hierárquico.
- * - **Estados visuais de navegação:** Reflete estados ativo, focado, hover e selecionado.
- *
- * ### Papel na composição
- *
- * Atua como item interativo central da navegação.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado exclusivamente dentro de um `br-menu-list`.
- * - Quando contiver subníveis, comunica-se com o orquestrador `br-menu` para ativar a transição entre telas.
- *
-
  * @slot default - Conteúdo textual principal exibido no item de menu.
  * @slot icon - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.
  *