@govbr-ds/webcomponents 2.2.0 → 2.4.0

package/dist/collection/components/datetime-picker/datetime-picker.js

@@ -9,48 +9,52 @@ import { set } from "date-fns/set";
 import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../shared/utils/event";
 import { getFormValidationState, isFormControlDisabled, setFormValidity, } from "../../shared/utils/form";
-import { generateUniqueId } from "../../shared/utils/id";
-import { reportInvalidPropValue } from "../../shared/utils/prop-warning";
+import Helpers from "../../shared/utils/helpers";
 import { hasAssignedSlotContent } from "../../shared/utils/slot";
 import { resolveSsrLocalDate } from "../../shared/utils/ssr-date";
 import { resolveFormValidator, runFormValidator } from "../../shared/utils/validator";
-import { DATETIME_PICKER_LOCALE, DATETIME_PICKER_MODE } from "./datetime-picker-constants";
+import { DATETIME_PICKER_LOCALE, DATETIME_PICKER_MODE, DATETIME_RANGE_ORDER_MESSAGE, } from "./datetime-picker-constants";
 import { hasDatetimePickerMissingValue, parseDatetimePickerSerializedRange, parseDatetimePickerSerializedValue, serializeDatetimePickerFormValue, } from "./datetime-picker-form-associated";
-import { isValidDatetimePickerDateRange, normalizeDatetimePickerDisabledDates, normalizeDatetimePickerInitialMoment, normalizeDatetimePickerMode, normalizeDatetimePickerSelectionMode, normalizeDatetimePickerWeekStartsOn, } from "./datetime-picker-props-validation";
+import { normalizeDatetimePickerDisabledDates, normalizeDatetimePickerInitialMoment, normalizeDatetimePickerMode, normalizeDatetimePickerSelectionMode, normalizeDatetimePickerWeekStartsOn, } from "./datetime-picker-props-validation";
 /**
- * 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` é 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.
  *
  * ### Para que serve
  *
- * - **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.
+ * - 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`.
  *
  * ### Quando utilizar
  *
- * - **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).
+ * - 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.
  *
  * ### Composição e Subcomponentes
  *
- * | Subcomponente | Papel | Regra de uso |
+ * | Componente | 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. |
+ * | `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`. |
+ *
+ * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
  *
  * ### Como os subcomponentes se relacionam
  *
- * 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`).
+ * 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.
+ *
+ * `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 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).
+ * 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`.
  *
-
- * @category Formulários, Seleção
+ * 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).
+ *
+ * @category Formulários
  * @status stable
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  * @part container - Parte para o container base do seletor.
@@ -63,188 +67,334 @@ import { isValidDatetimePickerDateRange, normalizeDatetimePickerDisabledDates, n
 export class DatetimePicker {
     constructor() {
         /**
-         * Controla se o conteúdo do picker está visível.
-         */
-        this.isPickerOpen = false;
-        this.formDisabled = false;
-        this.hasFeedbackSlot = false;
-        this.customValidationMessage = '';
-        this.validatorMessage = null;
-        this.isValidating = false;
-        this.feedbackId = generateUniqueId('br-datetime-picker-feedback');
-        /** Lista normalizada de datas indisponíveis para seleção. */
-        this.normalizedDisabledDates = [];
-        /** Data final selecionada no modo de intervalo. */
-        this.rangeEnd = null;
-        /** Data inicial selecionada no modo de intervalo. */
-        this.rangeStart = null;
-        /**
-         * Mantém a data de referência que orienta a navegação visual do calendário.
-         */
-        this.referenceDate = new Date();
-        /**
-         * 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'
          */
         this.mode = DATETIME_PICKER_MODE.DEFAULT;
         /**
-         * Define o locale usado pelos subcomponentes para formatar datas e rótulos.
+         * Locale usado para formatação e rótulos.
          *
          * @default 'pt-BR'
          */
         this.locale = DATETIME_PICKER_LOCALE.DEFAULT;
         /**
-         * Define o placeholder exibido no campo de entrada do datetime picker.
+         * Texto placeholder exibido no input.
          *
          * @default ''
          */
         this.placeholder = '';
-        /** Nome do campo para submissão em formulários nativos. */
+        /**
+         * Nome do campo para submissão em formulários nativos.
+         *
+         * @default ''
+         */
         this.name = '';
-        /** 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
+         */
         this.required = false;
         /**
-         * 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
          */
         this.min = 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
          */
         this.max = null;
         /**
-         * 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'
          */
         this.selectionMode = 'single';
         /**
-         * 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
          */
         this.weekStartsOn = 0;
         /**
-         * 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>
-         * ```
          */
         this.initialMoment = null;
         /**
-         * 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).
          *
-         * @example
-         * ```js
-         * const picker = document.querySelector('br-datetime-picker');
-         * picker.value = new Date(2026, 8, 7, 14, 30);
-         * ```
+         * Pode ser controlado externamente e é refletido internamente.
+         *
+         * @default null
          */
         this.value = null;
         /**
          * Desabilita toda a interação do componente.
          *
-         * Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários.
-         *
          * @default false
          */
         this.disabled = false;
         /**
-         * 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'];
-         * ```
          */
         this.disabledDates = null;
         /**
-         * 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
          */
         this.fixedRowCount = false;
-        /** Snapshot da seleção inicial usada para restaurar em reset de formulário. */
+        /**
+         * Controla se o conteúdo do picker está visível.
+         *
+         * @internal Estado reativo interno; não usar externamente.
+         */
+        this.isPickerOpen = false;
+        /**
+         * Indica se o formulário associado desabilitou o componente.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.formDisabled = false;
+        /**
+         * Indica se existe slot `feedback` presente no host.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.hasFeedbackSlot = false;
+        /**
+         * Mensagem de validação customizada definida por `setCustomValidity`.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.customValidationMessage = '';
+        /**
+         * Mensagem retornada pelo validator customizado, se houver.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.validatorMessage = null;
+        /**
+         * Mensagem textual de validação proveniente do input interno.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.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
+         */
+        this.inputValidationPending = false;
+        /**
+         * Indicador de execução do validator assíncrono.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.isValidating = false;
+        /**
+         * Lista normalizada de datas indisponíveis para seleção.
+         *
+         * @internal Mantida em formato `Date[]` para uso interno pelo calendário.
+         */
+        this.normalizedDisabledDates = [];
+        /**
+         * Data final selecionada no modo de intervalo.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.rangeEnd = null;
+        /**
+         * Data inicial selecionada no modo de intervalo.
+         *
+         * @internal Estado reativo interno.
+         */
+        this.rangeStart = null;
+        /**
+         * Data de referência usada para navegação visual (mês/semana exibidos).
+         *
+         * @internal Controle de navegação do calendário.
+         */
+        this.referenceDate = new Date();
+        /**
+         * 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
+         */
+        this.feedbackId = Helpers.generateUniqueId('br-datetime-picker-feedback');
+        /**
+         * 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
+         */
         this.initialFormValue = null;
+        /**
+         * 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
+         */
         this.validationRunId = 0;
+        /**
+         * Indica se o componente já completou o ciclo `componentDidLoad`.
+         * Evita executar lógica de inicialização mais de uma vez.
+         *
+         * @internal
+         */
         this.isInitialized = false;
+        /**
+         * Flag para evitar loops de sincronização entre `value`, `valueAsDate` e `serializedValue`.
+         * Setada temporariamente durante operações programáticas de sincronização.
+         *
+         * @internal
+         */
         this.syncingCanonicalValues = false;
-        /** Mapeia cada modo para a função responsável por renderizar seu conteúdo. */
+        /**
+         * Flag que sinaliza atualizações internas em `rangeValue`.
+         * Usada para distinguir atribuições programáticas de alterações externas.
+         *
+         * @internal
+         */
+        this.syncingRangeValueInternally = false;
+        /**
+         * 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
+         */
         this.modeRendererMap = {
             [DATETIME_PICKER_MODE.DATE]: () => this.renderDatePicker(),
-            [DATETIME_PICKER_MODE.TIME]: () => this.renderTimePicker(),
+            [DATETIME_PICKER_MODE.TIME]: () => this.selectionMode === 'range' ? this.renderRangeTimePickers() : this.renderTimePicker(),
             [DATETIME_PICKER_MODE.DATETIME]: () => this.renderDateTimePicker(),
         };
         /**
-         * Sincroniza o estado local com a emissão dos subcomponentes de data e horário.
+         * Indica se o listener global de clique fora do componente está anexado.
+         * Evita anexações/remoções redundantes do mesmo handler.
+         *
+         * @internal
+         */
+        this.outsideClickListenerAttached = false;
+        /**
+         * Handler disparado por `br-datetime-input` para propagar mensagens de
+         * validação do input interno para o estado do componente.
+         *
+         * @param event CustomEvent<{ valid: boolean; message: string }> — detalhe com `valid` e `message`.
+         * @returns void
+         */
+        this.handleInputValidationChange = (event) => {
+            event.stopPropagation();
+            const valid = event.detail.valid;
+            if (valid === null) {
+                // usuário está editando: escondemos a mensagem visual, mas mantemos
+                // o estado de validade indefinido até commit/blur/enter
+                this.inputValidationMessage = '';
+                this.inputValidationPending = true;
+            }
+            else {
+                this.inputValidationMessage = valid ? '' : event.detail.message;
+                this.inputValidationPending = false;
+            }
+            this.syncFormValidity();
+        };
+        /**
+         * 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 - Evento com a data de referência e o valor selecionado.
+         * @param event CustomEvent<DatetimePickerDateState> — detalhe com `referenceDate`, `value` e `range`.
          */
         this.handleDateStateChange = (event) => {
-            // Evita que o evento interno dos subcomponentes vaze para fora do host.
             event.stopPropagation();
             if (this.isDisabled()) {
                 return;
             }
+            const origin = event.detail.origin;
+            if (origin !== 'BR-DATETIME-INPUT') {
+                this.inputValidationMessage = '';
+            }
             const { referenceDate, value, range } = event.detail;
+            if (this.isRangeNavigationState(value, range)) {
+                this.referenceDate = toDate(referenceDate);
+                this.updateFormInternals();
+                return;
+            }
             const selectedDate = this.resolveSelectedDateFromEvent(range, value);
             if (selectedDate !== null && this.isDateDisabled(selectedDate)) {
                 return;
             }
             this.referenceDate = toDate(referenceDate);
             const shouldEmitPublicEvent = this.resolvePublicEventEmissionForRange(range);
-            this.setComponentValue(value === null ? null : toDate(value), shouldEmitPublicEvent && this.isInitialized);
+            const nextValue = value === null ? null : toDate(value);
+            if (this.sameDate(this.value, nextValue)) {
+                this.handleUnchangedDateState(range, shouldEmitPublicEvent);
+                return;
+            }
+            this.setComponentValue(nextValue, shouldEmitPublicEvent && this.isInitialized);
+            this.emitPendingRangeChange(range, shouldEmitPublicEvent);
         };
+        /**
+         * 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`.
+         */
+        this.handleRangeTimeStateChange = (boundary, event) => {
+            event.stopPropagation();
+            if (this.isDisabled() || event.detail.value === null)
+                return;
+            const displayedStart = this.cloneDate(this.rangeStart ?? this.referenceDate);
+            const displayedEnd = this.cloneDate(this.rangeEnd ?? this.referenceDate);
+            if (this.rangeStart === null)
+                this.rangeStart = displayedStart;
+            if (this.rangeEnd === null)
+                this.rangeEnd = displayedEnd;
+            const selected = toDate(event.detail.value);
+            const current = boundary === 'start' ? this.rangeStart : this.rangeEnd;
+            const base = current ?? this.referenceDate;
+            const next = set(base, {
+                hours: selected.getHours(),
+                minutes: selected.getMinutes(),
+                seconds: 0,
+                milliseconds: 0,
+            });
+            if (boundary === 'start')
+                this.rangeStart = next;
+            else
+                this.rangeEnd = next;
+            const nextComponentValue = this.rangeEnd ?? this.rangeStart;
+            if (!this.sameDate(this.value, nextComponentValue)) {
+                this.value = this.cloneDate(nextComponentValue);
+            }
+            this.syncCanonicalValues();
+            if (this.isInitialized) {
+                this.emitDateStateChange();
+                void this.validate();
+            }
+            this.updateFormInternals();
+        };
+        this.handleRangeStartTimeStateChange = (event) => this.handleRangeTimeStateChange('start', event);
+        this.handleRangeEndTimeStateChange = (event) => this.handleRangeTimeStateChange('end', event);
         /**
          * Alterna visibilidade do picker quando o input solicita.
+         *
+         * @param event Event — evento de toggle vindo do input.
          */
         this.handleTogglePicker = (event) => {
             if (this.isDisabled()) {
@@ -254,11 +404,14 @@ export class DatetimePicker {
             const willOpen = !this.isPickerOpen;
             if (willOpen) {
                 this.referenceDate = this.value === null ? toDate(new Date()) : toDate(this.value);
+                this.initializeTimeRangeBoundaries();
             }
             this.isPickerOpen = willOpen;
         };
         /**
          * Fecha o picker quando o clique acontece fora do host.
+         *
+         * @param event MouseEvent — clique ocorrido no documento.
          */
         this.handleOutsideClick = (event) => {
             const eventPath = event.composedPath();
@@ -267,7 +420,6 @@ export class DatetimePicker {
             }
             this.isPickerOpen = false;
         };
-        this.outsideClickListenerAttached = false;
         /**
          * Fecha o picker ao pressionar Escape, devolvendo o foco ao input interno.
          *
@@ -278,42 +430,17 @@ export class DatetimePicker {
                 return;
             event.stopPropagation();
             this.isPickerOpen = false;
-            void this.focusInput();
+            this.getNativeInputElement()?.focus();
         };
     }
-    formDisabledCallback(disabled) {
-        this.formDisabled = disabled;
-    }
-    /** API nativa de reset de form-associated custom elements. */
-    formResetCallback() {
-        this.customValidationMessage = '';
-        this.validatorMessage = null;
-        this.validationRunId++;
-        this.restoreSelection(this.initialFormValue);
-    }
-    /** API nativa de restauração de estado (histórico/autofill) do formulário. */
-    formStateRestoreCallback(state) {
-        if (typeof state !== 'string') {
-            this.restoreSelection(null);
-            return;
-        }
-        if (this.isRangeRestoreMode()) {
-            this.restoreRangeStateFromSerialized(state);
-            return;
-        }
-        this.restoreSingleStateFromSerialized(state);
-    }
     /**
      * 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) {
         this.ensureValidMode(newValue);
-        if (this.selectionMode === 'range' && this.mode !== DATETIME_PICKER_MODE.DATE) {
-            this.selectionMode = 'single';
-            return;
-        }
+        this.initializeTimeRangeBoundaries();
         this.updateFormInternals();
     }
     /** Revalida o estado do formulário quando required mudar. */
@@ -330,14 +457,11 @@ export class DatetimePicker {
     /** Reage a mudanças no modo de seleção e limpa intervalo quando necessário. */
     handleSelectionModeChange(newValue) {
         this.ensureValidSelectionMode(newValue);
-        if (this.selectionMode === 'range' && this.mode !== DATETIME_PICKER_MODE.DATE) {
-            this.mode = DATETIME_PICKER_MODE.DATE;
-            return;
-        }
         if (this.selectionMode === 'single') {
             this.clearRangeState();
             return;
         }
+        this.initializeTimeRangeBoundaries();
         this.updateFormInternals();
     }
     /** Revalida o dia inicial da semana sempre que a prop mudar. */
@@ -347,13 +471,16 @@ export 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) {
         this.applyInitialMoment(newValue, this.isInitialized);
         this.initialFormValue = this.cloneDate(this.value);
     }
     /** 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) {
         const normalizedValue = newValue instanceof Date && !Number.isNaN(newValue.getTime()) ? toDate(newValue) : null;
         if (newValue !== null && normalizedValue === null) {
@@ -398,45 +525,33 @@ export class DatetimePicker {
         this.syncDisabledDates(newValue);
     }
     handleRangeValueChange(newValue) {
-        if (!newValue || this.selectionMode !== 'range')
+        if (this.syncingRangeValueInternally || !newValue || this.selectionMode !== 'range')
             return;
-        if (!isValidDatetimePickerDateRange(newValue)) {
-            reportInvalidPropValue(this.el, 'rangeValue', newValue, 'Informe um objeto com `start` e `end` como Date válido ou null.', 'Mantendo o último intervalo efetivo.');
-            return;
-        }
         this.rangeStart = this.cloneDate(newValue.start);
         this.rangeEnd = this.cloneDate(newValue.end);
-        const nextValue = newValue.end ?? newValue.start;
-        this.referenceDate = nextValue ? toDate(nextValue) : this.referenceDate;
-        this.setComponentValue(nextValue);
+        const nextValue = this.rangeEnd ?? this.rangeStart;
+        this.setComponentValue(nextValue, false);
     }
-    /** Registra o listener global somente enquanto o picker está aberto. */
     connectedCallback() {
         if (this.isPickerOpen)
             this.attachOutsideClickListener();
     }
-    /** Remove o listener global para evitar vazamento de eventos ao desmontar. */
-    disconnectedCallback() {
-        this.detachOutsideClickListener();
-    }
-    /**
-     * Normaliza o modo antes da primeira renderização e aplica a data atual quando solicitado.
-     */
     componentWillLoad() {
-        // A inicialização dos defaults sincroniza os espelhos; preserve as entradas do consumidor.
-        const { serializedValue, valueAsDate } = this;
+        const initialSerializedValue = this.serializedValue;
+        const initialValueAsDate = this.valueAsDate;
         this.referenceDate = resolveSsrLocalDate(this.el, this.referenceDate);
         this.initializeMode();
         this.initializeSelectionMode();
         this.initializeWeekStartsOn();
         this.initializeDisabledDates();
         this.initializeDefaultValue();
-        if (serializedValue !== undefined) {
-            this.restoreSerializedValue(serializedValue);
+        if (initialSerializedValue !== undefined) {
+            this.restoreSerializedValue(initialSerializedValue);
         }
-        else if (valueAsDate !== undefined) {
-            this.handleValueAsDateChange(valueAsDate);
+        else if (initialValueAsDate !== undefined) {
+            this.handleValueAsDateChange(initialValueAsDate);
         }
+        this.initializeTimeRangeBoundaries(true);
         this.initialFormValue = this.cloneDate(this.value);
         this.syncCanonicalValues();
         this.updateFormInternals();
@@ -445,18 +560,58 @@ export class DatetimePicker {
         this.isInitialized = true;
         this.hasFeedbackSlot = this.el.querySelector('[slot="feedback"]') !== null;
     }
+    disconnectedCallback() {
+        this.detachOutsideClickListener();
+    }
+    formDisabledCallback(disabled) {
+        this.formDisabled = disabled;
+    }
+    /** Restaura o estado do componente quando o formulário é restaurado. */
+    formResetCallback() {
+        this.customValidationMessage = '';
+        this.validatorMessage = null;
+        this.inputValidationMessage = '';
+        this.validationRunId++;
+        this.restoreSelection(this.initialFormValue);
+    }
+    /**
+     * Restaura o estado do formulário (autofill / histórico).
+     *
+     * @param {string | File | FormData | null} state Estado serializado fornecido pelo navegador.
+     */
+    formStateRestoreCallback(state) {
+        if (typeof state !== 'string') {
+            this.restoreSelection(null);
+            return;
+        }
+        if (this.isRangeRestoreMode()) {
+            this.restoreRangeStateFromSerialized(state);
+            return;
+        }
+        this.restoreSingleStateFromSerialized(state);
+    }
     /**
-     * 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.
      */
     async setDisabledDates(dates) {
         this.syncDisabledDates(dates);
     }
-    /** 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.
+     */
     async setValue(value) {
         if (this.isDisabled()) {
             return;
@@ -473,18 +628,32 @@ export class DatetimePicker {
         this.referenceDate = nextValue === null ? toDate(new Date()) : toDate(nextValue);
         this.setComponentValue(nextValue);
     }
-    /** 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`.
+     */
     async getValue() {
         return this.cloneDate(this.value);
     }
-    /** 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.
+     */
     async clear() {
         this.rangeStart = null;
         this.rangeEnd = null;
         this.referenceDate = toDate(new Date());
         this.setComponentValue(null);
     }
-    /** 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.
+     */
     async open() {
         if (this.isDisabled()) {
             return;
@@ -492,11 +661,19 @@ export class DatetimePicker {
         this.referenceDate = this.value === null ? toDate(new Date()) : toDate(this.value);
         this.isPickerOpen = true;
     }
-    /** Fecha o picker. */
+    /**
+     * Fecha o picker.
+     *
+     * @returns Promise<void> — resolve após atualização do estado de visibilidade.
+     */
     async close() {
         this.isPickerOpen = false;
     }
-    /** 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.
+     */
     async toggle() {
         if (this.isPickerOpen) {
             await this.close();
@@ -504,20 +681,32 @@ export class DatetimePicker {
         }
         await this.open();
     }
-    /** 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.
+     */
     async focusInput() {
-        const input = this.datetimeInputElement ?? this.el.shadowRoot?.querySelector('br-datetime-input');
-        await input?.focusInput?.();
+        this.getNativeInputElement()?.focus();
     }
-    /** 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.
+     */
     async setRange(start, end) {
         if (this.isDisabled()) {
             return;
         }
         this.selectionMode = 'range';
-        this.mode = DATETIME_PICKER_MODE.DATE;
-        const normalizedStart = this.parseMethodValue(start, DATETIME_PICKER_MODE.DATE);
-        const normalizedEnd = this.parseMethodValue(end, DATETIME_PICKER_MODE.DATE);
+        const normalizedStart = this.parseMethodValue(start, this.mode);
+        const normalizedEnd = this.parseMethodValue(end, this.mode);
         if ((normalizedStart !== null && this.isDateDisabled(normalizedStart)) ||
             (normalizedEnd !== null && this.isDateDisabled(normalizedEnd))) {
             this.clearRangeState();
@@ -525,17 +714,18 @@ export class DatetimePicker {
         }
         this.rangeStart = this.cloneDate(normalizedStart);
         this.rangeEnd = this.cloneDate(normalizedEnd);
-        const nextValue = normalizedEnd ?? normalizedStart;
+        const nextValue = this.rangeEnd ?? this.rangeStart;
         this.referenceDate = nextValue === null ? toDate(new Date()) : toDate(nextValue);
         this.setComponentValue(nextValue);
     }
     /**
      * 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`.
      */
     async getRange() {
-        if (this.selectionMode !== 'range' || this.mode !== DATETIME_PICKER_MODE.DATE) {
+        if (this.selectionMode !== 'range') {
             return null;
         }
         return {
@@ -546,29 +736,52 @@ export 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.
      */
     async isOpen() {
         return this.isPickerOpen;
     }
-    /** 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.
+     */
     async resetToInitial() {
         this.restoreSelection(this.initialFormValue);
     }
-    /** 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.
+     */
     async checkValidity() {
         return this.elementInternals.checkValidity();
     }
-    /** 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.
+     */
     async reportValidity() {
         return this.elementInternals.reportValidity();
     }
-    /** 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.
+     */
     async setCustomValidity(message) {
         this.customValidationMessage = message;
         this.syncFormValidity();
     }
-    /** 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.
+     */
     async validate() {
         const validator = resolveFormValidator(this.validator);
         if (!validator || this.isDisabled())
@@ -577,9 +790,16 @@ export class DatetimePicker {
         this.isValidating = true;
         this.validatorMessage = null;
         this.syncFormValidity();
-        this.brDatetimePickerValidationChange.emit({ validating: true, valid: null, message: null });
+        this.brDatetimePickerValidationChange.emit({
+            validating: true,
+            valid: null,
+            message: null,
+        });
         const value = this.selectionMode === 'range'
-            ? { start: this.cloneDate(this.rangeStart), end: this.cloneDate(this.rangeEnd) }
+            ? {
+                start: this.cloneDate(this.rangeStart),
+                end: this.cloneDate(this.rangeEnd),
+            }
             : this.cloneDate(this.value);
         const message = await runFormValidator(validator, value);
         if (runId !== this.validationRunId)
@@ -588,10 +808,19 @@ export class DatetimePicker {
         this.isValidating = false;
         this.syncFormValidity();
         const valid = message === null && (await this.checkValidity());
-        this.brDatetimePickerValidationChange.emit({ validating: false, valid, message });
+        this.brDatetimePickerValidationChange.emit({
+            validating: false,
+            valid,
+            message,
+        });
         return valid;
     }
-    /** 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`.
+     */
     async getValidationState() {
         return getFormValidationState(this.elementInternals);
     }
@@ -603,36 +832,52 @@ export class DatetimePicker {
     ensureValidSelectionMode(value) {
         this.selectionMode = normalizeDatetimePickerSelectionMode(value);
     }
-    /**
-     * Normaliza o modo de seleção logo na inicialização.
-     */
     initializeSelectionMode() {
         this.handleSelectionModeChange(this.selectionMode);
     }
-    /** Normaliza o dia inicial da semana logo na inicialização. */
     initializeWeekStartsOn() {
         this.handleWeekStartsOnChange(this.weekStartsOn);
     }
-    /** Valida o dia inicial da semana e corrige para padrão quando necessário. */
+    /**
+     * 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.
+     */
     ensureValidWeekStartsOn(value) {
         this.weekStartsOn = normalizeDatetimePickerWeekStartsOn(value);
     }
-    /**
-     * Limpa o estado do intervalo de datas ao mudar para modo single.
-     */
     clearRangeState() {
         this.rangeStart = null;
         this.rangeEnd = null;
         this.updateFormInternals();
     }
-    /** 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.
+     */
+    initializeTimeRangeBoundaries(duringInitialization = false) {
+        if ((!this.isInitialized && !duringInitialization) ||
+            this.selectionMode !== 'range' ||
+            this.mode !== DATETIME_PICKER_MODE.TIME) {
+            return;
+        }
+        const fallback = this.cloneDate(this.value ?? this.referenceDate);
+        if (this.rangeStart === null)
+            this.rangeStart = this.cloneDate(fallback);
+        if (this.rangeEnd === null)
+            this.rangeEnd = this.cloneDate(fallback);
+        this.value = this.cloneDate(this.rangeEnd);
+    }
     isRangeDateSelectionMode() {
-        return this.selectionMode === 'range' && this.mode === DATETIME_PICKER_MODE.DATE;
+        return this.selectionMode === 'range';
     }
     /**
-     * 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.
      */
     resolvePublicEventEmissionForRange(range) {
         if (!this.isRangeDateSelectionMode()) {
@@ -645,13 +890,63 @@ export class DatetimePicker {
         this.setRangeState(range);
         return isFinalRangeClick;
     }
-    /** 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.
+     */
     resolveSelectedDateFromEvent(range, value) {
         if (!this.isRangeDateSelectionMode() || range === undefined) {
             return value;
         }
         return range.end ?? range.start ?? value;
     }
+    /**
+     * 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.
+     */
+    isRangeNavigationState(value, range) {
+        return (range !== undefined &&
+            this.sameDate(range.start, this.rangeStart) &&
+            this.sameDate(range.end, this.rangeEnd) &&
+            this.sameDate(value, this.value));
+    }
+    /**
+     * 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.
+     */
+    handleUnchangedDateState(range, shouldEmitPublicEvent) {
+        this.syncCanonicalValues();
+        const shouldNotifyRange = this.isInitialized && this.isRangeDateSelectionMode() && range !== undefined;
+        if (shouldNotifyRange && shouldEmitPublicEvent) {
+            this.emitDateStateChange();
+            void this.validate();
+        }
+        else if (shouldNotifyRange) {
+            this.emitCanonicalChange(range);
+        }
+        this.updateFormInternals();
+    }
+    /**
+     * 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.
+     */
+    emitPendingRangeChange(range, shouldEmitPublicEvent) {
+        if (shouldEmitPublicEvent || !this.isInitialized || !this.isRangeDateSelectionMode() || range === undefined) {
+            return;
+        }
+        this.emitCanonicalChange(range);
+    }
     attachOutsideClickListener() {
         if (this.outsideClickListenerAttached)
             return;
@@ -664,15 +959,9 @@ export class DatetimePicker {
         document.removeEventListener('click', this.handleOutsideClick);
         this.outsideClickListenerAttached = false;
     }
-    /**
-     * Garante que o componente inicie com um modo suportado.
-     */
     initializeMode() {
         this.ensureValidMode(this.mode);
     }
-    /**
-     * Normaliza a coleção de datas desabilitadas na inicialização.
-     */
     initializeDisabledDates() {
         this.syncDisabledDates(this.disabledDates);
     }
@@ -693,9 +982,6 @@ export class DatetimePicker {
             this.setComponentValue(null);
         }
     }
-    /**
-     * Aplica a seleção inicial configurada na prop.
-     */
     initializeDefaultValue() {
         if (this.value instanceof Date && !Number.isNaN(this.value.getTime())) {
             this.referenceDate = toDate(this.value);
@@ -736,13 +1022,16 @@ export class DatetimePicker {
         this.rangeEnd = null;
         this.setComponentValue(selectedDate, shouldEmitEvents);
     }
-    /** Indica se o estado serializado deve ser interpretado como intervalo. */
     isRangeRestoreMode() {
-        return this.selectionMode === 'range' && this.mode === DATETIME_PICKER_MODE.DATE;
+        return this.selectionMode === 'range';
     }
-    /** 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.
+     */
     restoreRangeStateFromSerialized(serializedState) {
-        const restoredRange = parseDatetimePickerSerializedRange(serializedState);
+        const restoredRange = parseDatetimePickerSerializedRange(serializedState, this.mode, this.referenceDate);
         if (restoredRange === null) {
             this.restoreSelection(null);
             return;
@@ -752,7 +1041,11 @@ export class DatetimePicker {
         this.rangeEnd = end;
         this.restoreSelection(end);
     }
-    /** 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.
+     */
     restoreSingleStateFromSerialized(serializedState) {
         const restoredValue = parseDatetimePickerSerializedValue(serializedState, this.mode, this.referenceDate);
         if (restoredValue !== null && this.isDateDisabled(restoredValue)) {
@@ -761,7 +1054,13 @@ export class DatetimePicker {
         }
         this.restoreSelection(restoredValue);
     }
-    /** 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.
+     */
     parseMethodValue(value, mode) {
         if (value === null) {
             return null;
@@ -771,7 +1070,11 @@ export class DatetimePicker {
         }
         return parseDatetimePickerSerializedValue(value, mode, this.referenceDate);
     }
-    /** 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.
+     */
     restoreSerializedValue(serializedValue) {
         if (this.isRangeRestoreMode()) {
             this.restoreRangeStateFromSerialized(serializedValue);
@@ -790,7 +1093,11 @@ export class DatetimePicker {
         this.valueAsDate = nextValueAsDate;
         this.syncingCanonicalValues = false;
     }
-    /** 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`.
+     */
     getSerializedValue() {
         const zero = (date) => (date === null ? null : set(date, { seconds: 0, milliseconds: 0 }));
         return (serializeDatetimePickerFormValue(this.value === null ? null : zero(this.value), {
@@ -804,11 +1111,24 @@ export class DatetimePicker {
     sameDate(left, right) {
         return left === right || (left !== null && right !== null && left.getTime() === right.getTime());
     }
-    /** 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.
+     */
     getNativeInputElement() {
-        return (this.datetimeInputElement ?? this.el.shadowRoot?.querySelector('br-datetime-input') ?? undefined);
+        return this.el.shadowRoot
+            ?.querySelector('br-datetime-input')
+            ?.shadowRoot?.querySelector('br-input')
+            ?.shadowRoot?.querySelector('input');
     }
-    /** 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
+     */
     setComponentValue(nextValue, shouldEmitPublicEvent = true) {
         this.value = this.cloneDate(nextValue);
         this.syncCanonicalValues();
@@ -820,13 +1140,13 @@ export class DatetimePicker {
     }
     /** Propaga o estado atual consolidado para consumidores externos do componente raiz. */
     emitDateStateChange() {
-        const range = this.selectionMode === 'range' && this.mode === DATETIME_PICKER_MODE.DATE
+        const range = this.selectionMode === 'range'
             ? {
                 start: this.cloneDate(this.rangeStart),
                 end: this.cloneDate(this.rangeEnd),
             }
             : undefined;
-        const rangeDates = range !== undefined && range.start !== null && range.end !== null
+        const rangeDates = this.mode === DATETIME_PICKER_MODE.DATE && range !== undefined && range.start !== null && range.end !== null
             ? this.buildRangeDatesState(range.start, range.end)
             : undefined;
         this.dateStateChange.emit({
@@ -835,13 +1155,118 @@ export class DatetimePicker {
             range,
             rangeDates,
         });
-        if (range)
-            this.rangeValue = range;
+        this.emitCanonicalChange(range);
         this.valueChange.emit(this.cloneDate(this.value));
         dispatchNativeFormEvent(this.el, 'input');
         dispatchNativeFormEvent(this.el, 'change');
     }
-    /** Expande o intervalo completo e marca quais dias estão desabilitados. */
+    /** Emite o contrato público sem expor detalhes incidentais do estado interno. */
+    emitCanonicalChange(rangeSnapshot) {
+        const serializedValue = this.getSerializedValue();
+        if (this.selectionMode === 'range') {
+            const range = rangeSnapshot ?? {
+                start: this.rangeStart,
+                end: this.rangeEnd,
+            };
+            const rangeValue = {
+                start: this.cloneDate(range.start),
+                end: this.cloneDate(range.end),
+            };
+            this.syncingRangeValueInternally = true;
+            this.rangeValue = rangeValue;
+            this.syncingRangeValueInternally = false;
+            const value = {
+                start: this.serializeRangeBoundary(rangeValue.start),
+                end: this.serializeRangeBoundary(rangeValue.end),
+            };
+            const detail = {
+                selectionMode: 'range',
+                value,
+                serializedValue,
+                complete: value.start !== null && value.end !== null,
+            };
+            if (this.mode === DATETIME_PICKER_MODE.DATE) {
+                this.brDatetimePickerChange.emit({ mode: 'date', ...detail });
+            }
+            else if (this.mode === DATETIME_PICKER_MODE.TIME) {
+                this.brDatetimePickerChange.emit({ mode: 'time', ...detail });
+            }
+            else {
+                this.brDatetimePickerChange.emit({ mode: 'datetime', ...detail });
+            }
+            return;
+        }
+        if (this.mode === DATETIME_PICKER_MODE.TIME) {
+            this.brDatetimePickerChange.emit({
+                mode: 'time',
+                selectionMode: 'single',
+                value: this.value === null
+                    ? null
+                    : {
+                        hours: this.value.getHours(),
+                        minutes: this.value.getMinutes(),
+                    },
+                serializedValue,
+            });
+            return;
+        }
+        if (this.mode === DATETIME_PICKER_MODE.DATE) {
+            this.brDatetimePickerChange.emit({
+                mode: 'date',
+                selectionMode: 'single',
+                value: this.cloneDate(this.value),
+                serializedValue,
+            });
+            return;
+        }
+        this.brDatetimePickerChange.emit({
+            mode: 'datetime',
+            selectionMode: 'single',
+            value: this.cloneDate(this.value),
+            serializedValue,
+        });
+    }
+    /**
+     * 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`.
+     */
+    serializeDateOnly(value) {
+        const year = String(value.getFullYear()).padStart(4, '0');
+        const month = String(value.getMonth() + 1).padStart(2, '0');
+        const day = String(value.getDate()).padStart(2, '0');
+        return `${year}-${month}-${day}`;
+    }
+    /**
+     * 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`.
+     */
+    serializeRangeBoundary(value) {
+        if (value === null)
+            return null;
+        if (this.mode === DATETIME_PICKER_MODE.DATE)
+            return this.serializeDateOnly(value);
+        if (this.mode === DATETIME_PICKER_MODE.TIME) {
+            return `${String(value.getHours()).padStart(2, '0')}:${String(value.getMinutes()).padStart(2, '0')}`;
+        }
+        return serializeDatetimePickerFormValue(value, {
+            mode: DATETIME_PICKER_MODE.DATETIME,
+            selectionMode: 'single',
+            rangeStart: null,
+            rangeEnd: null,
+            referenceDate: value,
+        });
+    }
+    /**
+     * 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.
+     */
     buildRangeDatesState(start, end) {
         const intervalStart = start.getTime() <= end.getTime() ? start : end;
         const intervalEnd = start.getTime() <= end.getTime() ? end : start;
@@ -853,8 +1278,13 @@ export class DatetimePicker {
             disabled: this.isDateDisabled(date),
         }));
     }
-    /** 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.
+     */
     restoreSelection(nextValue) {
+        this.inputValidationMessage = '';
         this.value = this.cloneDate(nextValue);
         if (this.selectionMode === 'single') {
             this.rangeStart = null;
@@ -864,12 +1294,15 @@ export class DatetimePicker {
         this.syncCanonicalValues();
         this.updateFormInternals();
     }
-    /** 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.
+     */
     setRangeState(nextRange) {
         this.rangeStart = this.cloneDate(nextRange?.start ?? null);
         this.rangeEnd = this.cloneDate(nextRange?.end ?? null);
     }
-    /** Mantém ElementInternals sincronizado com estado e regras do componente. */
     updateFormInternals() {
         this.syncFormValue();
         this.syncFormValidity();
@@ -889,9 +1322,20 @@ export class DatetimePicker {
                 });
             this.elementInternals.setFormValue(nextValue);
         }
-        catch {
-            // Ambientes de teste podem esconder attachInternals parcialmente.
-        }
+        catch { }
+    }
+    /** Deriva o erro de ordenação sem modificar os limites escolhidos. */
+    getRangeOrderValidationMessage() {
+        const invalidRange = this.selectionMode === 'range' &&
+            this.mode !== DATETIME_PICKER_MODE.TIME &&
+            this.rangeStart !== null &&
+            this.rangeEnd !== null &&
+            this.rangeStart.getTime() > this.rangeEnd.getTime();
+        if (!invalidRange)
+            return '';
+        return this.mode === DATETIME_PICKER_MODE.DATETIME
+            ? DATETIME_RANGE_ORDER_MESSAGE
+            : 'A data inicial deve anteceder a data final.';
     }
     /** Espelha a regra de required no mecanismo nativo de validade. */
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: consolida flags nativos relacionados sem esconder a precedência das mensagens.
@@ -907,50 +1351,40 @@ export class DatetimePicker {
                 rangeEnd: this.rangeEnd,
                 referenceDate: this.referenceDate,
             });
-            const min = this.parseConstraintValue(this.min, 'min');
-            const max = this.parseConstraintValue(this.max, 'max');
+            const min = this.parseConstraintValue(this.min);
+            const max = this.parseConstraintValue(this.max);
             const values = this.selectionMode === 'range' ? [this.rangeStart, this.rangeEnd] : [this.value];
             const rangeUnderflow = min !== null && values.some((value) => value !== null && value.getTime() < min.getTime());
             const rangeOverflow = max !== null && values.some((value) => value !== null && value.getTime() > max.getTime());
-            const invalidRange = this.selectionMode === 'range' &&
-                this.rangeStart !== null &&
-                this.rangeEnd !== null &&
-                this.rangeStart.getTime() > this.rangeEnd.getTime();
+            const rangeOrderMessage = this.getRangeOrderValidationMessage();
             const flags = {
-                customError: this.customValidationMessage !== '' || Boolean(this.validatorMessage) || invalidRange,
+                customError: this.customValidationMessage !== '' ||
+                    this.inputValidationMessage !== '' ||
+                    Boolean(this.validatorMessage) ||
+                    rangeOrderMessage !== '' ||
+                    this.inputValidationPending,
                 rangeOverflow,
                 rangeUnderflow,
                 valueMissing: missing,
             };
             const message = this.customValidationMessage ||
+                this.inputValidationMessage ||
                 this.validatorMessage ||
                 (missing
                     ? 'Preencha este campo.'
-                    : invalidRange
-                        ? 'A data inicial deve anteceder a data final.'
+                    : rangeOrderMessage
+                        ? rangeOrderMessage
                         : rangeUnderflow
                             ? 'Selecione uma data igual ou posterior ao mínimo.'
                             : rangeOverflow
                                 ? 'Selecione uma data igual ou anterior ao máximo.'
                                 : '');
-            setFormValidity(this.elementInternals, flags, message, this.getNativeInputElement());
-        }
-        catch {
-            // Ambientes sem ElementInternals completo não devem falhar.
+            setFormValidity(this.elementInternals, flags, message, this.getNativeInputElement() ?? undefined);
         }
+        catch { }
     }
-    parseConstraintValue(value, propertyName) {
-        if (value === null)
-            return null;
-        if (!(value instanceof Date) && typeof value !== 'string') {
-            reportInvalidPropValue(this.el, propertyName, value, 'Informe uma data válida como Date ou string compatível com o modo atual.', 'Aplicando fallback null (sem limite).');
-            return null;
-        }
-        const parsedValue = this.parseMethodValue(value, this.mode);
-        if (parsedValue !== null)
-            return parsedValue;
-        reportInvalidPropValue(this.el, propertyName, value, 'Informe uma data válida como Date ou string compatível com o modo atual.', 'Aplicando fallback null (sem limite).');
-        return null;
+    parseConstraintValue(value) {
+        return value === null ? null : this.parseMethodValue(value, this.mode);
     }
     isDisabled() {
         return isFormControlDisabled(this.disabled, this.formDisabled);
@@ -1008,24 +1442,35 @@ export class DatetimePicker {
     }
     /** Renderiza o campo de entrada responsável por abrir e sincronizar o picker. */
     renderInputField() {
-        return (h("br-datetime-input", { ref: (element) => {
-                this.datetimeInputElement = element;
-            }, referenceDate: this.referenceDate, value: this.value, selectionMode: this.selectionMode, rangeStart: this.rangeStart, rangeEnd: this.rangeEnd, placeholder: this.placeholder, mode: this.mode, disabled: this.isDisabled(), onDateStateChange: this.handleDateStateChange, onTogglePicker: this.handleTogglePicker, exportparts: "container: input-container, input: input-field, icon: input-icon" }));
+        return (h("br-datetime-input", { referenceDate: this.referenceDate, value: this.value, selectionMode: this.selectionMode, rangeStart: this.rangeStart, rangeEnd: this.rangeEnd, placeholder: this.placeholder, mode: this.mode, disabled: this.isDisabled(), onDateStateChange: this.handleDateStateChange, onInputValidationChange: this.handleInputValidationChange, onTogglePicker: this.handleTogglePicker, exportparts: "container: input-container, input: input-field, icon: input-icon" }));
     }
     /** Renderiza apenas o seletor de data. */
     renderDatePicker() {
-        const effectiveSelectionMode = this.mode === DATETIME_PICKER_MODE.DATE ? this.selectionMode : 'single';
+        const effectiveSelectionMode = this.selectionMode;
         return (h("br-date-picker", { ...this.getSharedDateStateBindings(), selectionMode: effectiveSelectionMode, weekStartsOn: this.weekStartsOn, locale: this.locale, disabled: this.isDisabled(), disabledDates: this.normalizedDisabledDates, fixedRowCount: this.fixedRowCount }));
     }
-    /** Renderiza apenas o seletor de hora. */
-    renderTimePicker() {
-        return h("br-time-picker", { ...this.getSharedDateStateBindings(), disabled: this.isDisabled() });
+    /** Renderiza um seletor de hora simples ou um limite do intervalo. */
+    renderTimePicker(boundary) {
+        const rangeValue = boundary === 'start' ? this.rangeStart : this.rangeEnd;
+        const referenceDate = this.cloneDate(rangeValue ?? this.referenceDate);
+        const selectedValue = this.cloneDate(rangeValue);
+        const timerKey = boundary === undefined ? 'single' : `${boundary}-${rangeValue?.getTime() ?? `empty-${referenceDate.getTime()}`}`;
+        const handler = boundary === 'start'
+            ? this.handleRangeStartTimeStateChange
+            : boundary === 'end'
+                ? this.handleRangeEndTimeStateChange
+                : this.handleDateStateChange;
+        return (h("br-time-picker", { key: timerKey, referenceDate: referenceDate, value: boundary === undefined ? this.cloneDate(this.value) : selectedValue, onDateStateChange: handler, disabled: this.isDisabled() }));
+    }
+    /** Renderiza os horários inicial e final lado a lado no modo range. */
+    renderRangeTimePickers() {
+        return (h("div", { class: "range-time-pickers", role: "group", "aria-label": "Intervalo de hor\u00E1rios" }, h("div", { class: "range-time-picker" }, h("span", { class: "range-time-label" }, "In\u00EDcio"), this.renderTimePicker('start')), h("span", { class: "range-time-separator", "aria-hidden": "true" }, "-"), h("div", { class: "range-time-picker" }, h("span", { class: "range-time-label" }, "Fim"), this.renderTimePicker('end'))));
     }
     /**
      * Renderiza a combinação de data e horário no modo `datetime`.
      */
     renderDateTimePicker() {
-        return (h(Fragment, null, this.renderDatePicker(), this.renderDivider(), this.renderTimePicker()));
+        return (h(Fragment, null, this.renderDatePicker(), this.renderDivider(), this.selectionMode === 'range' ? this.renderRangeTimePickers() : this.renderTimePicker()));
     }
     /** Renderiza o separador visual entre data e hora no modo combinado. */
     renderDivider() {
@@ -1045,7 +1490,11 @@ export class DatetimePicker {
      * Renderização principal do componente.
      */
     render() {
-        return (h(Host, { key: 'b964215e48b1871bf6ab1b045612f3d166543177', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || this.customValidationMessage || this.validatorMessage ? this.feedbackId : null, "aria-errormessage": this.customValidationMessage || this.validatorMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '50ba10963ba4e8bdf7c70f0d4513eea657692df8', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: 'b220e70a85d8ba941dabed18a5a0dcdc9a99124f', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !this.customValidationMessage && !this.validatorMessage }, h("slot", { key: 'cdcc69b126491b2cea3b634066f1e4071c1c3b61', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && (this.customValidationMessage || this.validatorMessage) ? (h("br-message", { state: "danger", message: this.customValidationMessage || this.validatorMessage })) : null)));
+        const validationMessage = this.customValidationMessage ||
+            this.inputValidationMessage ||
+            this.validatorMessage ||
+            (this.inputValidationPending ? '' : this.getRangeOrderValidationMessage());
+        return (h(Host, { key: '0640504e844713daaf31d7c8a34b96fb48bcf499', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || validationMessage ? this.feedbackId : null, "aria-errormessage": validationMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '7512ed8a4437a99d6d0702351af659bfa1d270b0', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: '80a8d3a717ceacc4dfb6bd0ac4850b61e3b2d311', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !validationMessage }, h("slot", { key: '41a8e4fad5edaa3729d63b7ee469f248a53129a1', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && validationMessage ? (h("br-message", { state: "danger", "attr:message": validationMessage, feedback: true })) : null)));
     }
     static get is() { return "br-datetime-picker"; }
     static get encapsulation() { return "shadow"; }
@@ -1084,7 +1533,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "'datetime'"
                         }],
-                    "text": "Define o modo de sele\u00E7\u00E3o exibido pelo componente: data, hor\u00E1rio ou ambos.\n\nValores aceitos: `date`, `time` ou `datetime`.\nValores inv\u00E1lidos s\u00E3o corrigidos automaticamente para o valor padr\u00E3o,\nmantendo o atributo refletido sempre consistente com o modo exibido."
+                    "text": "Modo exibido pelo componente.\n\nValores: `date` | `time` | `datetime`.\nValores inv\u00E1lidos s\u00E3o normalizados para o padr\u00E3o."
                 },
                 "getter": false,
                 "setter": false,
@@ -1114,7 +1563,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "'pt-BR'"
                         }],
-                    "text": "Define o locale usado pelos subcomponentes para formatar datas e r\u00F3tulos."
+                    "text": "Locale usado para formata\u00E7\u00E3o e r\u00F3tulos."
                 },
                 "getter": false,
                 "setter": false,
@@ -1137,7 +1586,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "''"
                         }],
-                    "text": "Define o placeholder exibido no campo de entrada do datetime picker."
+                    "text": "Texto placeholder exibido no input."
                 },
                 "getter": false,
                 "setter": false,
@@ -1156,7 +1605,10 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "default",
+                            "text": "''"
+                        }],
                     "text": "Nome do campo para submiss\u00E3o em formul\u00E1rios nativos."
                 },
                 "getter": false,
@@ -1176,8 +1628,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Indica se o campo deve ter valor antes do envio do formul\u00E1rio."
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Indica se o campo \u00E9 requerido para submiss\u00E3o do formul\u00E1rio."
                 },
                 "getter": false,
                 "setter": false,
@@ -1202,10 +1657,10 @@ export class DatetimePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```html\n<br-datetime-picker mode=\"date\" min=\"2026-01-01\"></br-datetime-picker>\n```"
+                            "name": "default",
+                            "text": "null"
                         }],
-                    "text": "Menor data/hor\u00E1rio aceito, interpretado conforme `mode`. Valores inv\u00E1lidos s\u00E3o ignorados.\nAceita texto no atributo HTML ou uma inst\u00E2ncia de `Date` por property binding."
+                    "text": "Menor data/hora aceito (Date | string | null)."
                 },
                 "getter": false,
                 "setter": false,
@@ -1230,10 +1685,10 @@ export class DatetimePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```html\n<br-datetime-picker mode=\"date\" max=\"2026-12-31\"></br-datetime-picker>\n```"
+                            "name": "default",
+                            "text": "null"
                         }],
-                    "text": "Maior data/hor\u00E1rio aceito, interpretado conforme `mode`. Valores inv\u00E1lidos s\u00E3o ignorados.\nAceita texto no atributo HTML ou uma inst\u00E2ncia de `Date` por property binding."
+                    "text": "Maior data/hora aceito (Date | string | null)."
                 },
                 "getter": false,
                 "setter": false,
@@ -1260,10 +1715,10 @@ export class DatetimePicker {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.validator = (value) => value === null ? 'Escolha uma data' : null;\n```"
+                            "name": "default",
+                            "text": "undefined"
                         }],
-                    "text": "Regra s\u00EDncrona ou ass\u00EDncrona aplicada \u00E0 data ou intervalo selecionado.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor."
+                    "text": "Validador customizado (s\u00EDncrono ou ass\u00EDncrono) para a sele\u00E7\u00E3o.\n\nRecebe `Date | DatetimePickerDateRange | null` como valor."
                 },
                 "getter": false,
                 "setter": false
@@ -1286,8 +1741,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Define o tipo de sele\u00E7\u00E3o de datas para o calend\u00E1rio: \u00FAnica ou intervalo.\n\n`range` s\u00F3 funciona em conjunto com `mode=\"date\"`.\nSe `selectionMode=\"range\"` for informado, o componente ajusta automaticamente\n`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente\nnormaliza `selectionMode` para `single` quando necess\u00E1rio.\nValores inv\u00E1lidos usam `single`."
+                    "tags": [{
+                            "name": "default",
+                            "text": "'single'"
+                        }],
+                    "text": "Tipo de sele\u00E7\u00E3o: `single` ou `range`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1317,7 +1775,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "0"
                         }],
-                    "text": "Define o dia inicial da semana exibida no calend\u00E1rio.\n\nValores suportados: 0 (domingo) a 6 (s\u00E1bado)."
+                    "text": "Dia inicial da semana exibido no calend\u00E1rio (0 = Dom, 6 = S\u00E1b)."
                 },
                 "getter": false,
                 "setter": false,
@@ -1346,11 +1804,8 @@ export class DatetimePicker {
                     "tags": [{
                             "name": "default",
                             "text": "null"
-                        }, {
-                            "name": "example",
-                            "text": "```html\n<br-datetime-picker initial-moment=\"now\"></br-datetime-picker>\n```"
                         }],
-                    "text": "Define a sele\u00E7\u00E3o inicial do componente.\n\nAceita:\n- `'now'`: seleciona o momento atual.\n- `Date` ou `string`: seleciona uma data arbitr\u00E1ria.\n- `null`: inicia sem sele\u00E7\u00E3o.\n\nReativo em runtime: mudan\u00E7as na prop atualizam estado e subcomponentes."
+                    "text": "Valor inicial da sele\u00E7\u00E3o: `'now' | Date | string | null`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1375,10 +1830,10 @@ export class DatetimePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.value = new Date(2026, 8, 7, 14, 30);\n```"
+                            "name": "default",
+                            "text": "null"
                         }],
-                    "text": "Inst\u00E2ncia de `Date` selecionada pelo usu\u00E1rio no modo simples.\nPode ser controlada por property binding e \u00E9 atualizada pelo evento `valueChange`.\nPara formul\u00E1rios e atributos textuais, use `serializedValue`."
+                    "text": "Valor selecionado pelo usu\u00E1rio (Date | null).\n\nPode ser controlado externamente e \u00E9 refletido internamente."
                 },
                 "getter": false,
                 "setter": false,
@@ -1396,10 +1851,10 @@ export class DatetimePicker {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```html\n<br-datetime-picker mode=\"datetime\" serialized-value=\"2026-09-07T14:30\"></br-datetime-picker>\n```"
+                            "name": "default",
+                            "text": "undefined"
                         }],
-                    "text": "Representa\u00E7\u00E3o serializada compat\u00EDvel com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`\nou ISO local, conforme `mode`). Em intervalos, usa `in\u00EDcio/fim`.\n\nNa inicializa\u00E7\u00E3o, tem preced\u00EAncia sobre `valueAsDate`, `value` e `initialMoment`.\nUma string vazia inicia sem sele\u00E7\u00E3o, mesmo quando outra prop fornece uma data."
+                    "text": "Representa\u00E7\u00E3o serializada compat\u00EDvel com controles HTML.\n\nFormatos variam conforme `mode`. Em intervalos, usa `in\u00EDcio/fim`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1423,10 +1878,13 @@ export class DatetimePicker {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.valueAsDate = new Date(2026, 8, 7);\n```"
+                            "name": "internal",
+                            "text": "Mant\u00E9m compatibilidade com APIs legadas."
+                        }, {
+                            "name": "default",
+                            "text": "undefined"
                         }],
-                    "text": "Espelho tipado da sele\u00E7\u00E3o atual, equivalente ao padr\u00E3o `valueAsDate` dos controles HTML.\nDiferentemente de `serializedValue`, recebe e retorna uma inst\u00E2ncia de `Date`.\nNa inicializa\u00E7\u00E3o, tem preced\u00EAncia sobre `value` e `initialMoment` quando `serializedValue`\nn\u00E3o \u00E9 informado. `null` inicia sem sele\u00E7\u00E3o; `undefined` permite usar as outras props."
+                    "text": "Espelho tipado da sele\u00E7\u00E3o atual (`valueAsDate`)."
                 },
                 "getter": false,
                 "setter": false
@@ -1450,10 +1908,10 @@ export class DatetimePicker {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.selectionMode = 'range';\npicker.rangeValue = {\n  start: new Date(2026, 8, 7),\n  end: new Date(2026, 8, 12),\n};\n```"
+                            "name": "default",
+                            "text": "undefined"
                         }],
-                    "text": "Intervalo controlado quando `selectionMode=\"range\"`.\nDeve conter datas v\u00E1lidas ou `null` em `start` e `end`; valores inv\u00E1lidos mant\u00EAm o \u00FAltimo intervalo efetivo.\nPasse o objeto por property binding; atributos HTML n\u00E3o representam objetos com `Date`."
+                    "text": "Intervalo controlado quando `selectionMode=\"range\"`.\n\nEm `datetime`, preserva as datas e hor\u00E1rios informados; t\u00E9rmino anterior ao\nin\u00EDcio torna o controle inv\u00E1lido, sem reordenar ou avan\u00E7ar datas."
                 },
                 "getter": false,
                 "setter": false
@@ -1473,7 +1931,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "false"
                         }],
-                    "text": "Desabilita toda a intera\u00E7\u00E3o do componente.\n\nQuando `true`, impede abrir o picker, alterar valores e navegar entre datas/hor\u00E1rios."
+                    "text": "Desabilita toda a intera\u00E7\u00E3o do componente."
                 },
                 "getter": false,
                 "setter": false,
@@ -1502,14 +1960,8 @@ export class DatetimePicker {
                     "tags": [{
                             "name": "default",
                             "text": "null"
-                        }, {
-                            "name": "example",
-                            "text": "```html\n<br-datetime-picker mode=\"date\" disabled-dates=\"2026-09-07 2026-09-08\"></br-datetime-picker>\n```"
-                        }, {
-                            "name": "example",
-                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.disabledDates = [new Date(2026, 8, 7), '2026-09-08'];\n```"
                         }],
-                    "text": "Define um conjunto de datas indispon\u00EDveis para sele\u00E7\u00E3o.\n\nAceita uma lista de `Date` e/ou strings analis\u00E1veis, ou uma string com datas\nseparadas por espa\u00E7o em branco. Datas inv\u00E1lidas s\u00E3o ignoradas com warning.\nA compara\u00E7\u00E3o considera apenas o dia (ano/m\u00EAs/dia), ignorando hora."
+                    "text": "Datas indispon\u00EDveis para sele\u00E7\u00E3o. Aceita `Date[]`, `string` ou `null`.\n\nDatas inv\u00E1lidas s\u00E3o ignoradas. A compara\u00E7\u00E3o considera apenas o dia."
                 },
                 "getter": false,
                 "setter": false,
@@ -1532,7 +1984,7 @@ export class DatetimePicker {
                             "name": "default",
                             "text": "false"
                         }],
-                    "text": "Define se o calend\u00E1rio deve manter um n\u00FAmero fixo de linhas (6 semanas = 42 dias)\nou variar conforme o m\u00EAs.\n\nQuando `true`, o calend\u00E1rio sempre exibe 6 semanas completas.\nQuando `false`, o calend\u00E1rio adapta-se ao m\u00EAs, exibindo apenas as semanas necess\u00E1rias."
+                    "text": "Mant\u00E9m n\u00FAmero fixo de linhas no calend\u00E1rio (6 semanas) quando `true`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1549,6 +2001,8 @@ export class DatetimePicker {
             "hasFeedbackSlot": {},
             "customValidationMessage": {},
             "validatorMessage": {},
+            "inputValidationMessage": {},
+            "inputValidationPending": {},
             "isValidating": {},
             "normalizedDisabledDates": {},
             "rangeEnd": {},
@@ -1564,12 +2018,18 @@ export class DatetimePicker {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Evento p\u00FAblico emitido quando a data de refer\u00EAncia ou a sele\u00E7\u00E3o mudam."
+                    "tags": [{
+                            "name": "event",
+                            "text": "dateStateChange"
+                        }, {
+                            "name": "type",
+                            "text": "{CustomEvent<DatetimePickerDateState>}"
+                        }],
+                    "text": "Evento p\u00FAblico emitido quando a data de refer\u00EAncia ou a sele\u00E7\u00E3o mudam.\n\nPayload (`DatetimePickerDateState`):\n- `referenceDate`: Date \u2014 data usada para navega\u00E7\u00E3o visual (m\u00EAs/semana exibidos).\n- `value`: Date | null \u2014 valor selecionado atualmente."
                 },
                 "complexType": {
                     "original": "DatetimePickerDateState",
-                    "resolved": "{ referenceDate: Date; value: Date; range?: DatetimePickerDateRange; rangeDates?: DatetimePickerRangeDateState[]; }",
+                    "resolved": "{ referenceDate: Date; value: Date; range?: DatetimePickerDateRange; rangeDates?: DatetimePickerRangeDateState[]; origin?: string; }",
                     "references": {
                         "DatetimePickerDateState": {
                             "location": "import",
@@ -1579,6 +2039,34 @@ export class DatetimePicker {
                         }
                     }
                 }
+            }, {
+                "method": "brDatetimePickerChange",
+                "name": "brDatetimePickerChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "event",
+                            "text": "brDatetimePickerChange"
+                        }, {
+                            "name": "type",
+                            "text": "{CustomEvent<DatetimePickerChangeDetail>}"
+                        }],
+                    "text": "Evento p\u00FAblico can\u00F4nico emitido quando a sele\u00E7\u00E3o muda.\n\nPayload (`DatetimePickerChangeDetail`):\n- `mode`: DatetimePickerMode \u2014 modo atual do componente (`date` | `time` | `datetime`).\n- `selectionMode`: DatetimePickerSelectionMode \u2014 `single` ou `range`.\n- `value`: Date | null | DatetimePickerDateRange \u2014 sele\u00E7\u00E3o atual (tipo depende de `selectionMode`).\n- `serializedValue`: string | undefined \u2014 representa\u00E7\u00E3o serializada para integra\u00E7\u00E3o com formul\u00E1rios."
+                },
+                "complexType": {
+                    "original": "DatetimePickerChangeDetail",
+                    "resolved": "{ mode: \"date\"; selectionMode: \"range\"; value: { start: string; end: string; }; serializedValue: string; complete: boolean; } | { mode: \"date\"; selectionMode: \"single\"; value: Date; serializedValue: string; } | { mode: \"datetime\"; selectionMode: \"range\"; value: { start: string; end: string; }; serializedValue: string; complete: boolean; } | { mode: \"datetime\"; selectionMode: \"single\"; value: Date; serializedValue: string; } | { mode: \"time\"; selectionMode: \"range\"; value: { start: string; end: string; }; serializedValue: string; complete: boolean; } | { mode: \"time\"; selectionMode: \"single\"; value: { hours: number; minutes: number; }; serializedValue: string; }",
+                    "references": {
+                        "DatetimePickerChangeDetail": {
+                            "location": "import",
+                            "path": "./datetime-picker.types",
+                            "id": "src/components/datetime-picker/datetime-picker.types.ts::DatetimePickerChangeDetail",
+                            "referenceLocation": "DatetimePickerChangeDetail"
+                        }
+                    }
+                }
             }, {
                 "method": "valueChange",
                 "name": "valueChange",
@@ -1588,7 +2076,13 @@ export class DatetimePicker {
                 "docs": {
                     "tags": [{
                             "name": "deprecated",
-                            "text": "Use `input`/`change` e leia `event.target.value`."
+                            "text": "Use `brDatetimePickerChange` para receber a sele\u00E7\u00E3o completa e tipada.\n\nPayload (legacy): `Date | null` \u2014 valor selecionado."
+                        }, {
+                            "name": "event",
+                            "text": "valueChange"
+                        }, {
+                            "name": "type",
+                            "text": "{CustomEvent<Date | null>}"
                         }],
                     "text": "Evento emitido quando o valor selecionado muda."
                 },
@@ -1609,8 +2103,14 @@ export class DatetimePicker {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emitido ao iniciar e concluir a valida\u00E7\u00E3o customizada."
+                    "tags": [{
+                            "name": "event",
+                            "text": "brDatetimePickerValidationChange"
+                        }, {
+                            "name": "type",
+                            "text": "{CustomEvent<FormValidationChangeDetail>}"
+                        }],
+                    "text": "Emitido ao iniciar e concluir a valida\u00E7\u00E3o customizada.\n\nPayload (`FormValidationChangeDetail`):\n- `validating`: boolean \u2014 indica se a valida\u00E7\u00E3o est\u00E1 em execu\u00E7\u00E3o.\n- `valid`: boolean | null \u2014 resultado da valida\u00E7\u00E3o (`null` enquanto valida).\n- `message`: string | null \u2014 mensagem de valida\u00E7\u00E3o associada."
                 },
                 "complexType": {
                     "original": "FormValidationChangeDetail",
@@ -1634,7 +2134,7 @@ export class DatetimePicker {
                     "parameters": [{
                             "name": "dates",
                             "type": "DatetimePickerDisabledDate[]",
-                            "docs": "- Lista de datas (Date|string) a bloquear."
+                            "docs": "Lista de datas (`Date` | `string`) a bloquear, ou `null` para limpar."
                         }],
                     "references": {
                         "Promise": {
@@ -1651,10 +2151,13 @@ export class DatetimePicker {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Define programaticamente as datas desabilitadas por meio de array.\n\n\u00DAtil quando o componente \u00E9 usado via HTML e o consumidor precisa enviar\numa lista tipada em runtime.",
+                    "text": "Define programaticamente as datas desabilitadas.\n\nUse quando scripts externos precisam fornecer uma lista tipada de\ndatas a bloquear no calend\u00E1rio. Substitui a prop `disabledDates` para\natualiza\u00E7\u00F5es imperativas.",
                     "tags": [{
                             "name": "param",
-                            "text": "dates - Lista de datas (Date|string) a bloquear."
+                            "text": "dates Lista de datas (`Date` | `string`) a bloquear, ou `null` para limpar."
+                        }, {
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando a atualiza\u00E7\u00E3o interna for aplicada."
                         }]
                 }
             },
@@ -1664,7 +2167,7 @@ export class DatetimePicker {
                     "parameters": [{
                             "name": "value",
                             "type": "string | Date",
-                            "docs": ""
+                            "docs": "Date | string | null \u2014 valor a aplicar; `null` limpa a sele\u00E7\u00E3o."
                         }],
                     "references": {
                         "Promise": {
@@ -1679,8 +2182,14 @@ export class DatetimePicker {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Define o valor atual de forma imperativa aceitando Date, string serializada ou null.",
-                    "tags": []
+                    "text": "Define o valor do componente de forma imperativa.\n\nAceita `Date`, string compat\u00EDvel com o `mode`, ou `null` para limpar a sele\u00E7\u00E3o.\nValida\u00E7\u00E3o de datas desabilitadas \u00E9 aplicada antes da atribui\u00E7\u00E3o.",
+                    "tags": [{
+                            "name": "param",
+                            "text": "value Date | string | null \u2014 valor a aplicar; `null` limpa a sele\u00E7\u00E3o."
+                        }, {
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando o componente aplicar e sincronizar o valor."
+                        }]
                 }
             },
             "getValue": {
@@ -1701,7 +2210,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Retorna uma c\u00F3pia do valor selecionado atualmente.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<Date | null> \u2014 c\u00F3pia imut\u00E1vel do `value` atual, ou `null`."
+                        }]
                 }
             },
             "clear": {
@@ -1717,8 +2229,11 @@ export class DatetimePicker {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Limpa valor e intervalo selecionados.",
-                    "tags": []
+                    "text": "Limpa valor e intervalo selecionados.\n\nRemove sele\u00E7\u00E3o atual e restaura a refer\u00EAncia de navega\u00E7\u00E3o para a data atual.",
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve ap\u00F3s a limpeza e sincroniza\u00E7\u00E3o internas."
+                        }]
                 }
             },
             "open": {
@@ -1735,7 +2250,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Abre o picker quando o componente estiver habilitado.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando o estado visual for atualizado."
+                        }]
                 }
             },
             "close": {
@@ -1752,7 +2270,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Fecha o picker.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve ap\u00F3s atualiza\u00E7\u00E3o do estado de visibilidade."
+                        }]
                 }
             },
             "toggle": {
@@ -1769,7 +2290,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Alterna o estado de abertura do picker.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando a transi\u00E7\u00E3o de estado terminar."
+                        }]
                 }
             },
             "focusInput": {
@@ -1780,17 +2304,16 @@ export class DatetimePicker {
                         "Promise": {
                             "location": "global",
                             "id": "global::Promise"
-                        },
-                        "HTMLBrDatetimeInputElement": {
-                            "location": "global",
-                            "id": "global::HTMLBrDatetimeInputElement"
                         }
                     },
                     "return": "Promise<void>"
                 },
                 "docs": {
                     "text": "Move o foco para o input nativo interno.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve imediatamente ap\u00F3s tentar focar o elemento."
+                        }]
                 }
             },
             "setRange": {
@@ -1799,11 +2322,11 @@ export class DatetimePicker {
                     "parameters": [{
                             "name": "start",
                             "type": "string | Date",
-                            "docs": ""
+                            "docs": "Date | string | null \u2014 data inicial do intervalo."
                         }, {
                             "name": "end",
                             "type": "string | Date",
-                            "docs": ""
+                            "docs": "Date | string | null \u2014 data final do intervalo."
                         }],
                     "references": {
                         "Promise": {
@@ -1818,8 +2341,17 @@ export class DatetimePicker {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Define intervalo de datas de forma imperativa, for\u00E7ando modo date e selectionMode range.",
-                    "tags": []
+                    "text": "Define um intervalo no modo atual e ativa `selectionMode=\"range\"`.\n\nValida datas contra bloqueios e sincroniza estado visual e de formul\u00E1rio.\nEm `datetime`, mant\u00E9m os limites informados e sinaliza intervalo inv\u00E1lido\nquando o t\u00E9rmino precede o in\u00EDcio, sem ajustar datas automaticamente.",
+                    "tags": [{
+                            "name": "param",
+                            "text": "start Date | string | null \u2014 data inicial do intervalo."
+                        }, {
+                            "name": "param",
+                            "text": "end Date | string | null \u2014 data final do intervalo."
+                        }, {
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando o intervalo for aplicado e sincronizado."
+                        }]
                 }
             },
             "getRange": {
@@ -1842,7 +2374,7 @@ export class DatetimePicker {
                     "text": "Retorna o intervalo de datas selecionado quando em modo `selectionMode=\"range\"`.",
                     "tags": [{
                             "name": "returns",
-                            "text": "Objeto com datas `start` e `end`, ou `null` se n\u00E3o estiver em modo range."
+                            "text": "Promise<{ start: Date | null; end: Date | null } | null> \u2014 objeto com `start`/`end` ou `null` quando\nn\u00E3o estiver em modo `range`."
                         }]
                 }
             },
@@ -1862,7 +2394,7 @@ export class DatetimePicker {
                     "text": "Consulta se o picker est\u00E1 atualmente aberto.",
                     "tags": [{
                             "name": "returns",
-                            "text": "`true` se o picker est\u00E1 vis\u00EDvel, `false` caso contr\u00E1rio."
+                            "text": "Promise<boolean> \u2014 `true` se o picker est\u00E1 vis\u00EDvel, `false` caso contr\u00E1rio."
                         }]
                 }
             },
@@ -1880,7 +2412,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Restaura o estado inicial atualmente registrado para reset.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve quando a sele\u00E7\u00E3o inicial for restaurada."
+                        }]
                 }
             },
             "checkValidity": {
@@ -1897,7 +2432,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Permite que consumidores acionem valida\u00E7\u00E3o nativa do formul\u00E1rio via host.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<boolean> \u2014 resultado da Constraint Validation API para o host."
+                        }]
                 }
             },
             "reportValidity": {
@@ -1914,7 +2452,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Permite exibir mensagens nativas de valida\u00E7\u00E3o no host.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<boolean> \u2014 `true` se a mensagem foi exibida e o formul\u00E1rio \u00E9 v\u00E1lido."
+                        }]
                 }
             },
             "setCustomValidity": {
@@ -1923,7 +2464,7 @@ export class DatetimePicker {
                     "parameters": [{
                             "name": "message",
                             "type": "string",
-                            "docs": ""
+                            "docs": "string \u2014 mensagem de valida\u00E7\u00E3o; string vazia remove a mensagem."
                         }],
                     "references": {
                         "Promise": {
@@ -1935,7 +2476,13 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Define ou limpa uma mensagem de validade customizada.",
-                    "tags": []
+                    "tags": [{
+                            "name": "param",
+                            "text": "message string \u2014 mensagem de valida\u00E7\u00E3o; string vazia remove a mensagem."
+                        }, {
+                            "name": "returns",
+                            "text": "Promise<void> \u2014 resolve ap\u00F3s sincronizar a validade no host."
+                        }]
                 }
             },
             "validate": {
@@ -1961,8 +2508,11 @@ export class DatetimePicker {
                     "return": "Promise<boolean>"
                 },
                 "docs": {
-                    "text": "Executa o validator do picker e retorna se a sele\u00E7\u00E3o atual \u00E9 v\u00E1lida.",
-                    "tags": []
+                    "text": "Executa o validator customizado (se houver) e valida o controle.\n\nEmite eventos de in\u00EDcio/conclus\u00E3o da valida\u00E7\u00E3o e atualiza mensagens internas.",
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<boolean> \u2014 `true` se a sele\u00E7\u00E3o for considerada v\u00E1lida."
+                        }]
                 }
             },
             "getValidationState": {
@@ -1985,7 +2535,10 @@ export class DatetimePicker {
                 },
                 "docs": {
                     "text": "Retorna um snapshot serializ\u00E1vel da Constraint Validation API.",
-                    "tags": []
+                    "tags": [{
+                            "name": "returns",
+                            "text": "Promise<FormValidationState> \u2014 estado atual de valida\u00E7\u00E3o do host,\npronto para convers\u00E3o e restaura\u00E7\u00E3o via `formStateRestoreCallback`."
+                        }]
                 }
             }
         };