@govbr-ds/webcomponents 2.1.2 → 2.2.0

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

@@ -1,10 +1,34 @@
 /**
- * ## Design System
+ * O componente `br-checkbox-group` é o contêiner semântico e orquestrador de múltiplos controles `br-checkbox` que pertencem a um mesmo contexto ou pergunta em formulários do GovBR-DS.
  *
- * 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/checkgroup?tab=designer).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **Agrupamento semântico e acessibilidade:** Cria a estrutura recomendada de `fieldset` e `legend` para leitores de tela, garantindo que o contexto da pergunta seja anunciado antes de cada opção individual.
+ * - **Validação conjunta:** Permite coordenar regras de validação em grupo (como exigir uma quantidade mínima ou máxima de checkboxes selecionados).
+ * - **Alinhamento e padronização visual:** Organiza os checkboxes vertical ou horizontalmente conforme o leiaute da interface.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - Existirem duas ou mais opções em checkbox que respondem à mesma pergunta ou pertencem ao mesmo conjunto lógico de preferências.
+ *   - For necessário aplicar rótulo geral e mensagens de validação ao grupo completo de escolhas.
+ * - **Evite e prefira outro componente quando:**
+ *   - Houver apenas um único checkbox independente (ex.: aceite de termos): use `br-checkbox` isoladamente.
+ *   - A seleção for de escolha única (mutuamente exclusiva): use `br-radio-group`.
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-checkbox-group` atua como container orquestrador:
+ * - `default`: Slot onde devem ser inseridos os elementos `br-checkbox` que compõem o grupo.
+ * - `feedback`: Slot opcional para mensagem de erro ou orientação de validação associada ao grupo todo.
+ *
+ * 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/checkgroup?tab=designer).
+ *
+
+ * @category Formulários, Seleção
  * @status stable
+ * @see br-checkbox
+ * @see br-checkgroup
  * @slot default - Slot para adicionar os checkboxes controlados pelo grupo.
  */
 export declare class CheckboxGroup {
@@ -14,6 +38,8 @@ export declare class CheckboxGroup {
     checked: boolean;
     /** Estado indeterminado do controlador do grupo. */
     isIndeterminate: boolean;
+    /** Desabilita o controlador e os checkboxes contidos no grupo. */
+    readonly disabled: boolean;
     /** Texto descritivo do grupo. */
     label?: string;
     /** Rótulo para desmarcar todos os checkboxes. */
@@ -22,24 +48,40 @@ export declare class CheckboxGroup {
     selectAllLabel: string;
     /** Define o estado indeterminado inicial do grupo. */
     indeterminate: boolean;
-    /** Orientação visual das opções. */
+    /** Orientação visual das opções. Valores inválidos usam `vertical`. */
     readonly orientation: 'horizontal' | 'vertical';
     /** Identificador único do controlador. */
     readonly customId: string;
     private syncingChildren;
+    private controller?;
+    private structureObserver?;
+    private managedChildren;
+    private readonly reconciler;
     componentWillLoad(): void;
     componentDidLoad(): void;
     disconnectedCallback(): void;
-    handleChildChange(event: CustomEvent<boolean>): void;
+    handleDisabledChange(): void;
+    handleChildChange(event?: CustomEvent<boolean>): Promise<void>;
+    handleInternalChildStateChange(event: Event): void;
     private readonly handleSlotChange;
+    private readonly handleStructureChange;
+    private dispatchGroupState;
+    private syncManagedChildren;
+    private releaseManagedChildren;
     private getSlotElement;
     private getChildCheckboxes;
     private getEventCheckboxTarget;
     private isParentCheckbox;
+    private isCheckboxDisabledOrReadonly;
+    private isCheckboxChecked;
+    private isCheckboxIndeterminate;
     private readonly handleParentChange;
     private updateGroupState;
+    componentDidUpdate(): void;
+    private syncControllerState;
     private setParentState;
     private setNumberOfChildren;
     private getCssClassMap;
+    private get effectiveOrientation();
     render(): any;
 }

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

@@ -1,19 +1,39 @@
 /**
- * @category Formulários
+ * O componente `br-checkgroup` é o alias legado mantido para compatibilidade com versões anteriores da biblioteca.
+ *
+ * ### Papel na biblioteca
+ *
+ * - Atua como um redirecionador direto para a implementação do `br-checkbox-group`.
+ * - Permite que aplicações já existentes mantenham o funcionamento sem interrupções enquanto realizam a transição gradativa.
+ *
+ * ### Regra de uso e migração
+ *
+ * Em novos projetos e manutenções ativas, **utilize sempre a tag canônica `br-checkbox-group`**. O uso de `br-checkgroup` está depreciado e deve ser substituído pela tag oficial.
+ *
+ * Para a documentação canônica completa, consulte a página do [br-checkbox-group](/docs/components/checkbox-group).
+ *
+
+ * @category Formulários, Seleção
  * @status deprecated
+ * @see br-checkbox-group
  * @slot default - Slot para adicionar os checkboxes controlados pelo grupo.
  * @deprecated Use `br-checkbox-group`.
  */
 export declare class Checkgroup {
+    el: HTMLElement;
     /** Texto descritivo do grupo. */
     label?: string;
-    /** Rótulo legado para desmarcar todos. */
-    /** @deprecated Use `unselectAllLabel`. */
+    /**
+     * Rótulo legado para desmarcar todos.
+     * @deprecated Use `unselectAllLabel`.
+     */
     labelSelecionado?: string;
     /** Rótulo para desmarcar todos. */
     unselectAllLabel?: string;
-    /** Rótulo legado para marcar todos. */
-    /** @deprecated Use `selectAllLabel`. */
+    /**
+     * Rótulo legado para marcar todos.
+     * @deprecated Use `selectAllLabel`.
+     */
     labelDesselecionado?: string;
     /** Rótulo para marcar todos. */
     selectAllLabel?: string;
@@ -21,5 +41,7 @@ export declare class Checkgroup {
     indeterminate: boolean;
     /** Identificador legado do controlador. */
     readonly customId?: string;
+    /** Desabilita o controlador e os checkboxes contidos no grupo. */
+    readonly disabled: boolean;
     render(): any;
 }

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

@@ -1,10 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CollapseChangeDetail, CollapseColorMode, CollapseExpansionDirection, CollapseIconPosition, CollapseTriggerVariant } from './collapse.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/collapse?tab=designer).
+ * O componente `br-collapse` é o controle retrátil do GovBR-DS baseado no elemento semântico HTML5 `<details>`, desenvolvido para permitir que a pessoa usuária expanda ou recolha seções de conteúdo sob demanda.
  *
- * @category Conteúdo
+ * ### Para que serve
+ *
+ * - **Otimização de espaço e hierarquia:** Reduz a sobrecarga de informação inicial na tela, ocultando blocos secundários até que o usuário decida visualizá-los.
+ * - **Estruturação de perguntas e respostas:** Padrão oficial para construção de seções de FAQ (perguntas frequentes) e listas explicativas sanfonadas (accordion).
+ * - **Acessibilidade nativa:** Por utilizar internamente os elementos `<details>` e `<summary>`, possui controle total de teclado, estado acessível (`open`) e anúncios para tecnologias assistivas sem exigir scripts adicionais complexos.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - O conteúdo for extenso, dividido em tópicos independentes e a maioria dos usuários só precisa consultar itens específicos.
+ *   - Houver seções complementares opcionais em um formulário longo.
+ * - **Evite e prefira outro componente quando:**
+ *   - A informação contida for crítica para a tomada de decisão imediata ou segurança da pessoa usuária (ela deve ficar permanentemente visível).
+ *   - A intenção for alternar entre diferentes visões de uma mesma tela completa (prefira `br-tab`).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-collapse` organiza o acionamento e a área expansível:
+ * - `trigger`: Slot para personalizar o botão/gatilho de expansão (texto, ícones ou componentes de apoio dentro do summary).
+ * - `default`: Slot para inserção do conteúdo que é revelado quando o componente é expandido.
+ *
+ * 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/collapse?tab=designer).
+ *
+
+ * @category Conteúdo, Ações
  * @status stable
+ * @see br-list
  * @slot default - Slot para o conteúdo expansível exibido ao abrir o collapse.
  * @slot trigger - Slot para personalizar o acionador (texto, ícones, imagens, etc.).
  *
@@ -42,11 +67,11 @@ export declare class Collapse {
      */
     accordionGroup?: string;
     /**
-     * Classe CSS do ícone exibido quando o conteúdo está oculto.
+     * Identificador do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local.
      */
     iconToShow: string;
     /**
-     * Classe CSS do ícone exibido quando o conteúdo está visível.
+     * Identificador do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local.
      */
     iconToHide: string;
     /**
@@ -71,6 +96,10 @@ export declare class Collapse {
      * @default 'surface'
      */
     triggerVariant: CollapseTriggerVariant;
+    private get effectiveColorMode();
+    private get effectiveExpansionDirection();
+    private get effectiveIconPosition();
+    private get effectiveTriggerVariant();
     /**
      * Emitido ao expandir, com o identificador e o grupo de accordion.
      */

package/dist/types/components/cookiebar/cookiebar-cookie/cookiebar-cookie.d.ts

@@ -1,9 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Representa um cookie individual dentro de um `br-cookiebar-group`.
- * Exibe os detalhes do cookie (nome, vencimento, domínio etc.) e,
- * quando o cookie pode ser desativado, um switch de ativação.
+ * O componente `br-cookiebar-cookie` é o subcomponente do GovBR-DS que descreve as especificações técnicas de um cookie individual.
  *
+ * ### Para que serve
+ *
+ * - **Transparência técnica:** Detalha nome, validade, finalidade e fornecedor do cookie.
+ * - **Esclarecimento ao cidadão:** Oferece visibilidade granular sobre cada elemento de persistência.
+ *
+ * ### Papel na composição
+ *
+ * Atua como item folha descritivo na listagem de cookies.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser utilizado exclusivamente dentro de um `br-cookiebar-group`.
+ * - Não deve ser utilizado fora do ecossistema de gestão de cookies.
+ *
+
  * @slot default - Área livre para inserir conteúdo personalizado abaixo dos itens do cookie.
  *
  * @part card - Container principal do cookie.

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

@@ -1,14 +1,23 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { CookiebarSelectionState } from '../cookiebar.types';
 /**
- * Representa um grupo (classe) de cookies dentro do `br-cookiebar`.
- * Agrupa cookies relacionados, exibe um checkbox para seleção coletiva
- * e permite expandir a lista de `br-cookiebar-cookie` filhos.
+ * O componente `br-cookiebar-group` é o subcomponente do GovBR-DS que representa uma categoria de cookies (ex.: necessários, desempenho, marketing) acompanhada de um controle de seleção (switch ou checkbox).
  *
- * Suporta dois modos:
- * - **Opt-out** (`group-opt-out="true"`, padrão): o usuário pode desativar o grupo.
- * - **Sempre ativo** (`group-opt-out="false"`): exibe badge fixo, sem checkbox.
+ * ### Para que serve
  *
+ * - **Segmentação por finalidade:** Organiza os cookies conforme o tipo e necessidade técnica.
+ * - **Controle de consentimento:** Permite habilitar ou desabilitar categorias não obrigatórias.
+ *
+ * ### Papel na composição
+ *
+ * Atua como contêiner de agrupamento intermediário dentro do `br-cookiebar`, contendo instâncias de `br-cookiebar-cookie`.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser utilizado dentro do corpo de configuração do `br-cookiebar`.
+ * - Recebe elementos filhos do tipo `br-cookiebar-cookie`.
+ *
+
  * @slot default - Recebe os subcomponentes `br-cookiebar-cookie` do grupo.
  *
  * @part container - Div raiz do grupo.

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

@@ -1,15 +1,21 @@
 /**
- * Cabeçalho introdutório do painel aberto do `br-cookiebar`.
- * Exibe o título da política de cookies, a data da última atualização e um texto de introdução.
+ * O componente `br-cookiebar-header` é o subcomponente de topo do GovBR-DS que apresenta o título e o texto introdutório do aviso de cookies.
  *
- * Pode ser usado de duas formas:
- * - **Estruturada** (padrão): informe `main-title`, `entry-text` e opcionalmente `last-update`
- *   para renderizar o cabeçalho com o layout oficial do Design System.
- * - **Livre**: insira conteúdo HTML no slot default e ele substituirá completamente o layout
- *   interno, mantendo apenas o container estilizado.
+ * ### Para que serve
  *
- * Deve ser inserido no slot `header` do `br-cookiebar`.
+ * - **Apresentação do contexto:** Explica resumidamente a finalidade do aviso de privacidade.
+ * - **Identificação visual:** Fornece o cabeçalho padronizado da barra de cookies.
  *
+ * ### Papel na composição
+ *
+ * Atua como elemento introdutório estrutural do `br-cookiebar`.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser posicionado no slot de cabeçalho do `br-cookiebar`.
+ * - Não deve ser utilizado de forma independente fora do aviso de cookies.
+ *
+
  * @slot default - Conteúdo HTML personalizado que substitui o layout estruturado.
  *   Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas.
  *

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

@@ -1,13 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * Link complementar exibido na área de rodapé do `br-cookiebar`.
- * Use dentro do slot `links` do `br-cookiebar` para adicionar links externos estruturados,
- * como "Política de Privacidade" ou "Termos de Uso".
+ * O componente `br-cookiebar-link` é o subcomponente de hiperlink do GovBR-DS destinado a apontar para Políticas de Privacidade, Termos de Uso e orientações legais.
  *
- * Quando `target="_blank"`, exibe automaticamente um ícone de link externo
- * e adiciona `rel="noopener noreferrer"` por segurança.
+ * ### Para que serve
  *
+ * - **Acesso a termos legais:** Encaminha a pessoa usuária para a documentação completa de proteção de dados.
+ * - **Estilo consistente:** Garante conformidade visual e acessibilidade no contexto do aviso de cookies.
+ *
+ * ### Papel na composição
+ *
+ * Atua como item de navegação auxiliar no aviso de cookies.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Pode ser utilizado dentro do cabeçalho, notas ou corpo do componente `br-cookiebar`.
+ *
+
  * @part link - Elemento âncora (`<a>`) do link.
  */
 export declare class CookiebarLink {
@@ -31,6 +40,8 @@ export declare class CookiebarLink {
      * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
      */
     readonly navigationMode: BrNavigationMode;
+    private get effectiveTarget();
+    private get effectiveNavigationMode();
     /**
      * Evento cancelável emitido em `navigation-mode="event"` para cliques primários sem modificadores em links `_self`.
      * Chame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.

package/dist/types/components/cookiebar/cookiebar-note/cookiebar-note.d.ts

@@ -1,9 +1,19 @@
 /**
- * Subcomponente de `br-cookiebar-note-group` que representa um par pergunta/resposta
- * dentro da seção de avisos de cookies.
+ * O componente `br-cookiebar-note` é o subcomponente textual do GovBR-DS que exibe notas explicativas, orientações complementares ou avisos jurídicos adicionais.
  *
- * Deve ser inserido dentro de um `br-cookiebar-note-group`.
+ * ### Para que serve
  *
+ * - **Notas de rodapé do aviso:** Apresenta esclarecimentos sobre retenção de dados, atualizações de termos ou exceções regulatórias.
+ *
+ * ### Papel na composição
+ *
+ * Atua como bloco textual informativo complementar.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser utilizado diretamente no `br-cookiebar` ou dentro de um `br-cookiebar-note-group`.
+ *
+
  * @part container - Div raiz do item.
  * @part question - Parágrafo da pergunta.
  * @part answer - Parágrafo da resposta.

package/dist/types/components/cookiebar/cookiebar-note-group/cookiebar-note-group.d.ts

@@ -1,10 +1,20 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * Seção retrátil de avisos e notas sobre cookies, exibida na área complementar do `br-cookiebar`.
- * Agrupa um ou mais `br-cookiebar-note` sob um título clicável que expande ou recolhe o conteúdo.
+ * O componente `br-cookiebar-note-group` é o subcomponente contêiner do GovBR-DS que agrupa uma ou mais notas informativas `br-cookiebar-note`.
  *
- * Se o slot estiver vazio, o componente não renderiza nada.
+ * ### Para que serve
  *
+ * - **Estruturação de notas:** Agrupa avisos jurídicos e observações complementares em uma seção visualmente delimitada.
+ *
+ * ### Papel na composição
+ *
+ * Atua como contêiner estrutural para instâncias de `br-cookiebar-note`.
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * - Deve ser inserido na seção de notas informativas do `br-cookiebar`.
+ *
+
  * @slot default - Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre.
  *
  * @part container - Div raiz do grupo.

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

@@ -1,19 +1,42 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CookiebarMode, CookiebarOutputData } from './cookiebar.types';
 /**
- * Componente de gestão de consentimento de cookies (LGPD), obrigatório em sites e aplicativos do
- * Governo Federal que coletam dados de usuários.
+ * O componente `br-cookiebar` é o orquestrador completo do GovBR-DS para aviso e gestão de consentimento de cookies, atendendo às exigências da LGPD (Lei Geral de Proteção de Dados).
  *
- * Apresenta duas etapas visuais:
- * - **default** – barra inferior com texto informativo e botões de ação;
- * - **open** – painel de tela cheia com lista de classes de cookies configuráveis.
+ * ### Para que serve
  *
- * A persistência do consentimento é responsabilidade do consumidor: ouça o evento
- * `brCookiebarAccept` e armazene o payload onde desejar (localStorage, cookie HTTP, API etc.).
+ * - **Aviso de privacidade e cookies:** Informa com clareza à pessoa usuária sobre a coleta e finalidade de cookies no sistema.
+ * - **Gestão de consentimento:** Permite aceitar todos os cookies, rejeitar os não essenciais ou gerenciar categorias de forma granular.
+ * - **Detalhamento transparente:** Exibe a relação técnica de cookies utilizados por categoria com nome, validade e finalidade.
  *
- * Para a documentação completa, consulte o [Design System do GovBR](https://www.gov.br/ds/components/cookiebar?tab=designer).
+ * ### Quando utilizar
  *
- * @category Feedback
+ * - **Utilize quando:**
+ *   - A aplicação ou portal público utilizar cookies de sessão, rastreamento ou preferências que demandem consentimento explícito.
+ *   - For necessário dar cumprimento às diretrizes de privacidade e proteção de dados pessoais (LGPD).
+ * - **Evite e prefira outro componente quando:**
+ *   - A notificação for apenas um alerta contextual ou mensagem simples de status sem relação com consentimento (prefira `br-message` ou `br-notification`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | Papel | Regra de uso |
+ * | --- | --- | --- |
+ * | `br-cookiebar` | **Orquestrador principal.** Gerencia abertura, fechamento, persistência e emissão dos eventos de consentimento. | Declarado como contêiner do aviso de cookies na aplicação. |
+ * | `br-cookiebar-header` | **Cabeçalho informativo.** Exibe título e mensagem inicial de contexto. | Inserido no slot de topo do `br-cookiebar`. |
+ * | `br-cookiebar-group` | **Categoria de cookies.** Agrupa cookies por finalidade com controle de seleção. | Inserido no corpo de opções do `br-cookiebar`. |
+ * | `br-cookiebar-cookie` | **Item de cookie.** Descreve detalhadamente um cookie específico. | Inserido dentro de um `br-cookiebar-group`. |
+ * | `br-cookiebar-link` | **Link informativo.** Atalho para a Política de Privacidade e termos. | Usado no cabeçalho ou notas do `br-cookiebar`. |
+ * | `br-cookiebar-note` | **Nota complementar.** Mensagem ou aviso jurídico adicional. | Inserido individualmente ou em `br-cookiebar-note-group`. |
+ * | `br-cookiebar-note-group` | **Agrupador de notas.** Organiza múltiplas notas informativas. | Posicionado na área de notas do `br-cookiebar`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * O `br-cookiebar` atua como orquestrador central. Ele controla a visualização do painel (modo compacto ou expandido), agrupa as categorias (`br-cookiebar-group`) com seus respectivos cookies (`br-cookiebar-cookie`) e disponibiliza os botões de ação para aceitar todos, rejeitar ou salvar preferências. A aplicação consome eventos unificados de consentimento disparados pelo componente pai.
+ *
+ * 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/cookiebar?tab=designer).
+ *
+
+ * @category Feedback, Sobreposições
  * @status stable
  * @slot default - Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`.
  * @slot header - Recebe `br-cookiebar-header` ou HTML livre.
@@ -60,7 +83,7 @@ export declare class Cookiebar {
      */
     show: boolean;
     /**
-     * Estado visual atual do painel.
+     * Estado visual atual do painel. Valores inválidos usam `default`.
      * - `default`: barra inferior com texto e botões.
      * - `open`: painel de tela cheia com grupos de cookies configuráveis.
      */
@@ -284,6 +307,7 @@ export declare class Cookiebar {
      * Monta o texto anunciado pela região `aria-live` ao entrar no modo `open`.
      */
     private buildOpenAnnouncement;
+    private getOwnedHeaderElement;
     /**
      * Recalcula o estado do checkbox "Selecionar tudo" com base nos grupos opt-out.
      * Grupos `always-active` (`group-opt-out="false"`) são ignorados no cálculo.
@@ -388,6 +412,7 @@ export declare class Cookiebar {
     private handleKeyDown;
     /** Gera o mapa de classes CSS do container raiz com base no `mode` atual. */
     private getCssClassMap;
+    private get effectiveMode();
     /**
      * Renderiza o checkbox "Selecionar tudo" com seu estado atual e a mensagem de alerta
      * exibida quando nenhum ou apenas alguns grupos estão selecionados.

package/dist/types/components/datetime-picker/date-picker/date-picker.d.ts

@@ -1,9 +1,22 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerSelectionMode, WeekDayIndex } from '../datetime-picker.types';
 /**
- * ## Design System
+ * Subcomponente de calendário visual do GovBR-DS, projetado para seleção interativa de datas individuais ou intervalos.
  *
- * 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/date-picker?tab=designer).
+ * ### Papel na composição
+ *
+ * - Exibe a grade mensal navegável com suporte a seleção de dia, navegação entre meses e anos, e destaque para a data atual e intervalos.
+ * - Implementa navegação acessível por teclado WAI-ARIA Grid (setas direcionais para dias e semanas).
+ *
+ * ### Regra de uso e relacionamento
+ *
+ * Geralmente exibido dentro da superfície suspensa coordenada pelo `br-datetime-picker`. Pode ser declarado isoladamente quando a interface demandar um calendário estático permanentemente embutido na página (inline calendar).
+ *
+ * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
+ *
+
+ * @category Formulários, Seleção
+ * @status stable
  *
  * @part container - Parte para o container base do calendário.
  * @part header - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).
@@ -20,24 +33,64 @@ export declare class DatePicker {
     el: HTMLBrDatePickerElement;
     /** Data com foco atual na navegação por teclado do calendário. */
     private focusedDate;
+    /** Datas inválidas são removidas da lista antes da comparação com o calendário. */
+    private normalizedDisabledDates;
     /** Define o índice do dia em que a semana começa na interface do calendário. */
     weekStartsOn: WeekDayIndex;
-    /** Data usada como base visual para o mês atualmente exibido. */
+    /**
+     * Data usada como base visual para o mês atualmente exibido, sem alterar a seleção.
+     * Recebe uma instância de `Date` por property binding; valores inválidos usam a data atual.
+     *
+     * @example
+     * ```js
+     * const calendar = document.querySelector('br-date-picker');
+     * calendar.referenceDate = new Date(2026, 8, 1);
+     * ```
+     */
     referenceDate: Date;
-    /** Data atualmente selecionada pelo usuário, ou `null` quando não há seleção. */
+    /**
+     * Data efetivamente selecionada, ou `null` quando não há seleção; é diferente de `referenceDate`, que controla apenas o mês visível.
+     * Recebe uma instância de `Date` por property binding; datas inválidas usam `null`.
+     *
+     * @example
+     * ```js
+     * const calendar = document.querySelector('br-date-picker');
+     * calendar.value = new Date(2026, 8, 7);
+     * ```
+     */
     value: Date | null;
-    /** Define se a seleção ocorre por data única ou por intervalo. */
+    /** Define se a seleção ocorre por data única ou por intervalo. Valores inválidos usam `single`. */
     selectionMode: DatetimePickerSelectionMode;
+    private get effectiveSelectionMode();
     /** Data inicial selecionada quando o calendário opera no modo de intervalo. */
     rangeStart: Date | null;
     /** Data final selecionada quando o calendário opera no modo de intervalo. */
     rangeEnd: Date | null;
-    /** Intervalo controlado no modo `range`. */
+    /**
+     * Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualização.
+     * Deve conter datas válidas ou `null`; valores inválidos são ignorados. Passe o objeto por property binding.
+     *
+     * @example
+     * ```js
+     * const calendar = document.querySelector('br-date-picker');
+     * calendar.selectionMode = 'range';
+     * calendar.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };
+     * ```
+     */
     rangeValue?: DatetimePickerDateRange;
     handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
     /** Desabilita a interação do calendário quando ativo. */
     disabled: boolean;
-    /** Lista de datas indisponíveis para seleção no calendário. */
+    /**
+     * Lista de datas indisponíveis para seleção no calendário.
+     * Recebe instâncias de `Date` por property binding; datas inválidas são ignoradas.
+     *
+     * @example
+     * ```js
+     * const calendar = document.querySelector('br-date-picker');
+     * calendar.disabledDates = [new Date(2026, 8, 7), new Date(2026, 8, 8)];
+     * ```
+     */
     disabledDates: Date[];
     /** Locale usado para gerar nomes de meses e dias da semana. */
     locale: string;
@@ -57,6 +110,7 @@ export declare class DatePicker {
      * @param newValue - Novo valor recebido via prop.
      */
     handleValueChange(newValue: Date | null): void;
+    handleReferenceDateChange(newValue: Date): void;
     /**
      * Revalida a configuração quando o início da semana muda.
      *
@@ -69,6 +123,7 @@ export declare class DatePicker {
      * @param newValue - Novo valor recebido via prop.
      */
     handleLocaleChange(newValue: string): void;
+    handleDisabledDatesChange(newValue: Date[]): void;
     /** Evento emitido quando a data de referência ou a seleção mudam. */
     dateStateChange: EventEmitter<DatetimePickerDateState>;
     /**
@@ -87,6 +142,7 @@ export declare class DatePicker {
      * @param value - Valor bruto informado pelo consumidor.
      */
     private ensureValidWeekStartsOn;
+    private normalizeDateProp;
     /**
      * Garante que o locale informado seja suportado.
      *