@govbr-ds/webcomponents 2.4.0 → 2.5.0

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

@@ -1,32 +1,36 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CollapseChangeDetail, CollapseColorMode, CollapseExpansionDirection, CollapseIconPosition, CollapseTriggerVariant } from './collapse.types';
 /**
- * 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.
+ * O `br-collapse` mostra e esconde um bloco de conteúdo ao clicar no título. Funciona como um `<details>`.
  *
- * ### Para que serve
+ * ```html
+ * <br-collapse>
+ *   <span slot="trigger">Quem pode solicitar?</span>
+ *   <p>Qualquer pessoa com CPF regular.</p>
+ * </br-collapse>
+ * ```
  *
- * - **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.
+ * Use `open` para começar aberto. Para que só um item fique aberto por vez (sanfona), dê o mesmo `accordion-group` a todos:
  *
- * ### Quando utilizar
+ * ```html
+ * <br-collapse accordion-group="faq">…</br-collapse>
+ * <br-collapse accordion-group="faq">…</br-collapse>
+ * ```
  *
- * - **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`).
+ * Os ícones de abrir e fechar podem ser trocados por `icon-to-show` e `icon-to-hide`, como propriedade ou como slot.
  *
- * ### Estrutura e Slots
+ * ### Quando usar
  *
- * 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.
+ * - Perguntas frequentes e conteúdos longos divididos em tópicos.
+ * - Seções opcionais de um formulário longo.
  *
- * 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).
+ * ### Quando evitar
+ *
+ * - Informação essencial, que precisa ficar sempre visível.
+ * - Alternar entre visões diferentes da mesma tela: use `br-tab`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/collapse?tab=designer).
  *
-
  * @category Conteúdo, Ações
  * @status stable
  * @see br-list
@@ -109,14 +113,14 @@ export declare class Collapse {
      */
     /** @deprecated Use `brCollapseOpen`. */
     brDidOpen: EventEmitter<CollapseChangeDetail>;
-    /** Evento canônico emitido ao expandir. */
+    /** Evento emitido ao expandir. */
     brCollapseOpen: EventEmitter<CollapseChangeDetail>;
     /**
      * Emitido ao recolher, com o identificador e o grupo de accordion.
      */
     /** @deprecated Use `brCollapseClose`. */
     brDidClose: EventEmitter<CollapseChangeDetail>;
-    /** Evento canônico emitido ao recolher. */
+    /** Evento emitido ao recolher. */
     brCollapseClose: EventEmitter<CollapseChangeDetail>;
     /**
      * Remove o listener do <details> ao desmontar o componente.

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

@@ -1,22 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-cookiebar-cookie` é o subcomponente do GovBR-DS que descreve as especificações técnicas de um cookie individual.
+ * Descreve um cookie dentro de um `br-cookiebar-group`: nome, validade, domínio, empresa responsável, finalidade e descrição.
  *
- * ### Para que serve
+ * Use `cookie-opt-out="false"` quando o cookie não puder ser desativado.
  *
- * - **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,23 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { CookiebarSelectionState } from '../cookiebar.types';
 /**
- * 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).
+ * Uma categoria de cookies dentro do `br-cookiebar`, como "Necessários" ou "Estatísticas". Contém um `br-cookiebar-cookie` para cada cookie.
  *
- * ### Para que serve
+ * Informe `group-id`, `group-name` e `group-text`. Use `group-opt-out="false"` quando a categoria não puder ser desativada: ela aparece como "Sempre ativo".
  *
- * - **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,21 +1,8 @@
 /**
- * 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.
+ * Título e texto de introdução do painel do `br-cookiebar`. Use no slot `header` do cookiebar.
  *
- * ### Para que serve
+ * Informe `main-title`, `entry-text` e, se quiser, a data em `last-update`. Para outro layout, coloque seu próprio conteúdo dentro do componente.
  *
- * - **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,22 +1,10 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { BrNavigateDetail, BrNavigationMode } from '../../global.types';
 /**
- * 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.
+ * Link do `br-cookiebar` para a política de privacidade ou os termos de uso. Use no slot `links` do cookiebar.
  *
- * ### Para que serve
+ * Informe `name` e `href`. Em SPA, use `navigation-mode="event"` e trate o evento `brNavigate`.
  *
- * - **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 {

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

@@ -1,19 +1,8 @@
 /**
- * O componente `br-cookiebar-note` é o subcomponente textual do GovBR-DS que exibe notas explicativas, orientações complementares ou avisos jurídicos adicionais.
+ * Uma pergunta e resposta complementar no painel do `br-cookiebar`. Informe `question` e `answer`.
  *
- * ### Para que serve
+ * Para reunir várias notas, coloque-as em um `br-cookiebar-note-group`.
  *
- * - **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,20 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 /**
- * O componente `br-cookiebar-note-group` é o subcomponente contêiner do GovBR-DS que agrupa uma ou mais notas informativas `br-cookiebar-note`.
+ * Agrupa notas do `br-cookiebar` em uma seção que pode ser expandida. O título vem de `note-title`.
  *
- * ### Para que serve
+ * Coloque dentro dele elementos `br-cookiebar-note` ou outro conteúdo.
  *
- * - **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,41 +1,46 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { CookiebarMode, CookiebarOutputData } from './cookiebar.types';
 /**
- * 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).
+ * O `br-cookiebar` avisa sobre o uso de cookies e registra o consentimento da pessoa, por categoria e por cookie.
  *
- * ### Para que serve
+ * Ele aparece como uma barra no rodapé (`mode="default"`) e abre um painel com as categorias quando a pessoa escolhe "Definir Cookies" (`mode="open"`).
  *
- * - **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.
+ * ### Como usar
  *
- * ### Quando utilizar
+ * 1. Escreva o texto da barra em `info-text`.
+ * 2. Coloque o título e a introdução do painel em um `br-cookiebar-header`.
+ * 3. Crie um `br-cookiebar-group` por categoria e, dentro dele, um `br-cookiebar-cookie` por cookie. Use `group-opt-out="false"` nas categorias que não podem ser desativadas.
+ * 4. Adicione os links de política em `br-cookiebar-link`, no slot `links`.
+ * 5. Ouça `brCookiebarResponse` para salvar a escolha e ative `show` somente enquanto não houver escolha salva.
  *
- * - **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`).
+ * ```html
+ * <br-cookiebar info-text="Usamos cookies para melhorar sua experiência.">
+ *   <br-cookiebar-header slot="header" main-title="Aviso de cookies" entry-text="Escolha quais cookies aceitar."></br-cookiebar-header>
  *
- * ### Composição e Subcomponentes
+ *   <br-cookiebar-group group-id="necessarios" group-name="Necessários" group-text="Essenciais para o site funcionar." group-opt-out="false">
+ *     <br-cookiebar-cookie cookie-id="sessao" cookie-name="sessao" expires="Ao fechar o navegador" domain="exemplo.gov.br" enterprise="Próprio" purpose="Manter a sessão" description="Identifica a sessão de acesso."></br-cookiebar-cookie>
+ *   </br-cookiebar-group>
  *
- * | 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`. |
+ *   <br-cookiebar-link slot="links" name="Política de privacidade" href="/privacidade"></br-cookiebar-link>
+ * </br-cookiebar>
+ * ```
  *
- * ### Como os subcomponentes se relacionam
+ * ```js
+ * const cookiebar = document.querySelector('br-cookiebar');
+ * cookiebar.show = !localStorage.getItem('consentimento');
+ * cookiebar.addEventListener('brCookiebarResponse', (event) => {
+ *   localStorage.setItem('consentimento', JSON.stringify(event.detail));
+ * });
+ * ```
  *
- * 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.
+ * `event.detail` traz o estado de cada categoria (`cookieGroups`) e de cada cookie (`cookieList`). Para reabrir o painel depois, por exemplo num link "Preferências de cookies", chame `openPanel()`.
  *
- * 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).
+ * ### Quando evitar
+ *
+ * - Avisos que não tratam de consentimento: use `br-message` ou `br-notification`.
+ *
+ * Consulte as [diretrizes de design 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`.

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

@@ -25,12 +25,20 @@ export declare function resolveDateFnsLocale(localeCode?: string): Locale;
  * @param {string} localeCode - Código de locale aceito pelo componente.
  * @returns {string[]} Lista com os 12 meses formatados para exibição.
  */
-export declare function getMonthLabels(localeCode: string): string[];
+export declare function getMonthLabels(localeCode: string): readonly string[];
 /**
- * Gera os rótulos dos dias da semana considerando o início informado.
+ * Gera os rótulos abreviados dos dias da semana considerando o início informado.
  *
  * @param {string} localeCode - Código de locale aceito pelo componente.
  * @param {WeekDayIndex} weekStartsOn - Índice do primeiro dia da semana.
- * @returns {string[]} Lista com abreviações dos sete dias da semana.
+ * @returns {readonly string[]} Lista com abreviações dos sete dias da semana.
  */
-export declare function getWeekdayLabels(localeCode: string, weekStartsOn: WeekDayIndex): string[];
+export declare function getWeekdayLabels(localeCode: string, weekStartsOn: WeekDayIndex): readonly string[];
+/**
+ * Gera os nomes completos dos dias da semana, usados como nome acessível dos cabeçalhos.
+ *
+ * @param {string} localeCode - Código de locale aceito pelo componente.
+ * @param {WeekDayIndex} weekStartsOn - Índice do primeiro dia da semana.
+ * @returns {readonly string[]} Lista com os nomes completos dos sete dias da semana.
+ */
+export declare function getWeekdayFullNames(localeCode: string, weekStartsOn: WeekDayIndex): readonly string[];

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

@@ -1,19 +1,25 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerSelectionMode, WeekDayIndex } from '../datetime-picker.types';
 /**
- * O `br-date-picker` é o subcomponente de calendário do `br-datetime-picker`, responsável pela seleção visual de uma data ou de um intervalo.
+ * Calendário usado pelo `br-datetime-picker`. Também pode ser usado sozinho, quando a tela precisa de um calendário sempre visível.
  *
- * ### Papel na composição
+ * Usado sozinho, ele não tem campo de texto nem participa de formulário: a aplicação lê a seleção e cuida da validação.
  *
- * Exibe a grade mensal, a navegação entre meses e anos e os estados de seleção e bloqueio dos dias. `referenceDate` determina o período exibido, enquanto `value` e os limites do intervalo representam a seleção.
+ * ```html
+ * <br-date-picker id="agenda"></br-date-picker>
+ * ```
  *
- * ### Regra de uso e relacionamento
+ * ```js
+ * const calendario = document.querySelector('#agenda');
+ * calendario.addEventListener('change', () => console.log(calendario.value));
+ * ```
  *
- * O `br-datetime-picker` instancia e configura este calendário internamente nos modos `date` e `datetime`, recebendo suas alterações pelo evento `dateStateChange`. Não declare o calendário em um slot do pai.
+ * - `value`: data selecionada (`Date`).
+ * - `referenceDate`: mês exibido.
+ * - `disabledDates`: datas que não podem ser escolhidas.
+ * - `selectionMode="range"`: seleção de intervalo, lida em `rangeValue`.
  *
- * Use diretamente quando precisar de um calendário embutido e permanentemente visível. Nesse caso, a aplicação deve coordenar valores e eventos e implementar a integração com formulários e a validação do fluxo completo. O calendário isolado não fornece o campo textual, o seletor de horários nem a associação ao formulário do orquestrador.
- *
- * 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).
+ * Para mudar o idioma, veja "Idiomas" na documentação do `br-datetime-picker`.
  *
  * @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).
@@ -113,6 +119,16 @@ export declare class DatePicker {
      * @internal
      */
     private shouldFocusDate;
+    /**
+     * Lista de `disabledDates` usada para gerar `disabledDateKeysCache`.
+     * @internal
+     */
+    private disabledDateKeysSource?;
+    /**
+     * Chaves `yyyy-MM-dd` das datas bloqueadas, para consulta O(1) por célula.
+     * @internal
+     */
+    private disabledDateKeysCache;
     /**
      * Observador para a prop `rangeValue` — sincroniza `rangeStart` e `rangeEnd`.
      * @param {DatetimePickerDateRange | undefined} newValue - novo intervalo controlado recebido (`undefined` quando não fornecido)
@@ -127,9 +143,10 @@ export declare class DatePicker {
     /**
      * Observador para a prop `value` — atualiza `focusedDate` quando a seleção externa muda.
      * @param {Date | null} newValue - novo valor de seleção (ou `null`)
+     * @param {Date | null} oldValue - valor anterior da seleção
      * @internal
      */
-    handleValueChange(newValue: Date | null): void;
+    handleValueChange(newValue: Date | null, oldValue: Date | null): void;
     /**
      * Revalida a configuração quando o início da semana muda.
      *
@@ -224,6 +241,17 @@ export declare class DatePicker {
      * @internal
      */
     private increaseMonth;
+    /**
+     * Exibe o mês informado preservando a seleção, o intervalo completo e o dia em foco.
+     *
+     * O foco vai para a data selecionada quando ela pertence ao novo mês; caso
+     * contrário, mantém o mesmo dia do mês, limitado ao último dia disponível
+     * (ex.: 31/01 → 28/02).
+     *
+     * @param monthDate - primeiro dia do mês de destino
+     * @internal
+     */
+    private navigateToMonth;
     /**
      * Verifica se uma data está indisponível para seleção.
      * @param date - data a verificar
@@ -231,6 +259,12 @@ export declare class DatePicker {
      * @internal
      */
     private isDateDisabled;
+    /**
+     * Chaves locais das datas bloqueadas, recalculadas somente quando `disabledDates` é substituída.
+     * Entradas inválidas são ignoradas.
+     * @internal
+     */
+    private get disabledDateKeys();
     /**
      * Data base usada para todos os cálculos de calendário.
      * @returns data de referência interna
@@ -253,6 +287,7 @@ export declare class DatePicker {
     /**
      * Constrói o rótulo acessível da célula de dia, incluindo estado (selecionado/início/fim).
      * @param date - dia representado pela célula
+     * @param state - estado já calculado da célula
      * @returns string para `aria-label`
      * @internal
      */
@@ -263,9 +298,17 @@ export declare class DatePicker {
      */
     private get dateFnsLocale();
     /**
-     * Calcula o mapa de classes CSS da célula do dia.
+     * Calcula uma única vez o estado de seleção da célula, compartilhado por classes, ARIA e foco.
      * @param date - dia da grade
      * @param today - instante atual compartilhado pela renderização da grade
+     * @returns estado da célula
+     * @internal
+     */
+    private getDayCellState;
+    /**
+     * Calcula o mapa de classes CSS da célula do dia.
+     * @param state - estado já calculado da célula
+     * @param disabled - indica se a célula está bloqueada
      * @returns mapa de classes booleanas
      * @internal
      */
@@ -320,7 +363,10 @@ export declare class DatePicker {
     private getMonthLabels;
     /**
      * Gerencia navegação por teclado dentro da grade de dias.
-     * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown, Home/End, Enter/Space.
+     * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown (mês), Shift+PageUp/PageDown (ano),
+     * Home/End, Enter/Space.
+     *
+     * Permanece ativo em datas bloqueadas para que o foco não fique preso nelas; somente a seleção é ignorada.
      * @param event - evento de teclado
      * @returns void
      * @internal

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

@@ -1,19 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerMode, DatetimePickerSelectionMode } from '../datetime-picker.types';
 /**
- * O `br-datetime-input` é o subcomponente de edição textual do `br-datetime-picker`, com máscara, interpretação de datas e horários e validação local sobre um `br-input` interno.
+ * Campo de texto com máscara usado pelo `br-datetime-picker`. Interpreta a data ou a hora digitada e abre o calendário pelo botão do campo.
  *
- * ### Papel na composição
- *
- * Exibe e permite editar a seleção única ou os limites de um intervalo nos modos `date`, `time` e `datetime`. Comunica alterações por `dateStateChange`, informa a validação local por `inputValidationChange` e solicita a abertura ou o fechamento do painel por `togglePicker`.
- *
- * ### Regra de uso e relacionamento
- *
- * O `br-datetime-picker` instancia este campo internamente e fornece valores e configurações por propriedades. O pai coordena a seleção com o calendário e os controles de horário; o campo não abre esses seletores por conta própria nem deve ser fornecido em slot.
- *
- * Prefira o `br-datetime-picker` para o controle completo. Use o campo isoladamente apenas em composições personalizadas nas quais a aplicação assuma a sincronização de estado, o tratamento dos eventos e a integração com formulários. Este subcomponente não possui a associação nativa ao formulário do orquestrador.
- *
- * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
+ * É criado pelo `br-datetime-picker`; não é preciso declará-lo. Para um campo de data em formulário, use o `br-datetime-picker`.
  *
  * @see https://www.gov.br/ds/components/datetime?tab=designer
  * @part container - Container do campo.

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

@@ -3,42 +3,38 @@ import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { DatetimePickerChangeDetail, DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex } from './datetime-picker.types';
 /**
- * O `br-datetime-picker` é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.
+ * O `br-datetime-picker` é um campo para informar data, hora ou data e hora. A pessoa pode digitar ou escolher no calendário e nos controles de horário.
  *
- * ### Para que serve
+ * Escolha o tipo em `mode`: `date`, `time` ou `datetime`. Para início e fim, use `selection-mode="range"`.
  *
- * - Oferece os modos `date`, `time` e `datetime`, com seleção única (`single`) ou de intervalo (`range`).
- * - Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
- * - Centraliza restrições de seleção, validação e submissão do valor por meio de `formAssociated`.
+ * ```html
+ * <br-datetime-picker mode="date" name="nascimento" required></br-datetime-picker>
  *
- * ### Quando utilizar
+ * <br-datetime-picker mode="date" selection-mode="range" name="periodo"></br-datetime-picker>
+ * ```
  *
- * - Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
- * - Utilize para períodos com início e fim, inclusive com horários nos modos `time` e `datetime`.
- * - Evite quando precisar apenas apresentar uma data: prefira texto formatado.
- * - Para um calendário permanentemente visível sem o campo textual, considere `br-date-picker`; a aplicação assume a integração com o restante do formulário.
- * - A seleção não oferece uma coleção de datas independentes: use `single` para um valor ou `range` para um intervalo.
+ * ### Ler o valor
  *
- * ### Composição e Subcomponentes
+ * | Onde | Formato |
+ * | --- | --- |
+ * | `value` | `Date` (ou `null`) |
+ * | `rangeValue` | `{ start, end }` com `Date` |
+ * | `serialized-value` e envio do formulário | `2026-05-20` (data), `14:30` (hora), `2026-05-20T14:30:00-03:00` (data e hora), `início/fim` (intervalo) |
  *
- * | Componente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-datetime-picker` | Orquestrador do valor consolidado, validação, formulário e abertura do painel. | Declare este controle no template para obter a composição completa. |
- * | `br-datetime-input` | Campo textual com máscara, interpretação da entrada e ação de abertura do painel. | Instanciado internamente pelo pai; não deve ser fornecido em slot. |
- * | `br-date-picker` | Calendário para navegação e seleção de data única ou intervalo. | Criado pelo pai nos modos `date` e `datetime`; pode ser usado isoladamente como calendário embutido. |
- * | `br-time-picker` | Controles de hora e minuto. | Criado pelo pai nos modos `time` e `datetime`, com uma instância por limite quando a seleção é `range`. |
+ * Atribua valores do tipo `Date` pelo JavaScript (`picker.value = new Date()`), não por atributo. Para restringir datas, use `min`, `max` e `disabled-dates`.
  *
- * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
+ * ### Quando usar
  *
- * ### Como os subcomponentes se relacionam
+ * - Formulários que pedem uma data, um horário ou um período.
  *
- * O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.
+ * ### Quando evitar
  *
- * `referenceDate` representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo `brDatetimePickerChange` para a seleção completa e tipada.
+ * - Para só exibir uma data: use texto formatado.
+ * - Para escolher várias datas soltas: o componente aceita uma data ou um intervalo.
  *
- * O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do `br-datetime-picker`.
+ * O calendário (`br-date-picker`), os controles de horário (`br-time-picker`) e o campo de texto (`br-datetime-input`) são criados pelo próprio componente; não é preciso declará-los.
  *
- * 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/datetimepicker?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetimepicker?tab=designer).
  *
  * @category Formulários
  * @status stable
@@ -264,7 +260,7 @@ export declare class DatetimePicker {
      */
     dateStateChange: EventEmitter<DatetimePickerDateState>;
     /**
-     * Evento público canônico emitido quando a seleção muda.
+     * Evento emitido quando a seleção muda.
      *
      * Payload (`DatetimePickerChangeDetail`):
      * - `mode`: DatetimePickerMode — modo atual do componente (`date` | `time` | `datetime`).
@@ -676,7 +672,7 @@ export declare class DatetimePicker {
      * @param serializedValue string — valor serializado a ser restaurado.
      */
     private restoreSerializedValue;
-    /** Atualiza os nomes canônicos sem emitir eventos adicionais ou criar ciclos de watchers. */
+    /** Atualiza os nomes padrão sem emitir eventos adicionais ou criar ciclos de watchers. */
     private syncCanonicalValues;
     /**
      * Retorna o mesmo valor que será submetido pelo ElementInternals.

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

@@ -1,19 +1,9 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateState } from '../datetime-picker.types';
 /**
- * O `br-time-picker` é o subcomponente de ajuste de horas e minutos do `br-datetime-picker`.
+ * Controles de hora e minuto usados pelo `br-datetime-picker`. Em um intervalo, o componente cria um controle para o início e outro para o fim.
  *
- * ### Papel na composição
- *
- * Oferece campos textuais e botões de incremento e decremento para hora e minuto. Usa uma data de referência e comunica alterações por `dateStateChange`; não coordena diretamente o calendário nem o campo textual principal.
- *
- * ### Regra de uso e relacionamento
- *
- * O `br-datetime-picker` instancia e sincroniza este seletor nos modos `time` e `datetime`. Na seleção de intervalo, o pai cria dois seletores, um para o início e outro para o fim, e consolida os respectivos valores. Não forneça seletores de horário em slots do pai.
- *
- * Prefira o orquestrador para um controle completo de horário com campo textual e formulário. Use diretamente apenas quando precisar dos controles de hora e minuto em uma composição personalizada e assumir a sincronização de estado, a validação e a integração com formulários. O uso isolado não herda a associação nativa ao formulário do pai.
- *
- * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
+ * Para um campo de horário em formulário, use `<br-datetime-picker mode="time">`. Usado sozinho, ele não participa de formulário: leia o horário em `value` e trate a validação na aplicação.
  *
  * @part container - Container base do seletor de horários.
  * @part timer - Grupo que contém os campos de hora e minuto.
@@ -31,7 +21,7 @@ export declare class TimePicker {
      */
     referenceDate: Date;
     /**
-     * Valor canônico selecionado pelo usuário.
+     * Valor selecionado pelo usuário.
      *
      * @default null
      */