@govbr-ds/webcomponents 2.4.0 → 2.6.0

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

@@ -1,30 +1,26 @@
 import type { DividerAlign, DividerBorderStyle, DividerOrientation, DividerThickness } from './divider.types';
 /**
- * O componente `br-divider` é o elemento separador visual e semântico do GovBR-DS, utilizado para demarcar limites claros entre seções, listas de conteúdos ou áreas temáticas da página.
+ * O `br-divider` é uma linha que separa seções ou grupos de conteúdo. Pode ser horizontal ou vertical e ter um texto no meio.
  *
- * ### Para que serve
+ * ```html
+ * <br-divider></br-divider>
  *
- * - **Separação visual estruturada:** Cria linhas divisórias sutis horizontais ou verticais para organizar blocos de informação com espaçamentos padronizados.
- * - **Rotulação intermediária:** Permite incluir texto (ex.: "ou"), ícones ou outros elementos centralizados ao longo da linha divisória através do slot padrão.
- * - **Variações visuais:** Suporta estilos contínuos, tracejados (`dashed`) e diferentes densidades para se adequar ao leiaute.
+ * <br-divider>ou</br-divider>
  *
- * ### Quando utilizar
+ * <br-divider orientation="vertical" thickness="medium" border-style="dashed"></br-divider>
+ * ```
  *
- * - **Utilize quando:**
- *   - Houver necessidade de indicar explicitamente o término de um bloco temático e o início de outro.
- *   - Separar alternativas com um divisor textual (ex.: "Entrar com conta Gov.BR" --- ou --- "Entrar com certificado digital").
- *   - Dividir colunas de rodapés, menus laterais ou cabeçalhos.
- * - **Evite e prefira outro componente quando:**
- *   - Os espaçamentos em branco (margens e paddings) já forem suficientes para garantir a percepção de separação sem sobrecarregar visualmente a tela.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Marcar o fim de um bloco e o início de outro.
+ * - Separar alternativas, como "Entrar com gov.br" ou "Entrar com certificado digital".
  *
- * O `br-divider` é um componente autônomo e de apresentação:
- * - `default`: Slot opcional para texto ou elemento centralizado intercalado na linha do divisor.
+ * ### 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/divider?tab=designer).
+ * - Quando o espaço em branco já separa bem o conteúdo.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/divider?tab=designer).
  *
-
  * @category Layout, Estrutura
  * @status stable
  * @slot default - Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados).
@@ -61,7 +57,7 @@ export declare class Divider {
      * @deprecated Use `colorMode`.
      */
     isDarkMode: boolean;
-    /** Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`; valores inválidos usam `light`. */
+    /** Esquema de cor padrão. Quando informado, tem precedência sobre `isDarkMode`; valores inválidos usam `light`. */
     colorMode?: 'light' | 'dark';
     /**
      * Cor do divisor.

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

@@ -1,33 +1,34 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { DropdownArrowPosition, DropdownOpenChangeDetail, DropdownPlacement } from './dropdown.types';
 /**
- * O componente `br-dropdown` é o painel flutuante de sobreposição do GovBR-DS, ativado por um controle gatilho para apresentar listas contextuais de comandos, opções ou conteúdos complementares.
+ * O `br-dropdown` abre um painel flutuante a partir de um botão, com ações ou conteúdo complementar, como um menu "Mais opções".
  *
- * ### Para que serve
+ * Coloque o botão no slot `trigger` e o conteúdo no slot `target`:
  *
- * - **Menus de contexto e ações:** Agrupa múltiplas ações secundárias ou suplementares que não precisam ficar expostas permanentemente na interface (ex.: menu "Mais opções", "Exportar", "Filtrar por").
- * - **Posicionamento flutuante inteligente:** Gerencia a exibição da superfície suspensa sobre o conteúdo da página, garantindo contraste, elevação e fechamento ao clicar fora (`click outside`) ou pressionar a tecla Escape.
- * - **Comportamento acessível:** Associa o elemento acionador ao painel de destino via atributos WAI-ARIA (`aria-expanded`, `aria-haspopup`).
+ * ```html
+ * <br-dropdown>
+ *   <br-button slot="trigger" emphasis="tertiary">Mais opções</br-button>
+ *   <br-list slot="target">
+ *     <br-item>Exportar</br-item>
+ *     <br-item>Imprimir</br-item>
+ *   </br-list>
+ * </br-dropdown>
+ * ```
  *
- * ### Quando utilizar
+ * O painel fecha com Escape ou com um clique fora dele (desative com `prevent-auto-dismiss`). A posição é definida por `placement`, por exemplo `bottom-start` ou `top-end`. Para acompanhar a abertura e o fechamento, ouça `brDropdownOpenChange`.
  *
- * - **Utilize quando:**
- *   - O espaço na barra de ferramentas ou cabeçalho for limitado e houver várias ações pontuais a serem oferecidas.
- *   - For necessário apresentar uma lista suspensa de comandos acionáveis.
- * - **Evite e prefira outro componente quando:**
- *   - O objetivo for permitir a seleção de valor para submissão em formulário (prefira `br-select`).
- *   - O conteúdo for a estrutura principal de navegação do site (prefira `br-menu`).
- *   - A mensagem for uma notificação assíncrona ou alerta (prefira `br-message` ou `br-notification`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Várias ações secundárias quando há pouco espaço na tela.
  *
- * O `br-dropdown` é composto por duas regiões fundamentais:
- * - `trigger`: Slot obrigatório onde a aplicação declara o botão ou link de acionamento (como um `br-button`).
- * - `target`: Slot onde a aplicação declara o painel, lista de itens ou conteúdo flutuante exibido ao abrir o dropdown.
+ * ### 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/dropdown?tab=designer).
+ * - Escolher um valor de formulário: use `br-select`.
+ * - Navegação principal do site: use `br-menu`.
+ * - Avisos: use `br-message` ou `br-notification`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/dropdown?tab=designer).
  *
-
  * @category Ações, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a abertura do dropdown.
@@ -143,7 +144,7 @@ export declare class Dropdown {
     brDropdownChange: EventEmitter<{
         isOpen: boolean;
     }>;
-    /** Evento canônico emitido quando o estado aberto muda. */
+    /** Evento emitido quando o estado aberto muda. */
     brDropdownOpenChange: EventEmitter<DropdownOpenChangeDetail>;
     connectedCallback(): void;
     disconnectedCallback(): void;

package/dist/types/components/footer/footer-category/footer-category.d.ts

@@ -1,21 +1,8 @@
 /**
- * O componente `br-footer-category` é o subcomponente do GovBR-DS que agrupa links de rodapé por tema sob um título estruturado.
+ * Grupo de links do mapa do site no `br-footer`. O título vem de `label` e os links são `br-footer-item`.
  *
- * ### Para que serve
+ * Em telas pequenas, a categoria vira uma seção que abre e fecha.
  *
- * - **Organização temática:** Divide os links de apoio em blocos temáticos claros.
- * - **Colapso responsivo:** Funciona como seção que pode ser expandida ou recolhida no layout mobile, otimizando o espaço da tela.
- *
- * ### Papel na composição
- *
- * Atua como agrupador intermediário entre o `br-footer` e os itens filhos individuais `br-footer-item`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser inserido dentro do `br-footer`.
- * - Acomoda instâncias de `br-footer-item` representando cada link pertencente àquela categoria.
- *
-
  * @slot default - Slot para os itens da categoria no rodapé, utilizando br-footer-item.
  */
 export declare class FooterCategory {

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

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-footer-item` é o subcomponente folha do GovBR-DS que renderiza um link de navegação individual dentro de uma categoria do rodapé.
+ * Um link do mapa do site, dentro de um `br-footer-category`. Informe o destino em `href` e o texto no conteúdo.
  *
- * ### Para que serve
+ * Em SPA, use `navigation-mode="event"` e trate o evento `brNavigate`.
  *
- * - **Acesso direto a links:** Conduz a pessoa usuária a páginas de serviços, transparência ou seções institucionais.
- * - **Estilo padronizado:** Garante tipografia, espaçamento e estados acessíveis no rodapé.
- *
- * ### Papel na composição
- *
- * Atua como item de link final na hierarquia de rodapé.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado exclusivamente dentro de um componente `br-footer-category`.
- * - Não deve ser declarado de forma isolada fora de uma categoria de rodapé.
- *
-
  * @slot default - Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs.
  */
 export declare class FooterItem {

package/dist/types/components/footer/footer-legal/footer-legal.d.ts

@@ -1,20 +1,6 @@
 /**
- * O componente `br-footer-legal` é o subcomponente do GovBR-DS que apresenta as informações de licenciamento aberto de conteúdo (como Creative Commons) e termos legais obrigatórios.
+ * Informações legais do `br-footer`, como licença de uso e direitos autorais. Use no slot `legal`.
  *
- * ### Para que serve
- *
- * - **Transparência jurídica:** Comunica a licença de uso dos dados e conteúdos do portal público.
- * - **Fechamento de conformidade:** Atende às normas governamentais de publicação de páginas federais.
- *
- * ### Papel na composição
- *
- * Atua como elemento informativo legal no rodapé.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser posicionado na área base de menções legais do `br-footer`.
- *
-
  * @slot default - Slot para informações legais no rodapé, como direitos autorais ou termos de uso.
  *
  * @part container - Wrapper principal do footer-legal.

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

@@ -2,23 +2,10 @@ import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 import type { FooterLogoPosition } from './footer-logo.types';
 /**
- * O componente `br-footer-logo` é o subcomponente do GovBR-DS responsável por renderizar a marca oficial do órgão ou a marca unificada do Governo Federal no rodapé.
+ * Logotipo do `br-footer`. Use no slot `logo` para a marca do órgão, ou com `partner` no slot `partner-logo` para parceiros.
  *
- * ### Para que serve
+ * Informe a imagem em `src` e o texto alternativo em `description`. Com `href`, a logo vira link.
  *
- * - **Assinatura institucional:** Reforça a autenticidade governamental no fechamento da página.
- * - **Link oficial:** Permite redirecionar a pessoa usuária para o portal principal do Governo Federal ou do órgão.
- *
- * ### Papel na composição
- *
- * Atua como elemento de identidade institucional no rodapé.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser inserido na área ou slot de logotipo do `br-footer`.
- * - Não deve ser utilizado fora do ecossistema de rodapé.
- *
-
  * @part container - Wrapper principal do footer-logo.
  */
 export declare class FooterLogo {

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

@@ -1,22 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-footer-social` é o subcomponente do GovBR-DS que agrupa e renderiza atalhos e ícones para os canais oficiais de redes sociais da organização pública.
+ * Link para uma rede social no `br-footer`. Use no slot `social-network`.
  *
- * ### Para que serve
+ * Informe em `icon` o nome do ícone de marca, como `instagram` ou `youtube`; em `description`, o nome da rede (usado como texto acessível); e em `href`, o endereço. Para outro ícone, use o slot `icon`.
  *
- * - **Canais oficiais:** Facilita o acesso do cidadão às mídias sociais e de comunicação do órgão.
- * - **Acessibilidade nos atalhos:** Fornece rótulos acessíveis e abertura segura de links externos.
- *
- * ### Papel na composição
- *
- * Atua como bloco de engajamento social no rodapé.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser inserido na área ou slot destinado a redes sociais do `br-footer`.
- *
-
  * @slot icon - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.
  */
 export declare class FooterSocial {
@@ -34,9 +22,8 @@ export declare class FooterSocial {
      */
     customId: string;
     /**
-     * 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.
+     * Nome do ícone Font Awesome 5 Free presente no cache local, sem o prefixo
+     * `fa-brands:` (ex.: `instagram`). Use o slot `icon` para conteúdo próprio.
      */
     icon: string;
     /**

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

@@ -1,40 +1,36 @@
 import type { FooterLayoutWidth, FooterTheme } from './footer.types';
 /**
- * O componente `br-footer` é o orquestrador completo de rodapé institucional do GovBR-DS. Fornece o fechamento estrutural da página, centralizando links de navegação categorizados, canais de redes sociais, menção legal de licenciamento aberto e a marca do Governo Federal.
+ * O `br-footer` é o rodapé da página: logotipo, mapa do site, redes sociais, parceiros e informações legais.
  *
- * ### Para que serve
+ * ### Como montar
  *
- * - **Fechamento e navegação secundária:** Agrupa em categorias os links úteis de apoio, mapas do site e serviços da entidade pública.
- * - **Conformidade legal e transparência:** Apresenta a nota de licenciamento de conteúdo (ex.: Creative Commons) e termos legais obrigatórios.
- * - **Redes sociais institucionais:** Exibe links oficiais de comunicação pública com a sociedade.
- * - **Responsividade integrada:** Converte categorias de links em painéis expansíveis (sanfona) automaticamente no modo mobile.
+ * | Área | Onde colocar |
+ * | --- | --- |
+ * | Logotipo | `br-footer-logo` no slot `logo` |
+ * | Mapa do site | `br-footer-category` com `br-footer-item`, no conteúdo do footer |
+ * | Redes sociais | `br-footer-social` no slot `social-network` |
+ * | Parceiros | `br-footer-logo partner` no slot `partner-logo` |
+ * | Informações legais | `br-footer-legal` no slot `legal` |
  *
- * ### Quando utilizar
+ * ```html
+ * <br-footer social-network-title="Redes sociais">
+ *   <br-footer-logo slot="logo" src="/logo.svg" description="Nome do órgão" href="/"></br-footer-logo>
  *
- * - **Utilize quando:**
- *   - Finalizar a estrutura da página em portais e sistemas governamentais alinhados ao padrão GovBR-DS.
- *   - Oferecer navegação complementar, canais sociais e declarações de direitos autorais.
- * - **Evite e prefira outro componente quando:**
- *   - A interface for um diálogo modal ou painel isolado que não representa uma página completa do portal.
+ *   <br-footer-category label="Serviços">
+ *     <br-footer-item href="/servicos/emitir">Emitir documento</br-footer-item>
+ *     <br-footer-item href="/servicos/consultar">Consultar processo</br-footer-item>
+ *   </br-footer-category>
  *
- * ### Composição e Subcomponentes
+ *   <br-footer-social slot="social-network" icon="instagram" description="Instagram" href="https://instagram.com/orgao" target="_blank"></br-footer-social>
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-footer` | **Orquestrador principal.** Gerencia a distribuição visual em colunas/linhas e o comportamento sanfona em telas menores. | Deve ser declarado como elemento de rodapé ao final da página. |
- * | `br-footer-category` | **Categoria de links.** Agrupa links temáticos sob um título expansível. | Deve ser inserido no contêiner de categorias do `br-footer`. |
- * | `br-footer-item` | **Item de link.** Link individual dentro de uma categoria de rodapé. | Deve ser utilizado dentro de um `br-footer-category`. |
- * | `br-footer-logo` | **Logotipo.** Exibe a logomarca do órgão ou do Governo Federal. | Posicionado na área designada de logotipo do `br-footer`. |
- * | `br-footer-social` | **Redes sociais.** Reúne links e ícones para canais sociais oficiais. | Posicionado no slot ou área de mídias sociais do `br-footer`. |
- * | `br-footer-legal` | **Texto legal.** Exibe termos de licenciamento aberto e direitos autorais. | Posicionado na base legal do `br-footer`. |
+ *   <br-footer-legal slot="legal">Texto destinado a exibir informações sobre o licenciamento.</br-footer-legal>
+ * </br-footer>
+ * ```
  *
- * ### Como os subcomponentes se relacionam
+ * Em telas pequenas, as categorias viram seções que abrem e fecham. O tema padrão é escuro; use `theme="light"` para o claro.
  *
- * O `br-footer` atua como contêiner estrutural orquestrador. Ele organiza as categorias (`br-footer-category`) em colunas no desktop e alterna para comportamento de acordeão no mobile. Os itens (`br-footer-item`) herdam o contexto da categoria correspondente, enquanto as áreas de logotipo, redes sociais e notas legais completam o fechamento padronizado.
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/footer?tab=designer).
  *
- * 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/footer?tab=designer).
- *
-
  * @category Estrutura, Navegação
  * @status stable
  * @slot logo - Slot para o logo do rodapé, utilizando o componente br-logo.
@@ -68,7 +64,7 @@ export declare class Footer {
      * @deprecated Use `colorMode`.
      */
     theme: FooterTheme;
-    /** Esquema de cor canônico. Quando informado, tem precedência sobre `theme`. */
+    /** Esquema de cor padrão. Quando informado, tem precedência sobre `theme`. */
     colorMode?: FooterTheme;
     /**
      * Texto de descrição das redes sociais.

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

@@ -2,23 +2,19 @@ import { type EventEmitter } from '../../../stencil-public-runtime';
 import { type Breakpoint } from '../../../shared/utils/breakpoint-observer';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-header-function` é o subcomponente do GovBR-DS que representa uma ação funcional ou utilitária rápida no cabeçalho (como alto contraste, atalhos de acessibilidade, suporte ou configurações).
+ * Atalho do `br-header`, como contraste ou ajuda, dentro de um `br-header-list` no slot `functions`.
  *
- * ### Para que serve
+ * Coloque o ícone no slot `icon` e o nome no conteúdo:
  *
- * - **Ações utilitárias rápidas:** Permite disparar funcionalidades auxiliares com ícone e rótulo sem sair do fluxo da página.
- * - **Feedback interativo:** Oferece estados visuais consistentes de foco, hover e ativação.
+ * ```html
+ * <br-header-function href="/ajuda">
+ *   <br-icon slot="icon" src="/icones/ajuda.svg"></br-icon>
+ *   Ajuda
+ * </br-header-function>
+ * ```
  *
- * ### Papel na composição
+ * Em telas grandes, aparece como botão de ícone, e o nome é usado como texto acessível. Em telas menores, aparece com ícone e nome dentro do menu da lista.
  *
- * Atua como controle interativo de utilidade dentro do cabeçalho.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado dentro de um `br-header-list` posicionado no slot `functions` do `br-header`.
- * - Não deve ser utilizado como botão genérico de formulário ou ação primária de conteúdo (para esses casos, utilize `br-button`).
- *
-
  * @slot default - Slot para o nome ou rótulo da funcionalidade.
  * @slot icon - Slot para ícone que representa a funcionalidade.
  */

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

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-header-link` é o subcomponente de navegação do GovBR-DS que representa um atalho ou hiperlink de navegação institucional no cabeçalho.
+ * Link do `br-header`, dentro de um `br-header-list` no slot `links`. Informe o destino em `href` e o texto no conteúdo.
  *
- * ### Para que serve
+ * Em SPA, use `navigation-mode="event"` e trate `brNavigate`.
  *
- * - **Navegação institucional:** Oferece acesso direto a páginas de serviços, portais correlatos ou áreas centrais do órgão.
- * - **Integração SPA:** Suporta navegação web padrão via atributo `href` ou integração com roteadores SPA via eventos de navegação.
- *
- * ### Papel na composição
- *
- * Atua como item folha de navegação dentro do cabeçalho.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado dentro de um `br-header-list` posicionado no slot `links` do `br-header`.
- * - Não deve ser utilizado de forma avulsa fora do ecossistema de cabeçalho.
- *
-
  * @slot default - Slot para o conteúdo do link exibido no cabeçalho.
  */
 export declare class HeaderLink {

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

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import { type Breakpoint } from '../../../shared/utils/breakpoint-observer';
 /**
- * O componente `br-header-list` é o subcomponente contêiner do GovBR-DS que organiza links de navegação ou botões funcionais em uma estrutura de lista horizontal acessível.
+ * Lista de links ou atalhos do `br-header`. Use no slot `links`, com `br-header-link`, ou no slot `functions`, com `br-header-function`.
  *
- * ### Para que serve
+ * Em telas menores, a lista vira um menu que abre e fecha; o título desse menu vem de `list-title`.
  *
- * - **Agrupamento semântico:** Estrutura itens navegáveis ou funcionais em elementos de lista semânticos.
- * - **Distribuição e espaçamento:** Garante o alinhamento horizontal padronizado de itens no cabeçalho.
- *
- * ### Papel na composição
- *
- * Atua como elo intermediário entre o orquestrador `br-header` e os itens filhos individuais (`br-header-link` ou `br-header-function`).
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser inserido nos slots `links` ou `functions` do orquestrador `br-header`.
- * - Serve de contêiner direto para subcomponentes `br-header-link` ou `br-header-function`.
- *
-
  * @slot default - Slot para o conteúdo da lista de navegação no cabeçalho.
  */
 export declare class HeaderList {

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

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * O componente `br-header-logo` é o subcomponente do GovBR-DS responsável por renderizar a marca visual oficial ou a assinatura do órgão dentro do cabeçalho.
+ * Logotipo do `br-header`. Use no slot `logo`.
  *
- * ### Para que serve
+ * Informe a imagem em `src` e o texto alternativo em `description`. Com `href`, a logo vira link; em SPA, use `navigation-mode="event"` e trate `brNavigate`.
  *
- * - **Exibição de marca:** Apresenta a imagem ou logotipo institucional no topo da página.
- * - **Link de retorno:** Permite associar um link à marca, direcionando a pessoa usuária à página inicial do portal ou sistema.
- *
- * ### Papel na composição
- *
- * Atua como elemento de identidade visual no cabeçalho. Não gerencia a estrutura do topo nem as ações utilitárias, papel reservado ao orquestrador `br-header`.
- *
- * ### Regra de uso e relacionamento
- *
- * - Deve ser utilizado posicionado preferencialmente no slot `logo` ou `signature` do componente orquestrador `br-header`.
- * - Não deve ser utilizado isoladamente fora do contexto de cabeçalho institucional.
- *
-
  * @slot default - Slot para a logo personalizada exibida no cabeçalho.
  *
  * @part container - Wrapper da logo do header.

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

@@ -2,46 +2,49 @@ import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../global.types';
 import type { HeaderArea, HeaderCompactChangeDetail, HeaderDensity, HeaderLayoutWidth, HeaderShrinkFirst } from './header.types';
 /**
- * O componente `br-header` é o orquestrador principal de cabeçalho do GovBR-DS. Centraliza a identidade visual do órgão ou sistema público, links de navegação hierárquica, atalhos de funcionalidades, mecanismo de busca e botão de acesso ou autenticação.
+ * O `br-header` é o cabeçalho da página: logotipo, nome do sistema, links, atalhos, busca, acesso e botão do menu.
  *
- * ### Para que serve
+ * ### Como montar
  *
- * - **Identidade institucional unificada:** Apresenta a marca e assinatura visual oficial do Governo Federal e da entidade pública.
- * - **Navegação e atalhos rápidos:** Reúne links para áreas centrais e botões funcionais (como contraste, acessibilidade e suporte).
- * - **Busca e autenticação integradas:** Fornece áreas reservadas e slots para barra de busca rápida e gatilho de login/acesso.
- * - **Comportamento responsivo e densidades:** Adapta-se automaticamente a diferentes telas com suporte a densidades padrão, compacta, pequena e grande.
+ * Cada área tem um slot:
  *
- * ### Quando utilizar
+ * | Área | Slot | Componente sugerido |
+ * | --- | --- | --- |
+ * | Logotipo | `logo` | `br-header-logo` |
+ * | Nome e subtítulo | — | props `caption` e `subcaption` |
+ * | Links | `links` | `br-header-list` com `br-header-link` |
+ * | Atalhos (contraste, ajuda…) | `functions` | `br-header-list` com `br-header-function` |
+ * | Busca | `search` e `search-icon` | `br-input` e um `br-button` com ícone |
+ * | Entrar | `access` | `br-sign-in` |
+ * | Menu | `menu-trigger` | `br-button` que abre o `br-menu` |
  *
- * - **Utilize quando:**
- *   - Desenvolver páginas, portais e sistemas públicos federais que requerem a barra superior padronizada do GovBR-DS.
- *   - For necessário integrar identidade visual, navegação rápida, busca e acesso em uma estrutura consistente.
- * - **Evite e prefira outro componente quando:**
- *   - A navegação for exclusivamente lateral ou contextual interna de uma ferramenta gráfica (prefira `br-menu` ou barras de ferramentas específicas).
+ * ```html
+ * <br-header caption="Nome do sistema" subcaption="Nome do órgão" sticky>
+ *   <br-header-logo slot="logo" src="/logo.svg" description="gov.br"></br-header-logo>
  *
- * ### Composição e Subcomponentes
+ *   <br-header-list slot="links" list-title="Acesso rápido">
+ *     <br-header-link href="/servicos">Serviços</br-header-link>
+ *   </br-header-list>
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-header` | **Orquestrador principal.** Estrutura as áreas superior e inferior, gerencia responsividade e densidade. | Deve ser declarado como elemento raiz do topo da página. |
- * | `br-header-logo` | **Identidade visual.** Exibe o logotipo ou brasão institucional. | Posicionado nos slots `logo` ou `signature` do `br-header`. |
- * | `br-header-list` | **Agrupador de lista.** Contêiner semântico horizontal para links ou funções. | Encaixa-se nos slots `links` ou `functions` do `br-header`. |
- * | `br-header-link` | **Item de link.** Atalho ou hiperlink de navegação institucional. | Deve ser inserido dentro de um `br-header-list` no slot `links`. |
- * | `br-header-function` | **Ação funcional.** Botão de utilidade rápida (contraste, ajuda, etc.). | Deve ser inserido dentro de um `br-header-list` no slot `functions`. |
+ *   <br-input slot="search" label="Buscar" type="search"></br-input>
  *
- * ### Como os subcomponentes se relacionam
+ *   <br-button slot="menu-trigger" shape="circle" aria-label="Abrir menu" data-toggle="menu" data-target="#menu-principal">
+ *     <br-icon src="/icones/menu.svg"></br-icon>
+ *   </br-button>
+ * </br-header>
+ * ```
  *
- * O `br-header` orquestra as áreas da barra através de slots nomeados (`logo`, `signature`, `links`, `functions`, `search`, `access`, `menu-trigger`, `caption`, `subcaption`). Ele observa o tamanho de tela e a densidade configurada, reorganizando os blocos e delegando a exibição correta aos subcomponentes filhos.
+ * Use `sticky` para manter o cabeçalho visível ao rolar a página e `compact` para a versão reduzida. Em telas menores, a busca fica escondida até o clique no botão do slot `search-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/header?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/header?tab=designer).
  *
-
  * @category Estrutura, Navegação, Identidade
  * @status stable
  * @slot logo - Slot para a logo do cabeçalho.
  * @slot signature - Slot para a assinatura visual da organização.
  * @slot links - Slot para links de navegação principais.
  * @slot functions - Slot para botões de ação no cabeçalho.
+ * @slot search-icon - Botão que mostra o campo de busca em telas menores e no modo compacto.
  * @slot search - Slot para o campo de busca.
  * @slot access - Slot para o botão de acesso ou autenticação.
  * @slot menu-trigger - Slot para o botão que abre o menu.
@@ -101,7 +104,7 @@ export declare class Header {
      * @deprecated Use `compact`.
      */
     isCompact: boolean;
-    /** Estado compacto canônico. Quando informado, tem precedência sobre `isCompact`. */
+    /** Estado compacto. Quando informado, tem precedência sobre `isCompact`. */
     compact?: boolean;
     /**
      * Fixa o cabeçalho no topo durante a rolagem.
@@ -165,7 +168,7 @@ export declare class Header {
         parentId: string;
         isCompact: boolean;
     }>;
-    /** Evento canônico emitido quando o modo compacto muda. */
+    /** Evento emitido quando o modo compacto muda. */
     brHeaderCompactChange: EventEmitter<HeaderCompactChangeDetail>;
     /**
      * Evento disparado para indicar qual lista deve encolher primeiro.