@govbr-ds/webcomponents 2.1.3 → 2.3.0

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,10 +82,16 @@ 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;
+    /**
+     * Devolve o foco ao elemento que abriu o modal. Sem esse alvo (ex.: modal aberto por
+     * `show` inicial ou foco anterior no body), libera o foco que ainda estiver no conteúdo
+     * sendo ocultado, para que a digitação não continue num campo invisível.
+     */
+    private returnFocusOnClose;
     /**
      * Evento emitido quando o modal é aberto (quando `show` muda de `false` para `true`).
      */
@@ -200,6 +234,8 @@ export declare class Modal {
     private handleParentScrimClose;
     private openParentScrim;
     private getCssClassMap;
+    private get effectiveSize();
+    private get effectiveAlignFooter();
     private handleClose;
     private handleNativeCancel;
     render(): any;

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

@@ -1,9 +1,18 @@
 /**
- * ## Design System
+ * Subcomponente de corpo da superfície `br-notification`, responsável por agrupar e organizar a lista de itens de notificação.
  *
- * Subcomponente `br-notification-body`: representa a região principal do painel de notificações,
- * organizando abas, lista e eventuais estados vazios.
+ * ### Papel na composiçã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,10 +1,19 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * ## Design System
+ * Subcomponente de cabeçalho da superfície `br-notification`, responsável pela identificação da área e controles de fechamento.
  *
- * Subcomponente `br-notification-header`: representa a região superior do painel de notificações,
- * responsável por agrupar dados do usuário, título contextual e botão de fechar.
+ * ### Papel na composição
  *
+ * - 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.

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

@@ -1,11 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { NotificationItemDetail, NotificationItemState } from './notification-item.types';
 /**
- * ## Design System
+ * Subcomponente individual de `br-notification`, utilizado para representar visualmente cada mensagem, aviso ou comunicado do sistema.
  *
- * Subcomponente `br-notification-item`: representa uma entrada individual de notificação.
- * Respeita a organização visual e os estados interativos equivalentes ao componente `item` do design system.
+ * ### Papel na composição
  *
+ * - 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.
@@ -43,8 +52,11 @@ export declare class NotificationItem {
     clickable: boolean;
     /**
      * Define o estado visual da notificação.
+     * Aceita `success`, `danger`, `warning` ou `info`.
+     * Valores inválidos são ignorados.
      */
     state?: NotificationItemState;
+    private get effectiveState();
     /**
      * Informa seleção ou acionamento do item.
      */

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

@@ -1,12 +1,42 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { NotificationCloseDetail, NotificationCloseReason, NotificationItemClickDetail, NotificationPlacement } from './notification.types';
 /**
- * ## Design System
+ * 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.
  *
- * 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/notification?tab=designer).
+ * ### Para que serve
  *
- * @category Feedback
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | 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`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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.
  * @slot header - Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado.
@@ -64,7 +94,7 @@ export declare class Notification {
      */
     readonly internalScroll: boolean;
     /**
-     * Define o posicionamento do painel em relação ao acionador.
+     * Define o posicionamento do painel em relação ao acionador. Valores inválidos usam `bottom-end`.
      */
     readonly placement: NotificationPlacement;
     /**
@@ -157,6 +187,7 @@ export declare class Notification {
     private readonly getTriggerElements;
     private readonly updateTriggerAria;
     private readonly getCssClassMap;
+    private get effectivePlacement();
     private readonly checkSlotVisibility;
     render(): any;
 }

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

@@ -1,9 +1,34 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { PaginationColorMode, PaginationDensity, PaginationPageChangeDetail, PaginationPerPageChangeDetail, PaginationVariant } from './pagination.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/pagination?tab=designer).
+ * 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.
  *
- * @category Navegação
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Estrutura e Slots
+ *
+ * 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.
+ *
+ * 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).
+ *
+
+
+ * @category Navegação, Dados, Progresso
  * @status stable
  *
  * @slot pagination-info - Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído.
@@ -17,16 +42,19 @@ import type { PaginationColorMode, PaginationDensity, PaginationPageChangeDetail
  * @part per-page - Parte para o seletor de itens por página na variante contextual.
  * @part per-page-container - Contêiner encaminhado do seletor de itens por página.
  * @part per-page-input - Campo encaminhado do seletor de itens por página.
+ * @part per-page-input-label - Rótulo encaminhado do seletor de itens por página.
  * @part per-page-list - Lista encaminhada do seletor de itens por página.
  * @part go-to - Parte para o seletor de navegação direta na variante contextual.
  * @part go-to-container - Contêiner encaminhado do seletor de navegação direta.
  * @part go-to-input - Campo encaminhado do seletor de navegação direta.
+ * @part go-to-input-label - Rótulo encaminhado do seletor de navegação direta.
  * @part go-to-list - Lista encaminhada do seletor de navegação direta.
  * @part prev-button - Parte para o botão de página anterior, usada para estilização via ::part().
  * @part prev-button-inner - Botão interno encaminhado da página anterior.
  * @part next-button - Parte para o botão de próxima página, usada para estilização via ::part().
  * @part next-button-inner - Botão interno encaminhado da próxima página.
  * @part loading - Área do indicador de carregamento.
+ *
  */
 export declare class Pagination {
     private static readonly ELLIPSIS_VISIBLE_ITEMS;
@@ -55,7 +83,7 @@ export declare class Pagination {
      */
     private ellipsisItemHeight;
     /**
-     * Define se a paginação usará um esquema de cores escuro.
+     * Define se a paginação usará um esquema de cores escuro. Valores inválidos são ignorados.
      * Quando definido como `dark`, aplica a classe `dark-mode` ao container principal.
      */
     colorMode?: PaginationColorMode;
@@ -63,22 +91,18 @@ export declare class Pagination {
      * Identificador único do componente.
      * Quando omitido, um valor é gerado automaticamente.
      *
-     * > **Padrão:** valor único gerado por Helpers.generateUniqueId().
+     * > **Padrão:** valor único gerado por `generateUniqueId()`.
      *
      * > **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`.
      */
     customId: string;
-    /**
-     * Quantidade total de páginas (mínimo 1).
-     */
+    /** Quantidade total de páginas (inteiro mínimo 1). Valores inválidos usam 1. */
     total: number;
-    /** Quantidade total de páginas. Tem precedência sobre `total`. */
+    /** Quantidade total de páginas. Tem precedência sobre `total`; valores inválidos usam 1. */
     totalPages?: number;
-    /**
-     * Página atual (1-indexada). Valores fora do intervalo serão ajustados.
-     */
+    /** Página atual (inteira e 1-indexada). Valores inválidos usam 1; valores fora do intervalo são ajustados. */
     current: number;
-    /** Página atual. Tem precedência sobre `current`. */
+    /** Página atual. Tem precedência sobre `current`; valores inválidos usam 1. */
     currentPage?: number;
     /**
      * Define o rótulo acessível usado por tecnologias assistivas.
@@ -106,10 +130,11 @@ export declare class Pagination {
      * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
      *
      * > **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `density`.
+     * Valores inválidos usam `medium`.
      */
     density: PaginationDensity;
     /**
-     * Variante de renderização do componente.
+     * Variante de renderização do componente. Valores inválidos usam `default`.
      * - `default`: paginação numérica (padrão)
      * - `contextual`: paginação contextual com seletores e informação de itens
      */
@@ -127,16 +152,19 @@ export declare class Pagination {
      * @default false
      */
     loading: boolean;
-    /**
-     * Total de itens (aplicável na variante contextual).
-     */
+    /** Total de itens (inteiro não negativo, aplicável na variante contextual). Valores inválidos usam 0. */
     totalItems?: number;
-    /**
-     * Itens por página (aplicável na variante contextual).
-     */
+    /** Itens por página (inteiro positivo, aplicável na variante contextual). Valores inválidos usam 10. */
     perPage: number;
     /**
-     * Opções disponíveis de itens por página (variante contextual).
+     * Opções disponíveis de itens por página na variante `contextual`.
+     * Passe o array por property binding; atributos HTML não representam arrays.
+     *
+     * @example
+     * ```js
+     * const pagination = document.querySelector('br-pagination');
+     * pagination.perPageOptions = [10, 25, 50, 100];
+     * ```
      */
     perPageOptions: number[];
     /**
@@ -210,7 +238,17 @@ export declare class Pagination {
     private setupMediaQuery;
     private cleanupMediaQuery;
     private getCssClassMap;
+    private get effectiveDensity();
+    private get effectiveColorMode();
+    private get effectiveVariant();
+    private get effectiveTotal();
+    private get effectiveTotalPages();
+    private get effectiveCurrentPage();
+    private get effectiveTotalItems();
+    private get effectivePerPage();
+    private get effectivePerPageOptions();
     private getDefaultTotalPages;
+    private get effectiveCurrent();
     private clampPage;
     private goTo;
     private handlePrevClick;

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

@@ -3,12 +3,34 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { RadioValidator } from './radio.types';
 /**
- * ## Design System
+ * 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`.
  *
- * 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/radio?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`.
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-radio` é um controle individual:
+ * - `default`: Slot para o texto do rótulo da opção (alternativa à propriedade `label`).
+ *
+ * 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).
+ *
+
+ * @category Formulários, Seleção
  * @status stable
+ * @see br-radio-group
  * @slot default - Slot para o rótulo do rádio, como alternativa à propriedade label.
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  *
@@ -38,11 +60,18 @@ export declare class Radio {
     groupManaged: boolean;
     groupDisabled: boolean;
     groupTabIndex: number;
+    groupNativeName: string;
     /**
      * Define o estado de seleção do radio.
      * Se definido como verdadeiro, o radio estará marcado. Caso contrário, estará desmarcado.
      */
     checked: boolean;
+    /**
+     * Permite desmarcar o radio ao clicar novamente sobre ele quando já estiver selecionado.
+     * Por padrão, um radio selecionado permanece marcado ao receber um novo clique.
+     * Quando usada junto com `uncheckOnDoubleClick`, esta opção tem precedência.
+     */
+    readonly uncheckOnClick: boolean;
     /**
      * Permite desmarcar o radio ao clicar duas vezes sobre ele.
      * Por padrão, um radio selecionado permanece marcado ao receber um segundo clique.
@@ -56,7 +85,16 @@ export declare class Radio {
      * Se verdadeiro, o radio é obrigatório e uma opção deve ser selecionada antes que o formulário possa ser enviado.
      */
     readonly required: boolean;
-    /** Regra síncrona ou assíncrona aplicada ao estado booleano do radio. */
+    /**
+     * Regra síncrona ou assíncrona aplicada ao estado booleano do radio.
+     * Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
+     *
+     * @example
+     * ```js
+     * const radio = document.querySelector('br-radio');
+     * radio.validator = (checked) => checked ? null : 'Selecione esta opção';
+     * ```
+     */
     readonly validator?: RadioValidator;
     /**
      * Indica a validade do radio.
@@ -94,10 +132,14 @@ export declare class Radio {
      */
     readonly value: string;
     checkedChanged(): void;
+    disabledChanged(): void;
+    valueChanged(): void;
+    private dispatchInternalStateChange;
     handleRadioGroupState(event: CustomEvent<{
         managed: boolean;
         disabled: boolean;
         tabIndex: number;
+        nativeName?: string;
     }>): void;
     /**
      * Disparado depois que o valor do `checked` foi alterado.
@@ -159,9 +201,11 @@ export declare class Radio {
     private syncFormState;
     private isDisabled;
     private isManagedByGroup;
+    private getNativeName;
     private isStandalonePeer;
     private updateValidity;
     private getCssClassMap;
+    private get effectiveState();
     /**
      * Handler para o event `click`
      * @param event Objeto Event
@@ -173,6 +217,7 @@ export declare class Radio {
      */
     private readonly onChange;
     handleDoubleClick(): void;
+    private uncheck;
     private computeTabIndex;
     private syncGroupTabStops;
     render(): any;