@govbr-ds/webcomponents 2.1.3 → 2.2.0

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

@@ -1,7 +1,32 @@
 import type { BrDensity } 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/magic-button?tab=designer).
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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.
+ *
+ * ### Estrutura e Slots
+ *
+ * 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`).
+ *
+ * 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).
+ *
+
+
  * @category Ações
  * @status stable
  * @slot default - Conteúdo interno do botão (texto ou ícone).
@@ -9,6 +34,7 @@ import type { BrDensity } from '../global.types';
  *
  * @part container - Wrapper principal do magic-button.
  * @part button - Elemento button interno.
+ *
  */
 export declare class MagicButton {
     /**
@@ -30,8 +56,9 @@ export declare class MagicButton {
      */
     label: string;
     /**
-     * Nome do ícone a ser exibido.
-     * Deve corresponder a um ícone disponível no sistema de ícones.
+     * Identificador legado do ícone a ser exibido.
+     * Nomes simples (por exemplo, `question`) são resolvidos pelo registro SVG local.
+     * Para classes CSS ou SVGs personalizados, prefira o slot `icon`.
      */
     icon: string;
     /**
@@ -41,6 +68,7 @@ export declare class MagicButton {
      * - `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: BrDensity;
     /**
@@ -68,6 +96,12 @@ export declare class MagicButton {
      * @returns `label-icon` quando houver `label` e `icon`; string vazia caso contrário.
      */
     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.
+     */
+    private getIconName;
     /**
      * Renderiza o componente.
      */

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

@@ -1,15 +1,33 @@
 /**
- * Agrupamento visual não interativo para itens de menu.
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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.
  * @part list - Contêiner dos itens agrupados.
  */
 export declare class MenuGroup {
+    private el;
     /** Rótulo visual do grupo. O elemento não entra na ordem de foco. */
     label?: string;
     /** Exibe uma linha separadora antes do grupo. */
     divider: boolean;
+    /** Foca o primeiro item do grupo, mantendo a busca dentro do próprio Shadow DOM. @internal */
+    focusFirstItem(): Promise<boolean>;
     render(): any;
 }

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

@@ -1,7 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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/menu-header?tab=designer).
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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,6 +1,19 @@
 /**
- * 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/menu-info?tab=designer).
+ * 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.
  *
+ * ### 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,8 +2,23 @@ import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 import type { MenuItemDisplayMode } from './menu-item.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/menu?tab=designer).
+ * 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.
  *
+ * ### Para que serve
+ *
+ * - **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`.
  *
@@ -16,8 +31,9 @@ export declare class MenuItem {
     el: HTMLBrMenuItemElement;
     private hasIconSlot;
     /**
-     * Ícone exibido no item do menu.
-     * Utilize esta propriedade para definir o ícone que será mostrado ao lado do conteúdo do item.
+     * Identificador legado do ícone exibido no item do menu.
+     * Nomes simples conhecidos são resolvidos pelo registro SVG local; para
+     * classes CSS, SVGs ou bibliotecas externas, prefira o slot `icon`.
      */
     icon: string;
     /**
@@ -31,6 +47,7 @@ export declare class MenuItem {
      * - `_blank`: abre em nova aba ou janela
      * - `_parent`: abre no contexto pai
      * - `_top`: abre no contexto de nível superior
+     * Valores inválidos usam `_self`.
      */
     target?: BrLinkTarget;
     /**
@@ -48,6 +65,7 @@ export declare class MenuItem {
      * - `accordion`: exibe setas para cima/baixo (usado em menus de nível 0).
      * - `drill-down`: exibe seta para a direita (usado em menus de níveis 1+).
      * - `none`: não exibe ícones de expansão.
+     * Valores inválidos usam `none`.
      */
     displayMode: MenuItemDisplayMode;
     /**
@@ -61,13 +79,19 @@ export declare class MenuItem {
      * - `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.
      * - `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.
      * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
+     * Valores inválidos usam `native`.
      */
     navigationMode: BrNavigationMode;
+    private get effectiveTarget();
+    private get effectiveDisplayMode();
+    private get effectiveNavigationMode();
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.
      * Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.
      */
     brNavigate: EventEmitter<BrNavigateDetail>;
+    /** Move o foco para o link interno sem exigir acesso ao Shadow DOM do item. @internal */
+    focusLink(): Promise<boolean>;
     componentWillLoad(): void;
     render(): any;
 }

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

@@ -1,8 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } 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/menu?tab=designer).
+ * O componente `br-menu-link` é o subcomponente do GovBR-DS que renderiza um hiperlink textual acessível dentro da estrutura de menu.
  *
+ * ### Para que serve
+ *
+ * - **Navegação direta:** Oferece link textual para destinos internos ou externos.
+ * - **Estilo GovBR-DS:** Aplica a tipografia e cores padronizadas de links de menu.
+ *
+ * ### Papel na composição
+ *
+ * Atua como elemento folha de navegação.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Utilizado dentro de `br-menu-item` ou seções de apoio do `br-menu`.
+ *
+
  * @slot icon - Slot para ícone personalizado do link.
  * @slot url - Slot para o texto exibido no link.
  *
@@ -33,6 +47,8 @@ export declare class MenuLink {
      * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
      */
     navigationMode: BrNavigationMode;
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
     /**
      * Título do link
      * @deprecated Use `label`.

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

@@ -1,7 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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/menu?tab=designer).
+ * O componente `br-menu-list` é o subcomponente do GovBR-DS que fornece a estrutura semântica de lista de navegação para acomodar os itens interativos do menu.
  *
+ * ### Para que serve
+ *
+ * - **Semântica de lista:** Garante marcação acessível (`<ul>`) para tecnologias assistivas.
+ * - **Alinhamento e ordenação:** Organiza os itens verticalmente com espaçamentos padronizados.
+ *
+ * ### Papel na composição
+ *
+ * Atua como contêiner semântico de itens dentro de `br-menu` ou `br-menu-group`.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser inserido no interior de `br-menu` ou `br-menu-group`.
+ * - Acomoda múltiplos subcomponentes `br-menu-item`.
+ *
+
  * @slot default - Itens filhos renderizados no conteúdo do grupo.
  * @slot icon - Ícone personalizado do item principal. Quando preenchido, substitui `icon`.
  *
@@ -24,8 +39,9 @@ export declare class MenuList {
      */
     shouldHide: boolean;
     /**
-     * Ícone exibido no item do menu.
-     * Utilize esta propriedade para definir o ícone que será mostrado ao lado do label.
+     * Identificador legado do ícone exibido no item principal do menu.
+     * Nomes simples conhecidos são resolvidos pelo registro SVG local; para
+     * classes CSS, SVGs ou bibliotecas externas, prefira o slot `icon`.
      */
     icon: string;
     /**
@@ -72,6 +88,8 @@ export declare class MenuList {
     private handleKeyDown;
     private isVisibleElement;
     private focusFirstChildAnchor;
-    private findFirstChildAnchor;
+    /** Foca o primeiro item navegável do submenu. @internal */
+    focusFirstItem(): Promise<boolean>;
+    private focusFirstChildOf;
     render(): any;
 }

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

@@ -1,7 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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/menu?tab=designer).
+ * O componente `br-menu-logo` é o subcomponente do GovBR-DS que renderiza a logomarca do sistema ou do Governo Federal no menu lateral.
  *
+ * ### Para que serve
+ *
+ * - **Identidade no menu:** Reforça a marca da aplicação na navegação lateral móvel ou desktop.
+ *
+ * ### Papel na composição
+ *
+ * Atua como identificador visual institucional no menu.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Posiciona-se preferencialmente no topo ou no cabeçalho do `br-menu`.
+ *
+
  * @slot default - Slot para logo ou conteúdo que substitui a imagem padrão.
  * @event brMenuLogoError - Emitido quando a imagem principal e o fallback falham.
  *

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

@@ -1,8 +1,21 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } 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/menu?tab=designer).
+ * O componente `br-menu-social` é o subcomponente do GovBR-DS que reúne atalhos para os canais de redes sociais institucionais no interior do menu.
  *
+ * ### Para que serve
+ *
+ * - **Acesso rápido a mídias:** Permite que o cidadão acesse perfis institucionais a partir da gaveta de navegação.
+ *
+ * ### Papel na composição
+ *
+ * Atua como bloco de engajamento social no menu.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Posiciona-se preferencialmente na base ou rodapé interno do `br-menu`.
+ *
+
  * @slot icon - Slot para ícone personalizado da rede social.
  */
 export declare class MenuSocial {
@@ -23,6 +36,7 @@ export declare class MenuSocial {
     href: string;
     /**
      * Target do link quando href é fornecido.
+     * Aceita `_self`, `_blank`, `_parent` ou `_top`. Valores inválidos usam `_self`.
      */
     target?: BrLinkTarget;
     /**
@@ -30,15 +44,20 @@ export declare class MenuSocial {
      * - `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.
      * - `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.
      * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
+     * Valores inválidos usam `native`.
      */
     navigationMode: BrNavigationMode;
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
     /**
      * Define o rótulo acessível usado por tecnologias assistivas.
      *
      */
     ariaLabel: string;
     /**
-     * Ícone da rede social
+     * Identificador da rede social. Os ícones oficiais mais comuns são
+     * renderizados pelo registro SVG local; use o slot `icon` para uma fonte
+     * diferente ou uma classe Font Awesome personalizada.
      */
     icon: string;
     /**

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

@@ -1,15 +1,46 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { MenuDensity, MenuOpenChangeDetail } from './menu.types';
 /**
- * ## Design System
+ * O componente `br-menu` é o orquestrador completo de navegação lateral (drawer/sidebar) do GovBR-DS. Estrutura a navegação multinível de portais e sistemas públicos, oferecendo suporte a hierarquias em árvore, agrupamentos, busca interna, informações do usuário e canais sociais.
  *
- * 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/menu?tab=designer).
+ * ### Para que serve
  *
- * ### Comportamento de Acionamento Automático
- * O menu monitora eventos de clique globais no documento. Qualquer elemento que possua o atributo `data-toggle="menu"`
- * e cujo `data-target` coincida com o ID ou `customId` do menu (ou seja omitido) irá alternar automaticamente o estado do menu (`isOpen`).
+ * - **Navegação estruturada em árvore:** Permite navegar por hierarquias profundas de seções e subsistemas governamentais.
+ * - **Modos responsivos:** Suporta exibição fixa/lateral no desktop e painel retrátil suspenso com cortina de fundo (`br-scrim`) em telas mobile.
+ * - **Acessibilidade completa:** Gerencia controle de foco por teclado, armadilha de foco (trap focus) quando aberto e atributos WAI-ARIA (`aria-expanded`, `role="dialog"` ou `role="navigation"`).
+ * - **Navegação multinível fluida:** Oferece transições suaves entre níveis hierárquicos com botões de retorno ao nível anterior.
  *
- * @category Navegação
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - A aplicação ou portal exigir uma estrutura de navegação lateral abrangente, com menus de múltiplos níveis e categorias.
+ *   - Houver necessidade de um menu que possa ser recolhido ou deslizado em dispositivos móveis com controle de foco integrado.
+ * - **Evite e prefira outro componente quando:**
+ *   - A navegação tiver poucos itens e puder ser acomodada confortavelmente apenas no cabeçalho (prefira `br-header`).
+ *   - O objetivo for alternar visualizações na mesma tela de forma plana (prefira `br-tab`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-menu` | **Orquestrador principal.** Gerencia estado aberto/fechado, navegação multinível, scrim e armadilha de foco. | Deve ser declarado como contêiner principal da navegação lateral. |
+ * | `br-menu-header` | **Cabeçalho do menu.** Exibe título e botão de fechar o painel. | Inserido no topo do `br-menu`. |
+ * | `br-menu-group` | **Agrupador temático.** Agrupa itens sob um subtítulo de seção. | Inserido no corpo de navegação do `br-menu`. |
+ * | `br-menu-list` | **Lista de opções.** Estrutura semântica de lista contendo itens navegáveis. | Inserido no `br-menu` ou dentro de um `br-menu-group`. |
+ * | `br-menu-item` | **Item de menu.** Opção clicável de rota ou gatilho para submenu. | Deve ser utilizado dentro de um `br-menu-list`. |
+ * | `br-menu-link` | **Hiperlink.** Link textual padronizado no menu. | Inserido dentro de `br-menu-item` ou seções de apoio. |
+ * | `br-menu-info` | **Informações de apoio.** Exibe dados de sessão, versão ou contexto do sistema. | Posicionado na base ou topo do `br-menu`. |
+ * | `br-menu-logo` | **Logotipo.** Exibe a marca do órgão no interior do menu. | Posicionado no cabeçalho ou topo do `br-menu`. |
+ * | `br-menu-social` | **Redes sociais.** Bloco de canais sociais oficiais no menu. | Posicionado preferencialmente no rodapé do `br-menu`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * O `br-menu` atua como o orquestrador soberano da navegação. Ele controla a transição de visibilidade, a ativação do scrim de fundo e o comportamento dos subníveis. Ao navegar entre níveis, os itens (`br-menu-item`) comunicam suas seleções ao `br-menu`, que desliza os painéis correspondentes e mantém a ordem correta de tabulação do teclado.
+ *
+ * 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/menu?tab=designer).
+ *
+
+ * @category Navegação, Estrutura
  * @status stable
  * @slot default - Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).
  * @slot header - Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push.
@@ -81,6 +112,7 @@ export declare class Menu {
      * - `small` (densidade alta): itens mais compactos
      * - `medium` (padrão): equilíbrio entre economia de espaço e separação
      * - `large` (densidade baixa): maior espaçamento (recomendado em touch)
+     * Valores inválidos usam `medium`.
      */
     density: MenuDensity;
     /**
@@ -159,6 +191,7 @@ export declare class Menu {
     private scrimRef;
     private nativeDialogRef;
     private activeMenuItem;
+    private getOwnedMenuElements;
     private get usesNativeDialog();
     private syncNativeDialog;
     private handleNativeCancel;

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

@@ -10,12 +10,8 @@ export declare function isVisibleElement(el: Element | null): el is HTMLElement;
  * @returns Elemento br-menu-list encontrado ou null
  */
 export declare function findClosestMenuListFrom(node: Element): HTMLElement | null;
-/**
- * Obtém o elemento ativo mais profundo, incluindo dentro de shadow roots aninhados.
- * @param root Raiz a partir da qual buscar (document ou ShadowRoot)
- * @returns Elemento ativo ou null
- */
-export declare function getDeepActiveElement(root?: Document | ShadowRoot): Element | null;
+import { getDeepActiveElement } from '../../shared/utils/focus';
+export { getDeepActiveElement };
 /**
  * Define ou remove o atributo drill-active em um elemento.
  * @param element Elemento alvo

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

@@ -1,9 +1,37 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrFeedbackState } 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/message?tab=designer).
+ * O componente `br-message` é a superfície de feedback contextual e notificação em linha do GovBR-DS, utilizada para comunicar mensagens de sucesso, informação, alerta ou erro diretamente associadas à tela ou a um formulário.
  *
- * @category Feedback
+ * ### Para que serve
+ *
+ * - **Comunicação de estados do sistema:** Exibe mensagens com cores, ícones e semânticas padronizadas: `success` (sucesso), `info` (informação), `warning` (aviso) e `danger` (erro).
+ * - **Validação de formulários:** Atua como o contêiner oficial de mensagem de erro e orientação nos slots `feedback` de componentes de formulário (como `br-input`, `br-select` e `br-checkbox`).
+ * - **Opção de fechamento:** Suporta botão de dispensa (`closable`), permitindo que a pessoa usuária feche a notificação após a leitura.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - For necessário dar feedback sobre uma ação recém-executada (ex.: "Dados salvos com sucesso").
+ *   - Houver orientações contextuais ou erros de validação em campos de formulário.
+ * - **Evite e prefira outro componente quando:**
+ *   - A mensagem for crítica e exigir confirmação bloqueadora antes de continuar (prefira `br-modal`).
+ *   - As notificações forem assíncronas do sistema e acumuladas em uma central de mensagens (prefira `br-notification`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-message` oferece personalização modular:
+ * - `message-title`: Slot para título de destaque da mensagem.
+ * - `message-body`: Slot para o corpo detalhado do texto.
+ * - `icon`: Slot para substituição do ícone contextual padrão.
+ * - `close-button`: Slot para botão de fechar customizado.
+ * - `default`: Slot livre para renderização direta do conteúdo.
+ *
+ * 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/message?tab=designer).
+ *
+
+
+ * @category Feedback, Conteúdo
  * @status stable
  * @slot default - Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.
  * @slot icon - Ícone customizado da mensagem. Quando utilizado, o ícone padrão gerado pela prop `state` é ignorado.
@@ -15,6 +43,7 @@ import type { BrFeedbackState } from '../global.types';
  * @part icon - Área do ícone da mensagem.
  * @part content - Área de conteúdo da mensagem.
  * @part close - Área do botão de fechar.
+ *
  */
 export declare class Message {
     /**
@@ -43,8 +72,8 @@ export declare class Message {
     /**
      * Exibe o rótulo e o controle na mesma linha.
      *
+     * @deprecated Use `inline`.
      */
-    /** @deprecated Use `inline`. */
     isInline: boolean;
     /** Exibe o conteúdo em linha. Quando informada, tem precedência sobre `isInline`. */
     inline?: boolean;
@@ -52,8 +81,9 @@ export declare class Message {
      * Se definido como verdadeiro, um botão de fechar será exibido para permitir que o usuário feche a mensagem.
      * O fechamento emitirá o evento `brDidClose`, mas não removerá automaticamente o componente do DOM, a menos que a propriedade `autoRemove` também esteja definida como `true`.
      * Este recurso não está disponível para mensagens do tipo feedback.
+     *
+     * @deprecated Use `closable`.
      */
-    /** @deprecated Use `closable`. */
     isClosable: boolean;
     /** Exibe ação de fechar. Quando informada, tem precedência sobre `isClosable`. */
     closable?: boolean;
@@ -74,13 +104,14 @@ export declare class Message {
     /**
      * Define se a mensagem é do tipo feedback, geralmente usada para fornecer contexto adicional sobre ações do usuário.
      * Exemplos incluem mensagens de validação em campos de formulário. Não disponível para mensagens que não sejam de feedback.
+     *
+     * @deprecated Use `feedback`.
      */
-    /** @deprecated Use `feedback`. */
     isFeedback: boolean;
     /** Usa apresentação de feedback. Quando informada, tem precedência sobre `isFeedback`. */
     feedback?: boolean;
     /**
-     * Define o estado do message.
+     * Define o estado do message. Valores inválidos usam `info`.
      * Os possíveis valores são:
      * - 'info': Mensagem informativa.
      * - 'warning': Mensagem de aviso.
@@ -102,13 +133,11 @@ export declare class Message {
     /** Evento canônico emitido quando a mensagem é fechada. */
     brMessageClose: EventEmitter<void>;
     disconnectedCallback(): void;
-    componentDidLoad(): Promise<void>;
+    componentDidLoad(): void;
     private get effectiveInline();
     private get effectiveClosable();
     private get effectiveFeedback();
     private get effectiveFeedbackState();
-    private previousFocus;
-    private closeButton?;
     private dismissHandler;
     private handleKeyDown;
     private checkIconState;

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

@@ -1,14 +1,41 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { ModalFooterAlign, ModalSize } from './modal.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/modal?tab=designer).
+ * O componente `br-modal` é a caixa de diálogo bloqueadora (dialog modal) do GovBR-DS, desenvolvida para capturar o foco e exigir a atenção imediata da pessoa usuária antes de permitir o retorno ao fluxo de trabalho normal.
  *
+ * ### Para que serve
+ *
+ * - **Confirmação de ações críticas:** Solicita confirmação explícita para ações irreversíveis ou de grande impacto (ex.: excluir registro, cancelar processo em andamento).
+ * - **Entrada de dados pontual:** Permite preencher formulários breves e contextuais sem sair da tela principal.
+ * - **Gestão de foco e acessibilidade WAI-ARIA:** Bloqueia o foco dentro do diálogo (`focus trap`), impede a rolagem do fundo, aplica `aria-modal="true"` e fecha com a tecla Escape ou clique externo.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - A decisão for estritamente obrigatória e a continuação sem ela puder causar perda de dados ou inconsistência.
+ *   - Apresentar detalhes suplementares que requerem fechamento explícito.
+ * - **Evite e prefira outro componente quando:**
+ *   - A mensagem for informativa e não exigir ação imediata (prefira `br-message`).
+ *   - O conteúdo for extenso, demandando navegação complexa (prefira uma nova página dedicada).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-modal` organiza o diálogo em regiões padronizadas:
+ * - `header`: Slot para cabeçalho e título (substitui a prop `title-text`).
+ * - `default`: Slot principal onde é inserido o corpo de texto ou formulário do modal.
+ * - `footer`: Slot para ações de rodapé (botões de confirmação, envio e cancelamento com `br-button`).
+ * - `close-button`: Slot para personalizar o botão de fechar do canto superior.
+ *
+ * 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/modal?tab=designer).
+ *
+
+
  * @slot header - Cabeçalho do modal. Se não for usado, o `title-text` será exibido.
  * @slot default - Corpo do modal.
  * @slot footer - Rodapé do modal.
  * @slot close-button - Botão de fechar customizado. Se não for usado, o botão padrão será exibido.
  *
- * @category Feedback
+ * @category Feedback, Sobreposições
  * @status stable
  * @part container - Wrapper principal do modal.
  * @part header - Cabeçalho do modal.
@@ -17,6 +44,7 @@ import type { ModalFooterAlign, ModalSize } from './modal.types';
  * @part footer - Rodapé do modal.
  * @part close-button - Botão de fechar do modal.
  *
+ *
  */
 export declare class Modal {
     /** Referência ao elemento host do componente. */
@@ -46,7 +74,7 @@ export declare class Modal {
      */
     initialFocusSelector: string;
     /**
-     * Define o tamanho (largura) do modal.
+     * Define o tamanho (largura) do modal. Valores inválidos usam `medium`.
      */
     size: ModalSize;
     /**
@@ -54,7 +82,7 @@ export declare class Modal {
      */
     scrollable: boolean;
     /**
-     * Define o alinhamento do conteúdo do rodapé (slot="footer").
+     * Define o alinhamento do conteúdo do rodapé (slot="footer"). Valores inválidos usam `center`.
      */
     alignFooter: ModalFooterAlign;
     handleShowChange(newValue: boolean, oldValue: boolean): void;
@@ -200,6 +228,8 @@ export declare class Modal {
     private handleParentScrimClose;
     private openParentScrim;
     private getCssClassMap;
+    private get effectiveSize();
+    private get effectiveAlignFooter();
     private handleClose;
     private handleNativeCancel;
     render(): any;