@govbr-ds/webcomponents 2.3.0 → 2.4.0

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

@@ -12,133 +12,153 @@ import { parse } from "date-fns/parse";
 import { set } from "date-fns/set";
 import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../../shared/utils/event";
-import { reportInvalidPropValue } from "../../../shared/utils/prop-warning";
-import { resolveAllowedPropValue } from "../../../shared/utils/props";
 import { resolveSsrLocalDate } from "../../../shared/utils/ssr-date";
-import { isValidDatetimePickerDateRange } from "../datetime-picker-props-validation";
+import { DATETIME_RANGE_ORDER_MESSAGE } from "../datetime-picker-constants";
+import { INPUT_FORMAT_CONFIG } from "./datetime-input-constants";
 import { normalizeDatetimeInputMode, normalizeDatetimeInputReferenceDate, normalizeDatetimeInputValue, } from "./datetime-input-props-validation";
 /**
- * Subcomponente especializado do ecossistema de datas do GovBR-DS, responsável pela digitação e formatação de datas e horários via teclado.
+ * O `br-datetime-input` é o subcomponente de edição textual do `br-datetime-picker`, com máscara, interpretação de datas e horários e validação local sobre um `br-input` interno.
  *
  * ### Papel na composição
  *
- * - Aplica máscaras automáticas de digitação conforme o formato configurado (ex.: `DD/MM/AAAA`, `HH:mm`, `DD/MM/AAAA HH:mm`).
- * - Contém o botão de acionamento para expandir ou recolher o popup do calendário.
+ * Exibe e permite editar a seleção única ou os limites de um intervalo nos modos `date`, `time` e `datetime`. Comunica alterações por `dateStateChange`, informa a validação local por `inputValidationChange` e solicita a abertura ou o fechamento do painel por `togglePicker`.
  *
  * ### Regra de uso e relacionamento
  *
- * No fluxo usual da aplicação, é instanciado e coordenado automaticamente pelo orquestrador `br-datetime-picker`. Pode ser utilizado de forma autônoma apenas quando o leiaute exigir somente o campo de digitação textual sem o painel flutuante de calendário.
+ * O `br-datetime-picker` instancia este campo internamente e fornece valores e configurações por propriedades. O pai coordena a seleção com o calendário e os controles de horário; o campo não abre esses seletores por conta própria nem deve ser fornecido em slot.
  *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
+ * Prefira o `br-datetime-picker` para o controle completo. Use o campo isoladamente apenas em composições personalizadas nas quais a aplicação assuma a sincronização de estado, o tratamento dos eventos e a integração com formulários. Este subcomponente não possui a associação nativa ao formulário do orquestrador.
  *
- * @category Formulários, Seleção
- * @status stable
+ * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
  *
- * @part container - Parte para o container base do campo.
- * @part input - Parte para o campo textual interno.
- * @part icon - Parte para o ícone de ação (calendário/relógio).
+ * @see https://www.gov.br/ds/components/datetime?tab=designer
+ * @part container - Container do campo.
+ * @part input - Elemento de entrada textual interno.
+ * @part icon - Ícone de ação (calendário/relógio).
  */
 export class DatetimeInput {
     constructor() {
-        /** Valor textual exibido no campo e usado durante a edição manual. */
-        this.inputValue = '';
         /**
-         * Define o placeholder do campo de entrada.
+         * Texto de placeholder exibido quando o campo estiver vazio.
          *
          * @default ''
          */
         this.placeholder = '';
         /**
-         * Define o modo de entrada: `date`, `time` ou `datetime`.
+         * Modo de entrada que controla máscara, parser e formato exibido.
          *
          * @default 'datetime'
          */
         this.mode = 'datetime';
         /**
-         * Data de referência que orienta a navegação visual do calendário sem alterar a seleção.
-         * Recebe uma instância de `Date` por property binding.
+         * Data de referência usada para navegação e preenchimento de valores parciais.
          *
          * @default new Date()
-         * @example
-         * ```js
-         * const input = document.querySelector('br-datetime-input');
-         * input.referenceDate = new Date(2026, 8, 1);
-         * ```
          */
         this.referenceDate = new Date();
         /**
-         * Data efetivamente selecionada, ou `null` quando nada foi escolhido; é diferente
-         * de `referenceDate`, que controla apenas a referência visual.
-         * Recebe uma instância de `Date` por property binding.
+         * Valor atualmente selecionado pelo componente.
          *
          * @default null
-         * @example
-         * ```js
-         * const input = document.querySelector('br-datetime-input');
-         * input.value = new Date(2026, 8, 7, 14, 30);
-         * ```
          */
         this.value = null;
         /**
-         * Desabilita digitação e abertura do picker quando ativo.
+         * Controla os estados de read-only ou bloqueio de formulário.
          *
          * @default false
          */
         this.disabled = false;
         /**
-         * Define se a seleção ocorre por data única ou por intervalo.
-         * Aceita `single` ou `range`; valores inválidos usam `single`.
+         * Define o modo de seleção: `single` (valor único) ou `range` (intervalo).
          *
          * @default 'single'
          */
         this.selectionMode = 'single';
         /**
-         * Data inicial do intervalo quando em modo range.
+         * Início do intervalo em `selectionMode === 'range'`.
          *
          * @default null
          */
         this.rangeStart = null;
         /**
-         * Data final do intervalo quando em modo range.
+         * Fim do intervalo em `selectionMode === 'range'`.
          *
          * @default null
          */
         this.rangeEnd = null;
+        /**
+         * Marcador do último texto confirmado (commit) exibido no input.
+         *
+         * @internal
+         * @type {string | null}
+         * @default null
+         */
+        this.lastCommittedInputText = null;
+        /**
+         * Texto atual do campo usado durante a edição manual.
+         *
+         * @internal Mantido localmente; não faz parte do contrato público do componente.
+         * @type {string}
+         * @default ''
+         */
+        this.inputValue = '';
+        /**
+         * Handler do clique no botão de ação interno.
+         *
+         * @param event - Ativação pública da ação do br-input.
+         * @returns {void}
+         */
         this.handleActionButtonClick = (event) => {
             if (this.disabled)
                 return;
             event.stopPropagation();
+            event.detail.originalEvent.stopPropagation();
             this.togglePicker.emit();
         };
         /**
-         * Confirma o conteúdo digitado quando o foco sai do input nativo, inclusive
-         * quando avança para o botão de calendário dentro do mesmo `br-input`.
+         * Blur handler: consome o evento e confirma o conteúdo atual.
+         *
+         * @param {FocusEvent} event - Evento de blur do input.
+         * @returns {void}
          */
         this.handleInputBlur = (event) => {
-            if (!(event.composedPath()[0] instanceof HTMLInputElement)) {
-                return;
-            }
-            if (this.disabled) {
-                return;
-            }
-            this.commitInputValue();
+            event.stopPropagation();
+            this.commitCurrentInput();
+        };
+        /**
+         * Handler para commit disparado pelo `change` do `br-input`.
+         *
+         * @param {Event} event - Evento de change.
+         * @returns {void}
+         */
+        this.handleInputCommit = (event) => {
+            event.stopPropagation();
+            this.commitCurrentInput();
         };
         /**
          * Atualiza o estado local com o valor digitado no campo.
          *
-         * @param event - Evento de input disparado pelo campo textual.
+         * @param {Event} event - Evento de input redistribuído pelo `br-input`.
+         * @returns {void}
          */
         this.handleInputChange = (event) => {
+            event.stopPropagation();
             if (this.disabled) {
                 return;
             }
             const input = event.target;
-            this.inputValue = input.value;
+            this.lastCommittedInputText = null;
+            this.emitInputValidation(null);
+            this.setInternalInputValue(input.value ?? '');
         };
         /**
-         * Permite confirmar a digitação pressionando Enter.
+         * Handler de teclado no campo de entrada.
+         *
+         * Suporta atalhos ARIA (Alt+ArrowDown / F4) para abrir/fechar o picker
+         * e Enter para confirmar a edição.
          *
-         * @param event - Evento de teclado do campo de entrada.
+         * @param {KeyboardEvent} event - Evento de teclado.
+         * @returns {void}
          */
         this.handleInputKeydown = (event) => {
             if (this.disabled) {
@@ -150,37 +170,23 @@ export class DatetimeInput {
                 this.togglePicker.emit();
                 return;
             }
-            if (event.key === 'Enter') {
-                this.commitInputValue();
-            }
-        };
-        /**
-         * Evita propagação do clique e solicita a abertura/fechamento do picker.
-         *
-         * @param event - Evento de clique no ícone de ação.
-         */
-        this.handleToggleDropdown = (event) => {
-            if (this.disabled) {
-                return;
+            if (event.key === 'Enter' && event.composedPath().some((target) => target instanceof HTMLInputElement)) {
+                // Previne submissão de formulários e garante deduplicação
+                // usando a mesma rotina que blur/change usam.
+                event.preventDefault();
+                this.commitCurrentInput();
             }
-            event.stopPropagation();
-            this.togglePicker.emit();
         };
     }
-    /** Move o foco para o input interno sem expor a árvore privada ao componente pai. @internal */
-    async focusInput() {
-        this.el.shadowRoot?.querySelector('br-input')?.focus();
-    }
-    get effectiveSelectionMode() {
-        return resolveAllowedPropValue(this.el, 'selectionMode', this.selectionMode, ['single', 'range'], 'single');
-    }
+    /**
+     * Watcher: sincroniza `rangeStart`/`rangeEnd` a partir de `rangeValue` controlado.
+     *
+     * @param {DatetimePickerDateRange | undefined} newValue - Novo intervalo ou `undefined`.
+     * @returns {void}
+     */
     handleRangeValueChange(newValue) {
         if (!newValue)
             return;
-        if (!isValidDatetimePickerDateRange(newValue)) {
-            reportInvalidPropValue(this.el, 'rangeValue', newValue, 'Informe um objeto com `start` e `end` como Date válido ou null.', 'Ignorando o intervalo inválido e mantendo o último intervalo efetivo.');
-            return;
-        }
         this.rangeStart = newValue.start;
         this.rangeEnd = newValue.end;
         this.syncInputValueFromProps();
@@ -190,6 +196,13 @@ export class DatetimeInput {
      *
      * @param newValue - Novo valor recebido via prop.
      */
+    /**
+     * Watcher: reage a mudanças externas em `value`, normalizando e sincronizando
+     * o texto exibido no input.
+     *
+     * @param {Date | null} newValue - Novo valor recebido via prop.
+     * @returns {void}
+     */
     handleValueChange(newValue) {
         this.ensureValidValue(newValue);
         this.syncInputValueFromProps();
@@ -199,6 +212,12 @@ export class DatetimeInput {
      *
      * @param newValue - Novo modo recebido via prop.
      */
+    /**
+     * Watcher: aplica normalização do `mode` e atualiza a máscara/valor exibido.
+     *
+     * @param {string} newValue - Novo modo recebido via prop.
+     * @returns {void}
+     */
     handleModeChange(newValue) {
         this.ensureValidMode(newValue);
         this.syncInputValueFromProps();
@@ -208,6 +227,12 @@ export class DatetimeInput {
      *
      * @param newValue - Nova data de referência recebida.
      */
+    /**
+     * Watcher: valida `referenceDate` e resina o input quando não há seleção.
+     *
+     * @param {Date} newValue - Nova data de referência recebida.
+     * @returns {void}
+     */
     handleReferenceDateChange(newValue) {
         this.ensureValidReferenceDate(newValue);
         if (this.value === null) {
@@ -219,8 +244,13 @@ export class DatetimeInput {
      *
      * @param newValue - Nova data inicial do range.
      */
+    /**
+     * Watcher: atualiza a representação textual quando o início do range muda.
+     *
+     * @returns {void}
+     */
     handleRangeStartChange() {
-        if (this.effectiveSelectionMode === 'range') {
+        if (this.selectionMode === 'range') {
             this.syncInputValueFromProps();
         }
     }
@@ -229,8 +259,13 @@ export class DatetimeInput {
      *
      * @param newValue - Nova data final do range.
      */
+    /**
+     * Watcher: atualiza a representação textual quando o fim do range muda.
+     *
+     * @returns {void}
+     */
     handleRangeEndChange() {
-        if (this.effectiveSelectionMode === 'range') {
+        if (this.selectionMode === 'range') {
             this.syncInputValueFromProps();
         }
     }
@@ -245,41 +280,36 @@ export class DatetimeInput {
         this.syncInputValueFromProps();
     }
     /**
-     * Registra os listeners do input nativo e do botão de ação após o DOM estar disponível.
+     * Confirma o conteúdo atual evitando commits duplicados (blur + change).
      *
-     * O br-button que envolve o slot "action" é focável. Quando Space/Enter é pressionado,
-     * o browser dispara um click sintético. Adicionamos um listener imperativo para
-     * garantir que o clique no botão de ação acione o toggle. O blur é observado na raiz
-     * interna porque mover o foco do input para essa ação não desfoca o host `br-input`.
+     * @returns {void}
      */
-    async componentDidLoad() {
-        // Tenta encontrar o br-button dentro do br-input que envolve o slot action
-        const brInput = this.el.shadowRoot?.querySelector('br-input');
-        if (!brInput)
+    commitCurrentInput() {
+        if (this.disabled)
             return;
-        if (!brInput.shadowRoot)
-            await brInput.componentOnReady();
-        if (!this.el.isConnected || !brInput.shadowRoot)
+        const currentText = this.inputValue.trim();
+        if (this.lastCommittedInputText === currentText)
             return;
-        this.inputShadowRoot = brInput.shadowRoot;
-        this.inputShadowRoot.addEventListener('blur', this.handleInputBlur, true);
-        const actionButton = this.inputShadowRoot.querySelector('br-button.button-transform');
-        if (!actionButton)
-            return;
-        this.actionButton = actionButton;
-        // Listener para clique no botão de ação (funciona para mouse e Space/Enter via button nativo)
-        actionButton.addEventListener('click', this.handleActionButtonClick);
+        this.lastCommittedInputText = currentText;
+        this.commitInputValue();
+        this.lastCommittedInputText = this.inputValue.trim();
     }
-    disconnectedCallback() {
-        this.inputShadowRoot?.removeEventListener('blur', this.handleInputBlur, true);
-        this.inputShadowRoot = undefined;
-        this.actionButton?.removeEventListener('click', this.handleActionButtonClick);
-        this.actionButton = undefined;
+    /**
+     * Retorna a máscara delegada ao `br-input` de acordo com o modo atual.
+     *
+     * @returns {string | undefined} - Máscara a ser aplicada, ou `undefined` quando indisponível.
+     */
+    getInputMask() {
+        if (this.selectionMode === 'range') {
+            const boundaryMask = INPUT_FORMAT_CONFIG[this.mode].mask;
+            return `${boundaryMask} - ${boundaryMask}`;
+        }
+        return INPUT_FORMAT_CONFIG[this.mode].mask;
     }
     /**
      * Retorna o rótulo acessível do botão de alternância do picker.
      *
-     * @returns Texto anunciado pelo leitor de tela para o ícone de ação.
+     * @returns {string} - Texto anunciado pelo leitor de tela para o ícone de ação.
      */
     getToggleAriaLabel() {
         switch (this.mode) {
@@ -292,9 +322,10 @@ export class DatetimeInput {
         }
     }
     /**
-     * Normaliza o modo de operação para um valor suportado.
+     * Normaliza e aplica um modo válido (`date` | `time` | `datetime`).
      *
-     * @param value - Modo informado externamente.
+     * @param {string} value - Modo informado externamente.
+     * @returns {void}
      */
     ensureValidMode(value = this.mode) {
         const normalizedMode = normalizeDatetimeInputMode(value);
@@ -303,9 +334,10 @@ export class DatetimeInput {
         }
     }
     /**
-     * Garante que a data de referência seja uma instância válida de `Date`.
+     * Garante que `referenceDate` seja uma `Date` válida; caso contrário, normaliza.
      *
-     * @param value - Data de referência recebida via prop.
+     * @param {Date} value - Data de referência recebida via prop.
+     * @returns {void}
      */
     ensureValidReferenceDate(value = this.referenceDate) {
         const normalizedReferenceDate = normalizeDatetimeInputReferenceDate(value);
@@ -316,7 +348,8 @@ export class DatetimeInput {
     /**
      * Normaliza o valor selecionado para `Date` válido ou `null`.
      *
-     * @param value - Valor recebido via prop.
+     * @param {Date | null} value - Valor recebido via prop.
+     * @returns {void}
      */
     ensureValidValue(value = this.value) {
         const normalizedValue = normalizeDatetimeInputValue(value);
@@ -326,47 +359,131 @@ export class DatetimeInput {
     }
     /**
      * Consolida o texto digitado, tenta analisar e emite o novo estado selecionado.
+     *
+     * Trata modos `single` e `range` e valida mensagens de erro apropriadas.
+     *
+     * @returns {void}
      */
     commitInputValue() {
         const inputText = this.inputValue.trim();
         if (inputText === '') {
+            this.emitInputValidation(true);
             this.value = null;
             this.dateStateChange.emit({
                 referenceDate: this.referenceDate,
                 value: null,
+                origin: this.el.tagName,
             });
             this.emitNativeValueChange();
             return;
         }
-        if (this.effectiveSelectionMode === 'range' && this.mode === 'date') {
+        if (this.selectionMode === 'range') {
             const parsedRange = this.parseRangeInput(inputText);
-            if (parsedRange === null)
+            if (parsedRange === null) {
+                this.emitInputValidation(false, this.getRangeValidationMessage(inputText));
                 return;
+            }
+            if (this.mode === 'datetime' && compareAsc(parsedRange.end, parsedRange.start) < 0) {
+                this.emitInputValidation(false, DATETIME_RANGE_ORDER_MESSAGE);
+                return;
+            }
             const normalizedRange = this.normalizeRangeBounds(parsedRange.start, parsedRange.end);
+            this.emitInputValidation(true);
             this.rangeValue = normalizedRange;
-            this.inputValue = `${this.formatDateByMode(normalizedRange.start)} - ${this.formatDateByMode(normalizedRange.end)}`;
+            this.setInternalInputValue(`${this.formatDateByMode(normalizedRange.start)} - ${this.formatDateByMode(normalizedRange.end)}`);
             this.value = normalizedRange.end;
             this.dateStateChange.emit({
                 referenceDate: normalizedRange.end,
                 value: normalizedRange.end,
                 range: normalizedRange,
+                origin: this.el.tagName,
             });
             this.emitNativeValueChange();
             return;
         }
+        if (!this.isInputComplete(inputText)) {
+            this.emitInputValidation(false, this.getInputValidationMessage(inputText));
+            return;
+        }
         const parsed = this.parseInputValue(inputText);
-        if (parsed === null)
+        if (parsed === null) {
+            this.emitInputValidation(false, this.getInputValidationMessage(inputText));
             return;
+        }
+        this.emitInputValidation(true);
         const newDate = new Date(parsed);
         newDate.setSeconds(0, 0);
-        this.inputValue = this.formatDateByMode(newDate);
+        this.setInternalInputValue(this.formatDateByMode(newDate));
         this.value = newDate;
         this.dateStateChange.emit({
             referenceDate: newDate,
             value: newDate,
+            origin: this.el.tagName,
         });
         this.emitNativeValueChange();
     }
+    /**
+     * Emite o resultado da validação textual sem alterar o valor selecionado.
+     *
+     * @param {boolean} valid - Indica se a entrada é válida.
+     * @param {string} [message] - Mensagem de erro quando inválido.
+     * @returns {void}
+     */
+    emitInputValidation(valid, message = '') {
+        this.inputValidationChange.emit({ valid, message: valid ? '' : message, origin: this.el.tagName });
+    }
+    /**
+     * Verifica se a entrada possui a quantidade de dígitos esperada para o modo atual.
+     *
+     * @param {string} value - Texto de entrada a ser verificado.
+     * @returns {boolean} - `true` quando completo.
+     */
+    isInputComplete(value) {
+        const digits = value.replace(/\D/g, '');
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        return config.acceptedDigitCounts.includes(digits.length);
+    }
+    /**
+     * Retorna mensagem de validação contextual para uma entrada incompleta ou inválida.
+     *
+     * @param {string} value - Texto de entrada a ser avaliado.
+     * @returns {string} - Mensagem de validação apropriada.
+     */
+    getInputValidationMessage(value) {
+        const digits = value.replace(/\D/g, '');
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        if (!config)
+            return 'Informe um valor válido.';
+        const digitCount = digits.length;
+        if (this.mode === 'datetime' &&
+            config.acceptedDigitCounts.includes(digitCount) &&
+            digitCount < config.fullDigitCount) {
+            return config.messages.invalid;
+        }
+        return digitCount < config.fullDigitCount ? config.messages.incomplete : config.messages.invalid;
+    }
+    /**
+     * Mensagem específica para o formato de intervalo do modo atual.
+     *
+     * @param {string} value - Texto de intervalo informado no input.
+     * @returns {string} - Mensagem de validação do intervalo.
+     */
+    getRangeValidationMessage(value) {
+        const [startRaw = '', endRaw = ''] = value.split(/\s*-\s*/, 2);
+        const startDigits = startRaw.replace(/\D/g, '');
+        const endDigits = endRaw.replace(/\D/g, '');
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        const expectedDigits = config.fullDigitCount;
+        if (startDigits.length < expectedDigits || endDigits.length < expectedDigits) {
+            return `Complete o intervalo no formato ${config.rangeFormat}.`;
+        }
+        return config.messages.invalidRange;
+    }
+    /**
+     * Dispara eventos nativos `input` e `change` para compatibilidade com forms.
+     *
+     * @returns {void}
+     */
     emitNativeValueChange() {
         dispatchNativeFormEvent(this.el, 'input');
         dispatchNativeFormEvent(this.el, 'change');
@@ -388,55 +505,90 @@ export class DatetimeInput {
             return null;
         }
         const base = this.referenceDate ?? toDate(new Date());
-        const parsedStart = this.parseDateInput(startText, base);
-        const parsedEnd = this.parseDateInput(endText, base);
+        const parsedStart = this.parseInputValue(startText, this.rangeStart ?? base);
+        const parsedEnd = this.parseInputValue(endText, this.rangeEnd ?? base);
         if (parsedStart === null || parsedEnd === null) {
             return null;
         }
         return { start: parsedStart, end: parsedEnd };
     }
-    /** Normaliza os limites do intervalo para garantir ordem cronológica. */
+    /**
+     * Normaliza os limites do intervalo para garantir ordem cronológica.
+     *
+     * - Em `time` e `datetime` mantém os limites informados.
+     * - Em `date` reordena caso necessário.
+     *
+     * @param {Date} start - Data de início.
+     * @param {Date} end - Data de término.
+     * @returns {{ start: Date; end: Date }} - Limites normalizados.
+     */
     normalizeRangeBounds(start, end) {
+        if (this.mode !== 'date')
+            return { start, end };
         return compareAsc(start, end) <= 0 ? { start, end } : { start: end, end: start };
     }
     /**
-     * Sincroniza o texto do campo com as props atuais de valor e modo.
+     * Sincroniza o texto do input com as props `value`/`rangeStart`/`rangeEnd` e `mode`.
+     *
+     * @returns {void}
      */
     syncInputValueFromProps() {
-        if (this.effectiveSelectionMode === 'range') {
+        if (this.selectionMode === 'range') {
             if (this.rangeStart === null || this.rangeEnd === null) {
-                this.inputValue = '';
+                this.setInternalInputValue('');
                 return;
             }
             const startFormatted = this.formatDateByMode(this.rangeStart);
             const endFormatted = this.formatDateByMode(this.rangeEnd);
-            this.inputValue = `${startFormatted} - ${endFormatted}`;
+            this.setInternalInputValue(`${startFormatted} - ${endFormatted}`);
             return;
         }
         if (this.value === null) {
-            this.inputValue = '';
+            this.setInternalInputValue('');
             return;
         }
-        this.inputValue = this.formatDateByMode(this.value);
+        this.setInternalInputValue(this.formatDateByMode(this.value));
+    }
+    /**
+     * Retorna o elemento interno `<br-input>` quando disponível.
+     *
+     * @internal
+     * @returns {HTMLBrInputElement | null} Elemento interno `<br-input>` ou `null` se não estiver disponível.
+     */
+    getBrInputElement() {
+        return this.el.shadowRoot?.querySelector('br-input');
+    }
+    /**
+     * Define o valor interno do input imperativamente.
+     *
+     * @internal Define o valor interno do input sem re-renderizar o host.
+     * @param {string} value Valor a ser definido no input interno.
+     */
+    setInternalInputValue(value) {
+        this.inputValue = value;
+        const br = this.getBrInputElement();
+        if (br) {
+            // atualiza imperativamente o componente filho sem re-renderizar o host
+            try {
+                br.value = value;
+            }
+            catch { }
+        }
     }
     /**
      * Formata uma data de acordo com o modo atual do componente.
      *
-     * @param date - Data a ser formatada para exibição no input.
-     * @returns Representação textual da data/hora no padrão esperado.
+     * @param {Date} date - Data a ser formatada para exibição no input.
+     * @returns {string} - Representação textual da data/hora no padrão esperado.
      */
     formatDateByMode(date) {
-        switch (this.mode) {
-            case 'date':
-                return format(date, 'dd/MM/yyyy');
-            case 'time':
-                return format(date, 'HH:mm');
-            default:
-                return format(date, 'dd/MM/yyyy HH:mm');
-        }
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        return format(date, config.displayFormat);
     }
     /**
-     * Retorna as classes CSS base aplicadas ao host visual do componente.
+     * Retorna o mapa de classes CSS aplicado ao host do componente.
+     *
+     * @returns {CssClassMap}
      */
     getCssClassMap() {
         return {
@@ -446,7 +598,7 @@ export class DatetimeInput {
     /**
      * Seleciona o ícone do campo conforme o modo de entrada ativo.
      *
-     * @returns Nome do ícone usado na ação lateral do input.
+     * @returns {string} - Nome do ícone usado na ação lateral do input.
      */
     getInputIcon() {
         switch (this.mode) {
@@ -459,11 +611,11 @@ export class DatetimeInput {
     /**
      * Converte o texto digitado em `Date` com base no modo configurado.
      *
-     * @param value - Texto informado pelo usuário no input.
-     * @returns Data convertida em objeto `Date` ou `null` quando inválida.
+     * @param {string} value - Texto informado pelo usuário no input.
+     * @param {Date} [base] - Data base usada para completar valores parciais.
+     * @returns {Date | null} - Data convertida ou `null` quando inválida.
      */
-    parseInputValue(value) {
-        const base = this.value ?? this.referenceDate ?? toDate(new Date());
+    parseInputValue(value, base = this.value ?? this.referenceDate ?? toDate(new Date())) {
         switch (this.mode) {
             case 'date':
                 return this.parseDateInput(value, base);
@@ -478,12 +630,14 @@ export class DatetimeInput {
     /**
      * Faz parse de uma data no formato `dd/MM/yyyy`, preservando hora e minuto base.
      *
-     * @param value - Texto de data digitado pelo usuário.
-     * @param base - Data base usada para completar informações de tempo.
-     * @returns Data válida normalizada ou `null` quando o parse falhar.
+     * @param {string} value - Texto de data digitado pelo usuário.
+     * @param {Date} base - Data base usada para completar informações de tempo.
+     * @returns {Date | null} - Data válida normalizada ou `null` quando o parse falhar.
      */
     parseDateInput(value, base) {
-        const parsedDate = parse(value, 'dd/MM/yyyy', base);
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        const datePattern = config.parseFormats[0];
+        const parsedDate = parse(value, datePattern, base);
         if (!isValid(parsedDate))
             return null;
         return set(parsedDate, {
@@ -496,12 +650,14 @@ export class DatetimeInput {
     /**
      * Faz parse de hora no formato `HH:mm`, preservando o dia da data base.
      *
-     * @param value - Texto de hora digitado pelo usuário.
-     * @param base - Data base usada para manter dia, mês e ano.
-     * @returns Data válida com hora ajustada ou `null` quando inválida.
+     * @param {string} value - Texto de hora digitado pelo usuário.
+     * @param {Date} base - Data base usada para manter dia, mês e ano.
+     * @returns {Date | null} - Data válida com hora ajustada ou `null` quando inválida.
      */
     parseTimeInput(value, base) {
-        const parsedTime = parse(value, 'HH:mm', base);
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        const timePattern = config.parseFormats[0];
+        const parsedTime = parse(value, timePattern, base);
         if (!isValid(parsedTime))
             return null;
         return set(base, {
@@ -512,20 +668,23 @@ export class DatetimeInput {
         });
     }
     /**
-     * Faz parse de data e hora completas, com fallback para entradas parciais.
+     * Faz parse de data e hora completas, aceitando somente a data como fallback.
      *
-     * @param value - Texto digitado no input.
-     * @param base - Data base usada como contexto para completar o parse.
-     * @returns Data válida a partir da entrada ou `null` quando não reconhecida.
+     * @param {string} value - Texto digitado no input.
+     * @param {Date} base - Data base usada como contexto para completar o parse.
+     * @returns {Date | null} - Data válida a partir da entrada ou `null` quando não reconhecida.
      */
     parseDateTimeInput(value, base) {
+        const config = INPUT_FORMAT_CONFIG[this.mode];
+        const fullPattern = config.parseFormats[0];
+        const fallbackDatePattern = config.parseFormats[1];
         // data + hora
-        const full = parse(value, 'dd/MM/yyyy HH:mm', base);
+        const full = parse(value, fullPattern, base);
         if (isValid(full))
             return full;
-        // so data -> hora atual
-        const date = this.parseDateInput(value, base);
-        if (date !== null) {
+        // somente data -> preserva a hora da data base
+        const date = parse(value, fallbackDatePattern, base);
+        if (isValid(date)) {
             return set(date, {
                 hours: getHours(base),
                 minutes: getMinutes(base),
@@ -533,14 +692,7 @@ export class DatetimeInput {
                 milliseconds: 0,
             });
         }
-        // so hora -> data atual
-        return this.parseTimeInput(value, base);
-    }
-    /**
-     * Renderiza o campo textual e o ícone de ação do datetime input.
-     */
-    renderInputField() {
-        return (h("br-input", { type: "text", value: this.inputValue, placeholder: this.placeholder, disabled: this.disabled, actionLabel: this.getToggleAriaLabel(), onInput: this.handleInputChange, onKeyDown: this.handleInputKeydown, "aria-label": this.getInputAriaLabel(), part: "input" }, h("br-icon", { slot: "action", iconName: this.getInputIcon(), width: "16", height: "16", "aria-hidden": "true", onClick: this.handleToggleDropdown, part: "icon" })));
+        return null;
     }
     /**
      * Retorna o rótulo acessível do campo de entrada de acordo com o modo ativo.
@@ -557,11 +709,19 @@ export class DatetimeInput {
                 return 'Campo de data e hora';
         }
     }
+    /**
+     * Renderiza o campo textual e o ícone de ação do datetime input.
+     *
+     * @returns {JSX.Element}
+     */
+    renderInputField() {
+        return (h("br-input", { type: "text", mask: this.getInputMask(), placeholder: this.placeholder, disabled: this.disabled, actionLabel: this.getToggleAriaLabel(), onInput: this.handleInputChange, onChange: this.handleInputCommit, onBlur: this.handleInputBlur, onKeyDown: this.handleInputKeydown, onBrInputActionClick: this.handleActionButtonClick, "aria-label": this.getInputAriaLabel(), part: "input" }, h("br-icon", { slot: "action", iconName: this.getInputIcon(), width: "16", height: "16", "aria-hidden": "true", part: "icon" })));
+    }
     /**
      * Renderização principal do componente.
      */
     render() {
-        return (h(Host, { key: '8c5536c6a740ac0d42be7bf89ffc1098d896f895' }, h("div", { key: 'c9a1a995838739f5b6e00fcf39a21bee81362e90', class: this.getCssClassMap(), part: "container" }, this.renderInputField())));
+        return (h(Host, { key: '40033b7b73bd1760cf07c5b4797a86e918fde54b' }, h("div", { key: '31e968efbb7a6f43acb8a67fb225d6e0159af7f9', class: this.getCssClassMap(), part: "container" }, this.renderInputField())));
     }
     static get is() { return "br-datetime-input"; }
     static get encapsulation() { return "shadow"; }
@@ -593,7 +753,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "''"
                         }],
-                    "text": "Define o placeholder do campo de entrada."
+                    "text": "Texto de placeholder exibido quando o campo estiver vazio."
                 },
                 "getter": false,
                 "setter": false,
@@ -623,7 +783,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "'datetime'"
                         }],
-                    "text": "Define o modo de entrada: `date`, `time` ou `datetime`."
+                    "text": "Modo de entrada que controla m\u00E1scara, parser e formato exibido."
                 },
                 "getter": false,
                 "setter": false,
@@ -650,11 +810,8 @@ export class DatetimeInput {
                     "tags": [{
                             "name": "default",
                             "text": "new Date()"
-                        }, {
-                            "name": "example",
-                            "text": "```js\nconst input = document.querySelector('br-datetime-input');\ninput.referenceDate = new Date(2026, 8, 1);\n```"
                         }],
-                    "text": "Data de refer\u00EAncia que orienta a navega\u00E7\u00E3o visual do calend\u00E1rio sem alterar a sele\u00E7\u00E3o.\nRecebe uma inst\u00E2ncia de `Date` por property binding."
+                    "text": "Data de refer\u00EAncia usada para navega\u00E7\u00E3o e preenchimento de valores parciais."
                 },
                 "getter": false,
                 "setter": false,
@@ -679,11 +836,8 @@ export class DatetimeInput {
                     "tags": [{
                             "name": "default",
                             "text": "null"
-                        }, {
-                            "name": "example",
-                            "text": "```js\nconst input = document.querySelector('br-datetime-input');\ninput.value = new Date(2026, 8, 7, 14, 30);\n```"
                         }],
-                    "text": "Data efetivamente selecionada, ou `null` quando nada foi escolhido; \u00E9 diferente\nde `referenceDate`, que controla apenas a refer\u00EAncia visual.\nRecebe uma inst\u00E2ncia de `Date` por property binding."
+                    "text": "Valor atualmente selecionado pelo componente."
                 },
                 "getter": false,
                 "setter": false,
@@ -704,7 +858,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "false"
                         }],
-                    "text": "Desabilita digita\u00E7\u00E3o e abertura do picker quando ativo."
+                    "text": "Controla os estados de read-only ou bloqueio de formul\u00E1rio."
                 },
                 "getter": false,
                 "setter": false,
@@ -734,7 +888,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "'single'"
                         }],
-                    "text": "Define se a sele\u00E7\u00E3o ocorre por data \u00FAnica ou por intervalo.\nAceita `single` ou `range`; valores inv\u00E1lidos usam `single`."
+                    "text": "Define o modo de sele\u00E7\u00E3o: `single` (valor \u00FAnico) ou `range` (intervalo)."
                 },
                 "getter": false,
                 "setter": false,
@@ -762,7 +916,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "null"
                         }],
-                    "text": "Data inicial do intervalo quando em modo range."
+                    "text": "In\u00EDcio do intervalo em `selectionMode === 'range'`."
                 },
                 "getter": false,
                 "setter": false,
@@ -788,7 +942,7 @@ export class DatetimeInput {
                             "name": "default",
                             "text": "null"
                         }],
-                    "text": "Data final do intervalo quando em modo range."
+                    "text": "Fim do intervalo em `selectionMode === 'range'`."
                 },
                 "getter": false,
                 "setter": false,
@@ -813,10 +967,10 @@ export class DatetimeInput {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst input = document.querySelector('br-datetime-input');\ninput.selectionMode = 'range';\ninput.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };\n```"
+                            "name": "type",
+                            "text": "{DatetimePickerDateRange | undefined}"
                         }],
-                    "text": "Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualiza\u00E7\u00E3o.\nDeve conter datas v\u00E1lidas ou `null`; valores inv\u00E1lidos s\u00E3o ignorados. Passe o objeto por property binding."
+                    "text": "Intervalo controlado no modo `range` como objeto `{ start, end }`."
                 },
                 "getter": false,
                 "setter": false
@@ -831,12 +985,21 @@ export class DatetimeInput {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Emite quando o valor \u00E9 alterado via input ou parsing."
+                    "tags": [{
+                            "name": "property",
+                            "text": "{Date} referenceDate - Data de refer\u00EAncia usada na navega\u00E7\u00E3o."
+                        }, {
+                            "name": "property",
+                            "text": "{Date|null} value - Valor selecionado ou `null`."
+                        }, {
+                            "name": "property",
+                            "text": "{DatetimePickerDateRange} [range] - Intervalo quando `selectionMode === 'range'`."
+                        }],
+                    "text": "Evento emitido quando o estado de data/hora muda (ap\u00F3s commit ou parsing).\n\nPayload (`detail`):"
                 },
                 "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",
@@ -853,43 +1016,42 @@ export class DatetimeInput {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Solicita ao componente pai a altern\u00E2ncia da abertura do picker."
+                    "tags": [{
+                            "name": "event",
+                            "text": "togglePicker"
+                        }],
+                    "text": "Emite uma solicita\u00E7\u00E3o ao componente pai para alternar a abertura do picker.\nEmite sem payload."
                 },
                 "complexType": {
                     "original": "void",
                     "resolved": "void",
                     "references": {}
                 }
-            }];
-    }
-    static get methods() {
-        return {
-            "focusInput": {
-                "complexType": {
-                    "signature": "() => Promise<void>",
-                    "parameters": [],
-                    "references": {
-                        "Promise": {
-                            "location": "global",
-                            "id": "global::Promise"
-                        },
-                        "HTMLElement": {
-                            "location": "global",
-                            "id": "global::HTMLElement"
-                        }
-                    },
-                    "return": "Promise<void>"
-                },
+            }, {
+                "method": "inputValidationChange",
+                "name": "inputValidationChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
                 "docs": {
-                    "text": "Move o foco para o input interno sem expor a \u00E1rvore privada ao componente pai.",
                     "tags": [{
-                            "name": "internal",
-                            "text": undefined
-                        }]
+                            "name": "property",
+                            "text": "{boolean|null} valid - Indica se o texto \u00E9 considerado v\u00E1lido (`null` enquanto edi\u00E7\u00E3o)."
+                        }, {
+                            "name": "property",
+                            "text": "{string} message - Mensagem de erro explicativa (vazia quando v\u00E1lido)."
+                        }, {
+                            "name": "property",
+                            "text": "{string} [origin] - Identificador expl\u00EDcito da origem do evento"
+                        }],
+                    "text": "Emite valida\u00E7\u00E3o do texto digitado sem alterar o valor selecionado.\n\nPayload (`detail`):"
+                },
+                "complexType": {
+                    "original": "{ valid: boolean | null; message: string; origin?: string }",
+                    "resolved": "{ valid: boolean; message: string; origin?: string; }",
+                    "references": {}
                 }
-            }
-        };
+            }];
     }
     static get elementRef() { return "el"; }
     static get watchers() {