@govbr-ds/webcomponents 2.2.0 → 2.4.0

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

@@ -1,215 +1,316 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerMode, DatetimePickerSelectionMode } from '../datetime-picker.types';
 /**
- * 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 declare class DatetimeInput {
     /** Referência ao elemento host do componente no DOM. */
     el: HTMLBrDatetimeInputElement;
-    /** Move o foco para o input interno sem expor a árvore privada ao componente pai. @internal */
-    focusInput(): Promise<void>;
-    /** Valor textual exibido no campo e usado durante a edição manual. */
-    private inputValue;
-    private actionButton?;
     /**
-     * Define o placeholder do campo de entrada.
+     * Texto de placeholder exibido quando o campo estiver vazio.
      *
      * @default ''
      */
     placeholder: string;
     /**
-     * Define o modo de entrada: `date`, `time` ou `datetime`.
+     * Modo de entrada que controla máscara, parser e formato exibido.
      *
      * @default 'datetime'
      */
     mode: DatetimePickerMode;
     /**
-     * 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);
-     * ```
      */
     referenceDate: 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);
-     * ```
      */
     value: Date | null;
     /**
-     * Desabilita digitação e abertura do picker quando ativo.
+     * Controla os estados de read-only ou bloqueio de formulário.
      *
      * @default false
      */
     disabled: boolean;
     /**
-     * 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'
      */
     selectionMode: DatetimePickerSelectionMode;
-    private get effectiveSelectionMode();
     /**
-     * Data inicial do intervalo quando em modo range.
+     * Início do intervalo em `selectionMode === 'range'`.
      *
      * @default null
      */
     rangeStart: Date | null;
     /**
-     * Data final do intervalo quando em modo range.
+     * Fim do intervalo em `selectionMode === 'range'`.
      *
      * @default null
      */
     rangeEnd: Date | null;
     /**
-     * Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualização.
-     * Deve conter datas válidas ou `null`; valores inválidos são ignorados. Passe o objeto por property binding.
+     * Intervalo controlado no modo `range` como objeto `{ start, end }`.
      *
-     * @example
-     * ```js
-     * const input = document.querySelector('br-datetime-input');
-     * input.selectionMode = 'range';
-     * input.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };
-     * ```
+     * @type {DatetimePickerDateRange | undefined}
      */
     rangeValue?: DatetimePickerDateRange;
+    /**
+     * Evento emitido quando o estado de data/hora muda (após commit ou parsing).
+     *
+     * Payload (`detail`):
+     * @property {Date} referenceDate - Data de referência usada na navegação.
+     * @property {Date|null} value - Valor selecionado ou `null`.
+     * @property {DatetimePickerDateRange} [range] - Intervalo quando `selectionMode === 'range'`.
+     */
+    dateStateChange: EventEmitter<DatetimePickerDateState>;
+    /**
+     * Emite uma solicitação ao componente pai para alternar a abertura do picker.
+     * Emite sem payload.
+     *
+     * @event togglePicker
+     */
+    togglePicker: EventEmitter<void>;
+    /**
+     * Emite validação do texto digitado sem alterar o valor selecionado.
+     *
+     * Payload (`detail`):
+     * @property {boolean|null} valid - Indica se o texto é considerado válido (`null` enquanto edição).
+     * @property {string} message - Mensagem de erro explicativa (vazia quando válido).
+     * @property {string} [origin] - Identificador explícito da origem do evento
+     */
+    inputValidationChange: EventEmitter<{
+        valid: boolean | null;
+        message: string;
+        origin?: string;
+    }>;
+    /**
+     * Marcador do último texto confirmado (commit) exibido no input.
+     *
+     * @internal
+     * @type {string | null}
+     * @default null
+     */
+    private lastCommittedInputText;
+    /**
+     * 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 ''
+     */
+    private inputValue;
+    /**
+     * Watcher: sincroniza `rangeStart`/`rangeEnd` a partir de `rangeValue` controlado.
+     *
+     * @param {DatetimePickerDateRange | undefined} newValue - Novo intervalo ou `undefined`.
+     * @returns {void}
+     */
     handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
     /**
      * Revalida e reflete no input mudanças externas em `value`.
      *
      * @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: Date | null): void;
     /**
      * Garante modo suportado e ajusta máscara/valor textual exibido.
      *
      * @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: string): void;
     /**
      * Valida a data de referência e sincroniza o campo quando não há seleção.
      *
      * @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: Date): void;
     /**
      * Sincroniza o input quando o início do range muda.
      *
      * @param newValue - Nova data inicial do range.
      */
+    /**
+     * Watcher: atualiza a representação textual quando o início do range muda.
+     *
+     * @returns {void}
+     */
     handleRangeStartChange(): void;
     /**
      * Sincroniza o input quando o fim do range muda.
      *
      * @param newValue - Nova data final do range.
      */
-    handleRangeEndChange(): void;
-    /**
-     * Emite quando o valor é alterado via input ou parsing.
-     */
-    dateStateChange: EventEmitter<DatetimePickerDateState>;
     /**
-     * Solicita ao componente pai a alternância da abertura do picker.
+     * Watcher: atualiza a representação textual quando o fim do range muda.
+     *
+     * @returns {void}
      */
-    togglePicker: EventEmitter<void>;
-    private inputShadowRoot?;
+    handleRangeEndChange(): void;
     /**
      * Valida props iniciais e sincroniza o texto exibido no input.
      */
     componentWillLoad(): void;
     /**
-     * Registra os listeners do input nativo e do botão de ação após o DOM estar disponível.
+     * Handler do clique no botão de ação interno.
      *
-     * 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`.
+     * @param event - Ativação pública da ação do br-input.
+     * @returns {void}
      */
-    componentDidLoad(): Promise<void>;
-    disconnectedCallback(): void;
     private handleActionButtonClick;
     /**
-     * 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}
      */
     private handleInputBlur;
+    /**
+     * Handler para commit disparado pelo `change` do `br-input`.
+     *
+     * @param {Event} event - Evento de change.
+     * @returns {void}
+     */
+    private handleInputCommit;
+    /**
+     * Confirma o conteúdo atual evitando commits duplicados (blur + change).
+     *
+     * @returns {void}
+     */
+    private 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}
      */
     private handleInputChange;
     /**
-     * Permite confirmar a digitação pressionando Enter.
+     * Retorna a máscara delegada ao `br-input` de acordo com o modo atual.
      *
-     * @param event - Evento de teclado do campo de entrada.
+     * @returns {string | undefined} - Máscara a ser aplicada, ou `undefined` quando indisponível.
      */
-    private handleInputKeydown;
+    private getInputMask;
     /**
-     * Evita propagação do clique e solicita a abertura/fechamento do picker.
+     * 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 clique no ícone de ação.
+     * @param {KeyboardEvent} event - Evento de teclado.
+     * @returns {void}
      */
-    private handleToggleDropdown;
+    private handleInputKeydown;
     /**
      * 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.
      */
     private getToggleAriaLabel;
     /**
-     * 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}
      */
     private ensureValidMode;
     /**
-     * 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}
      */
     private ensureValidReferenceDate;
     /**
      * 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}
      */
     private ensureValidValue;
     /**
      * 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}
      */
     private commitInputValue;
+    /**
+     * 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}
+     */
+    private emitInputValidation;
+    /**
+     * 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.
+     */
+    private isInputComplete;
+    /**
+     * 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.
+     */
+    private getInputValidationMessage;
+    /**
+     * 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.
+     */
+    private getRangeValidationMessage;
+    /**
+     * Dispara eventos nativos `input` e `change` para compatibilidade com forms.
+     *
+     * @returns {void}
+     */
     private emitNativeValueChange;
     /**
      * Analisa o intervalo no formato `dd/MM/yyyy - dd/MM/yyyy`.
@@ -218,70 +319,100 @@ export declare class DatetimeInput {
      * @returns Intervalo analisado ou `null` quando inválido.
      */
     private parseRangeInput;
-    /** 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.
+     */
     private normalizeRangeBounds;
     /**
-     * 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}
      */
     private syncInputValueFromProps;
+    /**
+     * 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.
+     */
+    private getBrInputElement;
+    /**
+     * 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.
+     */
+    private setInternalInputValue;
     /**
      * 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.
      */
     private formatDateByMode;
     /**
-     * Retorna as classes CSS base aplicadas ao host visual do componente.
+     * Retorna o mapa de classes CSS aplicado ao host do componente.
+     *
+     * @returns {CssClassMap}
      */
     private getCssClassMap;
     /**
      * 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.
      */
     private getInputIcon;
     /**
      * 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.
      */
     private parseInputValue;
     /**
      * 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.
      */
     private parseDateInput;
     /**
      * 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.
      */
     private parseTimeInput;
     /**
-     * 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.
      */
     private parseDateTimeInput;
-    /**
-     * Renderiza o campo textual e o ícone de ação do datetime input.
-     */
-    private renderInputField;
     /**
      * Retorna o rótulo acessível do campo de entrada de acordo com o modo ativo.
      *
      * @returns Texto anunciado pelo leitor de tela para identificar o campo.
      */
     private getInputAriaLabel;
+    /**
+     * Renderiza o campo textual e o ícone de ação do datetime input.
+     *
+     * @returns {JSX.Element}
+     */
+    private renderInputField;
     /**
      * Renderização principal do componente.
      */

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

@@ -0,0 +1,36 @@
+/**
+ * Configuração estrutural da entrada textual para um modo do datetime input.
+ *
+ * @typedef {object} InputFormatConfig
+ * @property {string} mask - Máscara utilizada para render e validação (ex.: `yyyy-MM-dd`, `HH:mm`, `yyyy-MM-dd HH:mm`).
+ * @property {readonly number[]} acceptedDigitCounts - Conjuntos de contagens de dígitos aceitas (útil para validação incremental/formatos alternativos).
+ * @property {number} fullDigitCount - Quantidade total de dígitos esperada para uma entrada completa (usada para validação estrita).
+ * @property {string} displayFormat - Formato usado para `format(date, formatString)` (date-fns).
+ * @property {readonly string[]} parseFormats - Formatos aceitos para parse (em ordem de preferência) usados por `parse` (date-fns).
+ * @property {object} messages - Mensagens customizáveis para validação/estado do input.
+ * @property {string} rangeFormat - Formato textual usado para exibir o modelo de intervalo na mensagem.
+ */
+export type InputFormatConfig = {
+    mask: string;
+    acceptedDigitCounts: readonly number[];
+    fullDigitCount: number;
+    displayFormat: string;
+    parseFormats: readonly string[];
+    messages: InputFormatMessages;
+    rangeFormat: string;
+};
+/**
+ * Conjunto de mensagens usadas para feedback do `br-datetime-input`.
+ *
+ * @typedef {object} InputFormatMessages
+ * @property {string} incomplete - Mensagem quando a entrada está incompleta (ex.: falta digitar dígitos).
+ * @property {string} invalid - Mensagem quando a entrada completa é inválida (ex.: 31/02/2026).
+ * @property {string} incompleteRange - Mensagem quando o intervalo está incompleto (ex.: falta o fim).
+ * @property {string} invalidRange - Mensagem quando o intervalo é inválido (ex.: fim anterior ao início).
+ */
+export type InputFormatMessages = {
+    incomplete: string;
+    invalid: string;
+    incompleteRange: string;
+    invalidRange: string;
+};

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

@@ -1,7 +1,13 @@
 /**
- * Conjunto de modos suportados pelo datetime picker.
+ * Conjunto de modos suportados pelo `br-datetime-picker`.
  *
- * `DEFAULT` define o modo aplicado quando o consumidor não informa um valor válido.
+ * - `DATE`: modo de seleção apenas de data.
+ * - `TIME`: modo de seleção apenas de hora.
+ * - `DATETIME`: modo de seleção de data e hora.
+ * - `DEFAULT`: modo aplicado quando o consumidor não informa um valor válido.
+ *
+ * @readonly
+ * @constant {Readonly<Record<string, string>>}
  */
 export declare const DATETIME_PICKER_MODE: {
     readonly DATE: "date";
@@ -9,10 +15,14 @@ export declare const DATETIME_PICKER_MODE: {
     readonly DATETIME: "datetime";
     readonly DEFAULT: "datetime";
 };
+export declare const DATETIME_RANGE_ORDER_MESSAGE = "A data e hora de t\u00E9rmino devem ser iguais ou posteriores \u00E0s de in\u00EDcio.";
 /**
- * Valores de locale aceitos pelo componente.
+ * Valores de `locale` aceitos pelo componente.
+ *
+ * `DEFAULT` representa o locale padrão do design system (padrão: `pt-BR`).
  *
- * `DEFAULT` representa o locale padrão do design system.
+ * @readonly
+ * @constant {Readonly<Record<string, string>>}
  */
 export declare const DATETIME_PICKER_LOCALE: {
     readonly DEFAULT: "pt-BR";
@@ -20,7 +30,11 @@ export declare const DATETIME_PICKER_LOCALE: {
 /**
  * Ações de navegação emitidas pelos controles do calendário e do relógio.
  *
- * Os nomes são usados como contrato entre os componentes que compartilham a navegação.
+ * Os valores formam o contrato entre componentes que consomem ou disparam eventos
+ * de navegação (por exemplo, avançar mês/hora ou retroceder minuto).
+ *
+ * @readonly
+ * @constant {Readonly<Record<string, string>>}
  */
 export declare const NAVIGATION_ACTION: {
     readonly PREVIOUS_HOUR: "previous-hour";

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

@@ -1,9 +1,36 @@
 import type { DatetimePickerDateRange, DatetimePickerFormContext, DatetimePickerMissingValueContext, DatetimePickerMode } from './datetime-picker.types';
-/** Serializa o valor atual para envio em FormData conforme o modo ativo. */
+/**
+ * Serializa o valor atual para envio em FormData conforme o modo ativo.
+ *
+ * @param {Date | null} value - Valor selecionado a ser serializado para submissão.
+ * @param {DatetimePickerFormContext} context - Contexto com `mode`, `selectionMode` e limites (rangeStart/rangeEnd).
+ * @returns {string | null} Representação serializada pronta para `FormData`, ou `null` quando não houver valor.
+ */
 export declare function serializeDatetimePickerFormValue(value: Date | null, context: DatetimePickerFormContext): string | null;
-/** Analisa um valor serializado de formulário para Date respeitando o modo atual. */
+/**
+ * Analisa um valor serializado de formulário para `Date` respeitando o modo atual.
+ *
+ * @param {string} value - String serializada vinda do formulário.
+ * @param {DatetimePickerMode} mode - Modo (`date` | `time` | `datetime`) que dita o parser a ser usado.
+ * @param {Date} referenceDate - Data de referência usada ao analisar valores de hora.
+ * @returns {Date | null} Objeto Date quando a análise for bem-sucedida, ou `null` quando inválido.
+ */
 export declare function parseDatetimePickerSerializedValue(value: string, mode: DatetimePickerMode, referenceDate: Date): Date | null;
-/** Analisa intervalo serializado no formato YYYY-MM-DD/YYYY-MM-DD. */
-export declare function parseDatetimePickerSerializedRange(value: string): DatetimePickerDateRange | null;
-/** Informa se o componente deve sinalizar valueMissing na validação nativa. */
+/**
+ * Analisa um intervalo serializado no formato `start/end` conforme o modo ativo.
+ *
+ * @param {string} value - String no formato `start/end` contendo os dois lados do intervalo.
+ * @param {DatetimePickerMode} mode - Modo a ser usado para análise (padrão: `date`).
+ * @param {Date} referenceDate - Data de referência para análise de horários.
+ * @returns {DatetimePickerDateRange | null} `{ start, end }` quando válido, ou `null` quando inválido.
+ */
+export declare function parseDatetimePickerSerializedRange(value: string, mode?: DatetimePickerMode, referenceDate?: Date): DatetimePickerDateRange | null;
+/**
+ * Indica se o componente deve sinalizar `valueMissing` na validação nativa.
+ *
+ * A função considera `required`, `disabled` e se o valor (ou intervalo) está incompleto.
+ *
+ * @param {DatetimePickerMissingValueContext} context - Contexto contendo `required`, `disabled`, `value` e, quando aplicável, `rangeStart`/`rangeEnd`.
+ * @returns {boolean} `true` quando o controle deve reportar `valueMissing`.
+ */
 export declare function hasDatetimePickerMissingValue(context: DatetimePickerMissingValueContext): boolean;