@govbr-ds/webcomponents 2.3.0 → 2.5.0

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

@@ -1,41 +1,42 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import { type FormValidationState } from '../../shared/utils/form';
 import { type FormValidationChangeDetail } from '../../shared/utils/validator';
-import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex } from './datetime-picker.types';
+import type { DatetimePickerChangeDetail, DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex } from './datetime-picker.types';
 /**
- * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
+ * 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"`.
  *
- * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
- * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
- * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+ * ```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 exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
- *   - For necessário selecionar um período com data de início e fim.
- * - **Evite e prefira outro componente quando:**
- *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+ * ### 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) |
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
- * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
- * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
- * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+ * Atribua valores do tipo `Date` pelo JavaScript (`picker.value = new Date()`), não por atributo. Para restringir datas, use `min`, `max` e `disabled-dates`.
  *
- * ### Como os subcomponentes se relacionam
+ * ### Quando usar
  *
- * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
+ * - Formulários que pedem uma data, um horário ou um período.
  *
- * 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/datetime-picker?tab=designer).
+ * ### Quando evitar
  *
-
- * @category Formulários, Seleção
+ * - Para só exibir uma data: use texto formatado.
+ * - Para escolher várias datas soltas: o componente aceita uma data ou um intervalo.
+ *
+ * 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.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetimepicker?tab=designer).
+ *
+ * @category Formulários
  * @status stable
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  * @part container - Parte para o container base do seletor.
@@ -48,220 +49,313 @@ import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDi
 export declare class DatetimePicker {
     /** Fornece acesso à API de formulários nativos via ElementInternals. */
     elementInternals: ElementInternals;
-    formDisabledCallback(disabled: boolean): void;
-    /** API nativa de reset de form-associated custom elements. */
-    formResetCallback(): void;
-    /** API nativa de restauração de estado (histórico/autofill) do formulário. */
-    formStateRestoreCallback(state: string | File | FormData | null): void;
     /** Referência ao elemento host do componente no DOM. */
     el: HTMLBrDatetimePickerElement;
     /**
-     * Controla se o conteúdo do picker está visível.
-     */
-    private isPickerOpen;
-    private formDisabled;
-    private hasFeedbackSlot;
-    private customValidationMessage;
-    private validatorMessage;
-    private isValidating;
-    private readonly feedbackId;
-    /** Lista normalizada de datas indisponíveis para seleção. */
-    private normalizedDisabledDates;
-    /** Data final selecionada no modo de intervalo. */
-    private rangeEnd;
-    /** Data inicial selecionada no modo de intervalo. */
-    private rangeStart;
-    /**
-     * Mantém a data de referência que orienta a navegação visual do calendário.
-     */
-    private referenceDate;
-    /**
-     * Define o modo de seleção exibido pelo componente: data, horário ou ambos.
+     * Modo exibido pelo componente.
      *
-     * Valores aceitos: `date`, `time` ou `datetime`.
-     * Valores inválidos são corrigidos automaticamente para o valor padrão,
-     * mantendo o atributo refletido sempre consistente com o modo exibido.
+     * Valores: `date` | `time` | `datetime`.
+     * Valores inválidos são normalizados para o padrão.
      *
      * @default 'datetime'
      */
     mode: DatetimePickerMode;
     /**
-     * Define o locale usado pelos subcomponentes para formatar datas e rótulos.
+     * Locale usado para formatação e rótulos.
      *
      * @default 'pt-BR'
      */
     locale: DatetimePickerLocale;
     /**
-     * Define o placeholder exibido no campo de entrada do datetime picker.
+     * Texto placeholder exibido no input.
      *
      * @default ''
      */
     placeholder: string;
-    /** Nome do campo para submissão em formulários nativos. */
+    /**
+     * Nome do campo para submissão em formulários nativos.
+     *
+     * @default ''
+     */
     name: string;
-    /** Indica se o campo deve ter valor antes do envio do formulário. */
+    /**
+     * Indica se o campo é requerido para submissão do formulário.
+     *
+     * @default false
+     */
     required: boolean;
     /**
-     * Menor data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.
-     * Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
+     * Menor data/hora aceito (Date | string | null).
      *
-     * @example
-     * ```html
-     * <br-datetime-picker mode="date" min="2026-01-01"></br-datetime-picker>
-     * ```
+     * @default null
      */
     min: Date | string | null;
     /**
-     * Maior data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.
-     * Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
+     * Maior data/hora aceito (Date | string | null).
      *
-     * @example
-     * ```html
-     * <br-datetime-picker mode="date" max="2026-12-31"></br-datetime-picker>
-     * ```
+     * @default null
      */
     max: Date | string | null;
     /**
-     * Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado.
-     * Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
+     * Validador customizado (síncrono ou assíncrono) para a seleção.
+     *
+     * Recebe `Date | DatetimePickerDateRange | null` como valor.
      *
-     * @example
-     * ```js
-     * const picker = document.querySelector('br-datetime-picker');
-     * picker.validator = (value) => value === null ? 'Escolha uma data' : null;
-     * ```
+     * @default undefined
      */
     readonly validator?: DatetimePickerValidator;
     /**
-     * Define o tipo de seleção de datas para o calendário: única ou intervalo.
+     * Tipo de seleção: `single` ou `range`.
      *
-     * `range` só funciona em conjunto com `mode="date"`.
-     * Se `selectionMode="range"` for informado, o componente ajusta automaticamente
-     * `mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente
-     * normaliza `selectionMode` para `single` quando necessário.
-     * Valores inválidos usam `single`.
+     * @default 'single'
      */
     selectionMode: DatetimePickerSelectionMode;
     /**
-     * Define o dia inicial da semana exibida no calendário.
-     *
-     * Valores suportados: 0 (domingo) a 6 (sábado).
+     * Dia inicial da semana exibido no calendário (0 = Dom, 6 = Sáb).
      *
      * @default 0
      */
     weekStartsOn: DatetimePickerWeekDayIndex;
     /**
-     * Define a seleção inicial do componente.
-     *
-     * Aceita:
-     * - `'now'`: seleciona o momento atual.
-     * - `Date` ou `string`: seleciona uma data arbitrária.
-     * - `null`: inicia sem seleção.
-     *
-     * Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
+     * Valor inicial da seleção: `'now' | Date | string | null`.
      *
      * @default null
-     * @example
-     * ```html
-     * <br-datetime-picker initial-moment="now"></br-datetime-picker>
-     * ```
      */
     initialMoment: DatetimePickerInitialMoment;
     /**
-     * Instância de `Date` selecionada pelo usuário no modo simples.
-     * Pode ser controlada por property binding e é atualizada pelo evento `valueChange`.
-     * Para formulários e atributos textuais, use `serializedValue`.
+     * Valor selecionado pelo usuário (Date | null).
+     *
+     * Pode ser controlado externamente e é refletido internamente.
      *
-     * @example
-     * ```js
-     * const picker = document.querySelector('br-datetime-picker');
-     * picker.value = new Date(2026, 8, 7, 14, 30);
-     * ```
+     * @default null
      */
     value: Date | null;
     /**
-     * Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`
-     * ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.
+     * Representação serializada compatível com controles HTML.
      *
-     * Na inicialização, tem precedência sobre `valueAsDate`, `value` e `initialMoment`.
-     * Uma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.
+     * Formatos variam conforme `mode`. Em intervalos, usa `início/fim`.
      *
-     * @example
-     * ```html
-     * <br-datetime-picker mode="datetime" serialized-value="2026-09-07T14:30"></br-datetime-picker>
-     * ```
+     * @default undefined
      */
     serializedValue?: string;
     /**
-     * Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML.
-     * Diferentemente de `serializedValue`, recebe e retorna uma instância de `Date`.
-     * Na inicialização, tem precedência sobre `value` e `initialMoment` quando `serializedValue`
-     * não é informado. `null` inicia sem seleção; `undefined` permite usar as outras props.
+     * Espelho tipado da seleção atual (`valueAsDate`).
+     *
+     * @internal Mantém compatibilidade com APIs legadas.
      *
-     * @example
-     * ```js
-     * const picker = document.querySelector('br-datetime-picker');
-     * picker.valueAsDate = new Date(2026, 8, 7);
-     * ```
+     * @default undefined
      */
     valueAsDate?: Date | null;
     /**
      * Intervalo controlado quando `selectionMode="range"`.
-     * Deve conter datas válidas ou `null` em `start` e `end`; valores inválidos mantêm o último intervalo efetivo.
-     * Passe o objeto por property binding; atributos HTML não representam objetos com `Date`.
-     *
-     * @example
-     * ```js
-     * const picker = document.querySelector('br-datetime-picker');
-     * picker.selectionMode = 'range';
-     * picker.rangeValue = {
-     *   start: new Date(2026, 8, 7),
-     *   end: new Date(2026, 8, 12),
-     * };
-     * ```
+     *
+     * Em `datetime`, preserva as datas e horários informados; término anterior ao
+     * início torna o controle inválido, sem reordenar ou avançar datas.
+     *
+     * @default undefined
      */
     rangeValue?: DatetimePickerDateRange;
     /**
      * Desabilita toda a interação do componente.
      *
-     * Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários.
-     *
      * @default false
      */
     disabled: boolean;
     /**
-     * Define um conjunto de datas indisponíveis para seleção.
+     * Datas indisponíveis para seleção. Aceita `Date[]`, `string` ou `null`.
      *
-     * Aceita uma lista de `Date` e/ou strings analisáveis, ou uma string com datas
-     * separadas por espaço em branco. Datas inválidas são ignoradas com warning.
-     * A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
+     * Datas inválidas são ignoradas. A comparação considera apenas o dia.
      *
      * @default null
-     * @example
-     * ```html
-     * <br-datetime-picker mode="date" disabled-dates="2026-09-07 2026-09-08"></br-datetime-picker>
-     * ```
-     * @example
-     * ```js
-     * const picker = document.querySelector('br-datetime-picker');
-     * picker.disabledDates = [new Date(2026, 8, 7), '2026-09-08'];
-     * ```
      */
     disabledDates: DatetimePickerDisabledDates;
     /**
-     * Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)
-     * ou variar conforme o mês.
-     *
-     * Quando `true`, o calendário sempre exibe 6 semanas completas.
-     * Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias.
+     * Mantém número fixo de linhas no calendário (6 semanas) quando `true`.
      *
      * @default false
      */
     fixedRowCount: boolean;
+    /**
+     * Controla se o conteúdo do picker está visível.
+     *
+     * @internal Estado reativo interno; não usar externamente.
+     */
+    private isPickerOpen;
+    /**
+     * Indica se o formulário associado desabilitou o componente.
+     *
+     * @internal Estado reativo interno.
+     */
+    private formDisabled;
+    /**
+     * Indica se existe slot `feedback` presente no host.
+     *
+     * @internal Estado reativo interno.
+     */
+    private hasFeedbackSlot;
+    /**
+     * Mensagem de validação customizada definida por `setCustomValidity`.
+     *
+     * @internal Estado reativo interno.
+     */
+    private customValidationMessage;
+    /**
+     * Mensagem retornada pelo validator customizado, se houver.
+     *
+     * @internal Estado reativo interno.
+     */
+    private validatorMessage;
+    /**
+     * Mensagem textual de validação proveniente do input interno.
+     *
+     * @internal Estado reativo interno.
+     */
+    private inputValidationMessage;
+    /**
+     * Indica que o usuário está editando o texto do input e que a validação
+     * textual está pendente (mensagem escondida até commit/blur).
+     *
+     * @internal
+     */
+    private inputValidationPending;
+    /**
+     * Indicador de execução do validator assíncrono.
+     *
+     * @internal Estado reativo interno.
+     */
+    private isValidating;
+    /**
+     * Lista normalizada de datas indisponíveis para seleção.
+     *
+     * @internal Mantida em formato `Date[]` para uso interno pelo calendário.
+     */
+    private normalizedDisabledDates;
+    /**
+     * Data final selecionada no modo de intervalo.
+     *
+     * @internal Estado reativo interno.
+     */
+    private rangeEnd;
+    /**
+     * Data inicial selecionada no modo de intervalo.
+     *
+     * @internal Estado reativo interno.
+     */
+    private rangeStart;
+    /**
+     * Data de referência usada para navegação visual (mês/semana exibidos).
+     *
+     * @internal Controle de navegação do calendário.
+     */
+    private referenceDate;
+    /**
+     * Evento público emitido quando a data de referência ou a seleção mudam.
+     *
+     * Payload (`DatetimePickerDateState`):
+     * - `referenceDate`: Date — data usada para navegação visual (mês/semana exibidos).
+     * - `value`: Date | null — valor selecionado atualmente.
+     *
+     * @event dateStateChange
+     * @type {CustomEvent<DatetimePickerDateState>}
+     */
+    dateStateChange: EventEmitter<DatetimePickerDateState>;
+    /**
+     * Evento emitido quando a seleção muda.
+     *
+     * Payload (`DatetimePickerChangeDetail`):
+     * - `mode`: DatetimePickerMode — modo atual do componente (`date` | `time` | `datetime`).
+     * - `selectionMode`: DatetimePickerSelectionMode — `single` ou `range`.
+     * - `value`: Date | null | DatetimePickerDateRange — seleção atual (tipo depende de `selectionMode`).
+     * - `serializedValue`: string | undefined — representação serializada para integração com formulários.
+     *
+     * @event brDatetimePickerChange
+     * @type {CustomEvent<DatetimePickerChangeDetail>}
+     */
+    brDatetimePickerChange: EventEmitter<DatetimePickerChangeDetail>;
+    /**
+     * Evento emitido quando o valor selecionado muda.
+     *
+     * @deprecated Use `brDatetimePickerChange` para receber a seleção completa e tipada.
+     *
+     * Payload (legacy): `Date | null` — valor selecionado.
+     *
+     * @event valueChange
+     * @type {CustomEvent<Date | null>}
+     */
+    valueChange: EventEmitter<Date | null>;
+    /**
+     * Emitido ao iniciar e concluir a validação customizada.
+     *
+     * Payload (`FormValidationChangeDetail`):
+     * - `validating`: boolean — indica se a validação está em execução.
+     * - `valid`: boolean | null — resultado da validação (`null` enquanto valida).
+     * - `message`: string | null — mensagem de validação associada.
+     *
+     * @event brDatetimePickerValidationChange
+     * @type {CustomEvent<FormValidationChangeDetail>}
+     */
+    brDatetimePickerValidationChange: EventEmitter<FormValidationChangeDetail>;
+    /**
+     * ID único do contêiner de feedback interno.
+     * Gerado por `Helpers.generateUniqueId` no momento da criação da instância
+     * e usado para associar mensagens de validação ao input interno.
+     *
+     * @internal
+     */
+    private readonly feedbackId;
+    /**
+     * Snapshot da seleção inicial usada para restaurar em reset de formulário.
+     * Mantém uma cópia imutável do valor original para `formResetCallback`.
+     *
+     * @internal
+     */
+    private initialFormValue;
+    /**
+     * Contador monótono usado para invalidar execuções assíncronas de validação.
+     * Incrementado antes de cada execução; resultados com `runId` diferente são ignorados.
+     *
+     * @internal
+     */
+    private validationRunId;
+    /**
+     * Indica se o componente já completou o ciclo `componentDidLoad`.
+     * Evita executar lógica de inicialização mais de uma vez.
+     *
+     * @internal
+     */
+    private isInitialized;
+    /**
+     * Flag para evitar loops de sincronização entre `value`, `valueAsDate` e `serializedValue`.
+     * Setada temporariamente durante operações programáticas de sincronização.
+     *
+     * @internal
+     */
+    private syncingCanonicalValues;
+    /**
+     * Flag que sinaliza atualizações internas em `rangeValue`.
+     * Usada para distinguir atribuições programáticas de alterações externas.
+     *
+     * @internal
+     */
+    private syncingRangeValueInternally;
+    /**
+     * Mapeia cada modo para a função responsável por renderizar seu conteúdo.
+     * Facilita seleção de renderer sem condicionais espalhadas pelo código.
+     *
+     * @internal
+     */
+    private readonly modeRendererMap;
+    /**
+     * Indica se o listener global de clique fora do componente está anexado.
+     * Evita anexações/remoções redundantes do mesmo handler.
+     *
+     * @internal
+     */
+    private outsideClickListenerAttached;
     /**
      * Revalida o modo sempre que a prop mudar.
      *
-     * @param newValue - Valor recebido via atributo/prop.
+     * @param {string} newValue - Valor recebido via atributo/prop.
      */
     handleModeChange(newValue: string): void;
     /** Revalida o estado do formulário quando required mudar. */
@@ -276,10 +370,13 @@ export declare class DatetimePicker {
     /**
      * Aplica ou limpa a seleção da data atual conforme o novo valor da prop.
      *
-     * @param newValue - Novo estado da prop.
+     * @param {DatetimePickerInitialMoment} newValue - Novo estado da prop.
      */
     handleInitialMomentChange(newValue: DatetimePickerInitialMoment): void;
     /** Sincroniza alterações externas do valor com o estado visual e o formulário nativo. */
+    /**
+     * @param {Date | null} newValue - Novo valor recebido via prop.
+     */
     handleValueChange(newValue: Date | null): void;
     /** Converte alterações externas no valor serializado sem mudar o tipo da prop legada `value`. */
     handleSerializedValueChange(newValue?: string): void;
@@ -293,53 +390,95 @@ export declare class DatetimePicker {
      */
     handleDisabledDatesChange(newValue: DatetimePickerDisabledDates): void;
     handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
-    /** Evento público emitido quando a data de referência ou a seleção mudam. */
-    dateStateChange: EventEmitter<DatetimePickerDateState>;
-    /**
-     * Evento emitido quando o valor selecionado muda.
-     * @deprecated Use `input`/`change` e leia `event.target.value`.
-     */
-    valueChange: EventEmitter<Date | null>;
-    /** Emitido ao iniciar e concluir a validação customizada. */
-    brDatetimePickerValidationChange: EventEmitter<FormValidationChangeDetail>;
-    /** Registra o listener global somente enquanto o picker está aberto. */
     connectedCallback(): void;
-    /** Remove o listener global para evitar vazamento de eventos ao desmontar. */
+    componentWillLoad(): void;
+    componentDidLoad(): void;
     disconnectedCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    /** Restaura o estado do componente quando o formulário é restaurado. */
+    formResetCallback(): void;
     /**
-     * Normaliza o modo antes da primeira renderização e aplica a data atual quando solicitado.
+     * Restaura o estado do formulário (autofill / histórico).
+     *
+     * @param {string | File | FormData | null} state Estado serializado fornecido pelo navegador.
      */
-    componentWillLoad(): void;
-    componentDidLoad(): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
     /**
-     * Define programaticamente as datas desabilitadas por meio de array.
+     * Define programaticamente as datas desabilitadas.
      *
-     * Útil quando o componente é usado via HTML e o consumidor precisa enviar
-     * uma lista tipada em runtime.
+     * Use quando scripts externos precisam fornecer uma lista tipada de
+     * datas a bloquear no calendário. Substitui a prop `disabledDates` para
+     * atualizações imperativas.
      *
-     * @param dates - Lista de datas (Date|string) a bloquear.
+     * @param dates Lista de datas (`Date` | `string`) a bloquear, ou `null` para limpar.
+     * @returns Promise<void> — resolve quando a atualização interna for aplicada.
      */
     setDisabledDates(dates: DatetimePickerDisabledDate[] | null): Promise<void>;
-    /** Define o valor atual de forma imperativa aceitando Date, string serializada ou null. */
+    /**
+     * Define o valor do componente de forma imperativa.
+     *
+     * Aceita `Date`, string compatível com o `mode`, ou `null` para limpar a seleção.
+     * Validação de datas desabilitadas é aplicada antes da atribuição.
+     *
+     * @param value Date | string | null — valor a aplicar; `null` limpa a seleção.
+     * @returns Promise<void> — resolve quando o componente aplicar e sincronizar o valor.
+     */
     setValue(value: Date | string | null): Promise<void>;
-    /** Retorna uma cópia do valor selecionado atualmente. */
+    /**
+     * Retorna uma cópia do valor selecionado atualmente.
+     *
+     * @returns Promise<Date | null> — cópia imutável do `value` atual, ou `null`.
+     */
     getValue(): Promise<Date | null>;
-    /** Limpa valor e intervalo selecionados. */
+    /**
+     * Limpa valor e intervalo selecionados.
+     *
+     * Remove seleção atual e restaura a referência de navegação para a data atual.
+     *
+     * @returns Promise<void> — resolve após a limpeza e sincronização internas.
+     */
     clear(): Promise<void>;
-    /** Abre o picker quando o componente estiver habilitado. */
+    /**
+     * Abre o picker quando o componente estiver habilitado.
+     *
+     * @returns Promise<void> — resolve quando o estado visual for atualizado.
+     */
     open(): Promise<void>;
-    /** Fecha o picker. */
+    /**
+     * Fecha o picker.
+     *
+     * @returns Promise<void> — resolve após atualização do estado de visibilidade.
+     */
     close(): Promise<void>;
-    /** Alterna o estado de abertura do picker. */
+    /**
+     * Alterna o estado de abertura do picker.
+     *
+     * @returns Promise<void> — resolve quando a transição de estado terminar.
+     */
     toggle(): Promise<void>;
-    /** Move o foco para o input nativo interno. */
+    /**
+     * Move o foco para o input nativo interno.
+     *
+     * @returns Promise<void> — resolve imediatamente após tentar focar o elemento.
+     */
     focusInput(): Promise<void>;
-    /** Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range. */
+    /**
+     * Define um intervalo no modo atual e ativa `selectionMode="range"`.
+     *
+     * Valida datas contra bloqueios e sincroniza estado visual e de formulário.
+     * Em `datetime`, mantém os limites informados e sinaliza intervalo inválido
+     * quando o término precede o início, sem ajustar datas automaticamente.
+     *
+     * @param start Date | string | null — data inicial do intervalo.
+     * @param end Date | string | null — data final do intervalo.
+     * @returns Promise<void> — resolve quando o intervalo for aplicado e sincronizado.
+     */
     setRange(start: Date | string | null, end: Date | string | null): Promise<void>;
     /**
      * Retorna o intervalo de datas selecionado quando em modo `selectionMode="range"`.
      *
-     * @returns Objeto com datas `start` e `end`, ou `null` se não estiver em modo range.
+     * @returns Promise<{ start: Date | null; end: Date | null } | null> — objeto com `start`/`end` ou `null` quando
+     * não estiver em modo `range`.
      */
     getRange(): Promise<{
         start: Date | null;
@@ -348,80 +487,150 @@ export declare class DatetimePicker {
     /**
      * Consulta se o picker está atualmente aberto.
      *
-     * @returns `true` se o picker está visível, `false` caso contrário.
+     * @returns Promise<boolean> — `true` se o picker está visível, `false` caso contrário.
      */
     isOpen(): Promise<boolean>;
-    /** Restaura o estado inicial atualmente registrado para reset. */
+    /**
+     * Restaura o estado inicial atualmente registrado para reset.
+     *
+     * @returns Promise<void> — resolve quando a seleção inicial for restaurada.
+     */
     resetToInitial(): Promise<void>;
-    /** Permite que consumidores acionem validação nativa do formulário via host. */
+    /**
+     * Permite que consumidores acionem validação nativa do formulário via host.
+     *
+     * @returns Promise<boolean> — resultado da Constraint Validation API para o host.
+     */
     checkValidity(): Promise<boolean>;
-    /** Permite exibir mensagens nativas de validação no host. */
+    /**
+     * Permite exibir mensagens nativas de validação no host.
+     *
+     * @returns Promise<boolean> — `true` se a mensagem foi exibida e o formulário é válido.
+     */
     reportValidity(): Promise<boolean>;
-    /** Define ou limpa uma mensagem de validade customizada. */
+    /**
+     * Define ou limpa uma mensagem de validade customizada.
+     *
+     * @param message string — mensagem de validação; string vazia remove a mensagem.
+     * @returns Promise<void> — resolve após sincronizar a validade no host.
+     */
     setCustomValidity(message: string): Promise<void>;
-    /** Executa o validator do picker e retorna se a seleção atual é válida. */
+    /**
+     * Executa o validator customizado (se houver) e valida o controle.
+     *
+     * Emite eventos de início/conclusão da validação e atualiza mensagens internas.
+     *
+     * @returns Promise<boolean> — `true` se a seleção for considerada válida.
+     */
     validate(): Promise<boolean>;
-    /** Retorna um snapshot serializável da Constraint Validation API. */
+    /**
+     * Retorna um snapshot serializável da Constraint Validation API.
+     *
+     * @returns Promise<FormValidationState> — estado atual de validação do host,
+     * pronto para conversão e restauração via `formStateRestoreCallback`.
+     */
     getValidationState(): Promise<FormValidationState>;
-    /** Snapshot da seleção inicial usada para restaurar em reset de formulário. */
-    private initialFormValue;
-    private validationRunId;
-    private isInitialized;
-    private syncingCanonicalValues;
-    /** Mapeia cada modo para a função responsável por renderizar seu conteúdo. */
-    private readonly modeRendererMap;
     /**
      * Valida o modo de seleção e corrige para padrão se inválido.
      *
      * @param value - Modo informado pelo consumidor do componente.
      */
     private ensureValidSelectionMode;
-    /**
-     * Normaliza o modo de seleção logo na inicialização.
-     */
     private initializeSelectionMode;
-    /** Normaliza o dia inicial da semana logo na inicialização. */
     private initializeWeekStartsOn;
-    /** Valida o dia inicial da semana e corrige para padrão quando necessário. */
-    private ensureValidWeekStartsOn;
     /**
-     * Limpa o estado do intervalo de datas ao mudar para modo single.
+     * Valida o dia inicial da semana e corrige para padrão quando necessário.
+     *
+     * @param value unknown — valor recebido via prop/atributo a ser normalizado.
      */
+    private ensureValidWeekStartsOn;
     private clearRangeState;
-    /** Indica quando o componente está operando em seleção de intervalo por data. */
+    /**
+     * Materializa os horários exibidos pelos dois timers como limites reais.
+     * Assim o range de horário já nasce completo, o input pode representá-lo na
+     * primeira renderização e nenhum timer depende da referência do outro.
+     */
+    private initializeTimeRangeBoundaries;
     private isRangeDateSelectionMode;
     /**
-     * Resolve se o evento público deve ser emitido após um update vindo dos subcomponentes.
+     * Decide se um evento público deve ser emitido após atualização vinda de
+     * subcomponentes (calendário/relógio).
      *
-     * No modo range, o evento externo só é emitido no clique final (quando `end` é definido).
+     * @param range DatetimePickerDateRange | undefined — estado parcial do range vindo do subcomponente.
+     * @returns boolean — `true` quando o evento deve ser emitido externamente.
      */
     private resolvePublicEventEmissionForRange;
-    /** Resolve a data efetivamente selecionada no evento para validar bloqueio em single/range. */
+    /**
+     * Resolve a data efetivamente selecionada no evento para validações e bloqueios.
+     *
+     * @param range DatetimePickerDateRange | undefined — intervalo parcial (quando aplicável).
+     * @param value Date | null — valor principal vindo do subcomponente.
+     * @returns Date | null — data final a ser considerada para validação.
+     */
     private resolveSelectedDateFromEvent;
     /**
-     * Sincroniza o estado local com a emissão dos subcomponentes de data e horário.
+     * Handler disparado por `br-datetime-input` para propagar mensagens de
+     * validação do input interno para o estado do componente.
      *
-     * @param event - Evento com a data de referência e o valor selecionado.
+     * @param event CustomEvent<{ valid: boolean; message: string }> — detalhe com `valid` e `message`.
+     * @returns void
+     */
+    private handleInputValidationChange;
+    /**
+     * Identifica navegação visual que preserva integralmente o range selecionado.
+     *
+     * @param value Date | null — valor principal do evento.
+     * @param range DatetimePickerDateRange | undefined — range parcial do evento.
+     * @returns boolean — `true` quando a navegação não altera a seleção atual.
+     */
+    private isRangeNavigationState;
+    /**
+     * Consolida um evento cujo valor principal permaneceu inalterado.
+     *
+     * @param range DatetimePickerDateRange | undefined — estado parcial do range.
+     * @param shouldEmitPublicEvent boolean — indica se o evento público deve ser emitido.
+     */
+    private handleUnchangedDateState;
+    /**
+     * Emite a seleção parcial de range quando os eventos públicos foram adiados
+     * para evitar duplicidade com listeners legados.
+     *
+     * @param range DatetimePickerDateRange | undefined — snapshot parcial do range.
+     * @param shouldEmitPublicEvent boolean — se deve ser emitido publicamente.
+     */
+    private emitPendingRangeChange;
+    /**
+     * Handler principal que consolida eventos de `br-date-picker` / `br-time-picker`.
+     * Contém lógica de proteção contra valores desabilitados, navegação e emissão
+     * de eventos públicos apropriados.
+     *
+     * @param event CustomEvent<DatetimePickerDateState> — detalhe com `referenceDate`, `value` e `range`.
      */
     private handleDateStateChange;
+    /**
+     * Atualiza somente o horário de um dos limites do intervalo.
+     *
+     * @param boundary 'start' | 'end' — qual limite será atualizado.
+     * @param event CustomEvent<DatetimePickerDateState> — detalhe com novo `value`.
+     */
+    private handleRangeTimeStateChange;
+    private readonly handleRangeStartTimeStateChange;
+    private readonly handleRangeEndTimeStateChange;
     /**
      * Alterna visibilidade do picker quando o input solicita.
+     *
+     * @param event Event — evento de toggle vindo do input.
      */
     private handleTogglePicker;
     /**
      * Fecha o picker quando o clique acontece fora do host.
+     *
+     * @param event MouseEvent — clique ocorrido no documento.
      */
     private handleOutsideClick;
-    private outsideClickListenerAttached;
     private attachOutsideClickListener;
     private detachOutsideClickListener;
-    /**
-     * Garante que o componente inicie com um modo suportado.
-     */
     private initializeMode;
-    /**
-     * Normaliza a coleção de datas desabilitadas na inicialização.
-     */
     private initializeDisabledDates;
     /**
      * Normaliza e aplica as datas desabilitadas, limpando valor atual quando necessário.
@@ -429,9 +638,6 @@ export declare class DatetimePicker {
      * @param value - Valor bruto recebido por prop/atributo ou método público.
      */
     private syncDisabledDates;
-    /**
-     * Aplica a seleção inicial configurada na prop.
-     */
     private initializeDefaultValue;
     /**
      * Aplica a seleção inicial recebida, com normalização de valores inválidos.
@@ -439,38 +645,99 @@ export declare class DatetimePicker {
      * @param selection - Configuração de seleção inicial.
      */
     private applyInitialMoment;
-    /** Indica se o estado serializado deve ser interpretado como intervalo. */
     private isRangeRestoreMode;
-    /** Restaura estado de intervalo a partir do valor serializado do formulário. */
+    /**
+     * Restaura estado de intervalo a partir do valor serializado do formulário.
+     *
+     * @param serializedState string — valor serializado vindo do formulário.
+     */
     private restoreRangeStateFromSerialized;
-    /** Restaura estado de seleção única a partir do valor serializado do formulário. */
+    /**
+     * Restaura estado de seleção única a partir do valor serializado do formulário.
+     *
+     * @param serializedState string — valor serializado vindo do formulário.
+     */
     private restoreSingleStateFromSerialized;
-    /** Resolve Date|null a partir de valores aceitos pelos métodos públicos. */
+    /**
+     * Converte entradas aceitas por métodos públicos em `Date | null`.
+     *
+     * @param value Date | string | null — valor bruto recebido pelo método público.
+     * @param mode DatetimePickerMode — modo atual para parsing de strings.
+     * @returns Date | null — representação normalizada ou `null` se inválida.
+     */
     private parseMethodValue;
-    /** Aplica a ponte serializada usando os mesmos parsers já usados por restore de formulário. */
+    /**
+     * Aplica a ponte serializada usando os mesmos parsers já usados por restore de formulário.
+     *
+     * @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. */
+    /**
+     * Retorna o mesmo valor que será submetido pelo ElementInternals.
+     *
+     * @returns string — valor serializado pronto para `setFormValue`.
+     */
     private getSerializedValue;
     private sameDate;
-    /** Retorna a âncora de validação, ou undefined antes do primeiro render. */
+    /**
+     * Busca o input nativo interno para ações imperativas de foco.
+     *
+     * @returns HTMLElement | undefined — elemento `input` nativo interno, quando disponível.
+     */
     private getNativeInputElement;
-    private datetimeInputElement?;
-    /** Atualiza estado interno, FormData e validação com uma única chamada. */
+    /**
+     * Atualiza estado interno, FormData e validação com uma única chamada.
+     *
+     * @param nextValue Date | null — próximo valor a ser aplicado no componente.
+     * @param shouldEmitPublicEvent boolean — controla emissão de eventos públicos.
+     * @returns void
+     */
     private setComponentValue;
     /** Propaga o estado atual consolidado para consumidores externos do componente raiz. */
     private emitDateStateChange;
-    /** Expande o intervalo completo e marca quais dias estão desabilitados. */
+    /** Emite o contrato público sem expor detalhes incidentais do estado interno. */
+    private emitCanonicalChange;
+    /**
+     * Serializa uma data civil sem conversão para UTC ou mudança de dia.
+     *
+     * @param value Date — data a serializar (somente componente civil).
+     * @returns string — formato `YYYY-MM-DD`.
+     */
+    private serializeDateOnly;
+    /**
+     * Serializa um limite do intervalo conforme o modo sem expor objetos Date no payload.
+     *
+     * @param value Date | null — limite a serializar.
+     * @returns string | null — representação serializada do limite ou `null`.
+     */
+    private serializeRangeBoundary;
+    /**
+     * Expande o intervalo completo e marca quais dias estão desabilitados.
+     *
+     * @param start Date — início do intervalo.
+     * @param end Date — fim do intervalo.
+     * @returns Array<{date: Date, disabled: boolean}> — lista diária com flags.
+     */
     private buildRangeDatesState;
-    /** Restaura seleção e data de referência a partir de uma data já validada. */
+    /**
+     * Restaura seleção e data de referência a partir de uma data já validada.
+     *
+     * @param nextValue Date | null — valor validado a ser restaurado como seleção.
+     */
     private restoreSelection;
-    /** Atualiza o estado local de intervalo a partir do evento do calendário. */
+    /**
+     * Atualiza o estado local de intervalo a partir do evento do calendário.
+     *
+     * @param nextRange DatetimePickerDateRange | undefined — novo snapshot do intervalo.
+     */
     private setRangeState;
-    /** Mantém ElementInternals sincronizado com estado e regras do componente. */
     private updateFormInternals;
     /** Atualiza o valor submetido no FormData do form-associated custom element. */
     private syncFormValue;
+    /** Deriva o erro de ordenação sem modificar os limites escolhidos. */
+    private getRangeOrderValidationMessage;
     /** Espelha a regra de required no mecanismo nativo de validade. */
     private syncFormValidity;
     private parseConstraintValue;
@@ -502,24 +769,26 @@ export declare class DatetimePicker {
      * Agrupa os bindings compartilhados para evitar divergência entre data e horário.
      */
     private getSharedDateStateBindings;
+    /**
+     * Fecha o picker ao pressionar Escape, devolvendo o foco ao input interno.
+     *
+     * @param event - Evento de teclado disparado em qualquer descendente do componente.
+     */
+    private handlePickerKeydown;
     /** Renderiza o campo de entrada responsável por abrir e sincronizar o picker. */
     private renderInputField;
     /** Renderiza apenas o seletor de data. */
     private renderDatePicker;
-    /** Renderiza apenas o seletor de hora. */
+    /** Renderiza um seletor de hora simples ou um limite do intervalo. */
     private renderTimePicker;
+    /** Renderiza os horários inicial e final lado a lado no modo range. */
+    private renderRangeTimePickers;
     /**
      * Renderiza a combinação de data e horário no modo `datetime`.
      */
     private renderDateTimePicker;
     /** Renderiza o separador visual entre data e hora no modo combinado. */
     private renderDivider;
-    /**
-     * Fecha o picker ao pressionar Escape, devolvendo o foco ao input interno.
-     *
-     * @param event - Evento de teclado disparado em qualquer descendente do componente.
-     */
-    private handlePickerKeydown;
     /**
      * Resolve o conteúdo interno conforme o modo atual do componente.
      */