@govbr-ds/webcomponents 2.2.0 → 2.4.0

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

@@ -1,22 +1,19 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerSelectionMode, WeekDayIndex } from '../datetime-picker.types';
 /**
- * Subcomponente de calendário visual do GovBR-DS, projetado para seleção interativa de datas individuais ou intervalos.
+ * O `br-date-picker` é o subcomponente de calendário do `br-datetime-picker`, responsável pela seleção visual de uma data ou de um intervalo.
  *
  * ### Papel na composição
  *
- * - Exibe a grade mensal navegável com suporte a seleção de dia, navegação entre meses e anos, e destaque para a data atual e intervalos.
- * - Implementa navegação acessível por teclado WAI-ARIA Grid (setas direcionais para dias e semanas).
+ * Exibe a grade mensal, a navegação entre meses e anos e os estados de seleção e bloqueio dos dias. `referenceDate` determina o período exibido, enquanto `value` e os limites do intervalo representam a seleção.
  *
  * ### Regra de uso e relacionamento
  *
- * Geralmente exibido dentro da superfície suspensa coordenada pelo `br-datetime-picker`. Pode ser declarado isoladamente quando a interface demandar um calendário estático permanentemente embutido na página (inline calendar).
+ * O `br-datetime-picker` instancia e configura este calendário internamente nos modos `date` e `datetime`, recebendo suas alterações pelo evento `dateStateChange`. Não declare o calendário em um slot do pai.
  *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
+ * Use diretamente quando precisar de um calendário embutido e permanentemente visível. Nesse caso, a aplicação deve coordenar valores e eventos e implementar a integração com formulários e a validação do fluxo completo. O calendário isolado não fornece o campo textual, o seletor de horários nem a associação ao formulário do orquestrador.
  *
-
- * @category Formulários, Seleção
- * @status stable
+ * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/date-picker?tab=designer).
  *
  * @part container - Parte para o container base do calendário.
  * @part header - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).
@@ -29,266 +26,372 @@ import type { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerSe
  * @part day - Célula individual do dia no calendário.
  */
 export declare class DatePicker {
-    /** Referencia ao elemento host do componente no DOM. */
+    /**
+     * Referência ao elemento host do componente no DOM.
+     * @internal
+     */
     el: HTMLBrDatePickerElement;
-    /** Data com foco atual na navegação por teclado do calendário. */
-    private focusedDate;
-    /** Datas inválidas são removidas da lista antes da comparação com o calendário. */
-    private normalizedDisabledDates;
-    /** Define o índice do dia em que a semana começa na interface do calendário. */
+    /**
+     * Índice do dia em que a semana começa na interface do calendário.
+     * @default 0
+     */
     weekStartsOn: WeekDayIndex;
     /**
-     * Data usada como base visual para o mês atualmente exibido, sem alterar a seleção.
-     * Recebe uma instância de `Date` por property binding; valores inválidos usam a data atual.
-     *
-     * @example
-     * ```js
-     * const calendar = document.querySelector('br-date-picker');
-     * calendar.referenceDate = new Date(2026, 8, 1);
-     * ```
+     * Data usada como base visual para o mês atualmente exibido.
+     * @default new Date()
      */
     referenceDate: Date;
     /**
-     * Data efetivamente selecionada, ou `null` quando não há seleção; é diferente de `referenceDate`, que controla apenas o mês visível.
-     * Recebe uma instância de `Date` por property binding; datas inválidas usam `null`.
-     *
-     * @example
-     * ```js
-     * const calendar = document.querySelector('br-date-picker');
-     * calendar.value = new Date(2026, 8, 7);
-     * ```
+     * Data atualmente selecionada pelo usuário, ou `null` quando não há seleção.
+     * @default null
      */
     value: Date | null;
-    /** Define se a seleção ocorre por data única ou por intervalo. Valores inválidos usam `single`. */
+    /**
+     * Define se a seleção ocorre por data única ou por intervalo.
+     * @default 'single'
+     */
     selectionMode: DatetimePickerSelectionMode;
-    private get effectiveSelectionMode();
-    /** Data inicial selecionada quando o calendário opera no modo de intervalo. */
+    /**
+     * Data inicial selecionada quando o calendário opera no modo de intervalo.
+     * @default null
+     */
     rangeStart: Date | null;
-    /** Data final selecionada quando o calendário opera no modo de intervalo. */
+    /**
+     * Data final selecionada quando o calendário opera no modo de intervalo.
+     * @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.
-     *
-     * @example
-     * ```js
-     * const calendar = document.querySelector('br-date-picker');
-     * calendar.selectionMode = 'range';
-     * calendar.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };
-     * ```
+     * Intervalo controlado no modo `range`.
+     * Quando definido, mantém `rangeStart` e `rangeEnd` sincronizados.
+     * @default undefined
      */
     rangeValue?: DatetimePickerDateRange;
-    handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
-    /** Desabilita a interação do calendário quando ativo. */
+    /**
+     * Desabilita a interação do calendário quando `true`.
+     * @default false
+     */
     disabled: boolean;
     /**
      * Lista de datas indisponíveis para seleção no calendário.
-     * Recebe instâncias de `Date` por property binding; datas inválidas são ignoradas.
-     *
-     * @example
-     * ```js
-     * const calendar = document.querySelector('br-date-picker');
-     * calendar.disabledDates = [new Date(2026, 8, 7), new Date(2026, 8, 8)];
-     * ```
+     * @default []
      */
     disabledDates: Date[];
-    /** Locale usado para gerar nomes de meses e dias da semana. */
+    /**
+     * Locale usado para gerar nomes de meses e dias da semana.
+     * @default DATETIME_PICKER_LOCALE.DEFAULT
+     */
     locale: string;
     /**
-     * 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.
-     *
+     * Se `true`, o calendário sempre exibe 6 semanas (42 dias); caso contrário, adapta-se ao mês.
      * @default false
      */
     fixedRowCount: boolean;
+    /**
+     * Data atualmente com foco para navegação por teclado.
+     * Usada para controlar qual célula do calendário recebe `tabindex=0`.
+     * @type {Date}
+     * @default new Date()
+     * @internal
+     */
+    private focusedDate;
+    /**
+     * Emite o estado consolidado do componente quando há mudança de referência/seleção.
+     *
+     * Payload (DatetimePickerDateState):
+     * @property {Date} referenceDate - Data de referência atual do calendário (segundos/milissegundos zerados).
+     * @property {(Date|null)} value - Data selecionada ou `null` quando nenhuma seleção.
+     * @property {{start: Date, end: (Date|null)}=} range - Intervalo selecionado quando `selectionMode === 'range'`.
+     *
+     * Consumidores usam este evento para sincronizar UI externas e integração com formulários.
+     * @event dateStateChange
+     * @type {EventEmitter<DatetimePickerDateState>}
+     */
+    dateStateChange: EventEmitter<DatetimePickerDateState>;
+    /**
+     * Sinaliza ao `componentDidRender` que o foco deve ser movido para a célula atual.
+     * @internal
+     */
+    private shouldFocusDate;
+    /**
+     * Observador para a prop `rangeValue` — sincroniza `rangeStart` e `rangeEnd`.
+     * @param {DatetimePickerDateRange | undefined} newValue - novo intervalo controlado recebido (`undefined` quando não fornecido)
+     * @internal
+     */
+    handleRangeValueChange(newValue?: DatetimePickerDateRange): void;
     /**
      * Sincroniza `focusedDate` quando o valor selecionado muda externamente.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {Date | null} newValue - Novo valor recebido via prop.
+     */
+    /**
+     * Observador para a prop `value` — atualiza `focusedDate` quando a seleção externa muda.
+     * @param {Date | null} newValue - novo valor de seleção (ou `null`)
+     * @internal
      */
     handleValueChange(newValue: Date | null): void;
-    handleReferenceDateChange(newValue: Date): void;
     /**
      * Revalida a configuração quando o início da semana muda.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {number} newValue - Novo valor recebido via prop.
+     */
+    /**
+     * Observador para `weekStartsOn` — revalida a configuração quando alterada externamente.
+     * @param {number} newValue - novo índice do início da semana
+     * @internal
      */
     handleWeekStartsOnChange(newValue: number): void;
     /**
      * Revalida o locale quando a prop muda.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {string} newValue - Novo valor recebido via prop.
      */
-    handleLocaleChange(newValue: string): void;
-    handleDisabledDatesChange(newValue: Date[]): void;
-    /** Evento emitido quando a data de referência ou a seleção mudam. */
-    dateStateChange: EventEmitter<DatetimePickerDateState>;
     /**
-     * Normaliza os valores públicos antes da primeira renderização.
+     * Observador para `locale` — revalida/normaliza o locale informado.
+     * @param {string} newValue - nova string de locale
+     * @internal
      */
+    handleLocaleChange(newValue: string): void;
     componentWillLoad(): void;
-    /**
-     * Move o foco para a célula correspondente ao `focusedDate` após re-renderização.
-     */
     componentDidRender(): void;
-    /** Sinaliza ao componentDidRender que deve mover o foco para a célula atual. */
-    private shouldFocusDate;
     /**
-     * Garante que o valor de `weekStartsOn` esteja dentro do domínio suportado.
-     *
+     * Valida e normaliza `weekStartsOn`.
      * @param value - Valor bruto informado pelo consumidor.
+     * @internal
      */
     private ensureValidWeekStartsOn;
-    private normalizeDateProp;
     /**
-     * Garante que o locale informado seja suportado.
-     *
+     * Valida e normaliza o `locale` informado.
      * @param value - Valor bruto informado pelo consumidor.
+     * @internal
      */
     private ensureValidLocale;
     /**
-     * Emite o estado consolidado do componente para manter a navegação sincronizada.
+     * Emite `dateStateChange` atualizando `referenceDate`, `value` e `range`.
+     * Zera segundos/milissegundos para consistência.
      *
-     * @param nextReferenceDate - Nova data de referência após a interação.
-     * @param nextValue - Valor selecionado final; por padrão, mantém a seleção atual.
+     * @param nextReferenceDate - nova data de referência
+     * @param nextValue - data selecionada ou `null` (por padrão, mantém `this.value`)
+     * @param nextRange - intervalo de datas quando aplicável
+     * @internal
      */
     private emitDateStateChange;
     /**
-     * Resolve o ícone usado em cada ação de navegação.
-     *
-     * @param action - Ação de navegação representada pelo botão.
-     * @returns Nome do ícone ou um fallback quando a ação não é reconhecida.
+     * Resolve o nome do ícone para a ação de navegação.
+     * @param action - Ação de navegação
+     * @returns Nome do ícone
+     * @internal
      */
     private getIconForAction;
-    /** Mantém handlers estáveis por data para evitar recriação a cada renderização. */
-    private dayClickHandlers;
     /**
-     * Aplica a data clicada preservando hora e minuto da referência atual.
-     *
-     * @param date - Dia selecionado no calendário.
+     * Trata o clique numa célula de dia: aplica seleção ou atualiza intervalo.
+     * @param date - dia clicado
+     * @internal
      */
     private handleDayClick;
-    /** Atualiza o intervalo selecionado com base no clique atual. */
+    /**
+     * Atualiza o intervalo selecionado no modo `range`.
+     * @param clickedDate - data clicada pelo usuário
+     * @internal
+     */
     private handleRangeDayClick;
     /**
-     * Atualiza o mês exibido a partir da seleção do usuário.
-     *
-     * @param event - Mudança do `<select>` de mês.
+     * Handler de mudança do seletor de mês.
+     * @param event - evento de mudança do `<select>`
+     * @internal
      */
     private handleMonthChange;
     /**
-     * Executa a ação de navegação associada ao botão clicado.
-     *
-     * @param event - Clique no botão de navegação.
+     * Trata cliques nos botões de navegação do calendário.
+     * @param event - evento de clique
+     * @internal
      */
     private handleNavigationClick;
     /**
-     * Atualiza o ano exibido a partir do valor digitado.
-     *
-     * @param event - Mudança do campo de ano.
+     * Handler de alteração do campo ano.
+     * Valida o ano antes de aplicar a mudança.
+     * @param event - evento de mudança do input de ano
+     * @internal
      */
     private handleYearChange;
-    /** Decrementa o mês mantendo o primeiro dia do mês exibido e preservando a seleção de range. */
+    /**
+     * Decrementa o mês exibido e preserva seleção/intervalo quando aplicável.
+     * @internal
+     */
     private decreaseMonth;
-    /** Incrementa o mês mantendo o primeiro dia do mês exibido e preservando a seleção de range. */
+    /**
+     * Incrementa o mês exibido e preserva seleção/intervalo quando aplicável.
+     * @internal
+     */
     private increaseMonth;
-    /** Indica se um dia está indisponível para seleção. */
+    /**
+     * Verifica se uma data está indisponível para seleção.
+     * @param date - data a verificar
+     * @returns `true` se a data estiver na lista de `disabledDates`
+     * @internal
+     */
     private isDateDisabled;
-    /** Data base usada para todos os cálculos de calendário. */
+    /**
+     * Data base usada para todos os cálculos de calendário.
+     * @returns data de referência interna
+     * @internal
+     */
     private get baseDate();
     /**
-     * Recupera um handler estável para a célula do dia informado.
-     *
-     * @param date - Dia representado pela célula.
-     * @returns Função de clique reutilizável.
+     * Trata cliques com um handler compartilhado, lendo a data local da célula.
+     * @param event - evento de clique da célula
+     * @internal
+     */
+    private handleDayCellClick;
+    /**
+     * Formata o dia exibido com zero à esquerda (ex: '01', '09').
+     * @param date - data a formatar
+     * @returns string com dois dígitos do dia
+     * @internal
      */
-    private getDayClickHandler;
-    /** Formata o dia exibido com zero à esquerda. */
     private getDayWithLeadingZero;
     /**
-     * Constrói o rótulo acessível completo da célula de dia.
-     *
-     * @param date - Dia representado pela célula.
-     * @returns Texto anunciado pelo leitor de tela, incluindo estado de seleção.
+     * Constrói o rótulo acessível da célula de dia, incluindo estado (selecionado/início/fim).
+     * @param date - dia representado pela célula
+     * @returns string para `aria-label`
+     * @internal
      */
     private getDayCellAriaLabel;
-    /** Locale do date-fns derivado da prop pública do componente. */
+    /**
+     * Locale do `date-fns` derivado da prop pública `locale`.
+     * @internal
+     */
     private get dateFnsLocale();
     /**
-     * Calcula as classes CSS da célula do dia com base em seleção, mês e data atual.
-     *
-     * @param date - Dia da grade do calendário.
+     * Calcula o mapa de classes CSS da célula do dia.
+     * @param date - dia da grade
+     * @param today - instante atual compartilhado pela renderização da grade
+     * @returns mapa de classes booleanas
+     * @internal
      */
     private getDayCssClasses;
-    /** Normaliza os limites do intervalo para garantir ordem cronológica. */
+    /**
+     * Normaliza os limites do intervalo garantindo ordem cronológica (start <= end).
+     * @param start - data de início
+     * @param end - data de fim
+     * @returns tupla [start, end] na ordem correta
+     * @internal
+     */
     private normalizeRangeBounds;
-    /** Verifica se uma data está estritamente entre início e fim do intervalo. */
+    /**
+     * Verifica se uma data está estritamente entre `start` e `end`.
+     * @param date - data a verificar
+     * @param start - início do intervalo
+     * @param end - fim do intervalo
+     * @returns `true` se `start < date < end`
+     * @internal
+     */
     private isDateBetweenRange;
-    /** Gera a sequência completa de dias visíveis na grade do mês. */
-    private getMonthViewDates;
     /**
-     * Retorna o `focusedDate` normalizado para estar sempre dentro da grade visível.
-     *
-     * Se `focusedDate` não estiver visível no mês atual, retorna o primeiro dia
-     * da grade do mês para garantir que sempre haja um elemento com `tabIndex={0}`.
-     *
-     * @returns Data focada normalizada ou primeiro dia da grade.
+     * Calcula os limites da grade do mês, respeitando `fixedRowCount`, sem gerar suas datas.
+     * @returns limites inclusivos da grade
+     * @internal
+     */
+    private getMonthViewInterval;
+    /**
+     * Retorna o `focusedDate` normalizado para estar dentro da grade visível.
+     * Se não estiver visível, retorna o primeiro dia da grade.
+     * @param interval - limites da grade atual; calculados quando não fornecidos
+     * @returns data normalizada para foco
+     * @internal
      */
     private getNormalizedFocusedDate;
     /**
-     * Constrói o rótulo acessível dos botões de navegação do mês.
-     *
-     * @param action - Ação associada ao botão.
-     * @returns Texto acessível exibido para leitores de tela.
+     * Constrói o rótulo acessível para os botões de navegação.
+     * @param action - ação de navegação
+     * @returns rótulo para `aria-label`
+     * @internal
      */
     private getNavigationAriaLabel;
-    /** Retorna os rótulos das semanas conforme locale e início da semana. */
+    /**
+     * Retorna os rótulos dos dias da semana conforme `locale` e `weekStartsOn`.
+     * @internal
+     */
     private getWeekdayLabels;
-    /** Retorna os rótulos dos meses no locale atual. */
+    /**
+     * Retorna os rótulos dos meses no locale atual.
+     * @internal
+     */
     private getMonthLabels;
     /**
-     * Renderiza um botão consistente de navegação do calendário.
-     *
-     * @param action - Ação executada pelo botão.
+     * Gerencia navegação por teclado dentro da grade de dias.
+     * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown, Home/End, Enter/Space.
+     * @param event - evento de teclado
+     * @returns void
+     * @internal
+     */
+    private handleGridKeydown;
+    /**
+     * Move o foco de teclado para a data informada e atualiza `referenceDate` se necessário.
+     * @param date - data alvo do foco
+     * @returns void
+     * @internal
+     */
+    private moveFocusTo;
+    /**
+     * Renderiza um botão de navegação consistente para o calendário.
+     * @param action - ação do botão
+     * @returns elemento JSX do botão de navegação
+     * @internal
      */
     private renderNavigationButton;
-    /** Renderiza o cabeçalho do calendário com navegação, mês e ano. */
+    /**
+     * Renderiza o cabeçalho do calendário (navegação, mês e ano).
+     * @returns elemento JSX do cabeçalho
+     * @internal
+     */
     private renderCalendarHeader;
-    /** Renderiza a seleção de mês com label acessível. */
+    /**
+     * Renderiza o seletor de mês com rótulo acessível.
+     * @returns elemento JSX do seletor de mês
+     * @internal
+     */
     private renderMonthSelection;
-    /** Renderiza o campo de ano com label acessível. */
+    /**
+     * Renderiza o campo de ano com rótulo acessível.
+     * @returns elemento JSX do campo de ano
+     * @internal
+     */
     private renderYearSelection;
-    /** Renderiza uma opção do seletor de meses. */
+    /**
+     * Renderiza uma opção do seletor de meses.
+     * @param month - label do mês
+     * @param index - índice do mês (0-11)
+     * @returns elemento `<option>` para o mês
+     * @internal
+     */
     private renderMonthOption;
-    /** Renderiza a estrutura principal do calendário. */
+    /**
+     * Renderiza a estrutura principal do calendário (grade e cabeçalho).
+     * @returns elemento JSX com a grade do calendário
+     * @internal
+     */
     private renderCalendar;
-    /** Renderiza a linha de rótulos dos dias da semana. */
+    /**
+     * Renderiza os rótulos dos dias da semana.
+     * @returns elemento JSX com os cabeçalhos das colunas dos dias
+     * @internal
+     */
     private renderWeekdays;
-    /** Renderiza a grade com os dias do mês atual. */
-    private renderMonthGrid;
     /**
-     * Gerencia a navegação por teclado dentro da grade de dias.
-     *
-     * Teclas suportadas:
-     * - `ArrowLeft` / `ArrowRight`: avança ou recua um dia.
-     * - `ArrowUp` / `ArrowDown`: avança ou recua sete dias (linha inteira).
-     * - `PageUp` / `PageDown`: navega entre meses.
-     * - `Home` / `End`: primeiro ou último dia da semana atual.
-     * - `Enter` / `Space`: seleciona o dia com foco.
-     *
-     * @param event - Evento de teclado disparado na grade.
+     * Renderiza a grade de dias do mês atual.
+     * @returns elemento JSX contendo semanas e dias
+     * @internal
      */
-    private handleGridKeydown;
+    private renderMonthGrid;
     /**
-     * Move o foco de teclado para a data informada, navegando de mês quando necessário.
-     *
-     * @param date - Data de destino do foco.
+     * Renderiza uma célula de dia com estado visual apropriado.
+     * @param date - data representada pela célula
+     * @param normalizedFocusedDate - data de foco normalizada para a grade atual
+     * @param today - instante atual compartilhado pela renderização da grade
+     * @returns elemento JSX da célula de dia
+     * @internal
      */
-    private moveFocusTo;
-    /** Renderiza uma célula de dia com estado visual apropriado. */
     private renderDayCell;
     render(): any;
 }

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

@@ -0,0 +1,14 @@
+import type { InputFormatConfig } from './datetime-input.types';
+/**
+ * Configurações de formato e mensagens usadas por `br-datetime-input`.
+ *
+ * Cada chave representa um modo suportado (`date`, `time`, `datetime`) e
+ * mapeia para um `InputFormatConfig` que descreve máscara de entrada,
+ * contagens de dígitos aceitas, formatos de exibição/parse e mensagens de
+ * validação específicas do modo.
+ *
+ * Mantemos a configuração centralizada para evitar lógica dispersa pelo
+ * componente e permitir alterações de formato em um único local.
+ */
+export declare const INPUT_FORMAT_CONFIG: Record<string, InputFormatConfig>;
+export type { InputFormatConfig };

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

@@ -1,36 +1,40 @@
 import type { DatetimePickerMode } from '../datetime-picker.types';
 /**
- * Valida se o modo informado pertence ao conjunto suportado pelo datetime-input.
+ * Verifica se `value` é um modo suportado pelo `br-datetime-input`.
  *
- * @param value - Valor recebido via prop/atributo.
- * @returns `true` quando o modo é válido.
+ * @param {string} value - Valor recebido via prop/atributo.
+ * @returns {value is DatetimePickerMode} `true` quando pertence ao conjunto suportado.
  */
 export declare function isValidDatetimeInputMode(value: string): value is DatetimePickerMode;
 /**
- * Normaliza o modo do datetime-input para um valor suportado.
+ * Normaliza o modo do componente, aplicando o valor padrão quando inválido.
+ * Emite um aviso via `warnInvalidPropValue` quando o valor é inválido.
  *
- * @param value - Valor bruto informado via prop.
- * @returns Modo válido, aplicando o padrão quando necessário.
+ * @param {string} value - Valor bruto recebido via prop.
+ * @returns {DatetimePickerMode} - Modo válido (ou `DATETIME_PICKER_MODE.DEFAULT`).
  */
 export declare function normalizeDatetimeInputMode(value: string): DatetimePickerMode;
 /**
- * Verifica se o valor informado é uma instância de Date válida.
+ * Retorna `true` quando `value` é uma instância válida de `Date`.
  *
- * @param value - Valor recebido via prop.
- * @returns `true` quando é Date válido.
+ * @param {unknown} value - Valor a ser verificado.
+ * @returns {value is Date} - `true` para instâncias de Date válidas.
  */
 export declare function isValidDateInstance(value: unknown): value is Date;
 /**
- * Normaliza a data de referência para evitar valores inválidos.
+ * Normaliza a `referenceDate` garantindo uma `Date` válida.
+ * Quando `value` for inválido, retorna um fallback (data atual) e emite
+ * um warning com o valor sugerido em ISO.
  *
- * @param value - Valor recebido via prop.
- * @returns Date válido para uso interno.
+ * @param {unknown} value - Valor recebido via prop.
+ * @returns {Date} - Data válida para uso interno.
  */
 export declare function normalizeDatetimeInputReferenceDate(value: unknown): Date;
 /**
- * Normaliza o valor selecionado do input (Date válido ou null).
+ * Normaliza o `value` da prop para `Date` válido ou `null`.
+ * Emite warning quando o valor é inválido e retorna `null`.
  *
- * @param value - Valor recebido via prop.
- * @returns Date válido ou null quando o valor é inválido.
+ * @param {unknown} value - Valor recebido via prop.
+ * @returns {Date | null} - Data válida ou `null`.
  */
 export declare function normalizeDatetimeInputValue(value: unknown): Date | null;