@govbr-ds/webcomponents 2.2.0 → 2.4.0

package/dist/types/components.d.ts

@@ -15,14 +15,14 @@ import { FormValidationChangeDetail } from "./shared/utils/validator";
 import { FormValidationState } from "./shared/utils/form";
 import { CollapseChangeDetail, CollapseColorMode, CollapseExpansionDirection, CollapseIconPosition, CollapseTriggerVariant } from "./components/collapse/collapse.types";
 import { CookiebarMode, CookiebarOutputData, CookiebarSelectionState } from "./components/cookiebar/cookiebar.types";
-import { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex, WeekDayIndex } from "./components/datetime-picker/datetime-picker.types";
+import { DatetimePickerChangeDetail, DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex, WeekDayIndex } from "./components/datetime-picker/datetime-picker.types";
 import { DividerAlign, DividerBorderStyle, DividerOrientation, DividerThickness } from "./components/divider/divider.types";
 import { DropdownArrowPosition, DropdownOpenChangeDetail, DropdownPlacement } from "./components/dropdown/dropdown.types";
 import { FooterLayoutWidth, FooterTheme } from "./components/footer/footer.types";
 import { FooterLogoPosition } from "./components/footer/footer-logo/footer-logo.types";
 import { HeaderCompactChangeDetail, HeaderDensity, HeaderLayoutWidth, HeaderShrinkFirst } from "./components/header/header.types";
 import { IconFlip, IconRotate, IconSource } from "./components/icon/icon.types";
-import { InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from "./components/input/input.types";
+import { InputActionClickDetail, InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from "./components/input/input.types";
 import { ItemSelectDetail } from "./components/item/item.types";
 import { LoadingChangeDetail, LoadingCompleteDetail, LoadingCompletionBehavior, LoadingIndeterminateStateDetail, LoadingLabelPosition, LoadingMode, LoadingSize, LoadingSpeed, LoadingValueDetail } from "./components/loading/loading.types";
 import { MenuDensity, MenuOpenChangeDetail } from "./components/menu/menu.types";
@@ -34,7 +34,7 @@ import { PaginationColorMode, PaginationDensity, PaginationPageChangeDetail, Pag
 import { RadioValidator } from "./components/radio/radio.types";
 import { RadioGroupOrientation, RadioGroupValidator } from "./components/radio-group/radio-group.types";
 import { ScrimContentLayout, ScrimDisplayMode, ScrimLegibilityAnchor, ScrimPositionContent, ScrimScrollStrategy, ScrimSpotlightShape, ScrimVariant } from "./components/scrim/scrim.types";
-import { SelectOptionData, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from "./components/select/select.types";
+import { SelectComboboxState, SelectOptionData, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from "./components/select/select.types";
 import { SignInEmphasis, SignInShape } from "./components/sign-in/sign-in.types";
 import { SkipLinkItemFocusDetail, SkipLinkNavigateDetail, SkipLinkPosition, SkipLinkVariant } from "./components/skip-link/skip-link.types";
 import { SliderDensity, SliderRangeValue, SliderStep, SliderValidator } from "./components/slider/slider.types";
@@ -58,14 +58,14 @@ export { FormValidationChangeDetail } from "./shared/utils/validator";
 export { FormValidationState } from "./shared/utils/form";
 export { CollapseChangeDetail, CollapseColorMode, CollapseExpansionDirection, CollapseIconPosition, CollapseTriggerVariant } from "./components/collapse/collapse.types";
 export { CookiebarMode, CookiebarOutputData, CookiebarSelectionState } from "./components/cookiebar/cookiebar.types";
-export { DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex, WeekDayIndex } from "./components/datetime-picker/datetime-picker.types";
+export { DatetimePickerChangeDetail, DatetimePickerDateRange, DatetimePickerDateState, DatetimePickerDisabledDate, DatetimePickerDisabledDates, DatetimePickerInitialMoment, DatetimePickerLocale, DatetimePickerMode, DatetimePickerSelectionMode, DatetimePickerValidator, DatetimePickerWeekDayIndex, WeekDayIndex } from "./components/datetime-picker/datetime-picker.types";
 export { DividerAlign, DividerBorderStyle, DividerOrientation, DividerThickness } from "./components/divider/divider.types";
 export { DropdownArrowPosition, DropdownOpenChangeDetail, DropdownPlacement } from "./components/dropdown/dropdown.types";
 export { FooterLayoutWidth, FooterTheme } from "./components/footer/footer.types";
 export { FooterLogoPosition } from "./components/footer/footer-logo/footer-logo.types";
 export { HeaderCompactChangeDetail, HeaderDensity, HeaderLayoutWidth, HeaderShrinkFirst } from "./components/header/header.types";
 export { IconFlip, IconRotate, IconSource } from "./components/icon/icon.types";
-export { InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from "./components/input/input.types";
+export { InputActionClickDetail, InputDensity, InputState, InputToggle, InputType, InputValidationChangeDetail, InputValidator } from "./components/input/input.types";
 export { ItemSelectDetail } from "./components/item/item.types";
 export { LoadingChangeDetail, LoadingCompleteDetail, LoadingCompletionBehavior, LoadingIndeterminateStateDetail, LoadingLabelPosition, LoadingMode, LoadingSize, LoadingSpeed, LoadingValueDetail } from "./components/loading/loading.types";
 export { MenuDensity, MenuOpenChangeDetail } from "./components/menu/menu.types";
@@ -77,7 +77,7 @@ export { PaginationColorMode, PaginationDensity, PaginationPageChangeDetail, Pag
 export { RadioValidator } from "./components/radio/radio.types";
 export { RadioGroupOrientation, RadioGroupValidator } from "./components/radio-group/radio-group.types";
 export { ScrimContentLayout, ScrimDisplayMode, ScrimLegibilityAnchor, ScrimPositionContent, ScrimScrollStrategy, ScrimSpotlightShape, ScrimVariant } from "./components/scrim/scrim.types";
-export { SelectOptionData, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from "./components/select/select.types";
+export { SelectComboboxState, SelectOptionData, SelectSearchDetail, SelectSearchMode, SelectStateChangeDetail, SelectValidator } from "./components/select/select.types";
 export { SignInEmphasis, SignInShape } from "./components/sign-in/sign-in.types";
 export { SkipLinkItemFocusDetail, SkipLinkNavigateDetail, SkipLinkPosition, SkipLinkVariant } from "./components/skip-link/skip-link.types";
 export { SliderDensity, SliderRangeValue, SliderStep, SliderValidator } from "./components/slider/slider.types";
@@ -384,7 +384,7 @@ export namespace Components {
          */
         "shape"?: ButtonShape;
         /**
-          * Define o tipo de botão, especificando seu comportamento padrão. Valores inválidos usam `button`.
+          * Define o tipo de botão, especificando seu comportamento padrão. Quando omitido, usa `button`; valores inválidos também usam `button` e geram aviso no console.
          */
         "type"?: ButtonType;
         /**
@@ -901,12 +901,12 @@ export namespace Components {
          */
         "iconPosition": CollapseIconPosition;
         /**
-          * Identificador do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local.
+          * Identificador Iconify do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot `icon-to-hide`.
           * @default 'fa6-solid:chevron-up'
          */
         "iconToHide": string;
         /**
-          * Identificador do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local.
+          * Identificador Iconify do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot `icon-to-show`.
           * @default 'fa6-solid:chevron-down'
          */
         "iconToShow": string;
@@ -1413,36 +1413,33 @@ export namespace Components {
         "target"?: string;
     }
     /**
-     * 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).
-     * 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
+     * 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.
+     * 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.
+     * 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).
      */
     interface BrDatePicker {
         /**
-          * 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)]; ```
+          * Lista de datas indisponíveis para seleção no calendário.
           * @default []
          */
         "disabledDates": Date[];
         /**
-          * 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;
         /**
           * Locale usado para gerar nomes de meses e dias da semana.
-          * @default 'pt-BR'
+          * @default DATETIME_PICKER_LOCALE.DEFAULT
          */
         "locale": string;
         /**
@@ -1456,199 +1453,194 @@ export namespace Components {
          */
         "rangeStart": 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;
         /**
-          * 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;
         /**
-          * 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;
         /**
-          * 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 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;
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
+     * @see https://www.gov.br/ds/components/datetime?tab=designer
      */
     interface BrDatetimeInput {
         /**
-          * Desabilita digitação e abertura do picker quando ativo.
+          * Controla os estados de read-only ou bloqueio de formulário.
           * @default false
          */
         "disabled": boolean;
         /**
-          * Move o foco para o input interno sem expor a árvore privada ao componente pai.
-         */
-        "focusInput": () => Promise<void>;
-        /**
-          * Define o modo de entrada: `date`, `time` ou `datetime`.
+          * Modo de entrada que controla máscara, parser e formato exibido.
           * @default 'datetime'
          */
         "mode": DatetimePickerMode;
         /**
-          * Define o placeholder do campo de entrada.
+          * Texto de placeholder exibido quando o campo estiver vazio.
           * @default ''
          */
         "placeholder": string;
         /**
-          * Data final do intervalo quando em modo range.
+          * Fim do intervalo em `selectionMode === 'range'`.
           * @default null
          */
         "rangeEnd": Date | null;
         /**
-          * Data inicial do intervalo quando em modo range.
+          * Início do intervalo em `selectionMode === 'range'`.
           * @default null
          */
         "rangeStart": 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 input = document.querySelector('br-datetime-input'); input.selectionMode = 'range'; input.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) }; ```
+          * Intervalo controlado no modo `range` como objeto `{ start, end }`.
+          * @type {DatetimePickerDateRange | undefined}
          */
         "rangeValue"?: DatetimePickerDateRange;
         /**
-          * 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;
         /**
-          * 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;
         /**
-          * 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;
     }
     /**
-     * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
+     * O `br-datetime-picker` é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.
      * ### Para que serve
-     * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
-     * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
-     * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+     * - Oferece os modos `date`, `time` e `datetime`, com seleção única (`single`) ou de intervalo (`range`).
+     * - Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
+     * - Centraliza restrições de seleção, validação e submissão do valor por meio de `formAssociated`.
      * ### Quando utilizar
-     * - **Utilize quando:**
-     *   - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
-     *   - For necessário selecionar um período com data de início e fim.
-     * - **Evite e prefira outro componente quando:**
-     *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+     * - Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
+     * - Utilize para períodos com início e fim, inclusive com horários nos modos `time` e `datetime`.
+     * - Evite quando precisar apenas apresentar uma data: prefira texto formatado.
+     * - Para um calendário permanentemente visível sem o campo textual, considere `br-date-picker`; a aplicação assume a integração com o restante do formulário.
+     * - A seleção não oferece uma coleção de datas independentes: use `single` para um valor ou `range` para um intervalo.
      * ### Composição e Subcomponentes
-     * | Subcomponente | Papel | Regra de uso |
+     * | Componente | Papel | Regra de uso |
      * | --- | --- | --- |
-     * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
-     * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
-     * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
-     * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+     * | `br-datetime-picker` | Orquestrador do valor consolidado, validação, formulário e abertura do painel. | Declare este controle no template para obter a composição completa. |
+     * | `br-datetime-input` | Campo textual com máscara, interpretação da entrada e ação de abertura do painel. | Instanciado internamente pelo pai; não deve ser fornecido em slot. |
+     * | `br-date-picker` | Calendário para navegação e seleção de data única ou intervalo. | Criado pelo pai nos modos `date` e `datetime`; pode ser usado isoladamente como calendário embutido. |
+     * | `br-time-picker` | Controles de hora e minuto. | Criado pelo pai nos modos `time` e `datetime`, com uma instância por limite quando a seleção é `range`. |
+     * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
      * ### Como os subcomponentes se relacionam
-     * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
-     * @category Formulários, Seleção
+     * O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.
+     * `referenceDate` representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo `brDatetimePickerChange` para a seleção completa e tipada.
+     * O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do `br-datetime-picker`.
+     * 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/datetimepicker?tab=designer).
+     * @category Formulários
      * @status stable
      */
     interface BrDatetimePicker {
         /**
           * Permite que consumidores acionem validação nativa do formulário via host.
+          * @returns Promise<boolean> — resultado da Constraint Validation API para o host.
          */
         "checkValidity": () => Promise<boolean>;
         /**
-          * Limpa valor e intervalo selecionados.
+          * Limpa valor e intervalo selecionados.  Remove seleção atual e restaura a referência de navegação para a data atual.
+          * @returns Promise<void> — resolve após a limpeza e sincronização internas.
          */
         "clear": () => Promise<void>;
         /**
           * Fecha o picker.
+          * @returns Promise<void> — resolve após atualização do estado de visibilidade.
          */
         "close": () => Promise<void>;
         /**
-          * Desabilita toda a interação do componente.  Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários.
+          * Desabilita toda a interação do componente.
           * @default false
          */
         "disabled": boolean;
         /**
-          * Define um conjunto de datas indisponíveis para seleção.  Aceita uma lista de `Date` e/ou strings analisáveis, ou uma string com datas separadas por espaço em branco. Datas inválidas são ignoradas com warning. A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
+          * Datas indisponíveis para seleção. Aceita `Date[]`, `string` ou `null`.  Datas inválidas são ignoradas. A comparação considera apenas o dia.
           * @default null
-          * @example ```html <br-datetime-picker mode="date" disabled-dates="2026-09-07 2026-09-08"></br-datetime-picker> ```
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.disabledDates = [new Date(2026, 8, 7), '2026-09-08']; ```
          */
         "disabledDates": DatetimePickerDisabledDates;
         /**
-          * 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.
+          * Mantém número fixo de linhas no calendário (6 semanas) quando `true`.
           * @default false
          */
         "fixedRowCount": boolean;
         /**
           * Move o foco para o input nativo interno.
+          * @returns Promise<void> — resolve imediatamente após tentar focar o elemento.
          */
         "focusInput": () => Promise<void>;
         /**
           * Retorna o intervalo de datas selecionado quando em modo `selectionMode="range"`.
-          * @returns Objeto com datas `start` e `end`, ou `null` se não estiver em modo range.
+          * @returns Promise<{ start: Date | null; end: Date | null } | null> — objeto com `start`/`end` ou `null` quando não estiver em modo `range`.
          */
         "getRange": () => Promise<{ start: Date | null; end: Date | null; } | null>;
         /**
           * Retorna um snapshot serializável da Constraint Validation API.
+          * @returns Promise<FormValidationState> — estado atual de validação do host, pronto para conversão e restauração via `formStateRestoreCallback`.
          */
         "getValidationState": () => Promise<FormValidationState>;
         /**
           * Retorna uma cópia do valor selecionado atualmente.
+          * @returns Promise<Date | null> — cópia imutável do `value` atual, ou `null`.
          */
         "getValue": () => Promise<Date | null>;
         /**
-          * Define a seleção inicial do componente.  Aceita: - `'now'`: seleciona o momento atual. - `Date` ou `string`: seleciona uma data arbitrária. - `null`: inicia sem seleção.  Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
+          * Valor inicial da seleção: `'now' | Date | string | null`.
           * @default null
-          * @example ```html <br-datetime-picker initial-moment="now"></br-datetime-picker> ```
          */
         "initialMoment": DatetimePickerInitialMoment;
         /**
           * Consulta se o picker está atualmente aberto.
-          * @returns `true` se o picker está visível, `false` caso contrário.
+          * @returns Promise<boolean> — `true` se o picker está visível, `false` caso contrário.
          */
         "isOpen": () => Promise<boolean>;
         /**
-          * Define o locale usado pelos subcomponentes para formatar datas e rótulos.
+          * Locale usado para formatação e rótulos.
           * @default 'pt-BR'
          */
         "locale": DatetimePickerLocale;
         /**
-          * Maior data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
-          * @example ```html <br-datetime-picker mode="date" max="2026-12-31"></br-datetime-picker> ```
+          * Maior data/hora aceito (Date | string | null).
           * @default null
          */
         "max": Date | string | null;
         /**
-          * Menor data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
-          * @example ```html <br-datetime-picker mode="date" min="2026-01-01"></br-datetime-picker> ```
+          * Menor data/hora aceito (Date | string | null).
           * @default null
          */
         "min": Date | string | null;
         /**
-          * Define o modo de seleção exibido pelo componente: data, horário ou ambos.  Valores aceitos: `date`, `time` ou `datetime`. Valores inválidos são corrigidos automaticamente para o valor padrão, mantendo o atributo refletido sempre consistente com o modo exibido.
+          * Modo exibido pelo componente.  Valores: `date` | `time` | `datetime`. Valores inválidos são normalizados para o padrão.
           * @default 'datetime'
          */
         "mode": DatetimePickerMode;
@@ -1659,84 +1651,96 @@ export namespace Components {
         "name": string;
         /**
           * Abre o picker quando o componente estiver habilitado.
+          * @returns Promise<void> — resolve quando o estado visual for atualizado.
          */
         "open": () => Promise<void>;
         /**
-          * Define o placeholder exibido no campo de entrada do datetime picker.
+          * Texto placeholder exibido no input.
           * @default ''
          */
         "placeholder": string;
         /**
-          * Intervalo controlado quando `selectionMode="range"`. Deve conter datas válidas ou `null` em `start` e `end`; valores inválidos mantêm o último intervalo efetivo. Passe o objeto por property binding; atributos HTML não representam objetos com `Date`.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.selectionMode = 'range'; picker.rangeValue = {   start: new Date(2026, 8, 7),   end: new Date(2026, 8, 12), }; ```
+          * Intervalo controlado quando `selectionMode="range"`.  Em `datetime`, preserva as datas e horários informados; término anterior ao início torna o controle inválido, sem reordenar ou avançar datas.
+          * @default undefined
          */
         "rangeValue"?: DatetimePickerDateRange;
         /**
           * Permite exibir mensagens nativas de validação no host.
+          * @returns Promise<boolean> — `true` se a mensagem foi exibida e o formulário é válido.
          */
         "reportValidity": () => Promise<boolean>;
         /**
-          * Indica se o campo deve ter valor antes do envio do formulário.
+          * Indica se o campo é requerido para submissão do formulário.
           * @default false
          */
         "required": boolean;
         /**
           * Restaura o estado inicial atualmente registrado para reset.
+          * @returns Promise<void> — resolve quando a seleção inicial for restaurada.
          */
         "resetToInitial": () => Promise<void>;
         /**
-          * Define o tipo de seleção de datas para o calendário: única ou intervalo.  `range` só funciona em conjunto com `mode="date"`. Se `selectionMode="range"` for informado, o componente ajusta automaticamente `mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente normaliza `selectionMode` para `single` quando necessário. Valores inválidos usam `single`.
+          * Tipo de seleção: `single` ou `range`.
           * @default 'single'
          */
         "selectionMode": DatetimePickerSelectionMode;
         /**
-          * Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm` ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.  Na inicialização, tem precedência sobre `valueAsDate`, `value` e `initialMoment`. Uma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.
-          * @example ```html <br-datetime-picker mode="datetime" serialized-value="2026-09-07T14:30"></br-datetime-picker> ```
+          * Representação serializada compatível com controles HTML.  Formatos variam conforme `mode`. Em intervalos, usa `início/fim`.
+          * @default undefined
          */
         "serializedValue"?: string;
         /**
           * Define ou limpa uma mensagem de validade customizada.
+          * @param message string — mensagem de validação; string vazia remove a mensagem.
+          * @returns Promise<void> — resolve após sincronizar a validade no host.
          */
         "setCustomValidity": (message: string) => Promise<void>;
         /**
-          * Define programaticamente as datas desabilitadas por meio de array.  Útil quando o componente é usado via HTML e o consumidor precisa enviar uma lista tipada em runtime.
-          * @param dates - Lista de datas (Date|string) a bloquear.
+          * Define programaticamente as datas desabilitadas.  Use quando scripts externos precisam fornecer uma lista tipada de datas a bloquear no calendário. Substitui a prop `disabledDates` para atualizações imperativas.
+          * @param dates Lista de datas (`Date` | `string`) a bloquear, ou `null` para limpar.
+          * @returns Promise<void> — resolve quando a atualização interna for aplicada.
          */
         "setDisabledDates": (dates: DatetimePickerDisabledDate[] | null) => Promise<void>;
         /**
-          * Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range.
+          * Define um intervalo no modo atual e ativa `selectionMode="range"`.  Valida datas contra bloqueios e sincroniza estado visual e de formulário. Em `datetime`, mantém os limites informados e sinaliza intervalo inválido quando o término precede o início, sem ajustar datas automaticamente.
+          * @param start Date | string | null — data inicial do intervalo.
+          * @param end Date | string | null — data final do intervalo.
+          * @returns Promise<void> — resolve quando o intervalo for aplicado e sincronizado.
          */
         "setRange": (start: Date | string | null, end: Date | string | null) => Promise<void>;
         /**
-          * Define o valor atual de forma imperativa aceitando Date, string serializada ou null.
+          * Define o valor do componente de forma imperativa.  Aceita `Date`, string compatível com o `mode`, ou `null` para limpar a seleção. Validação de datas desabilitadas é aplicada antes da atribuição.
+          * @param value Date | string | null — valor a aplicar; `null` limpa a seleção.
+          * @returns Promise<void> — resolve quando o componente aplicar e sincronizar o valor.
          */
         "setValue": (value: Date | string | null) => Promise<void>;
         /**
           * Alterna o estado de abertura do picker.
+          * @returns Promise<void> — resolve quando a transição de estado terminar.
          */
         "toggle": () => Promise<void>;
         /**
-          * Executa o validator do picker e retorna se a seleção atual é válida.
+          * Executa o validator customizado (se houver) e valida o controle.  Emite eventos de início/conclusão da validação e atualiza mensagens internas.
+          * @returns Promise<boolean> — `true` se a seleção for considerada válida.
          */
         "validate": () => Promise<boolean>;
         /**
-          * Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado. Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.validator = (value) => value === null ? 'Escolha uma data' : null; ```
+          * Validador customizado (síncrono ou assíncrono) para a seleção.  Recebe `Date | DatetimePickerDateRange | null` como valor.
+          * @default undefined
          */
         "validator"?: DatetimePickerValidator;
         /**
-          * Instância de `Date` selecionada pelo usuário no modo simples. Pode ser controlada por property binding e é atualizada pelo evento `valueChange`. Para formulários e atributos textuais, use `serializedValue`.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.value = new Date(2026, 8, 7, 14, 30); ```
+          * Valor selecionado pelo usuário (Date | null).  Pode ser controlado externamente e é refletido internamente.
           * @default null
          */
         "value": Date | null;
         /**
-          * Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML. Diferentemente de `serializedValue`, recebe e retorna uma instância de `Date`. Na inicialização, tem precedência sobre `value` e `initialMoment` quando `serializedValue` não é informado. `null` inicia sem seleção; `undefined` permite usar as outras props.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.valueAsDate = new Date(2026, 8, 7); ```
+          * Espelho tipado da seleção atual (`valueAsDate`).
+          * @default undefined
          */
         "valueAsDate"?: Date | null;
         /**
-          * Define o dia inicial da semana exibida no calendário.  Valores suportados: 0 (domingo) a 6 (sábado).
+          * Dia inicial da semana exibido no calendário (0 = Dom, 6 = Sáb).
           * @default 0
          */
         "weekStartsOn": DatetimePickerWeekDayIndex;
@@ -2745,7 +2749,7 @@ export namespace Components {
          */
         "active"?: boolean;
         /**
-          * Renderiza o item como botão. Quando informado, tem precedência sobre `isButton`.
+          * Renderiza o item como botão de alternância: o acionamento alterna `selected`, emite `brItemSelect` e expõe o estado em `aria-pressed`. Para uma ação sem estado (ex.: "Sair"), use `href` com `navigation-mode="event"` ou um `br-button`. Quando informado, tem precedência sobre `isButton`.
          */
         "button"?: boolean;
         /**
@@ -3197,7 +3201,7 @@ export namespace Components {
          */
         "density": BrDensity;
         /**
-          * Identificador legado do ícone a ser exibido. Nomes simples (por exemplo, `question`) são resolvidos pelo registro SVG local. Para classes CSS ou SVGs personalizados, prefira o slot `icon`.
+          * Ícone como identificador Iconify (ex.: `fa6-solid:star`) ou nome simples (ex.: `question`, resolvido como `fa6-solid:question` no registro SVG local), renderizado pelo `br-icon`. Para classes CSS (ex.: Font Awesome) ou SVGs personalizados, use o slot `icon`, a forma preferida. Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-star`) não são exibidas no Shadow DOM e geram aviso.
           * @default ''
          */
         "icon": string;
@@ -4466,6 +4470,17 @@ export namespace Components {
      * - **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
      * - **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).
      * - **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.
+     * ### Navegação por teclado
+     * O foco permanece no campo `combobox` enquanto a lista está aberta; a opção em destaque é comunicada por `aria-activedescendant`.
+     * Ao receber foco, o campo abre a lista sem alterar a seleção atual.
+     * - **ArrowDown / ArrowUp:** abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
+     * - **Home / End:** em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
+     * - **Enter:** abre a lista quando fechada e confirma a opção destacada quando aberta.
+     * - **Espaço:** confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
+     * - **Escape:** fecha a lista, remove o destaque e devolve o foco ao campo.
+     * - **Tab:** fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
+     * - **Busca incremental:** em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
+     * - **Alt+ArrowDown / Alt+ArrowUp:** abre ou fecha a lista sem alterar a seleção.
      * ### Quando utilizar
      * - **Utilize quando:**
      *   - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
@@ -4545,7 +4560,7 @@ export namespace Components {
          */
         "customId": string;
         /**
-          * Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+          * Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`. A opção sintética de selecionar todos permanece com densidade `small`.
           * @default 'medium'
          */
         "density": BrDensity;
@@ -4575,6 +4590,11 @@ export namespace Components {
           * @deprecated Leia a propriedade `value` diretamente.
          */
         "getValue": () => Promise<string | string[]>;
+        /**
+          * Oculta os divisores entre opções consecutivas, sem alterar a altura das linhas.
+          * @default false
+         */
+        "hideDividers": boolean;
         /**
           * Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`.
          */
@@ -4831,10 +4851,11 @@ export namespace Components {
          */
         "setFocus": () => Promise<void>;
         /**
-          * Exibe o ícone de busca dentro do campo.
+          * Exibe a lupa mesmo quando o campo não é filtrável. Quando filterable é true, a lupa é exibida automaticamente.
           * @type {boolean | undefined}
          */
         "showSearchIcon"?: boolean;
+        "syncCombobox": (state: SelectComboboxState) => Promise<void>;
         /**
           * Valor textual apresentado no input.
           * @type {string | undefined}
@@ -4866,7 +4887,7 @@ export namespace Components {
          */
         "close": () => Promise<void>;
         /**
-          * Define a densidade visual da lista, das opções e do indicador de carregamento. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+          * Define a densidade visual da lista, das opções regulares e do indicador de carregamento. A opção sintética de selecionar todos permanece com densidade `small`. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
           * @default 'medium'
          */
         "density": BrDensity;
@@ -4881,6 +4902,11 @@ export namespace Components {
           * @returns As opções renderizadas no estado atual.
          */
         "getOptions": () => Promise<SelectOptionData[]>;
+        /**
+          * Oculta os divisores entre opções consecutivas, sem alterar a altura das linhas.
+          * @default false
+         */
+        "hideDividers": boolean;
         /**
           * Informa a altura base usada no cálculo de posicionamento das opções. Deve ser um número finito positivo; valores inválidos usam 56.
           * @default 56
@@ -4907,6 +4933,10 @@ export namespace Components {
           * @default 0
          */
         "overscan": number;
+        /**
+          * Torna o item ativo visível sem retirar o foco do campo.
+         */
+        "revealOption": (index: number) => Promise<boolean>;
         /**
           * Posiciona no topo a primeira opção selecionada na ordem visual da lista. A opção auxiliar de selecionar tudo não participa dessa escolha.
           * @returns `true` quando existe uma opção selecionada para posicionar.
@@ -5060,7 +5090,7 @@ export namespace Components {
      *   - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).
      * ### Estrutura e Slots
      * O `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).
+     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/signin?tab=designer).
      * @category Identidade, Ações, Formulários
      * @status stable
      */
@@ -5070,7 +5100,7 @@ export namespace Components {
          */
         "ariaLabel": string;
         /**
-          * Define se o sign-in usará um esquema de cores escuro.
+          * Define se o sign-in usará um esquema de cores escuro, para fundos escuros. Quando omitido, ou com valor diferente de `dark`, usa o esquema claro.
          */
         "colorMode": 'dark';
         /**
@@ -5830,7 +5860,7 @@ export namespace Components {
          */
         "counter": string;
         /**
-          * Define o ícone do item de tab usando classes CSS do Font Awesome 5, como `fas fa-bell`. O formato Iconify é aceito apenas para compatibilidade legada e não deve ser usado em novos códigos.
+          * Ícone da aba como identificador Iconify (ex.: `fa6-solid:bell`), renderizado em SVG pelo `br-icon`. Para ícones por classe CSS (ex.: Font Awesome), use o slot `icon-{id}` do `br-tab`, a forma preferida: `<i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>`. O slot tem precedência sobre esta prop. Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-bell`) não são exibidas no Shadow DOM, geram aviso e devem migrar para o slot `icon-{id}`. Identificadores Iconify continuam suportados.
          */
         "icon": string;
         /**
@@ -6427,31 +6457,27 @@ export namespace Components {
         "wrap"?: TextareaWrap;
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
      */
     interface BrTimePicker {
         /**
-          * 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;
         /**
-          * 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.
-          * @example ```js const timePicker = document.querySelector('br-time-picker'); timePicker.referenceDate = new Date(2026, 8, 7, 9); ```
+          * Data de referência usada para exibir e ajustar hora e minuto.
           * @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`.
-          * @example ```js const timePicker = document.querySelector('br-time-picker'); timePicker.value = new Date(2026, 8, 7, 14, 30); ```
+          * Valor canônico selecionado pelo usuário.
           * @default null
          */
         "value": Date | null;
@@ -7678,15 +7704,13 @@ declare global {
         "dateStateChange": DatetimePickerDateState;
     }
     /**
-     * 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).
-     * 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
+     * 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.
+     * 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.
+     * 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).
      */
     interface HTMLBrDatePickerElement extends Components.BrDatePicker, HTMLStencilElement {
         addEventListener<K extends keyof HTMLBrDatePickerElementEventMap>(type: K, listener: (this: HTMLBrDatePickerElement, ev: BrDatePickerCustomEvent<HTMLBrDatePickerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -7705,17 +7729,17 @@ declare global {
     interface HTMLBrDatetimeInputElementEventMap {
         "dateStateChange": DatetimePickerDateState;
         "togglePicker": void;
+        "inputValidationChange": { valid: boolean | null; message: string; origin?: string };
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
+     * @see https://www.gov.br/ds/components/datetime?tab=designer
      */
     interface HTMLBrDatetimeInputElement extends Components.BrDatetimeInput, HTMLStencilElement {
         addEventListener<K extends keyof HTMLBrDatetimeInputElementEventMap>(type: K, listener: (this: HTMLBrDatetimeInputElement, ev: BrDatetimeInputCustomEvent<HTMLBrDatetimeInputElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -7733,32 +7757,36 @@ declare global {
     };
     interface HTMLBrDatetimePickerElementEventMap {
         "dateStateChange": DatetimePickerDateState;
+        "brDatetimePickerChange": DatetimePickerChangeDetail;
         "valueChange": Date | null;
         "brDatetimePickerValidationChange": FormValidationChangeDetail;
     }
     /**
-     * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
+     * O `br-datetime-picker` é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.
      * ### Para que serve
-     * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
-     * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
-     * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+     * - Oferece os modos `date`, `time` e `datetime`, com seleção única (`single`) ou de intervalo (`range`).
+     * - Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
+     * - Centraliza restrições de seleção, validação e submissão do valor por meio de `formAssociated`.
      * ### Quando utilizar
-     * - **Utilize quando:**
-     *   - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
-     *   - For necessário selecionar um período com data de início e fim.
-     * - **Evite e prefira outro componente quando:**
-     *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+     * - Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
+     * - Utilize para períodos com início e fim, inclusive com horários nos modos `time` e `datetime`.
+     * - Evite quando precisar apenas apresentar uma data: prefira texto formatado.
+     * - Para um calendário permanentemente visível sem o campo textual, considere `br-date-picker`; a aplicação assume a integração com o restante do formulário.
+     * - A seleção não oferece uma coleção de datas independentes: use `single` para um valor ou `range` para um intervalo.
      * ### Composição e Subcomponentes
-     * | Subcomponente | Papel | Regra de uso |
+     * | Componente | Papel | Regra de uso |
      * | --- | --- | --- |
-     * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
-     * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
-     * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
-     * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+     * | `br-datetime-picker` | Orquestrador do valor consolidado, validação, formulário e abertura do painel. | Declare este controle no template para obter a composição completa. |
+     * | `br-datetime-input` | Campo textual com máscara, interpretação da entrada e ação de abertura do painel. | Instanciado internamente pelo pai; não deve ser fornecido em slot. |
+     * | `br-date-picker` | Calendário para navegação e seleção de data única ou intervalo. | Criado pelo pai nos modos `date` e `datetime`; pode ser usado isoladamente como calendário embutido. |
+     * | `br-time-picker` | Controles de hora e minuto. | Criado pelo pai nos modos `time` e `datetime`, com uma instância por limite quando a seleção é `range`. |
+     * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
      * ### Como os subcomponentes se relacionam
-     * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
-     * @category Formulários, Seleção
+     * O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.
+     * `referenceDate` representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo `brDatetimePickerChange` para a seleção completa e tipada.
+     * O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do `br-datetime-picker`.
+     * 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/datetimepicker?tab=designer).
+     * @category Formulários
      * @status stable
      */
     interface HTMLBrDatetimePickerElement extends Components.BrDatetimePicker, HTMLStencilElement {
@@ -8181,6 +8209,7 @@ declare global {
     interface HTMLBrInputElementEventMap {
         "valueChange": string;
         "brClear": void;
+        "brInputActionClick": InputActionClickDetail;
         "brInputValidationChange": InputValidationChangeDetail;
     }
     /**
@@ -9027,6 +9056,17 @@ declare global {
      * - **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
      * - **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).
      * - **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.
+     * ### Navegação por teclado
+     * O foco permanece no campo `combobox` enquanto a lista está aberta; a opção em destaque é comunicada por `aria-activedescendant`.
+     * Ao receber foco, o campo abre a lista sem alterar a seleção atual.
+     * - **ArrowDown / ArrowUp:** abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
+     * - **Home / End:** em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
+     * - **Enter:** abre a lista quando fechada e confirma a opção destacada quando aberta.
+     * - **Espaço:** confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
+     * - **Escape:** fecha a lista, remove o destaque e devolve o foco ao campo.
+     * - **Tab:** fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
+     * - **Busca incremental:** em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
+     * - **Alt+ArrowDown / Alt+ArrowUp:** abre ou fecha a lista sem alterar a seleção.
      * ### Quando utilizar
      * - **Utilize quando:**
      *   - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
@@ -9191,7 +9231,7 @@ declare global {
      *   - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).
      * ### Estrutura e Slots
      * O `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).
+     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/signin?tab=designer).
      * @category Identidade, Ações, Formulários
      * @status stable
      */
@@ -9745,15 +9785,13 @@ declare global {
         "dateStateChange": DatetimePickerDateState;
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
      */
     interface HTMLBrTimePickerElement extends Components.BrTimePicker, HTMLStencilElement {
         addEventListener<K extends keyof HTMLBrTimePickerElementEventMap>(type: K, listener: (this: HTMLBrTimePickerElement, ev: BrTimePickerCustomEvent<HTMLBrTimePickerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -10318,7 +10356,7 @@ declare namespace LocalJSX {
          */
         "shape"?: ButtonShape;
         /**
-          * Define o tipo de botão, especificando seu comportamento padrão. Valores inválidos usam `button`.
+          * Define o tipo de botão, especificando seu comportamento padrão. Quando omitido, usa `button`; valores inválidos também usam `button` e geram aviso no console.
          */
         "type"?: ButtonType;
         /**
@@ -10799,12 +10837,12 @@ declare namespace LocalJSX {
          */
         "iconPosition"?: CollapseIconPosition;
         /**
-          * Identificador do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local.
+          * Identificador Iconify do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot `icon-to-hide`.
           * @default 'fa6-solid:chevron-up'
          */
         "iconToHide"?: string;
         /**
-          * Identificador do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local.
+          * Identificador Iconify do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local. Para ícones por classe CSS, use o slot `icon-to-show`.
           * @default 'fa6-solid:chevron-down'
          */
         "iconToShow"?: string;
@@ -11354,40 +11392,42 @@ declare namespace LocalJSX {
         "target"?: string;
     }
     /**
-     * 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).
-     * 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
+     * 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.
+     * 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.
+     * 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).
      */
     interface BrDatePicker {
         /**
-          * 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)]; ```
+          * Lista de datas indisponíveis para seleção no calendário.
           * @default []
          */
         "disabledDates"?: Date[];
         /**
-          * 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;
         /**
           * Locale usado para gerar nomes de meses e dias da semana.
-          * @default 'pt-BR'
+          * @default DATETIME_PICKER_LOCALE.DEFAULT
          */
         "locale"?: string;
         /**
-          * Evento emitido quando a data de referência ou a seleção mudam.
+          * 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>}
          */
         "onDateStateChange"?: (event: BrDatePickerCustomEvent<DatetimePickerDateState>) => void;
         /**
@@ -11401,141 +11441,148 @@ declare namespace LocalJSX {
          */
         "rangeStart"?: 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;
         /**
-          * 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;
         /**
-          * 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;
         /**
-          * 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 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;
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
+     * @see https://www.gov.br/ds/components/datetime?tab=designer
      */
     interface BrDatetimeInput {
         /**
-          * 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 o modo de entrada: `date`, `time` ou `datetime`.
+          * Modo de entrada que controla máscara, parser e formato exibido.
           * @default 'datetime'
          */
         "mode"?: DatetimePickerMode;
         /**
-          * Emite quando o valor é alterado via input ou parsing.
+          * 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'`.
          */
         "onDateStateChange"?: (event: BrDatetimeInputCustomEvent<DatetimePickerDateState>) => void;
         /**
-          * Solicita ao componente pai a alternância da abertura do picker.
+          * 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
+         */
+        "onInputValidationChange"?: (event: BrDatetimeInputCustomEvent<{ valid: boolean | null; message: string; origin?: string }>) => void;
+        /**
+          * Emite uma solicitação ao componente pai para alternar a abertura do picker. Emite sem payload.
+          * @event togglePicker
          */
         "onTogglePicker"?: (event: BrDatetimeInputCustomEvent<void>) => void;
         /**
-          * Define o placeholder do campo de entrada.
+          * Texto de placeholder exibido quando o campo estiver vazio.
           * @default ''
          */
         "placeholder"?: string;
         /**
-          * Data final do intervalo quando em modo range.
+          * Fim do intervalo em `selectionMode === 'range'`.
           * @default null
          */
         "rangeEnd"?: Date | null;
         /**
-          * Data inicial do intervalo quando em modo range.
+          * Início do intervalo em `selectionMode === 'range'`.
           * @default null
          */
         "rangeStart"?: 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 input = document.querySelector('br-datetime-input'); input.selectionMode = 'range'; input.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) }; ```
+          * Intervalo controlado no modo `range` como objeto `{ start, end }`.
+          * @type {DatetimePickerDateRange | undefined}
          */
         "rangeValue"?: DatetimePickerDateRange;
         /**
-          * 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;
         /**
-          * 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;
         /**
-          * 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;
     }
     /**
-     * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
+     * O `br-datetime-picker` é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.
      * ### Para que serve
-     * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
-     * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
-     * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+     * - Oferece os modos `date`, `time` e `datetime`, com seleção única (`single`) ou de intervalo (`range`).
+     * - Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
+     * - Centraliza restrições de seleção, validação e submissão do valor por meio de `formAssociated`.
      * ### Quando utilizar
-     * - **Utilize quando:**
-     *   - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
-     *   - For necessário selecionar um período com data de início e fim.
-     * - **Evite e prefira outro componente quando:**
-     *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+     * - Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
+     * - Utilize para períodos com início e fim, inclusive com horários nos modos `time` e `datetime`.
+     * - Evite quando precisar apenas apresentar uma data: prefira texto formatado.
+     * - Para um calendário permanentemente visível sem o campo textual, considere `br-date-picker`; a aplicação assume a integração com o restante do formulário.
+     * - A seleção não oferece uma coleção de datas independentes: use `single` para um valor ou `range` para um intervalo.
      * ### Composição e Subcomponentes
-     * | Subcomponente | Papel | Regra de uso |
+     * | Componente | Papel | Regra de uso |
      * | --- | --- | --- |
-     * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
-     * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
-     * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
-     * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+     * | `br-datetime-picker` | Orquestrador do valor consolidado, validação, formulário e abertura do painel. | Declare este controle no template para obter a composição completa. |
+     * | `br-datetime-input` | Campo textual com máscara, interpretação da entrada e ação de abertura do painel. | Instanciado internamente pelo pai; não deve ser fornecido em slot. |
+     * | `br-date-picker` | Calendário para navegação e seleção de data única ou intervalo. | Criado pelo pai nos modos `date` e `datetime`; pode ser usado isoladamente como calendário embutido. |
+     * | `br-time-picker` | Controles de hora e minuto. | Criado pelo pai nos modos `time` e `datetime`, com uma instância por limite quando a seleção é `range`. |
+     * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
      * ### Como os subcomponentes se relacionam
-     * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
-     * @category Formulários, Seleção
+     * O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.
+     * `referenceDate` representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo `brDatetimePickerChange` para a seleção completa e tipada.
+     * O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do `br-datetime-picker`.
+     * 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/datetimepicker?tab=designer).
+     * @category Formulários
      * @status stable
      */
     interface BrDatetimePicker {
         /**
-          * Desabilita toda a interação do componente.  Quando `true`, impede abrir o picker, alterar valores e navegar entre datas/horários.
+          * Desabilita toda a interação do componente.
           * @default false
          */
         "disabled"?: boolean;
         /**
-          * Define um conjunto de datas indisponíveis para seleção.  Aceita uma lista de `Date` e/ou strings analisáveis, ou uma string com datas separadas por espaço em branco. Datas inválidas são ignoradas com warning. A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
+          * Datas indisponíveis para seleção. Aceita `Date[]`, `string` ou `null`.  Datas inválidas são ignoradas. A comparação considera apenas o dia.
           * @default null
-          * @example ```html <br-datetime-picker mode="date" disabled-dates="2026-09-07 2026-09-08"></br-datetime-picker> ```
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.disabledDates = [new Date(2026, 8, 7), '2026-09-08']; ```
          */
         "disabledDates"?: DatetimePickerDisabledDates;
         /**
-          * 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.
+          * Mantém número fixo de linhas no calendário (6 semanas) quando `true`.
           * @default false
          */
         "fixedRowCount"?: boolean;
@@ -11544,30 +11591,27 @@ declare namespace LocalJSX {
          */
         "form"?: string;
         /**
-          * Define a seleção inicial do componente.  Aceita: - `'now'`: seleciona o momento atual. - `Date` ou `string`: seleciona uma data arbitrária. - `null`: inicia sem seleção.  Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
+          * Valor inicial da seleção: `'now' | Date | string | null`.
           * @default null
-          * @example ```html <br-datetime-picker initial-moment="now"></br-datetime-picker> ```
          */
         "initialMoment"?: DatetimePickerInitialMoment;
         /**
-          * Define o locale usado pelos subcomponentes para formatar datas e rótulos.
+          * Locale usado para formatação e rótulos.
           * @default 'pt-BR'
          */
         "locale"?: DatetimePickerLocale;
         /**
-          * Maior data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
-          * @example ```html <br-datetime-picker mode="date" max="2026-12-31"></br-datetime-picker> ```
+          * Maior data/hora aceito (Date | string | null).
           * @default null
          */
         "max"?: Date | string | null;
         /**
-          * Menor data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados. Aceita texto no atributo HTML ou uma instância de `Date` por property binding.
-          * @example ```html <br-datetime-picker mode="date" min="2026-01-01"></br-datetime-picker> ```
+          * Menor data/hora aceito (Date | string | null).
           * @default null
          */
         "min"?: Date | string | null;
         /**
-          * Define o modo de seleção exibido pelo componente: data, horário ou ambos.  Valores aceitos: `date`, `time` ou `datetime`. Valores inválidos são corrigidos automaticamente para o valor padrão, mantendo o atributo refletido sempre consistente com o modo exibido.
+          * Modo exibido pelo componente.  Valores: `date` | `time` | `datetime`. Valores inválidos são normalizados para o padrão.
           * @default 'datetime'
          */
         "mode"?: DatetimePickerMode;
@@ -11577,61 +11621,67 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Emitido ao iniciar e concluir a validação customizada.
+          * Evento público canônico emitido quando a seleção muda.  Payload (`DatetimePickerChangeDetail`): - `mode`: DatetimePickerMode — modo atual do componente (`date` | `time` | `datetime`). - `selectionMode`: DatetimePickerSelectionMode — `single` ou `range`. - `value`: Date | null | DatetimePickerDateRange — seleção atual (tipo depende de `selectionMode`). - `serializedValue`: string | undefined — representação serializada para integração com formulários.
+          * @event brDatetimePickerChange
+          * @type {CustomEvent<DatetimePickerChangeDetail>}
+         */
+        "onBrDatetimePickerChange"?: (event: BrDatetimePickerCustomEvent<DatetimePickerChangeDetail>) => void;
+        /**
+          * Emitido ao iniciar e concluir a validação customizada.  Payload (`FormValidationChangeDetail`): - `validating`: boolean — indica se a validação está em execução. - `valid`: boolean | null — resultado da validação (`null` enquanto valida). - `message`: string | null — mensagem de validação associada.
+          * @event brDatetimePickerValidationChange
+          * @type {CustomEvent<FormValidationChangeDetail>}
          */
         "onBrDatetimePickerValidationChange"?: (event: BrDatetimePickerCustomEvent<FormValidationChangeDetail>) => void;
         /**
-          * Evento público emitido quando a data de referência ou a seleção mudam.
+          * Evento público emitido quando a data de referência ou a seleção mudam.  Payload (`DatetimePickerDateState`): - `referenceDate`: Date — data usada para navegação visual (mês/semana exibidos). - `value`: Date | null — valor selecionado atualmente.
+          * @event dateStateChange
+          * @type {CustomEvent<DatetimePickerDateState>}
          */
         "onDateStateChange"?: (event: BrDatetimePickerCustomEvent<DatetimePickerDateState>) => void;
         /**
           * Evento emitido quando o valor selecionado muda.
-          * @deprecated Use `input`/`change` e leia `event.target.value`.
+          * @deprecated Use `brDatetimePickerChange` para receber a seleção completa e tipada.  Payload (legacy): `Date | null` — valor selecionado.
+          * @event valueChange
+          * @type {CustomEvent<Date | null>}
          */
         "onValueChange"?: (event: BrDatetimePickerCustomEvent<Date | null>) => void;
         /**
-          * Define o placeholder exibido no campo de entrada do datetime picker.
+          * Texto placeholder exibido no input.
           * @default ''
          */
         "placeholder"?: string;
         /**
-          * Intervalo controlado quando `selectionMode="range"`. Deve conter datas válidas ou `null` em `start` e `end`; valores inválidos mantêm o último intervalo efetivo. Passe o objeto por property binding; atributos HTML não representam objetos com `Date`.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.selectionMode = 'range'; picker.rangeValue = {   start: new Date(2026, 8, 7),   end: new Date(2026, 8, 12), }; ```
+          * Intervalo controlado quando `selectionMode="range"`.  Em `datetime`, preserva as datas e horários informados; término anterior ao início torna o controle inválido, sem reordenar ou avançar datas.
+          * @default undefined
          */
         "rangeValue"?: DatetimePickerDateRange;
         /**
-          * Indica se o campo deve ter valor antes do envio do formulário.
+          * Indica se o campo é requerido para submissão do formulário.
           * @default false
          */
         "required"?: boolean;
         /**
-          * Define o tipo de seleção de datas para o calendário: única ou intervalo.  `range` só funciona em conjunto com `mode="date"`. Se `selectionMode="range"` for informado, o componente ajusta automaticamente `mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente normaliza `selectionMode` para `single` quando necessário. Valores inválidos usam `single`.
+          * Tipo de seleção: `single` ou `range`.
           * @default 'single'
          */
         "selectionMode"?: DatetimePickerSelectionMode;
         /**
-          * Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm` ou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.  Na inicialização, tem precedência sobre `valueAsDate`, `value` e `initialMoment`. Uma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.
-          * @example ```html <br-datetime-picker mode="datetime" serialized-value="2026-09-07T14:30"></br-datetime-picker> ```
+          * Representação serializada compatível com controles HTML.  Formatos variam conforme `mode`. Em intervalos, usa `início/fim`.
+          * @default undefined
          */
         "serializedValue"?: string;
         /**
-          * Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado. Retorne uma mensagem para invalidar ou `null` para aceitar o valor.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.validator = (value) => value === null ? 'Escolha uma data' : null; ```
+          * Validador customizado (síncrono ou assíncrono) para a seleção.  Recebe `Date | DatetimePickerDateRange | null` como valor.
+          * @default undefined
          */
         "validator"?: DatetimePickerValidator;
         /**
-          * Instância de `Date` selecionada pelo usuário no modo simples. Pode ser controlada por property binding e é atualizada pelo evento `valueChange`. Para formulários e atributos textuais, use `serializedValue`.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.value = new Date(2026, 8, 7, 14, 30); ```
+          * Valor selecionado pelo usuário (Date | null).  Pode ser controlado externamente e é refletido internamente.
           * @default null
          */
         "value"?: Date | null;
         /**
-          * Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML. Diferentemente de `serializedValue`, recebe e retorna uma instância de `Date`. Na inicialização, tem precedência sobre `value` e `initialMoment` quando `serializedValue` não é informado. `null` inicia sem seleção; `undefined` permite usar as outras props.
-          * @example ```js const picker = document.querySelector('br-datetime-picker'); picker.valueAsDate = new Date(2026, 8, 7); ```
-         */
-        "valueAsDate"?: Date | null;
-        /**
-          * Define o dia inicial da semana exibida no calendário.  Valores suportados: 0 (domingo) a 6 (sábado).
+          * Dia inicial da semana exibido no calendário (0 = Dom, 6 = Sáb).
           * @default 0
          */
         "weekStartsOn"?: DatetimePickerWeekDayIndex;
@@ -12568,6 +12618,10 @@ declare namespace LocalJSX {
           * Emitted when the input clear button action is triggered.
          */
         "onBrClear"?: (event: BrInputCustomEvent<void>) => void;
+        /**
+          * Notifica a ativação do botão do slot `action` por clique ou teclado. Emitido no host com `detail.originalEvent` contendo o clique original. Propaga e atravessa Shadow DOM; não é cancelável nem altera o clique nativo. Não emite para o campo textual, botão de senha, inicialização ou controle desabilitado.
+         */
+        "onBrInputActionClick"?: (event: BrInputCustomEvent<InputActionClickDetail>) => void;
         /**
           * Informa o início e o resultado do validator, inclusive quando ele consulta um serviço remoto. O `detail` contém `validating`, `valid` e `message`; escrita programática e reset não representam interação do usuário.
          */
@@ -12646,7 +12700,7 @@ declare namespace LocalJSX {
          */
         "active"?: boolean;
         /**
-          * Renderiza o item como botão. Quando informado, tem precedência sobre `isButton`.
+          * Renderiza o item como botão de alternância: o acionamento alterna `selected`, emite `brItemSelect` e expõe o estado em `aria-pressed`. Para uma ação sem estado (ex.: "Sair"), use `href` com `navigation-mode="event"` ou um `br-button`. Quando informado, tem precedência sobre `isButton`.
          */
         "button"?: boolean;
         /**
@@ -13125,7 +13179,7 @@ declare namespace LocalJSX {
          */
         "density"?: BrDensity;
         /**
-          * Identificador legado do ícone a ser exibido. Nomes simples (por exemplo, `question`) são resolvidos pelo registro SVG local. Para classes CSS ou SVGs personalizados, prefira o slot `icon`.
+          * Ícone como identificador Iconify (ex.: `fa6-solid:star`) ou nome simples (ex.: `question`, resolvido como `fa6-solid:question` no registro SVG local), renderizado pelo `br-icon`. Para classes CSS (ex.: Font Awesome) ou SVGs personalizados, use o slot `icon`, a forma preferida. Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-star`) não são exibidas no Shadow DOM e geram aviso.
           * @default ''
          */
         "icon"?: string;
@@ -14397,6 +14451,17 @@ declare namespace LocalJSX {
      * - **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
      * - **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).
      * - **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.
+     * ### Navegação por teclado
+     * O foco permanece no campo `combobox` enquanto a lista está aberta; a opção em destaque é comunicada por `aria-activedescendant`.
+     * Ao receber foco, o campo abre a lista sem alterar a seleção atual.
+     * - **ArrowDown / ArrowUp:** abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
+     * - **Home / End:** em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
+     * - **Enter:** abre a lista quando fechada e confirma a opção destacada quando aberta.
+     * - **Espaço:** confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
+     * - **Escape:** fecha a lista, remove o destaque e devolve o foco ao campo.
+     * - **Tab:** fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
+     * - **Busca incremental:** em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
+     * - **Alt+ArrowDown / Alt+ArrowUp:** abre ou fecha a lista sem alterar a seleção.
      * ### Quando utilizar
      * - **Utilize quando:**
      *   - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
@@ -14465,7 +14530,7 @@ declare namespace LocalJSX {
          */
         "customId"?: string;
         /**
-          * Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+          * Define a densidade visual compartilhada pelo campo e pela lista de opções. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`. A opção sintética de selecionar todos permanece com densidade `small`.
           * @default 'medium'
          */
         "density"?: BrDensity;
@@ -14483,6 +14548,11 @@ declare namespace LocalJSX {
           * The `id` of a `<form>` element to associate this element with.
          */
         "form"?: string;
+        /**
+          * Oculta os divisores entre opções consecutivas, sem alterar a altura das linhas.
+          * @default false
+         */
+        "hideDividers"?: boolean;
         /**
           * Exibe rótulo e controle em linha. Quando informada, tem precedência sobre `isInline`.
          */
@@ -14756,7 +14826,7 @@ declare namespace LocalJSX {
          */
         "required"?: boolean;
         /**
-          * Exibe o ícone de busca dentro do campo.
+          * Exibe a lupa mesmo quando o campo não é filtrável. Quando filterable é true, a lupa é exibida automaticamente.
           * @type {boolean | undefined}
          */
         "showSearchIcon"?: boolean;
@@ -14786,10 +14856,15 @@ declare namespace LocalJSX {
          */
         "activeOptionIndex"?: number;
         /**
-          * Define a densidade visual da lista, das opções e do indicador de carregamento. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
+          * Define a densidade visual da lista, das opções regulares e do indicador de carregamento. A opção sintética de selecionar todos permanece com densidade `small`. Aceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.
           * @default 'medium'
          */
         "density"?: BrDensity;
+        /**
+          * Oculta os divisores entre opções consecutivas, sem alterar a altura das linhas.
+          * @default false
+         */
+        "hideDividers"?: boolean;
         /**
           * Informa a altura base usada no cálculo de posicionamento das opções. Deve ser um número finito positivo; valores inválidos usam 56.
           * @default 56
@@ -14927,7 +15002,7 @@ declare namespace LocalJSX {
      *   - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).
      * ### Estrutura e Slots
      * O `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.
-     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).
+     * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/signin?tab=designer).
      * @category Identidade, Ações, Formulários
      * @status stable
      */
@@ -14937,7 +15012,7 @@ declare namespace LocalJSX {
          */
         "ariaLabel"?: string;
         /**
-          * Define se o sign-in usará um esquema de cores escuro.
+          * Define se o sign-in usará um esquema de cores escuro, para fundos escuros. Quando omitido, ou com valor diferente de `dark`, usa o esquema claro.
          */
         "colorMode"?: 'dark';
         /**
@@ -15631,7 +15706,7 @@ declare namespace LocalJSX {
          */
         "counter"?: string;
         /**
-          * Define o ícone do item de tab usando classes CSS do Font Awesome 5, como `fas fa-bell`. O formato Iconify é aceito apenas para compatibilidade legada e não deve ser usado em novos códigos.
+          * Ícone da aba como identificador Iconify (ex.: `fa6-solid:bell`), renderizado em SVG pelo `br-icon`. Para ícones por classe CSS (ex.: Font Awesome), use o slot `icon-{id}` do `br-tab`, a forma preferida: `<i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>`. O slot tem precedência sobre esta prop. Uso descontinuado: classes CSS nesta prop (ex.: `fas fa-bell`) não são exibidas no Shadow DOM, geram aviso e devem migrar para o slot `icon-{id}`. Identificadores Iconify continuam suportados.
          */
         "icon"?: string;
         /**
@@ -16221,35 +16296,36 @@ declare namespace LocalJSX {
         "wrap"?: TextareaWrap;
     }
     /**
-     * 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.
-     * 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
+     * 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.
+     * 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.
+     * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
      */
     interface BrTimePicker {
         /**
-          * 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.
+          * 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
          */
         "onDateStateChange"?: (event: BrTimePickerCustomEvent<DatetimePickerDateState>) => void;
         /**
-          * 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.
-          * @example ```js const timePicker = document.querySelector('br-time-picker'); timePicker.referenceDate = new Date(2026, 8, 7, 9); ```
+          * Data de referência usada para exibir e ajustar hora e minuto.
           * @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`.
-          * @example ```js const timePicker = document.querySelector('br-time-picker'); timePicker.value = new Date(2026, 8, 7, 14, 30); ```
+          * Valor canônico selecionado pelo usuário.
           * @default null
          */
         "value"?: Date | null;
@@ -17291,6 +17367,7 @@ declare namespace LocalJSX {
         "itemHeight": number;
         "inputWidth": string | undefined;
         "overscan": number;
+        "hideDividers": boolean;
         "isOpen": boolean;
         "open": boolean;
         "label": string;
@@ -17335,6 +17412,7 @@ declare namespace LocalJSX {
         "visibleItems": number;
         "itemHeight": number;
         "overscan": number;
+        "hideDividers": boolean;
         "selectAllLabel": string;
         "unselectAllLabel": string;
         "activeOptionIndex": number;
@@ -18037,52 +18115,52 @@ declare module "@stencil/core" {
              */
             "br-crumb": LocalJSX.IntrinsicElements["br-crumb"] & JSXBase.HTMLAttributes<HTMLBrCrumbElement>;
             /**
-             * 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).
-             * 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
+             * 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.
+             * 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.
+             * 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).
              */
             "br-date-picker": LocalJSX.IntrinsicElements["br-date-picker"] & JSXBase.HTMLAttributes<HTMLBrDatePickerElement>;
             /**
-             * 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.
-             * 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
+             * 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.
+             * 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.
+             * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetime?tab=designer).
+             * @see https://www.gov.br/ds/components/datetime?tab=designer
              */
             "br-datetime-input": LocalJSX.IntrinsicElements["br-datetime-input"] & JSXBase.HTMLAttributes<HTMLBrDatetimeInputElement>;
             /**
-             * O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.
+             * O `br-datetime-picker` é o controle completo do GovBR-DS para digitação e seleção visual de datas e horários. Orquestra o campo textual e os seletores internos, consolidando valor, validação e integração com formulários HTML.
              * ### Para que serve
-             * - **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).
-             * - **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.
-             * - **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.
+             * - Oferece os modos `date`, `time` e `datetime`, com seleção única (`single`) ou de intervalo (`range`).
+             * - Combina edição textual com máscara, calendário e ajuste de horas e minutos conforme o modo escolhido.
+             * - Centraliza restrições de seleção, validação e submissão do valor por meio de `formAssociated`.
              * ### Quando utilizar
-             * - **Utilize quando:**
-             *   - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.
-             *   - For necessário selecionar um período com data de início e fim.
-             * - **Evite e prefira outro componente quando:**
-             *   - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).
+             * - Utilize quando o formulário precisar de um controle completo de data ou horário com digitação e seleção visual.
+             * - Utilize para períodos com início e fim, inclusive com horários nos modos `time` e `datetime`.
+             * - Evite quando precisar apenas apresentar uma data: prefira texto formatado.
+             * - Para um calendário permanentemente visível sem o campo textual, considere `br-date-picker`; a aplicação assume a integração com o restante do formulário.
+             * - A seleção não oferece uma coleção de datas independentes: use `single` para um valor ou `range` para um intervalo.
              * ### Composição e Subcomponentes
-             * | Subcomponente | Papel | Regra de uso |
+             * | Componente | Papel | Regra de uso |
              * | --- | --- | --- |
-             * | `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |
-             * | `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |
-             * | `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |
-             * | `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |
+             * | `br-datetime-picker` | Orquestrador do valor consolidado, validação, formulário e abertura do painel. | Declare este controle no template para obter a composição completa. |
+             * | `br-datetime-input` | Campo textual com máscara, interpretação da entrada e ação de abertura do painel. | Instanciado internamente pelo pai; não deve ser fornecido em slot. |
+             * | `br-date-picker` | Calendário para navegação e seleção de data única ou intervalo. | Criado pelo pai nos modos `date` e `datetime`; pode ser usado isoladamente como calendário embutido. |
+             * | `br-time-picker` | Controles de hora e minuto. | Criado pelo pai nos modos `time` e `datetime`, com uma instância por limite quando a seleção é `range`. |
+             * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
              * ### Como os subcomponentes se relacionam
-             * O `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).
-             * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
-             * @category Formulários, Seleção
+             * O pai fornece valores e configurações aos filhos por propriedades e consolida suas alterações por eventos DOM. O campo textual solicita a abertura do painel; o calendário e os controles de horário atualizam a seleção compartilhada, sem coordenar diretamente uns aos outros.
+             * `referenceDate` representa a referência de navegação visual, distinta da seleção efetiva. O orquestrador mantém o campo textual, os seletores e o valor de formulário sincronizados. A aplicação consome o valor e os eventos do pai, incluindo `brDatetimePickerChange` para a seleção completa e tipada.
+             * O uso isolado dos filhos exige que a aplicação assuma a coordenação de estado, validação e formulário; eles não herdam a associação nativa ao formulário do `br-datetime-picker`.
+             * 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/datetimepicker?tab=designer).
+             * @category Formulários
              * @status stable
              */
             "br-datetime-picker": LocalJSX.IntrinsicElements["br-datetime-picker"] & JSXBase.HTMLAttributes<HTMLBrDatetimePickerElement>;
@@ -18768,6 +18846,17 @@ declare module "@stencil/core" {
              * - **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.
              * - **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).
              * - **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.
+             * ### Navegação por teclado
+             * O foco permanece no campo `combobox` enquanto a lista está aberta; a opção em destaque é comunicada por `aria-activedescendant`.
+             * Ao receber foco, o campo abre a lista sem alterar a seleção atual.
+             * - **ArrowDown / ArrowUp:** abre a lista e destaca a próxima opção na direção pressionada; com a lista aberta, move o destaque sem mover o foco físico.
+             * - **Home / End:** em modo não filtrável, destaca a primeira ou a última opção habilitada; em modo filtrável, preserva o movimento do cursor no texto.
+             * - **Enter:** abre a lista quando fechada e confirma a opção destacada quando aberta.
+             * - **Espaço:** confirma a opção destacada em modo não filtrável; em modo filtrável, insere um espaço no campo de busca.
+             * - **Escape:** fecha a lista, remove o destaque e devolve o foco ao campo.
+             * - **Tab:** fecha a lista e deixa o navegador mover o foco para o próximo controle, sem alterar a seleção implicitamente.
+             * - **Busca incremental:** em modo não filtrável, caracteres consecutivos destacam a primeira opção habilitada correspondente; em modo filtrável, a digitação filtra a lista.
+             * - **Alt+ArrowDown / Alt+ArrowUp:** abre ou fecha a lista sem alterar a seleção.
              * ### Quando utilizar
              * - **Utilize quando:**
              *   - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.
@@ -18875,7 +18964,7 @@ declare module "@stencil/core" {
              *   - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).
              * ### Estrutura e Slots
              * O `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.
-             * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).
+             * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/signin?tab=designer).
              * @category Identidade, Ações, Formulários
              * @status stable
              */
@@ -19179,15 +19268,13 @@ declare module "@stencil/core" {
              */
             "br-textarea": LocalJSX.IntrinsicElements["br-textarea"] & JSXBase.HTMLAttributes<HTMLBrTextareaElement>;
             /**
-             * 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.
-             * 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
+             * 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.
+             * 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.
+             * Consulte também as [diretrizes de design do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).
              */
             "br-time-picker": LocalJSX.IntrinsicElements["br-time-picker"] & JSXBase.HTMLAttributes<HTMLBrTimePickerElement>;
             /**