@govbr-ds/webcomponents 2.3.0 → 2.5.0

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

@@ -1,22 +1,25 @@
 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.
+ * Calendário usado pelo `br-datetime-picker`. Também pode ser usado sozinho, quando a tela precisa de um calendário sempre visível.
  *
- * ### Papel na composição
+ * Usado sozinho, ele não tem campo de texto nem participa de formulário: a aplicação lê a seleção e cuida da validaçã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).
+ * ```html
+ * <br-date-picker id="agenda"></br-date-picker>
+ * ```
  *
- * ### Regra de uso e relacionamento
+ * ```js
+ * const calendario = document.querySelector('#agenda');
+ * calendario.addEventListener('change', () => console.log(calendario.value));
+ * ```
  *
- * 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).
+ * - `value`: data selecionada (`Date`).
+ * - `referenceDate`: mês exibido.
+ * - `disabledDates`: datas que não podem ser escolhidas.
+ * - `selectionMode="range"`: seleção de intervalo, lida em `rangeValue`.
  *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
- *
-
- * @category Formulários, Seleção
- * @status stable
+ * Para mudar o idioma, veja "Idiomas" na documentação do `br-datetime-picker`.
  *
  * @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 +32,412 @@ 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;
+    /**
+     * Lista de `disabledDates` usada para gerar `disabledDateKeysCache`.
+     * @internal
+     */
+    private disabledDateKeysSource?;
+    /**
+     * Chaves `yyyy-MM-dd` das datas bloqueadas, para consulta O(1) por célula.
+     * @internal
+     */
+    private disabledDateKeysCache;
+    /**
+     * 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.
      */
-    handleValueChange(newValue: Date | null): void;
-    handleReferenceDateChange(newValue: Date): void;
+    /**
+     * Observador para a prop `value` — atualiza `focusedDate` quando a seleção externa muda.
+     * @param {Date | null} newValue - novo valor de seleção (ou `null`)
+     * @param {Date | null} oldValue - valor anterior da seleção
+     * @internal
+     */
+    handleValueChange(newValue: Date | null, oldValue: Date | null): 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. */
+    /**
+     * Exibe o mês informado preservando a seleção, o intervalo completo e o dia em foco.
+     *
+     * O foco vai para a data selecionada quando ela pertence ao novo mês; caso
+     * contrário, mantém o mesmo dia do mês, limitado ao último dia disponível
+     * (ex.: 31/01 → 28/02).
+     *
+     * @param monthDate - primeiro dia do mês de destino
+     * @internal
+     */
+    private navigateToMonth;
+    /**
+     * 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. */
+    /**
+     * Chaves locais das datas bloqueadas, recalculadas somente quando `disabledDates` é substituída.
+     * Entradas inválidas são ignoradas.
+     * @internal
+     */
+    private get disabledDateKeys();
+    /**
+     * 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
+     * @param state - estado já calculado da 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 uma única vez o estado de seleção da célula, compartilhado por classes, ARIA e foco.
+     * @param date - dia da grade
+     * @param today - instante atual compartilhado pela renderização da grade
+     * @returns estado da célula
+     * @internal
+     */
+    private getDayCellState;
+    /**
+     * Calcula o mapa de classes CSS da célula do dia.
+     * @param state - estado já calculado da célula
+     * @param disabled - indica se a célula está bloqueada
+     * @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.
+     * Gerencia navegação por teclado dentro da grade de dias.
+     * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown (mês), Shift+PageUp/PageDown (ano),
+     * Home/End, Enter/Space.
      *
-     * @param action - Ação executada pelo botão.
+     * Permanece ativo em datas bloqueadas para que o foco não fique preso nelas; somente a seleção é ignorada.
+     * @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 };