@govbr-ds/webcomponents 2.4.0 → 2.5.0

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

@@ -1,22 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * 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.
+ * Lista de itens de navegação dentro do `br-menu` ou `br-menu-group`.
  *
- * ### Para que serve
+ * Insira os elementos `br-menu-item` no slot padrão para compor a lista navegável.
  *
- * - **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`.
  *

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

@@ -1,20 +1,7 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-menu-logo` é o subcomponente do GovBR-DS que renderiza a logomarca do sistema ou do Governo Federal no menu lateral.
+ * Exibe o logotipo institucional no interior do `br-menu`. Use no cabeçalho ou rodapé do menu.
  *
- * ### 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,21 +1,8 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrLinkTarget, BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * 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.
+ * Bloco de canais e redes sociais institucionais dentro do `br-menu`. Use no slot `social` ou rodapé 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 {
@@ -65,7 +52,7 @@ export declare class MenuSocial {
      * @deprecated Use `brMenuSocialClick`.
      */
     brSocialClick: EventEmitter<void>;
-    /** Evento canônico emitido quando o link de rede social é clicado. */
+    /** Evento emitido quando o link de rede social é clicado. */
     brMenuSocialClick: EventEmitter<void>;
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.

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

@@ -1,45 +1,38 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { MenuDensity, MenuOpenChangeDetail } from './menu.types';
 /**
- * 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.
+ * O `br-menu` organiza a navegação lateral da aplicação em gaveta retrátil ou barra fixa.
  *
- * ### Para que serve
+ * Use `is-open` para controlar a visibilidade, ou chame os métodos `open()`, `close()` e `toggle()`. Estruture a navegação com os subcomponentes `br-menu-header`, `br-menu-group`, `br-menu-list` e `br-menu-item`.
  *
- * - **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.
+ * ```html
+ * <br-menu id="menu-principal">
+ *   <div slot="header">
+ *     <br-menu-header title-text="Menu Principal"></br-menu-header>
+ *   </div>
+ *   <br-menu-list>
+ *     <br-menu-item>
+ *       <br-menu-link href="/inicio">Início</br-menu-link>
+ *     </br-menu-item>
+ *     <br-menu-item>
+ *       <br-menu-link href="/servicos">Serviços</br-menu-link>
+ *     </br-menu-item>
+ *   </br-menu-list>
+ * </br-menu>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Menus com hierarquia de seções, grupos ou múltiplos níveis de páginas.
+ * - Navegação lateral que precisa ser recolhida em telas móveis com fechamento por máscara (`br-scrim`).
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | 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`. |
+ * - Poucos itens que cabem diretamente no cabeçalho: use `br-header`.
+ * - Alternar visões na mesma página: use `br-tab`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/menu?tab=designer).
  *
- * 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).
@@ -133,7 +126,7 @@ export declare class Menu {
         isOpen: boolean;
     }>;
     /**
-     * Evento canônico emitido quando o menu abre ou fecha.
+     * Evento emitido quando o menu abre ou fecha.
      * `detail.open` contém o estado concluído e `detail.sourceId` identifica a instância pelo `id` ou `customId`.
      */
     brMenuOpenChange: EventEmitter<MenuOpenChangeDetail>;

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

@@ -1,36 +1,33 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrFeedbackState } from '../global.types';
 /**
- * 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.
+ * O `br-message` apresenta um aviso contextual ou feedback em linha sobre uma operação ou estado do sistema.
  *
- * ### Para que serve
+ * Defina o tipo de mensagem em `state` (`success`, `danger`, `warning` ou `info`). Opcionalmente, adicione um botão para fechar com `closable`.
  *
- * - **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.
+ * ```html
+ * <br-message state="success" message-title="Sucesso">
+ *   Operação realizada com sucesso.
+ * </br-message>
+ * <br-message state="danger" closable>
+ *   Não foi possível salvar os dados. Tente novamente.
+ * </br-message>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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`).
+ * - Feedback sobre uma ação recém-executada na página (salvar, excluir, atualizar).
+ * - Mensagens de erro ou orientação em formulários (no slot `feedback` de inputs).
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * 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.
+ * - Avisos críticos que exigem decisão antes de prosseguir: use `br-modal`.
+ * - Notificações acumuladas em uma central: use `br-notification`.
  *
- * 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).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/message?tab=designer).
  *
-
-
+ * @category Feedback, Conteúdo
+ * @status stable
  * @category Feedback, Conteúdo
  * @status stable
  * @slot default - Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.
@@ -120,7 +117,7 @@ export declare class Message {
      * O valor padrão é 'info'.
      */
     state: BrFeedbackState;
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     feedbackState?: BrFeedbackState;
     /**
      * Define o rótulo acessível usado por tecnologias assistivas.
@@ -130,7 +127,7 @@ export declare class Message {
     /** Evento emitido quando o usuário fecha a mensagem, se closable for true. */
     /** @deprecated Use `brMessageClose`. */
     brDidClose: EventEmitter;
-    /** Evento canônico emitido quando a mensagem é fechada. */
+    /** Evento emitido quando a mensagem é fechada. */
     brMessageClose: EventEmitter<void>;
     disconnectedCallback(): void;
     componentDidLoad(): void;

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

@@ -1,35 +1,32 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { ModalFooterAlign, ModalSize } from './modal.types';
 /**
- * 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.
+ * O `br-modal` abre uma janela de diálogo bloqueadora sobre uma máscara, capturando a atenção imediata da pessoa usuária.
  *
- * ### Para que serve
+ * Controle a abertura com os métodos `open()`, `close()` e `showModal()`. Estruture o conteúdo usando os slots `header`, `default` (corpo) e `footer` (botões de ação).
  *
- * - **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.
+ * ```html
+ * <br-modal title-text="Excluir item">
+ *   <p>Deseja realmente excluir este registro? Esta ação não pode ser desfeita.</p>
+ *   <div slot="footer">
+ *     <br-button emphasis="secondary">Cancelar</br-button>
+ *     <br-button emphasis="primary">Excluir</br-button>
+ *   </div>
+ * </br-modal>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **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).
+ * - Confirmação de ações críticas ou irreversíveis (excluir registro, descartar alterações).
+ * - Formulários curtos e contextuais sem sair da tela atual.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * 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.
+ * - Mensagens informativas que não exigem confirmação: use `br-message`.
+ * - Conteúdos longos com navegação interna: use uma página dedicada.
  *
- * 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).
+ * Consulte as [diretrizes de design 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.

package/dist/types/components/notification/notification-body/notification-body.d.ts

@@ -1,18 +1,8 @@
 /**
- * Subcomponente de corpo da superfície `br-notification`, responsável por agrupar e organizar a lista de itens de notificação.
+ * Corpo do painel de notificações com rolagem independente. Use dentro do `br-notification`.
  *
- * ### Papel na composição
+ * Insira os itens `br-notification-item` no slot padrão.
  *
- * - Atua como contêiner com rolagem independente para a lista de comunicados (`br-notification-item`).
- * - Suporta filtros por abas ou categorias de mensagens (ex.: "Todas", "Não lidas").
- *
- * ### Regra de uso e relacionamento
- *
- * Declarado dentro do slot padrão do `br-notification`, posicionado abaixo do cabeçalho. Ele recebe múltiplos elementos `br-notification-item` em seu interior. Não deve ser usado fora do painel de notificação.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).
- *
-
  * @slot tabs - Navegação por abas quando presente.
  * @slot default - Lista principal de notificações.
  * @slot empty - Conteúdo para estado vazio.

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

@@ -1,20 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Subcomponente de cabeçalho da superfície `br-notification`, responsável pela identificação da área e controles de fechamento.
+ * Cabeçalho da central de notificações com título e botão de fechar. Use no slot `header` do `br-notification`.
  *
- * ### Papel na composição
+ * Defina o título em `title-text`. O botão de fechar emite o fechamento para o painel pai.
  *
- * - Exibe o título da central de notificações, avatar da pessoa autenticada e botão de ação para fechar o painel.
- * - Fornece contexto visual imediato ao abrir a gaveta de notificações.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser utilizado como o elemento inicial dentro do orquestrador `br-notification`. Ele é coordenado pelo painel pai para disparar o evento de fechamento quando o botão de dispensa é acionado. Não deve ser usado fora de um `br-notification`.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).
- *
-
- * @slot avatar - Área para avatar ou elemento visual do usuário.
  * @slot title - Conteúdo customizado do título.
  * @slot subtitle - Conteúdo customizado do subtítulo.
  * @slot actions - Região para botão de fechar ou outras ações contextuais.

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

@@ -1,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { NotificationItemDetail, NotificationItemState } from './notification-item.types';
 /**
- * Subcomponente individual de `br-notification`, utilizado para representar visualmente cada mensagem, aviso ou comunicado do sistema.
+ * Item individual de notificação com título, data e status de leitura. Use dentro do `br-notification-body`.
  *
- * ### Papel na composição
+ * Defina o título em `title-text` e a data em `date`. Use `read` para indicar se o item já foi lido.
  *
- * - Exibe o ícone de status (sucesso, aviso, erro, informação), título do comunicado, data/hora e texto explicativo.
- * - Suporta indicação visual de lida/não lida e botões de ação específicos (ex.: "Ver detalhes", "Arquivar").
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado dentro do contêiner `br-notification-body` (ou no slot padrão do `br-notification`). Comunica interações da pessoa usuária (clique no item, dispensa) através de eventos emitidos para a aplicação.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).
- *
-
- * @slot status - Região para tag, badge ou marcador visual de status.
- * @slot title - Conteúdo customizado do título.
- * @slot meta - Região para informação cronológica ou metadados.
  * @slot default - Conteúdo principal da notificação.
  * @slot actions - Ações contextuais do item.
  */

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

@@ -1,41 +1,32 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { NotificationCloseDetail, NotificationCloseReason, NotificationItemClickDetail, NotificationPlacement } from './notification.types';
 /**
- * O componente `br-notification` é o painel oficial do GovBR-DS para centralização e exibição de avisos, comunicados e notificações do sistema, tipicamente acionado a partir de um botão com ícone de sino no cabeçalho.
+ * O `br-notification` organiza a central de mensagens, comunicados e avisos do usuário em um painel retrátil.
  *
- * ### Para que serve
+ * Use os métodos `open()`, `close()` ou a propriedade `isOpen` para controlar o painel. Estruture o conteúdo com `br-notification-header`, `br-notification-body` e `br-notification-item`.
  *
- * - **Central de notificações do usuário:** Reúne em uma única gaveta ou painel suspenso todas as mensagens, lembretes e alertas direcionados à pessoa usuária.
- * - **Estruturação por abas e contexto:** Permite organizar notificações por abas (ex.: "Todas", "Não lidas", "Arquivadas") com ações rápidas (marcar como lida, excluir).
- * - **Gerenciamento de abertura e foco:** Controla abertura, fechamento, tecla Escape e foco acessível.
+ * ```html
+ * <br-notification>
+ *   <div slot="header">
+ *     <br-notification-header title-text="Notificações"></br-notification-header>
+ *   </div>
+ *   <br-notification-body>
+ *     <br-notification-item title-text="Seu processo foi atualizado" date="10/10/2026"></br-notification-item>
+ *   </br-notification-body>
+ * </br-notification>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - O sistema gerar eventos e comunicados assíncronos que a pessoa usuária precise consultar a qualquer momento.
- * - **Evite e prefira outro componente quando:**
- *   - A mensagem for uma resposta imediata a uma ação na tela atual (prefira `br-message`).
- *   - O aviso exigir confirmação bloqueadora antes de continuar (prefira `br-modal`).
+ * - Central de avisos acumulados da aplicação, normalmente acionada por um botão no cabeçalho.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-notification` | **Orquestrador principal.** Gerencia a superfície flutuante, estado de visibilidade e foco. | Contêiner raiz obrigatório. |
- * | `br-notification-header` | **Cabeçalho do painel.** Exibe o título, avatar do usuário, contadores e botão de fechar. | Declarado no slot `header` ou topo do `br-notification`. |
- * | `br-notification-body` | **Corpo principal.** Contém a listagem das notificações e abas de filtro opcionais. | Declarado no slot padrão do `br-notification`. |
- * | `br-notification-item` | **Notificação individual.** Representa cada mensagem com ícone, data, texto e ações. | Declarado dentro do `br-notification-body`. |
+ * - Mensagens em linha como resposta direta a uma ação na tela: use `br-message`.
+ * - Confirmação de ação crítica: use `br-modal`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/notification?tab=designer).
  *
- * O `br-notification` projeta o painel suspenso:
- * 1. O cabeçalho (`br-notification-header`) contextualiza o painel e fornece o botão de dispensa.
- * 2. O corpo (`br-notification-body`) agrupa e organiza a coleção de itens (`br-notification-item`).
- * 3. Cada item (`br-notification-item`) expõe eventos de clique e ações individuais (como marcar como lida).
- *
- * 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/notification?tab=designer).
- *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot trigger - Elemento acionador externo responsável por abrir e fechar o painel.

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

@@ -1,33 +1,25 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { PaginationColorMode, PaginationDensity, PaginationPageChangeDetail, PaginationPerPageChangeDetail, PaginationVariant } from './pagination.types';
 /**
- * O componente `br-pagination` é o controle de navegação paginada do GovBR-DS, desenvolvido para segmentar grandes volumes de dados ou conteúdos extensos em páginas sequenciais numeradas.
+ * O `br-pagination` divide grandes volumes de dados em páginas numeradas sequenciais.
  *
- * ### Para que serve
+ * Informe a quantidade total de itens em `total` e a página atual em `current`. Ouça o evento `brPaginationPageChange` para carregar a página solicitada. Para permitir alterar itens por página, use a variante contextual ou defina `per-page`.
  *
- * - **Segmentação de dados volumosos:** Divide listas, tabelas e catálogos em blocos gerenciáveis de itens, reduzindo o tempo de carregamento da página e o consumo de memória.
- * - **Navegação direta e sequencial:** Oferece botões para avançar, retroceder, ir diretamente a uma página específica e navegar através de atalhos de reticências.
- * - **Variante contextual completa:** Permite alterar a quantidade de itens exibidos por página (ex.: 10, 20, 50, 100 itens) e pular diretamente para qualquer página através de campo de digitação integrado.
+ * ```html
+ * <br-pagination total="100" per-page="10" current="1"></br-pagination>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - O número total de itens for superior ao limite recomendado para visualização em uma única rolagem (geralmente mais de 20 a 50 registros).
- *   - Integrar com tabelas de dados (`br-table`) ou grades de cartões (`br-card`).
- * - **Evite e prefira outro componente quando:**
- *   - O conjunto completo de itens for pequeno (menos de 20 itens) e puder ser visualizado sem perda de performance.
- *   - A navegação representar etapas interdependentes de um processo sequencial com validação (prefira `br-step` ou `br-wizard`).
+ * - Paginação de tabelas (`br-table`) ou listas extensas.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-pagination` disponibiliza slots para complementar a navegação:
- * - `pagination-info`: Slot para customização do texto de contagem (ex.: "Exibindo 1-20 de 240 itens").
- * - `loading`: Slot para indicador visual exibido durante a troca assíncrona de páginas.
+ * - Poucos itens (menos de 20 itens) que cabem em uma visualização direta.
+ * - Etapas sequenciais de um formulário ou cadastro: use `br-step` ou `br-wizard`.
  *
- * 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/pagination?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/pagination?tab=designer).
  *
-
-
  * @category Navegação, Dados, Progresso
  * @status stable
  *
@@ -195,7 +187,7 @@ export declare class Pagination {
      */
     pageChange: EventEmitter<PaginationPageChangeDetail>;
     /**
-     * Evento canônico para iniciar o carregamento de uma página.
+     * Evento para iniciar o carregamento de uma página.
      * O `detail` contém `{ page }`; o evento não é cancelável.
      */
     brPaginationPageChange: EventEmitter<PaginationPageChangeDetail>;
@@ -205,7 +197,7 @@ export declare class Pagination {
      */
     perPageChange: EventEmitter<PaginationPerPageChangeDetail>;
     /**
-     * Evento canônico para iniciar o carregamento de uma nova quantidade de
+     * Evento para iniciar o carregamento de uma nova quantidade de
      * itens. O `detail` contém `{ perPage }`; o evento não é cancelável.
      */
     brPaginationPerPageChange: EventEmitter<PaginationPerPageChangeDetail>;

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

@@ -3,31 +3,28 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { RadioValidator } from './radio.types';
 /**
- * O componente `br-radio` é o controle de formulário do GovBR-DS para seleção de uma única opção dentro de um conjunto mutuamente exclusivo. Compatível com as diretrizes WAI-ARIA, ele integra-se nativamente a formulários HTML via `formAssociated`.
+ * O `br-radio` representa uma opção individual dentro de um conjunto de escolha única.
  *
- * ### Para que serve
+ * Defina `name` para associar as opções do mesmo grupo, `value` para o valor enviado no formulário e `label` para o texto exibido.
  *
- * - **Escolha exclusiva:** Permite que a pessoa usuária escolha exatamente uma alternativa entre as opções apresentadas no mesmo grupo.
- * - **Integração com formulários:** Comunica valor, estado de seleção (`checked`), desativação e validação diretamente com a API nativa de formulários HTML (`ElementInternals`).
- * - **Navegação acessível:** Suporta foco e seleção via teclado (teclas de seta e barra de espaço) quando agrupado.
+ * ```html
+ * <br-radio name="preferencia" value="email" label="Receber por e-mail" checked></br-radio>
+ * <br-radio name="preferencia" value="sms" label="Receber por SMS"></br-radio>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, integra-se nativamente via `ElementInternals` com suporte a `required`.
  *
- * - **Utilize quando:**
- *   - Houver um conjunto pequeno de opções (entre 2 e 5 alternativas) mutuamente exclusivas e for importante manter todas as opções imediatamente visíveis.
- * - **Evite e prefira outro componente quando:**
- *   - O número de opções for superior a 5 ou 7 itens: prefira `br-select` para economizar espaço de tela.
- *   - A pessoa usuária puder selecionar múltiplas opções simultaneamente: prefira `br-checkbox` ou `br-checkbox-group`.
- *   - Houver uma escolha binária simples de ativação/desativação imediata: prefira `br-switch`.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Opção única em grupos pequenos de 2 a 5 alternativas.
  *
- * O `br-radio` é um controle individual:
- * - `default`: Slot para o texto do rótulo da opção (alternativa à propriedade `label`).
+ * ### 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/radio?tab=designer).
+ * - Mais de 5 opções: use `br-select`.
+ * - Seleção múltipla: use `br-checkbox`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/radio?tab=designer).
  *
-
  * @category Formulários, Seleção
  * @status stable
  * @see br-radio-group
@@ -101,7 +98,7 @@ export declare class Radio {
      * Se não for especificado, o valor padrão é `null`, indicando que a validade não foi definida.
      */
     readonly state: 'valid' | 'invalid';
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     readonly feedbackState?: 'valid' | 'invalid';
     /**
      * Define se o label associado ao radio deve ser oculto.

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

@@ -3,32 +3,32 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { RadioGroupOrientation, RadioGroupValidator } from './radio-group.types';
 /**
- * O componente `br-radio-group` é o contêiner semântico e orquestrador de opções `br-radio` no GovBR-DS, responsável por garantir a exclusividade mútua de seleção, a navegação contínua por teclado e a validação integrada do grupo.
+ * O `br-radio-group` agrupa opções de múltipla escolha onde apenas uma pode ser selecionada.
  *
- * ### Para que serve
+ * Adicione os elementos `br-radio` no slot padrão. Defina o rótulo do grupo em `label` e o valor selecionado em `value`.
  *
- * - **Coordenação de seleção mútua:** Garante que apenas um botão de rádio permaneça selecionado por vez entre todos os rádios filhos.
- * - **Navegação acessível por teclado WAI-ARIA:** Implementa o padrão de navegação com setas direcionais (cima/baixo/esquerda/direita) com foco cíclico dentro do grupo.
- * - **Agrupamento semântico:** Estrutura o grupo com a semântica de `radiogroup`, fornecendo rótulo acessível para tecnologias assistivas.
- * - **Associação com formulários:** Atua como controle integrado (`formAssociated`), emitindo o valor consolidado selecionado para o formulário pai.
+ * ```html
+ * <br-radio-group label="Turno de atendimento" name="turno">
+ *   <br-radio value="manha" label="Manhã"></br-radio>
+ *   <br-radio value="tarde" label="Tarde"></br-radio>
+ *   <br-radio value="noite" label="Noite"></br-radio>
+ * </br-radio-group>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o grupo integra-se via `ElementInternals`, controlando validação nativa com `required`.
  *
- * - **Utilize quando:**
- *   - Apresentar um conjunto de 2 a 5 alternativas mutuamente exclusivas onde todas as opções devam ser comparadas lado a lado ou em lista vertical.
- * - **Evite e prefira outro componente quando:**
- *   - Houver muitas alternativas (mais de 5 a 7 opções): prefira `br-select`.
- *   - A seleção permitir múltiplas alternativas independentes: prefira `br-checkbox-group`.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Entre 2 e 5 opções mutuamente exclusivas que devem permanecer visíveis.
  *
- * O `br-radio-group` é um orquestrador de seleção:
- * - `default`: Slot onde devem ser declarados os componentes filhos `br-radio`.
- * - `label`: Slot para personalização do rótulo ou enunciado da pergunta do grupo.
+ * ### 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/radio-group?tab=designer).
+ * - Mais de 6 opções: use `br-select` para economizar espaço de tela.
+ * - Seleção de múltiplas opções ao mesmo tempo: use `br-checkbox-group`.
+ * - Liga/desliga imediato: use `br-switch`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/radio-group?tab=designer).
  *
-
  * @category Formulários, Seleção
  * @see br-radio
  * @slot default - Radios pertencentes ao grupo.