@govbr-ds/webcomponents 2.2.0 → 2.4.0

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

@@ -2,24 +2,23 @@ import type { FormValidator } from '../../shared/utils/validator';
 import type { DATETIME_PICKER_LOCALE, DATETIME_PICKER_MODE, NAVIGATION_ACTION } from './datetime-picker-constants';
 import type { INPUT_TIME_TYPE } from './time-picker/time-picker-constants';
 /**
- * Representa os modos válidos de operação do datetime picker.
+ * Modos válidos de operação do datetime picker.
  *
- * Derivado de `DATETIME_PICKER_MODE` para manter tipo e constantes
- * sincronizados automaticamente.
+ * Derivado de `DATETIME_PICKER_MODE` para manter o tipo e os valores em sincronização.
  */
 export type DatetimePickerMode = (typeof DATETIME_PICKER_MODE)[keyof typeof DATETIME_PICKER_MODE];
 /**
- * Representa os locais suportados pelo componente.
+ * Locais suportados pelo componente.
  *
- * O tipo aceita o valor livre `string` para manter compatibilidade com
- * consumidores que ainda não usam a constante exportada.
+ * Aceita `string` livre para manter compatibilidade com consumidores que ainda
+ * não utilizam `DATETIME_PICKER_LOCALE`.
  */
 export type DatetimePickerLocale = string | (typeof DATETIME_PICKER_LOCALE)[keyof typeof DATETIME_PICKER_LOCALE];
 /**
- * Seleção inicial aceita pelo componente.
+ * Valor inicial aceito pelo componente.
  *
- * - `'now'`: usa o momento atual no carregamento/atualização da prop.
- * - `Date` ou `string`: usa uma data arbitrária informada pelo consumidor.
+ * - `'now'`: usa o instante atual ao carregar ou atualizar a prop.
+ * - `Date` ou `string`: usa uma data informada pelo consumidor.
  * - `null`: inicia sem seleção.
  */
 export type DatetimePickerInitialMoment = 'now' | Date | string | null;
@@ -28,22 +27,19 @@ export type DatetimePickerInitialMoment = 'now' | Date | string | null;
  */
 export type DatetimePickerDisabledDate = Date | string;
 /**
- * Conjunto de datas que devem ficar indisponíveis para seleção no calendário.
+ * Datas indisponíveis para seleção no calendário.
  *
- * Aceita:
- * - array de datas (Date|string)
- * - string com datas separadas por espaço em branco
- * - null
+ * Aceita um array de datas, uma string com datas separadas por espaço ou `null`.
  */
 export type DatetimePickerDisabledDates = DatetimePickerDisabledDate[] | string | null;
 /**
- * Modo de seleção usado no calendário de datas.
+ * Modo de seleção do calendário.
  *
- * `range` só é suportado quando o datetime picker está em `mode="date"`.
+ * `range` é suportado em `date`, `time` e `datetime`.
  */
 export type DatetimePickerSelectionMode = 'single' | 'range';
 /**
- * Índice numérico válido para o dia inicial da semana no calendário.
+ * Índice do dia inicial da semana no calendário.
  *
  * Dom = 0, Seg = 1, Ter = 2, Qua = 3, Qui = 4, Sex = 5, Sab = 6.
  */
@@ -55,6 +51,9 @@ export type DatetimePickerDateRange = {
     start: Date | null;
     end: Date | null;
 };
+/**
+ * Validador de dados usado pelo componente para validar seleção e intervalos.
+ */
 export type DatetimePickerValidator = FormValidator<Date | DatetimePickerDateRange | null>;
 /**
  * Representa um dia dentro do intervalo selecionado com seu estado de bloqueio.
@@ -64,7 +63,9 @@ export type DatetimePickerRangeDateState = {
     disabled: boolean;
 };
 /**
- * Representa a ação de navegação emitida pelos controles de calendário e horário.
+ * Ações de navegação emitidas pelos controles de calendário e horário.
+ *
+ * Derivado de `NAVIGATION_ACTION` para manter o tipo alinhado às ações públicas.
  */
 export type NavigationAction = (typeof NAVIGATION_ACTION)[keyof typeof NAVIGATION_ACTION];
 /**
@@ -78,17 +79,70 @@ export type DatetimePickerDateState = {
     value: Date | null;
     range?: DatetimePickerDateRange;
     rangeDates?: DatetimePickerRangeDateState[];
+    origin?: string;
+};
+/**
+ * Detalhe emitido pelo datetime picker em resposta a uma seleção.
+ *
+ * `value` representa a seleção completa do modo ativo. Em intervalos, inclui
+ * tanto o início quanto o fim.
+ */
+export type DatetimePickerChangeDetail = {
+    mode: 'date';
+    selectionMode: 'single';
+    value: Date | null;
+    serializedValue: string;
+} | {
+    mode: 'date';
+    selectionMode: 'range';
+    value: {
+        start: string | null;
+        end: string | null;
+    };
+    serializedValue: string;
+    complete: boolean;
+} | {
+    mode: 'time';
+    selectionMode: 'range';
+    value: {
+        start: string | null;
+        end: string | null;
+    };
+    serializedValue: string;
+    complete: boolean;
+} | {
+    mode: 'time';
+    selectionMode: 'single';
+    value: {
+        hours: number;
+        minutes: number;
+    } | null;
+    serializedValue: string;
+} | {
+    mode: 'datetime';
+    selectionMode: 'single';
+    value: Date | null;
+    serializedValue: string;
+} | {
+    mode: 'datetime';
+    selectionMode: 'range';
+    value: {
+        start: string | null;
+        end: string | null;
+    };
+    serializedValue: string;
+    complete: boolean;
 };
 /**
- * Índice numérico válido para o dia da semana.
+ * Índice do dia da semana.
  *
  * Dom = 0, Seg = 1, Ter = 2, Qua = 3, Qui = 4, Sex = 5, Sab = 6.
  */
 export type WeekDayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 /**
- * Representa os tipos de campo suportados pelo time picker.
+ * Tipos de campo suportados pelo time picker.
  *
- * Derivado de `INPUT_TIME_TYPE` para manter o tipo alinhado com as constantes públicas.
+ * Derivado de `INPUT_TIME_TYPE` para manter o tipo alinhado aos valores públicos.
  */
 export type InputTimeType = (typeof INPUT_TIME_TYPE)[keyof typeof INPUT_TIME_TYPE];
 export type DatetimePickerFormContext = {

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

@@ -1,103 +1,109 @@
 import type { DatetimePickerMode, InputTimeType, NavigationAction, WeekDayIndex } from './datetime-picker.types';
+/**
+ * Configuração de um campo de tempo usado pelos botões de navegação.
+ */
+export type TimeFieldConfig = {
+    value: number;
+    nextAction: NavigationAction;
+    prevAction: NavigationAction;
+};
 /**
  * Formata uma data para exibição no campo de entrada, conforme o modo do datetime-picker.
- * @param date Data a ser formatada
- * @param mode Modo do datetime-picker
- * @returns String formatada ou vazia se a data for inválida
+ *
+ * @param {Date | null | undefined} date Data a ser formatada.
+ * @param {DatetimePickerMode} mode Modo atual do componente.
+ * @returns {string} String formatada ou vazia quando a data for inválida.
  */
 export declare function formatDateForInput(date: Date | null | undefined, mode: DatetimePickerMode): string;
 /**
  * Retorna o dia do mês com zero à esquerda.
- * @param date Data para a qual o dia do mês será obtido
- * @returns String representando o dia do mês com dois dígitos
+ * @param {Date} date Data para a qual o dia do mês será obtido
+ * @returns {string} String representando o dia do mês com dois dígitos
  */
 export declare function getDayWithLeadingZero(date: Date): string;
 /**
  * Retorna o rótulo do mês e ano para uma determinada data.
- * @param date Data para a qual o rótulo será obtido
- * @returns Rótulo do mês e ano no formato "MMMM yyyy"
+ * @param {Date} date Data para a qual o rótulo será obtido
+ * @returns {string} Rótulo do mês e ano no formato "MMMM yyyy"
  */
 export declare function getMonthYearLabel(date: Date): string;
 /**
  * Retorna o ícone correspondente a uma ação de navegação.
- * @param action Ação de navegação
- * @returns Nome do ícone
+ * @param {NavigationAction} action Ação de navegação
+ * @returns {string} Nome do ícone
  */
 export declare function getIconForAction(action: NavigationAction): string;
 /**
  * Resolve o ícone do campo de entrada com base no modo atual.
- * @param mode Modo do datetime-picker
- * @returns Nome do ícone
+ * @param {DatetimePickerMode} mode Modo do datetime-picker
+ * @returns {string} Nome do ícone
  */
 export declare function getInputIcon(mode: DatetimePickerMode): string;
 /**
  * Retorna as datas que serão exibidas na visualização do mês.
- * @param baseDate Data base para o mês
- * @param weekStartsOn Dia da semana em que a semana começa
- * @returns Array de datas para exibir no calendário
+ * @param {Date} baseDate Data base para o mês
+ * @param {WeekDayIndex} weekStartsOn Dia da semana em que a semana começa
+ * @returns {Date[]} Array de datas para exibir no calendário
  */
 export declare function getMonthViewDates(baseDate: Date, weekStartsOn: WeekDayIndex): Date[];
 /**
  * Retorna os rótulos dos dias da semana, ajustados conforme o dia de início da semana.
- * @param weekStartsOn Dia da semana em que a semana começa
- * @param weekdays Array com os nomes abreviados dos dias da semana
- * @returns Array de rótulos dos dias da semana reordenados
+ * @param {WeekDayIndex} weekStartsOn Dia da semana em que a semana começa
+ * @param {string[]} weekdays Array com os nomes abreviados dos dias da semana
+ * @returns {string[]} Array de rótulos dos dias da semana reordenados
  */
 export declare function getWeekdayLabels(weekStartsOn: WeekDayIndex, weekdays: string[]): string[];
 /**
  * Retorna o rótulo aria para um campo de tempo específico.
- * @param type Tipo de campo de tempo (hora ou minuto)
- * @returns Rótulo aria correspondente ao campo de tempo
+ * @param {InputTimeType} type Tipo de campo de tempo (hora ou minuto)
+ * @returns {string} Rótulo aria correspondente ao campo de tempo
  */
 export declare function getTimeFieldAriaLabel(type: InputTimeType): string;
 /**
  * Retorna a configuração do campo de tempo com base no tipo especificado.
- * @param type Tipo de campo de tempo (hora ou minuto)
- * @param baseDate Data base para obter os valores
- * @returns Objeto contendo o valor atual e as ações de navegação
+ *
+ * @param {InputTimeType} type Tipo de campo de tempo: hora ou minuto.
+ * @param {Date} baseDate Data base usada para calcular os valores exibidos.
+ * @returns {TimeFieldConfig} Objeto com o valor atual e as ações de navegação associadas.
  */
-export declare function getTimeFieldConfig(type: InputTimeType, baseDate: Date): {
-    value: number;
-    nextAction: "next-hour";
-    prevAction: "previous-hour";
-} | {
-    value: number;
-    nextAction: "next-minute";
-    prevAction: "previous-minute";
-};
+export declare function getTimeFieldConfig(type: InputTimeType, baseDate: Date): TimeFieldConfig;
 /**
  * Retorna o valor do campo de tempo formatado com dois dígitos.
- * @param type Tipo de campo de tempo (hora ou minuto)
- * @param baseDate Data base para obter os valores
- * @returns Valor formatado do campo de tempo
+ * @param {InputTimeType} type Tipo de campo de tempo (hora ou minuto)
+ * @param {Date} baseDate Data base para obter os valores
+ * @returns {string} Valor formatado do campo de tempo
  */
 export declare function getTimeFieldValue(type: InputTimeType, baseDate: Date): string;
 /**
- * Retorna o rótulo aria para um botão de navegação específico.
- * @param action Ação de navegação
- * @param baseDate Data base atual
- * @returns Rótulo aria correspondente à ação de navegação
+ * Retorna o rótulo ARIA para um botão de navegação específico.
+ *
+ * @param {NavigationAction} action Ação de navegação.
+ * @param {Date} baseDate Data base usada para contextualizar o movimento.
+ * @returns {string} Texto descritivo do comportamento do botão para leitores de tela.
  */
 export declare function getNavigationAriaLabel(action: NavigationAction, baseDate: Date): string;
 /**
  * Analisa o valor de entrada de data e retorna um objeto Date ou null se inválido.
- * @param value Valor de entrada a ser analisado
- * @param base Data base para análise
- * @returns Objeto Date válido ou null se inválido
+ *
+ * @param {string} value Valor de entrada a ser analisado.
+ * @param {Date} base Data base usada como referência para campos parcialmente preenchidos.
+ * @returns {Date | null} Date válida ou null quando a entrada não puder ser convertida.
  */
 export declare function parseDateInput(value: string, base: Date): Date | null;
 /**
  * Analisa o valor de entrada de tempo e retorna um objeto Date ou null se inválido.
- * @param value Valor de entrada a ser analisado
- * @param base Data base para análise
- * @returns Objeto Date válido ou null se inválido
+ *
+ * @param {string} value Valor de entrada a ser analisado.
+ * @param {Date} base Data base usada para preservar os demais campos da data.
+ * @returns {Date | null} Date válida ou null quando a entrada não puder ser convertida.
  */
 export declare function parseTimeInput(value: string, base: Date): Date | null;
 /**
  * Analisa o valor de entrada de data e hora e retorna um objeto Date ou null se inválido.
- * @param value Valor de entrada a ser analisado
- * @param base Data base para análise
- * @returns Objeto Date válido ou null se inválido
+ *
+ * @param {string} value Valor de entrada a ser analisado.
+ * @param {Date} base Data base usada em casos de entrada parcial.
+ * @returns {Date | null} Date válida ou null quando a entrada não puder ser convertida.
  */
 export declare function parseDateTimeInput(value: string, base: Date): Date | null;
 /**

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

@@ -1,7 +1,8 @@
 /**
- * Conjunto de campos suportados pelo time picker.
+ * Conjunto imutável dos campos suportados pelo `br-time-picker`.
  *
- * Esses valores são usados como contrato entre a renderização do campo e a lógica de commit.
+ * @readonly
+ * @constant {Readonly<Record<string, string>>}
  */
 export declare const INPUT_TIME_TYPE: {
     readonly HOUR: "hour";

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

@@ -1,108 +1,145 @@
 import { type EventEmitter } from '../../../stencil-public-runtime';
 import type { DatetimePickerDateState } from '../datetime-picker.types';
 /**
- * Subcomponente de seleção de horários do GovBR-DS, desenvolvido para permitir a escolha intuitiva de horas e minutos.
+ * O `br-time-picker` é o subcomponente de ajuste de horas e minutos do `br-datetime-picker`.
  *
  * ### Papel na composição
  *
- * - Apresenta colunas ou controles de incremento/decremento para seleção de horas e minutos com validação de limites.
- * - Sincroniza o horário escolhido com o campo textual associado.
+ * Oferece campos textuais e botões de incremento e decremento para hora e minuto. Usa uma data de referência e comunica alterações por `dateStateChange`; não coordena diretamente o calendário nem o campo textual principal.
  *
  * ### Regra de uso e relacionamento
  *
- * Coordenado pelo componente pai `br-datetime-picker` no modo de horário ou composto. Pode ser utilizado avulso quando a aplicação demandar exclusivamente a captura de hora sem necessidade de calendário de datas.
+ * O `br-datetime-picker` instancia e sincroniza este seletor nos modos `time` e `datetime`. Na seleção de intervalo, o pai cria dois seletores, um para o início e outro para o fim, e consolida os respectivos valores. Não forneça seletores de horário em slots 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).
+ * Prefira o orquestrador para um controle completo de horário com campo textual e formulário. Use diretamente apenas quando precisar dos controles de hora e minuto em uma composição personalizada e assumir a sincronização de estado, a validação e a integração com formulários. O uso isolado não herda a associação nativa ao formulário do pai.
  *
-
- * @category Formulários, Seleção
- * @status stable
+ * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
  *
- * @part container - Parte para o container base do seletor de horários.
- * @part timer - Container para o grupo de hora e minuto.
- * @part field - Campo individual de entrada de tempo (com botões de ajuste).
- * @part separator - Separador visual de hora e minuto.
+ * @part container - Container base do seletor de horários.
+ * @part timer - Grupo que contém os campos de hora e minuto.
+ * @part field - Campo de tempo com botões de ajuste.
+ * @part separator - Separador visual entre hora e minuto.
  * @part input - Campo de entrada textual interno do tempo.
  */
 export declare class TimePicker {
     /** Referência ao elemento host do componente no DOM. */
     el: HTMLBrTimePickerElement;
-    /** Mantém o rascunho digitado por campo para evitar aplicar valor parcial prematuramente. */
-    private timeDraft;
     /**
-     * Data usada como referência para a navegação de hora e minuto, sem representar necessariamente a seleção.
-     * Recebe uma instância de `Date` por property binding; valores inválidos usam a data atual.
+     * Data de referência usada para exibir e ajustar hora e minuto.
      *
-     * @example
-     * ```js
-     * const timePicker = document.querySelector('br-time-picker');
-     * timePicker.referenceDate = new Date(2026, 8, 7, 9);
-     * ```
+     * @default new Date()
      */
     referenceDate: Date;
     /**
-     * Data que contém a hora e o minuto efetivamente selecionados, ou `null` quando vazio.
-     * Recebe uma instância de `Date` por property binding; datas inválidas usam `null`.
+     * Valor canônico selecionado pelo usuário.
      *
-     * @example
-     * ```js
-     * const timePicker = document.querySelector('br-time-picker');
-     * timePicker.value = new Date(2026, 8, 7, 14, 30);
-     * ```
+     * @default null
      */
     value: Date | null;
-    /** Desabilita todos os controles de navegação e edição de hora/minuto. */
+    /**
+     * Indica se os controles do seletor estão desabilitados.
+     *
+     * @default false
+     */
     disabled: boolean;
-    /** Evento emitido quando a data de referência ou o valor selecionado mudam. */
+    /**
+     * Rascunho dos valores digitados por cada campo (`hour` | `minute`).
+     * Mantém entradas parciais até o commit por blur/Enter.
+     */
+    private timeDraft;
+    /**
+     * Evento emitido sempre que `referenceDate` ou `value` são atualizados.
+     *
+     * O `detail` segue a forma de `DatetimePickerDateState` e contém o estado
+     * compartilhado entre subcomponentes de data e horário.
+     *
+     * Payload (`detail`):
+     * @property {Date} referenceDate - Data de referência utilizada para navegação/visualização (segundos zerados).
+     * @property {Date|null} value - Valor selecionado pelo usuário (ou `null` quando vazio).
+     * @property {object} [range] - Quando em `selectionMode: 'range'`, contém `{ start: Date|null, end: Date|null }`.
+     * @property {Array<{date: Date, disabled: boolean}>} [rangeDates] - Lista de dias do intervalo com indicador de bloqueio.
+     *
+     * @event dateStateChange
+     */
     dateStateChange: EventEmitter<DatetimePickerDateState>;
-    handleReferenceDateChange(newValue: Date): void;
+    /**
+     * Mapa memorizado de handlers para o evento `input` por tipo de campo.
+     *
+     * Motivo: evita recriar closures a cada render, reduz alocação e mantém
+     * identidade das funções (útil para comparação/remoção quando necessário).
+     *
+     * @private
+     * @type {Map<InputTimeType, (event: Event) => void>}
+     */
+    private timeInputChangeHandlers;
+    /**
+     * Mapa memorizado de handlers de commit (blur/confirm) por tipo de campo.
+     *
+     * Contém funções que finalizam o rascunho e aplicam o valor via
+     * `handleTimeInputCommit(type)`.
+     *
+     * @private
+     * @type {Map<InputTimeType, () => void>}
+     */
+    private timeInputCommitHandlers;
+    /**
+     * Mapa memorizado de handlers de teclado por tipo de campo.
+     *
+     * Suporta comportamento de `Enter` (confirma) e setas para ajuste.
+     * Memorizar evita recriar closures e melhora performance em re-renders.
+     *
+     * @private
+     * @type {Map<InputTimeType, (event: KeyboardEvent) => void>}
+     */
+    private timeInputKeydownHandlers;
+    /**
+     * Sincroniza `referenceDate` quando a prop `value` muda.
+     *
+     * Normaliza segundos/milissegundos e restaura rascunhos locais.
+     *
+     * @param {Date | null} newValue - Novo valor vindo da prop `value`.
+     * @returns {void}
+     */
     handleValueChange(newValue: Date | null): void;
     componentWillLoad(): void;
-    private normalizeDateProp;
     /**
      * Emite o estado consolidado para manter hora, minuto e data sincronizados.
      *
-     * @param nextReferenceDate - Nova data de referência após a interação.
-     * @param nextValue - Valor final selecionado; quando omitido, assume a data de referência.
+     * @param {Date} nextReferenceDate - Nova data de referência após a interação.
+     * @param {Date | null} nextValue - Valor final selecionado; quando omitido, assume a data de referência.
      */
     private emitDateStateChange;
     /**
      * Resolve o ícone associado à ação de navegação.
      *
-     * @param action - Ação representada pelo botão.
-     * @returns O nome do ícone ou uma string vazia quando a ação não é reconhecida.
+     * @param {NavigationAction} action - Ação representada pelo botão.
+     * @returns {string} O nome do ícone ou uma string vazia quando a ação não é reconhecida.
      */
     private getIconForAction;
-    /** Cacheia handlers por tipo de campo para preservar a mesma referência entre renderizações. */
-    private timeInputChangeHandlers;
-    /** Cacheia handlers de commit por tipo de campo. */
-    private timeInputCommitHandlers;
-    /** Cacheia handlers de teclado por tipo de campo. */
-    private timeInputKeydownHandlers;
     /**
      * Executa a navegação associada ao botão clicado.
      *
-     * @param event - Clique disparado pelo botão de navegação.
+     * @param {MouseEvent} event - Clique disparado pelo botão de navegação.
      */
     private handleNavigationClick;
     /**
      * Atualiza o rascunho do campo removendo qualquer caractere não numérico.
      *
-     * @param event - Evento de input do campo de hora ou minuto.
-     * @param type - Campo que está sendo editado.
+     * @param {Event} event - Evento de input do campo de hora ou minuto.
+     * @param {InputTimeType} type - Campo que está sendo editado.
      */
     private handleTimeInputChange;
     /**
      * Aplica o valor digitado ao estado do componente quando o campo é concluído.
      *
-     * @param type - Campo que será aplicado.
+     * @param {InputTimeType} type - Campo que será aplicado.
      */
     private handleTimeInputCommit;
     /**
      * Constrói o rótulo acessível das ações de navegação com base no valor atual.
      *
-     * @param action - Ação que o botão executa.
-     * @returns Texto acessível do botão.
+     * @param {NavigationAction} action - Ação que o botão executa.
+     * @returns {string} Texto acessível do botão.
      */
     private getNavigationAriaLabel;
     /**
@@ -147,28 +184,62 @@ export declare class TimePicker {
      * @returns Função reutilizável para eventos de teclado.
      */
     private getTimeInputKeydownHandler;
+    /**
+     * Ajusta o valor do campo via teclado (ArrowUp/ArrowDown).
+     *
+     * @param event - Evento de teclado que disparou a ação.
+     * @param type - Tipo do campo (`hour` | `minute`) a ser ajustado.
+     * @returns void
+     */
     private adjustTimeInputWithKeyboard;
-    /** Incrementa a hora mantendo os demais componentes da data intactos. */
+    /**
+     * Incrementa a hora sem alterar os demais componentes da data.
+     *
+     * @returns void
+     */
     private increaseHour;
-    /** Incrementa o minuto mantendo os demais componentes da data intactos. */
+    /**
+     * Incrementa o minuto sem alterar os demais componentes da data.
+     *
+     * @returns void
+     */
     private increaseMinute;
-    /** Decrementa a hora mantendo os demais componentes da data intactos. */
+    /**
+     * Decrementa a hora sem alterar os demais componentes da data.
+     *
+     * @returns void
+     */
     private decreaseHour;
-    /** Decrementa o minuto mantendo os demais componentes da data intactos. */
+    /**
+     * Decrementa o minuto sem alterar os demais componentes da data.
+     *
+     * @returns void
+     */
     private decreaseMinute;
     /**
      * Renderiza um botão de navegação consistente para hora ou minuto.
      *
-     * @param action - Ação que o botão executará.
+     * @param {NavigationAction} action - Ação que o botão executará.
+     * @returns {JSX.Element}
      */
     private renderNavigationButton;
-    /** Renderiza o bloco completo de hora e minuto. */
+    /**
+     * Renderiza o bloco completo de hora e minuto.
+     *
+     * @returns {JSX.Element}
+     */
     private renderTimePicker;
     /**
      * Renderiza um campo de edição com navegação lateral.
      *
-     * @param type - Tipo do campo a ser exibido.
+     * @param {InputTimeType} type - Tipo do campo a ser exibido.
+     * @returns {JSX.Element}
      */
     private renderTimeField;
+    /**
+     * Render principal do componente.
+     *
+     * @returns {JSX.Element}
+     */
     render(): any;
 }

package/dist/types/components/dropdown/dropdown.d.ts

@@ -207,6 +207,13 @@ export declare class Dropdown {
      * Foca em um elemento específico com suporte a componentes personalizados
      * @param targetElement Elemento a receber o foco
      */
+    /**
+     * Links e demais itens focáveis do target na ordem do documento. O Tab percorre
+     * esta sequência única para que listas mistas (links e botões) sejam alcançáveis.
+     */
+    private getTabCycle;
+    /** Move o foco para o próximo (ou anterior, com Shift) elemento do ciclo de Tab. */
+    private cycleTabFocus;
     private focusOnElement;
     /**
      * Foca no elemento interativo dentro do slot trigger
@@ -221,12 +228,13 @@ export declare class Dropdown {
     private syncTriggerAccessibilityAfterHydration;
     private getCssClassMap;
     /**
-     * Handler para eventos de keydown nos itens não-link
-     * Implementa navegação completa por setas, Tab não navega entre estes itens
+     * Handler para eventos de keydown nos itens não-link.
+     * Setas, Home e End navegam entre estes itens; Tab percorre o ciclo único
+     * (links e itens na ordem do documento).
      */
     private handleItemKeydown;
     /**
-     * Handler específico para links
+     * Handler específico para links. Tab percorre o ciclo único (links e itens).
      */
     private handleLinkKeydown;
     /**
@@ -235,7 +243,7 @@ export declare class Dropdown {
     private handleTriggerBehavior;
     /**
      * Inicializa os itens do dropdown com comportamentos de navegação com teclado,
-     * separando claramente entre elementos navegáveis por Tab e elementos navegáveis por setas
+     * separando links e demais itens (setas navegam entre itens; Tab percorre ambos na ordem do documento)
      */
     private initializeDropdownItems;
     /**

package/dist/types/components/header/header.d.ts

@@ -235,6 +235,8 @@ export declare class Header {
     /** Indica que o estado compacto atual foi derivado da rolagem. */
     private compactFromScroll;
     private headerResizeObserver?;
+    /** Última largura do host vista pelo `ResizeObserver`. */
+    private observedHostWidth?;
     private readonly headerResizeBatcher;
     private emitHeaderWidthChange;
     private handleNavigation;

package/dist/types/components/icon/icon.utils.d.ts

@@ -1 +1,7 @@
 export declare function sanitizeSvgMarkup(markup: string): string;
+/**
+ * Indica se um valor de ícone é uma lista de classes CSS (ex.: `fas fa-bell`), e não um
+ * identificador Iconify (`fa6-solid:bell`). Classes CSS não funcionam dentro do Shadow DOM,
+ * porque os estilos globais do Font Awesome não o atravessam; nesses casos use um slot.
+ */
+export declare function isIconClassList(value: string | null | undefined): boolean;