@govbr-ds/webcomponents 2.1.3 → 2.3.0

package/dist/collection/components/datetime-picker/datetime-picker.js

@@ -9,18 +9,48 @@ import { set } from "date-fns/set";
 import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../shared/utils/event";
 import { getFormValidationState, isFormControlDisabled, setFormValidity, } from "../../shared/utils/form";
+import { generateUniqueId } from "../../shared/utils/id";
+import { reportInvalidPropValue } from "../../shared/utils/prop-warning";
 import { hasAssignedSlotContent } from "../../shared/utils/slot";
 import { resolveSsrLocalDate } from "../../shared/utils/ssr-date";
 import { resolveFormValidator, runFormValidator } from "../../shared/utils/validator";
 import { DATETIME_PICKER_LOCALE, DATETIME_PICKER_MODE } from "./datetime-picker-constants";
 import { hasDatetimePickerMissingValue, parseDatetimePickerSerializedRange, parseDatetimePickerSerializedValue, serializeDatetimePickerFormValue, } from "./datetime-picker-form-associated";
-import { normalizeDatetimePickerDisabledDates, normalizeDatetimePickerInitialMoment, normalizeDatetimePickerMode, normalizeDatetimePickerSelectionMode, normalizeDatetimePickerWeekStartsOn, } from "./datetime-picker-props-validation";
+import { isValidDatetimePickerDateRange, normalizeDatetimePickerDisabledDates, normalizeDatetimePickerInitialMoment, normalizeDatetimePickerMode, normalizeDatetimePickerSelectionMode, normalizeDatetimePickerWeekStartsOn, } from "./datetime-picker-props-validation";
 /**
- * ## Design System
+ * 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.
  *
- * 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).
+ * ### Para que serve
  *
- * @category Formulários
+ * - **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.
+ *
+ * ### 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).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | Subcomponente | 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. |
+ *
+ * ### 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
  * @status stable
  * @slot feedback - Mensagem de validação, normalmente um `br-message`.
  * @part container - Parte para o container base do seletor.
@@ -41,7 +71,7 @@ export class DatetimePicker {
         this.customValidationMessage = '';
         this.validatorMessage = null;
         this.isValidating = false;
-        this.feedbackId = `br-datetime-picker-feedback-${datetimePickerId++}`;
+        this.feedbackId = generateUniqueId('br-datetime-picker-feedback');
         /** Lista normalizada de datas indisponíveis para seleção. */
         this.normalizedDisabledDates = [];
         /** Data final selecionada no modo de intervalo. */
@@ -78,9 +108,25 @@ export class DatetimePicker {
         this.name = '';
         /** Indica se o campo deve ter valor antes do envio do formulário. */
         this.required = false;
-        /** Menor data/horário aceito, interpretado conforme `mode`. */
+        /**
+         * 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>
+         * ```
+         */
         this.min = null;
-        /** Maior data/horário aceito, interpretado conforme `mode`. */
+        /**
+         * 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>
+         * ```
+         */
         this.max = null;
         /**
          * Define o tipo de seleção de datas para o calendário: única ou intervalo.
@@ -89,6 +135,7 @@ export class DatetimePicker {
          * 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`.
          */
         this.selectionMode = 'single';
         /**
@@ -110,11 +157,22 @@ export class DatetimePicker {
          * Reativo em runtime: mudanças na prop atualizam estado e subcomponentes.
          *
          * @default null
+         * @example
+         * ```html
+         * <br-datetime-picker initial-moment="now"></br-datetime-picker>
+         * ```
          */
         this.initialMoment = null;
         /**
-         * Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizado
-         * pelo evento `valueChange`.
+         * 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);
+         * ```
          */
         this.value = null;
         /**
@@ -133,6 +191,15 @@ export class DatetimePicker {
          * A comparação considera apenas o dia (ano/mês/dia), ignorando hora.
          *
          * @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'];
+         * ```
          */
         this.disabledDates = null;
         /**
@@ -211,7 +278,7 @@ export class DatetimePicker {
                 return;
             event.stopPropagation();
             this.isPickerOpen = false;
-            this.getNativeInputElement()?.focus();
+            void this.focusInput();
         };
     }
     formDisabledCallback(disabled) {
@@ -333,6 +400,10 @@ export class DatetimePicker {
     handleRangeValueChange(newValue) {
         if (!newValue || this.selectionMode !== 'range')
             return;
+        if (!isValidDatetimePickerDateRange(newValue)) {
+            reportInvalidPropValue(this.el, 'rangeValue', newValue, 'Informe um objeto com `start` e `end` como Date válido ou null.', 'Mantendo o último intervalo efetivo.');
+            return;
+        }
         this.rangeStart = this.cloneDate(newValue.start);
         this.rangeEnd = this.cloneDate(newValue.end);
         const nextValue = newValue.end ?? newValue.start;
@@ -352,17 +423,19 @@ export class DatetimePicker {
      * Normaliza o modo antes da primeira renderização e aplica a data atual quando solicitado.
      */
     componentWillLoad() {
+        // A inicialização dos defaults sincroniza os espelhos; preserve as entradas do consumidor.
+        const { serializedValue, valueAsDate } = this;
         this.referenceDate = resolveSsrLocalDate(this.el, this.referenceDate);
         this.initializeMode();
         this.initializeSelectionMode();
         this.initializeWeekStartsOn();
         this.initializeDisabledDates();
         this.initializeDefaultValue();
-        if (this.serializedValue !== undefined) {
-            this.restoreSerializedValue(this.serializedValue);
+        if (serializedValue !== undefined) {
+            this.restoreSerializedValue(serializedValue);
         }
-        else if (this.valueAsDate !== undefined) {
-            this.handleValueAsDateChange(this.valueAsDate);
+        else if (valueAsDate !== undefined) {
+            this.handleValueAsDateChange(valueAsDate);
         }
         this.initialFormValue = this.cloneDate(this.value);
         this.syncCanonicalValues();
@@ -433,7 +506,8 @@ export class DatetimePicker {
     }
     /** Move o foco para o input nativo interno. */
     async focusInput() {
-        this.getNativeInputElement()?.focus();
+        const input = this.datetimeInputElement ?? this.el.shadowRoot?.querySelector('br-datetime-input');
+        await input?.focusInput?.();
     }
     /** Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range. */
     async setRange(start, end) {
@@ -730,12 +804,9 @@ export class DatetimePicker {
     sameDate(left, right) {
         return left === right || (left !== null && right !== null && left.getTime() === right.getTime());
     }
-    /** Busca o input nativo interno para ações imperativas de foco. */
+    /** Retorna a âncora de validação, ou undefined antes do primeiro render. */
     getNativeInputElement() {
-        return this.el.shadowRoot
-            ?.querySelector('br-datetime-input')
-            ?.shadowRoot?.querySelector('br-input')
-            ?.shadowRoot?.querySelector('input');
+        return (this.datetimeInputElement ?? this.el.shadowRoot?.querySelector('br-datetime-input') ?? undefined);
     }
     /** Atualiza estado interno, FormData e validação com uma única chamada. */
     setComponentValue(nextValue, shouldEmitPublicEvent = true) {
@@ -836,8 +907,8 @@ export class DatetimePicker {
                 rangeEnd: this.rangeEnd,
                 referenceDate: this.referenceDate,
             });
-            const min = this.parseConstraintValue(this.min);
-            const max = this.parseConstraintValue(this.max);
+            const min = this.parseConstraintValue(this.min, 'min');
+            const max = this.parseConstraintValue(this.max, 'max');
             const values = this.selectionMode === 'range' ? [this.rangeStart, this.rangeEnd] : [this.value];
             const rangeUnderflow = min !== null && values.some((value) => value !== null && value.getTime() < min.getTime());
             const rangeOverflow = max !== null && values.some((value) => value !== null && value.getTime() > max.getTime());
@@ -868,8 +939,18 @@ export class DatetimePicker {
             // Ambientes sem ElementInternals completo não devem falhar.
         }
     }
-    parseConstraintValue(value) {
-        return value === null ? null : this.parseMethodValue(value, this.mode);
+    parseConstraintValue(value, propertyName) {
+        if (value === null)
+            return null;
+        if (!(value instanceof Date) && typeof value !== 'string') {
+            reportInvalidPropValue(this.el, propertyName, value, 'Informe uma data válida como Date ou string compatível com o modo atual.', 'Aplicando fallback null (sem limite).');
+            return null;
+        }
+        const parsedValue = this.parseMethodValue(value, this.mode);
+        if (parsedValue !== null)
+            return parsedValue;
+        reportInvalidPropValue(this.el, propertyName, value, 'Informe uma data válida como Date ou string compatível com o modo atual.', 'Aplicando fallback null (sem limite).');
+        return null;
     }
     isDisabled() {
         return isFormControlDisabled(this.disabled, this.formDisabled);
@@ -927,7 +1008,9 @@ export class DatetimePicker {
     }
     /** Renderiza o campo de entrada responsável por abrir e sincronizar o picker. */
     renderInputField() {
-        return (h("br-datetime-input", { referenceDate: this.referenceDate, value: this.value, selectionMode: this.selectionMode, rangeStart: this.rangeStart, rangeEnd: this.rangeEnd, placeholder: this.placeholder, mode: this.mode, disabled: this.isDisabled(), onDateStateChange: this.handleDateStateChange, onTogglePicker: this.handleTogglePicker, exportparts: "container: input-container, input: input-field, icon: input-icon" }));
+        return (h("br-datetime-input", { ref: (element) => {
+                this.datetimeInputElement = element;
+            }, referenceDate: this.referenceDate, value: this.value, selectionMode: this.selectionMode, rangeStart: this.rangeStart, rangeEnd: this.rangeEnd, placeholder: this.placeholder, mode: this.mode, disabled: this.isDisabled(), onDateStateChange: this.handleDateStateChange, onTogglePicker: this.handleTogglePicker, exportparts: "container: input-container, input: input-field, icon: input-icon" }));
     }
     /** Renderiza apenas o seletor de data. */
     renderDatePicker() {
@@ -962,7 +1045,7 @@ export class DatetimePicker {
      * Renderização principal do componente.
      */
     render() {
-        return (h(Host, { key: '906849439dfc93b18952963b95e35da332e5018b', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || this.customValidationMessage || this.validatorMessage ? this.feedbackId : null, "aria-errormessage": this.customValidationMessage || this.validatorMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '8a77432dc84c6897d7ffb2e403f72d42e333230a', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: '1e3f4df6f301fbb54d76eea49848ec7910bc3f33', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !this.customValidationMessage && !this.validatorMessage }, h("slot", { key: '7000d3c447c5bfa1f674c78024a1e58ca69652a3', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && (this.customValidationMessage || this.validatorMessage) ? (h("br-message", { state: "danger", message: this.customValidationMessage || this.validatorMessage })) : null)));
+        return (h(Host, { key: 'b964215e48b1871bf6ab1b045612f3d166543177', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || this.customValidationMessage || this.validatorMessage ? this.feedbackId : null, "aria-errormessage": this.customValidationMessage || this.validatorMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '50ba10963ba4e8bdf7c70f0d4513eea657692df8', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: 'b220e70a85d8ba941dabed18a5a0dcdc9a99124f', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !this.customValidationMessage && !this.validatorMessage }, h("slot", { key: 'cdcc69b126491b2cea3b634066f1e4071c1c3b61', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && (this.customValidationMessage || this.validatorMessage) ? (h("br-message", { state: "danger", message: this.customValidationMessage || this.validatorMessage })) : null)));
     }
     static get is() { return "br-datetime-picker"; }
     static get encapsulation() { return "shadow"; }
@@ -1118,8 +1201,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Menor data/hor\u00E1rio aceito, interpretado conforme `mode`."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<br-datetime-picker mode=\"date\" min=\"2026-01-01\"></br-datetime-picker>\n```"
+                        }],
+                    "text": "Menor data/hor\u00E1rio aceito, interpretado conforme `mode`. Valores inv\u00E1lidos s\u00E3o ignorados.\nAceita texto no atributo HTML ou uma inst\u00E2ncia de `Date` por property binding."
                 },
                 "getter": false,
                 "setter": false,
@@ -1143,8 +1229,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Maior data/hor\u00E1rio aceito, interpretado conforme `mode`."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<br-datetime-picker mode=\"date\" max=\"2026-12-31\"></br-datetime-picker>\n```"
+                        }],
+                    "text": "Maior data/hor\u00E1rio aceito, interpretado conforme `mode`. Valores inv\u00E1lidos s\u00E3o ignorados.\nAceita texto no atributo HTML ou uma inst\u00E2ncia de `Date` por property binding."
                 },
                 "getter": false,
                 "setter": false,
@@ -1170,8 +1259,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Regra s\u00EDncrona ou ass\u00EDncrona aplicada \u00E0 data ou intervalo selecionado."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.validator = (value) => value === null ? 'Escolha uma data' : null;\n```"
+                        }],
+                    "text": "Regra s\u00EDncrona ou ass\u00EDncrona aplicada \u00E0 data ou intervalo selecionado.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor."
                 },
                 "getter": false,
                 "setter": false
@@ -1195,7 +1287,7 @@ export class DatetimePicker {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Define o tipo de sele\u00E7\u00E3o de datas para o calend\u00E1rio: \u00FAnica ou intervalo.\n\n`range` s\u00F3 funciona em conjunto com `mode=\"date\"`.\nSe `selectionMode=\"range\"` for informado, o componente ajusta automaticamente\n`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente\nnormaliza `selectionMode` para `single` quando necess\u00E1rio."
+                    "text": "Define o tipo de sele\u00E7\u00E3o de datas para o calend\u00E1rio: \u00FAnica ou intervalo.\n\n`range` s\u00F3 funciona em conjunto com `mode=\"date\"`.\nSe `selectionMode=\"range\"` for informado, o componente ajusta automaticamente\n`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente\nnormaliza `selectionMode` para `single` quando necess\u00E1rio.\nValores inv\u00E1lidos usam `single`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1254,6 +1346,9 @@ export class DatetimePicker {
                     "tags": [{
                             "name": "default",
                             "text": "null"
+                        }, {
+                            "name": "example",
+                            "text": "```html\n<br-datetime-picker initial-moment=\"now\"></br-datetime-picker>\n```"
                         }],
                     "text": "Define a sele\u00E7\u00E3o inicial do componente.\n\nAceita:\n- `'now'`: seleciona o momento atual.\n- `Date` ou `string`: seleciona uma data arbitr\u00E1ria.\n- `null`: inicia sem sele\u00E7\u00E3o.\n\nReativo em runtime: mudan\u00E7as na prop atualizam estado e subcomponentes."
                 },
@@ -1279,8 +1374,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Valor selecionado pelo usu\u00E1rio. Pode ser controlado externamente e \u00E9 atualizado\npelo evento `valueChange`."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.value = new Date(2026, 8, 7, 14, 30);\n```"
+                        }],
+                    "text": "Inst\u00E2ncia de `Date` selecionada pelo usu\u00E1rio no modo simples.\nPode ser controlada por property binding e \u00E9 atualizada pelo evento `valueChange`.\nPara formul\u00E1rios e atributos textuais, use `serializedValue`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1297,8 +1395,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Representa\u00E7\u00E3o serializada compat\u00EDvel com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`\nou ISO local, conforme `mode`). Em intervalos, usa `in\u00EDcio/fim`.\n\nQuando informada, tem preced\u00EAncia sobre o valor legado `value` durante a inicializa\u00E7\u00E3o."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<br-datetime-picker mode=\"datetime\" serialized-value=\"2026-09-07T14:30\"></br-datetime-picker>\n```"
+                        }],
+                    "text": "Representa\u00E7\u00E3o serializada compat\u00EDvel com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`\nou ISO local, conforme `mode`). Em intervalos, usa `in\u00EDcio/fim`.\n\nNa inicializa\u00E7\u00E3o, tem preced\u00EAncia sobre `valueAsDate`, `value` e `initialMoment`.\nUma string vazia inicia sem sele\u00E7\u00E3o, mesmo quando outra prop fornece uma data."
                 },
                 "getter": false,
                 "setter": false,
@@ -1321,8 +1422,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Espelho tipado da sele\u00E7\u00E3o atual, equivalente ao padr\u00E3o `valueAsDate` dos controles HTML."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.valueAsDate = new Date(2026, 8, 7);\n```"
+                        }],
+                    "text": "Espelho tipado da sele\u00E7\u00E3o atual, equivalente ao padr\u00E3o `valueAsDate` dos controles HTML.\nDiferentemente de `serializedValue`, recebe e retorna uma inst\u00E2ncia de `Date`.\nNa inicializa\u00E7\u00E3o, tem preced\u00EAncia sobre `value` e `initialMoment` quando `serializedValue`\nn\u00E3o \u00E9 informado. `null` inicia sem sele\u00E7\u00E3o; `undefined` permite usar as outras props."
                 },
                 "getter": false,
                 "setter": false
@@ -1345,8 +1449,11 @@ export class DatetimePicker {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Intervalo controlado quando `selectionMode=\"range\"`."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.selectionMode = 'range';\npicker.rangeValue = {\n  start: new Date(2026, 8, 7),\n  end: new Date(2026, 8, 12),\n};\n```"
+                        }],
+                    "text": "Intervalo controlado quando `selectionMode=\"range\"`.\nDeve conter datas v\u00E1lidas ou `null` em `start` e `end`; valores inv\u00E1lidos mant\u00EAm o \u00FAltimo intervalo efetivo.\nPasse o objeto por property binding; atributos HTML n\u00E3o representam objetos com `Date`."
                 },
                 "getter": false,
                 "setter": false
@@ -1395,6 +1502,12 @@ export class DatetimePicker {
                     "tags": [{
                             "name": "default",
                             "text": "null"
+                        }, {
+                            "name": "example",
+                            "text": "```html\n<br-datetime-picker mode=\"date\" disabled-dates=\"2026-09-07 2026-09-08\"></br-datetime-picker>\n```"
+                        }, {
+                            "name": "example",
+                            "text": "```js\nconst picker = document.querySelector('br-datetime-picker');\npicker.disabledDates = [new Date(2026, 8, 7), '2026-09-08'];\n```"
                         }],
                     "text": "Define um conjunto de datas indispon\u00EDveis para sele\u00E7\u00E3o.\n\nAceita uma lista de `Date` e/ou strings analis\u00E1veis, ou uma string com datas\nseparadas por espa\u00E7o em branco. Datas inv\u00E1lidas s\u00E3o ignoradas com warning.\nA compara\u00E7\u00E3o considera apenas o dia (ano/m\u00EAs/dia), ignorando hora."
                 },
@@ -1667,6 +1780,10 @@ export class DatetimePicker {
                         "Promise": {
                             "location": "global",
                             "id": "global::Promise"
+                        },
+                        "HTMLBrDatetimeInputElement": {
+                            "location": "global",
+                            "id": "global::HTMLBrDatetimeInputElement"
                         }
                     },
                     "return": "Promise<void>"
@@ -1921,4 +2038,3 @@ export class DatetimePicker {
     }
     static get attachInternalsMemberName() { return "elementInternals"; }
 }
-let datetimePickerId = 0;

package/dist/collection/components/datetime-picker/time-picker/time-picker.css

@@ -1 +1 @@
-*,*::before,*::after{box-sizing:border-box}:host{line-height:var(--font-line-height-medium);-webkit-text-size-adjust:100%;-moz-text-size-adjust:100%;text-size-adjust:100%}main{display:block}hr{box-sizing:content-box;height:0;overflow:visible}a{background-color:rgba(0,0,0,0)}b,strong{font-weight:bolder}code{font-family:monospace;font-size:1em}small{font-size:80%}img{border-style:none}button,input,select,textarea{font-family:inherit;font-size:100%;line-height:var(--font-line-height-medium);margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type=button],[type=reset],[type=submit]{appearance:button}button::-moz-focus-inner,[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{appearance:none}::-webkit-file-upload-button{appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}.d-none{display:none !important}@media(min-width: 576px){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}}[data-toggle=dropdown]+*{position:absolute}.dropdown{position:relative}.dropdown [data-toggle=dropdown]+*{box-shadow:var(--surface-shadow-sm);left:0;position:absolute;top:100%}.dropdown>.br-notification{left:auto;right:0}.dropdown .br-item{--color: var(--color-light);--color-rgb: var(--color-light-rgb);--text-color: var(--color-light);--interactive: var(--interactive-light);--interactive-rgb: var(--color-rgb);--visited: var(--visited-light);--hover: var(--hover-light);--pressed: var(--pressed-light);--focus-color: var(--focus-color-light);--focus: var(--focus-color-light);--item-padding-y: var(--spacing-scale-2x);background-color:var(--background-light);color:var(--color)}.dropdown .br-item:not(:last-child){border-bottom:1px solid var(--border-color)}.dropdown .br-item.selected{--color: var(--color-dark);--color-rgb: var(--color-dark-rgb);--text-color: var(--color-dark);--interactive: var(--interactive-dark);--interactive-rgb: var(--interactive-dark-rgb);--visited: var(--visited-dark);--hover: var(--hover-dark);--pressed: var(--pressed-dark);--focus-color: var(--focus-color-dark);--focus: var(--focus-color-dark)}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.align-items-center{align-items:center !important}.col,[class*=col-]{padding-left:calc(var(--grid-gutter)*.5);padding-right:calc(var(--grid-gutter)*.5);width:100%}.col{flex:1 0 0%;min-width:8.3333333333%}.col-auto{flex:0 0 auto;width:auto}.col-2{flex-basis:16.6666666667%;max-width:16.6666666667%}.container,.container-fluid,.container-lg{--grid-margin: var(--grid-portrait-margin);--grid-maxwidth: var(--grid-portrait-maxwidth);margin-left:auto;margin-right:auto;max-width:var(--grid-maxwidth);padding-left:var(--grid-margin);padding-right:var(--grid-margin);width:100%}.row{--grid-gutter: var(--grid-portrait-gutter);display:flex;flex-wrap:wrap;margin-left:calc(var(--grid-gutter)*-0.5);margin-right:calc(var(--grid-gutter)*-0.5)}@media(min-width: 576px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tablet-margin)}.row{--grid-gutter: var(--grid-tablet-gutter)}.container{--grid-maxwidth: calc(var(--grid-breakpoint-sm) - var(--grid-tablet-margin))}.col-sm-4{flex-basis:33.3333333333%;max-width:33.3333333333%}}@media(min-width: 992px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tablet-margin)}.row{--grid-gutter: var(--grid-tablet-gutter)}.container{--grid-maxwidth: calc(var(--grid-breakpoint-md) - var(--grid-tablet-margin))}}@media(min-width: 1280px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-desktop-margin)}.row{--grid-gutter: var(--grid-desktop-gutter)}.container,.container-lg{--grid-maxwidth: calc(var(--grid-breakpoint-lg) - var(--grid-desktop-margin))}.col-lg-3{flex-basis:25%;max-width:25%}}@media(min-width: 1600px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tv-margin)}.row{--grid-gutter: var(--grid-tv-gutter)}.container,.container-lg{--grid-maxwidth: calc(var(--grid-breakpoint-xl) - var(--grid-tv-margin))}}.ease{animation-timing-function:cubic-bezier(0.25, 0.1, 0.25, 1)}.ease-in-out{animation-timing-function:cubic-bezier(0.42, 0, 0.58, 1)}.mt-1{margin-top:var(--spacing-scale-half) !important}.mr-1{margin-right:var(--spacing-scale-half) !important}.mb-1{margin-bottom:var(--spacing-scale-half) !important}.ml-1{margin-left:var(--spacing-scale-half) !important}.mx-3{margin-left:var(--spacing-scale-2x) !important;margin-right:var(--spacing-scale-2x) !important}.mb-4{margin-bottom:var(--spacing-scale-3x) !important}.ml-auto{margin-left:auto !important}.pt-half{padding-top:var(--spacing-scale-half) !important}@media(min-width: 576px){.ml-sm-0{margin-left:var(--spacing-scale-default) !important}}.highlight{background:var(--status-highlight-background) linear-gradient(var(--status-highlight-overlay), var(--status-highlight-overlay));color:var(--status-highlight-text);padding:0 var(--spacing-scale-half)}[disabled],.disabled{cursor:not-allowed;opacity:var(--disabled)}[disabled] *,.disabled *{pointer-events:none}.text-center{text-align:center !important}.text-right{text-align:right !important}.text-nowrap{white-space:nowrap !important}.text-uppercase{text-transform:uppercase !important}.text-bold{font-weight:700 !important}.text-base{font-size:var(--font-size-scale-base) !important}.text-down-01{font-size:var(--font-size-scale-down-01) !important}@media(min-width: 576px){.text-sm-center{text-align:center !important}.text-sm-left{text-align:left !important}.text-sm-right{text-align:right !important}}p{color:var(--color);font-size:var(--font-size-scale-base);font-weight:var(--font-weight-regular);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-2x);margin-top:0}p a{text-decoration:underline}@media(min-width: 576px){p{font-size:var(--font-size-scale-up-01)}}a{--focus-offset: var(--spacing-scale-half)}a:focus{outline:none}a.focus-visible,a:focus-visible{outline-color:var(--focus);outline-offset:var(--focus-offset);outline-style:var(--focus-style);outline-width:var(--focus-width)}a:not(:disabled):hover{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--hover)), rgba(var(--interactive-rgb), var(--hover)))}a:not(:disabled):active{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--pressed)), rgba(var(--interactive-rgb), var(--pressed)))}a{color:var(--interactive);text-decoration:none}.main-content a{text-decoration:underline}button{cursor:pointer}img{max-width:100%;vertical-align:middle}h2,.h2{color:var(--color);font-size:var(--font-size-scale-up-03);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-2xh);margin-top:var(--spacing-scale-3xh);padding-bottom:var(--spacing-scale-2xh)}@media(min-width: 576px){.h2,h2{font-size:var(--font-size-scale-up-05);font-weight:var(--font-weight-regular)}}ul,ol{margin-bottom:var(--spacing-scale-2x);margin-top:0;padding:0 0 0 var(--spacing-scale-5x)}table{--table-background: var(--background);--table-color: var(--color);--table-border-color: var(--gray-20);--table-border-style: solid;--table-border-width: 1px;--table-hover: var(--color-rgb);--table-padding: var(--spacing-scale-3x);--table-font-weight: var(--font-weight-medium);--table-th-background: var(--background-alternative);--table-th-font-weight: var(--font-weight-semi-bold);--table-row-size: var(--spacing-scale-2x);border-collapse:collapse;width:100%}tr.selected,tr.is-selected{--color: var(--color-dark);--color-rgb: var(--color-dark-rgb);--text-color: var(--color-dark);--interactive: var(--interactive-dark);--interactive-rgb: var(--interactive-dark-rgb);--visited: var(--visited-dark);--hover: var(--hover-dark);--pressed: var(--pressed-dark);--focus-color: var(--focus-color-dark);--focus: var(--focus-color-dark)}label,.label{color:var(--color);font-size:var(--font-size-scale-base);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-half)}fieldset,.fieldset{border:var(--surface-width-none);margin-bottom:var(--spacing-scale-5x);margin-top:0;padding:0}legend,.legend{color:var(--color);font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-2x);margin-top:var(--spacing-scale-2x)}::placeholder,.placeholder{color:var(--color-light);font-size:var(--font-size-scale-base);font-style:italic;font-weight:var(--font-weight-regular);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-half);margin-top:var(--spacing-scale-half);opacity:1}input,textarea,.input{color:var(--color-light);font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-medium);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-half)}.help{font-size:var(--font-size-scale-base)}code,.code{background:var(--gray-5);border-radius:4px;color:var(--gray-80);display:inline-block;font-family:monospace;font-size:var(--font-size-scale-base);font-weight:var(--font-weight-medium);line-height:var(--font-line-height-low);padding:var(--spacing-scale-half)}*[data-toggle=collapse]:not(:disabled):hover{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--hover)), rgba(var(--interactive-rgb), var(--hover)))}*[data-toggle=collapse]:focus{outline:none}*[data-toggle=collapse].focus-visible,*[data-toggle=collapse]:focus-visible{outline-color:var(--focus);outline-offset:var(--focus-offset);outline-style:var(--focus-style);outline-width:var(--focus-width)}:host{display:block;width:100%;max-width:144px;height:116px;margin-inline:auto;box-sizing:border-box}.br-time-picker{display:flex;justify-content:center;align-items:center;width:100%;height:100%;box-sizing:border-box}.timer{display:flex;flex-direction:row;justify-content:center;align-items:center;gap:var(--spacing-scale-sm);width:100%;box-sizing:border-box}.time-field{display:flex;flex-direction:column;align-items:center;justify-content:flex-end}.time-field label{font-size:var(--font-size-scale-down-01);color:var(--gray-70);margin-bottom:4px}.time-field input{width:var(--spacing-scale-6x);height:var(--spacing-scale-6x);padding:4px;font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);text-align:center;border-color:var(--border-color-alternative);border-radius:var(--surface-rounder-sm);border-style:var(--border-style);border-width:var(--border-width)}.time-field input:hover{background:linear-gradient(rgb(var(--color-rgb), var(--hover)), rgb(var(--color-rgb), var(--hover)))}.time-separator{display:inline-block;font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);color:var(--gray-70);align-self:center;line-height:1;padding:0 var(--spacing-scale-base)}
+*,*::before,*::after{box-sizing:border-box}:host{line-height:var(--font-line-height-medium);-webkit-text-size-adjust:100%;-moz-text-size-adjust:100%;text-size-adjust:100%}main{display:block}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace;font-size:1em}a{background-color:rgba(0,0,0,0)}b,strong{font-weight:bolder}code{font-family:monospace;font-size:1em}small{font-size:80%}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:var(--font-line-height-medium);margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type=button],[type=reset],[type=submit]{appearance:button}button::-moz-focus-inner,[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{appearance:none}::-webkit-file-upload-button{appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}.d-none{display:none !important}@media(min-width: 576px){.d-sm-block{display:block !important}.d-sm-flex{display:flex !important}}[data-toggle=dropdown]+*{position:absolute}.dropdown{position:relative}.dropdown [data-toggle=dropdown]+*{box-shadow:var(--surface-shadow-sm);left:0;position:absolute;top:100%}.dropdown>.br-notification{left:auto;right:0}.dropdown .br-item{--color: var(--color-light);--color-rgb: var(--color-light-rgb);--text-color: var(--color-light);--interactive: var(--interactive-light);--interactive-rgb: var(--color-rgb);--visited: var(--visited-light);--hover: var(--hover-light);--pressed: var(--pressed-light);--focus-color: var(--focus-color-light);--focus: var(--focus-color-light);--item-padding-y: var(--spacing-scale-2x);background-color:var(--background-light);color:var(--color)}.dropdown .br-item:not(:last-child){border-bottom:1px solid var(--border-color)}.dropdown .br-item.selected{--color: var(--color-dark);--color-rgb: var(--color-dark-rgb);--text-color: var(--color-dark);--interactive: var(--interactive-dark);--interactive-rgb: var(--interactive-dark-rgb);--visited: var(--visited-dark);--hover: var(--hover-dark);--pressed: var(--pressed-dark);--focus-color: var(--focus-color-dark);--focus: var(--focus-color-dark)}.justify-content-start{justify-content:flex-start !important}.justify-content-end{justify-content:flex-end !important}.justify-content-center{justify-content:center !important}.align-items-center{align-items:center !important}.col,[class*=col-]{padding-left:calc(var(--grid-gutter)*.5);padding-right:calc(var(--grid-gutter)*.5);width:100%}.col{flex:1 0 0%;min-width:8.3333333333%}.col-auto{flex:0 0 auto;width:auto}.col-2{flex-basis:16.6666666667%;max-width:16.6666666667%}.container,.container-fluid,.container-lg{--grid-margin: var(--grid-portrait-margin);--grid-maxwidth: var(--grid-portrait-maxwidth);margin-left:auto;margin-right:auto;max-width:var(--grid-maxwidth);padding-left:var(--grid-margin);padding-right:var(--grid-margin);width:100%}.row{--grid-gutter: var(--grid-portrait-gutter);display:flex;flex-wrap:wrap;margin-left:calc(var(--grid-gutter)*-0.5);margin-right:calc(var(--grid-gutter)*-0.5)}@media(min-width: 576px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tablet-margin)}.row{--grid-gutter: var(--grid-tablet-gutter)}.container{--grid-maxwidth: calc(var(--grid-breakpoint-sm) - var(--grid-tablet-margin))}.col-sm-4{flex-basis:33.3333333333%;max-width:33.3333333333%}}@media(min-width: 992px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tablet-margin)}.row{--grid-gutter: var(--grid-tablet-gutter)}.container{--grid-maxwidth: calc(var(--grid-breakpoint-md) - var(--grid-tablet-margin))}}@media(min-width: 1280px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-desktop-margin)}.row{--grid-gutter: var(--grid-desktop-gutter)}.container,.container-lg{--grid-maxwidth: calc(var(--grid-breakpoint-lg) - var(--grid-desktop-margin))}.col-lg-3{flex-basis:25%;max-width:25%}}@media(min-width: 1600px){.container,.container-lg,.container-fluid{--grid-margin: var(--grid-tv-margin)}.row{--grid-gutter: var(--grid-tv-gutter)}.container,.container-lg{--grid-maxwidth: calc(var(--grid-breakpoint-xl) - var(--grid-tv-margin))}}.ease{animation-timing-function:cubic-bezier(0.25, 0.1, 0.25, 1)}.ease-out{animation-timing-function:cubic-bezier(0, 0, 0.58, 1)}.ease-in-out{animation-timing-function:cubic-bezier(0.42, 0, 0.58, 1)}.fast{animation-duration:var(--duration-fast)}.slow{animation-duration:var(--duration-slow)}.mt-1{margin-top:var(--spacing-scale-half) !important}.mr-1{margin-right:var(--spacing-scale-half) !important}.mb-1{margin-bottom:var(--spacing-scale-half) !important}.ml-1{margin-left:var(--spacing-scale-half) !important}.mx-3{margin-left:var(--spacing-scale-2x) !important;margin-right:var(--spacing-scale-2x) !important}.mb-4{margin-bottom:var(--spacing-scale-3x) !important}.ml-auto{margin-left:auto !important}.pt-half{padding-top:var(--spacing-scale-half) !important}@media(min-width: 576px){.ml-sm-0{margin-left:var(--spacing-scale-default) !important}}.highlight{background:var(--status-highlight-background) linear-gradient(var(--status-highlight-overlay), var(--status-highlight-overlay));color:var(--status-highlight-text);padding:0 var(--spacing-scale-half)}[disabled],.disabled{cursor:not-allowed;opacity:var(--disabled)}[disabled] *,.disabled *{pointer-events:none}fieldset[disabled]{opacity:1}.text-center{text-align:center !important}.text-right{text-align:right !important}.text-nowrap{white-space:nowrap !important}.text-uppercase{text-transform:uppercase !important}.text-bold{font-weight:700 !important}.text-base{font-size:var(--font-size-scale-base) !important}.text-down-01{font-size:var(--font-size-scale-down-01) !important}@media(min-width: 576px){.text-sm-center{text-align:center !important}.text-sm-left{text-align:left !important}.text-sm-right{text-align:right !important}}p{color:var(--color);font-size:var(--font-size-scale-base);font-weight:var(--font-weight-regular);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-2x);margin-top:0}p a{text-decoration:underline}@media(min-width: 576px){p{font-size:var(--font-size-scale-up-01)}}a{--focus-offset: var(--spacing-scale-half)}a:focus{outline:none}a.focus-visible,a:focus-visible{outline-color:var(--focus);outline-offset:var(--focus-offset);outline-style:var(--focus-style);outline-width:var(--focus-width)}a:not(:disabled):hover{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--hover)), rgba(var(--interactive-rgb), var(--hover)))}a:not(:disabled):active{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--pressed)), rgba(var(--interactive-rgb), var(--pressed)))}a{color:var(--interactive);text-decoration:none}.main-content a{text-decoration:underline}button{cursor:pointer}img{max-width:100%;vertical-align:middle}h2,.h2{color:var(--color);font-size:var(--font-size-scale-up-03);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-2xh);margin-top:var(--spacing-scale-3xh);padding-bottom:var(--spacing-scale-2xh)}@media(min-width: 576px){.h2,h2{font-size:var(--font-size-scale-up-05);font-weight:var(--font-weight-regular)}}ul,ol{margin-bottom:var(--spacing-scale-2x);margin-top:0;padding:0 0 0 var(--spacing-scale-5x)}table{--table-background: var(--background);--table-color: var(--color);--table-border-color: var(--gray-20);--table-border-style: solid;--table-border-width: 1px;--table-hover: var(--color-rgb);--table-padding: var(--spacing-scale-3x);--table-font-weight: var(--font-weight-medium);--table-th-background: var(--background-alternative);--table-th-font-weight: var(--font-weight-semi-bold);--table-row-size: var(--spacing-scale-2x);border-collapse:collapse;width:100%}tr.selected,tr.is-selected{--color: var(--color-dark);--color-rgb: var(--color-dark-rgb);--text-color: var(--color-dark);--interactive: var(--interactive-dark);--interactive-rgb: var(--interactive-dark-rgb);--visited: var(--visited-dark);--hover: var(--hover-dark);--pressed: var(--pressed-dark);--focus-color: var(--focus-color-dark);--focus: var(--focus-color-dark)}label,.label{color:var(--color);font-size:var(--font-size-scale-base);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-half)}fieldset,.fieldset{border:var(--surface-width-none);margin-bottom:var(--spacing-scale-5x);margin-top:0;padding:0}legend,.legend{color:var(--color);font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-2x);margin-top:var(--spacing-scale-2x)}::placeholder,.placeholder{color:var(--color-light);font-size:var(--font-size-scale-base);font-style:italic;font-weight:var(--font-weight-regular);line-height:var(--font-line-height-medium);margin-bottom:var(--spacing-scale-half);margin-top:var(--spacing-scale-half);opacity:1}input,textarea,.input{color:var(--color-light);font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-medium);line-height:var(--font-line-height-low);margin-bottom:var(--spacing-scale-half)}code,.code{background:var(--gray-5);border-radius:4px;color:var(--gray-80);display:inline-block;font-family:monospace;font-size:var(--font-size-scale-base);font-weight:var(--font-weight-medium);line-height:var(--font-line-height-low);padding:var(--spacing-scale-half)}pre,.pre{background:var(--gray-5);margin:var(--spacing-scale-2x) 0 var(--spacing-scale-4x);padding:var(--spacing-scale-2x)}pre code,.pre code{display:inline;padding:0}*[data-toggle=collapse]:not(:disabled):hover{background-image:linear-gradient(rgba(var(--interactive-rgb), var(--hover)), rgba(var(--interactive-rgb), var(--hover)))}*[data-toggle=collapse]:focus{outline:none}*[data-toggle=collapse].focus-visible,*[data-toggle=collapse]:focus-visible{outline-color:var(--focus);outline-offset:var(--focus-offset);outline-style:var(--focus-style);outline-width:var(--focus-width)}@media(prefers-reduced-motion: reduce){:host,:host::before,:host::after,:host *,:host *::before,:host *::after{animation:none !important;scroll-behavior:auto !important;transition:none !important}}:host-context([data-wbc-reduced-motion=true])::before,:host-context([data-wbc-reduced-motion=true])::after,:host-context([data-wbc-reduced-motion=true]) *,:host-context([data-wbc-reduced-motion=true]) *::before,:host-context([data-wbc-reduced-motion=true]) *::after{animation:none !important;scroll-behavior:auto !important;transition:none !important}:host{display:block;width:100%;max-width:144px;height:116px;margin-inline:auto;box-sizing:border-box}.br-time-picker{display:flex;justify-content:center;align-items:center;width:100%;height:100%;box-sizing:border-box}.timer{display:flex;flex-direction:row;justify-content:center;align-items:center;gap:var(--spacing-scale-sm);width:100%;box-sizing:border-box}.time-field{display:flex;flex-direction:column;align-items:center;justify-content:flex-end}.time-field label{font-size:var(--font-size-scale-down-01);color:var(--gray-70);margin-bottom:4px}.time-field input{width:var(--spacing-scale-6x);height:var(--spacing-scale-6x);padding:4px;font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);text-align:center;border-color:var(--border-color-alternative);border-radius:var(--surface-rounder-sm);border-style:var(--border-style);border-width:var(--border-width)}.time-field input:hover{background:linear-gradient(rgb(var(--color-rgb), var(--hover)), rgb(var(--color-rgb), var(--hover)))}.time-separator{display:inline-block;font-size:var(--font-size-scale-up-01);font-weight:var(--font-weight-semi-bold);color:var(--gray-70);align-self:center;line-height:1;padding:0 var(--spacing-scale-base)}

package/dist/collection/components/datetime-picker/time-picker/time-picker.js

@@ -12,13 +12,27 @@ import { subHours } from "date-fns/subHours";
 import { subMinutes } from "date-fns/subMinutes";
 import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../../shared/utils/event";
+import { reportInvalidPropValue } from "../../../shared/utils/prop-warning";
 import { resolveSsrLocalDate } from "../../../shared/utils/ssr-date";
 import { NAVIGATION_ACTION } from "../datetime-picker-constants";
 import { INPUT_TIME_TYPE } from "./time-picker-constants";
 /**
- * ## Design System
+ * Subcomponente de seleção de horários do GovBR-DS, desenvolvido para permitir a escolha intuitiva de horas e minutos.
  *
- * 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/time-picker?tab=designer).
+ * ### 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.
+ *
+ * ### 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
  *
  * @part container - Parte para o container base do seletor de horários.
  * @part timer - Container para o grupo de hora e minuto.
@@ -30,9 +44,27 @@ export class TimePicker {
     constructor() {
         /** Mantém o rascunho digitado por campo para evitar aplicar valor parcial prematuramente. */
         this.timeDraft = {};
-        /** Data de referência usada para exibir e ajustar hora e minuto. */
+        /**
+         * 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);
+         * ```
+         */
         this.referenceDate = new Date();
-        /** Valor atualmente selecionado pelo usuário, ou `null` quando vazio. */
+        /**
+         * 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);
+         * ```
+         */
         this.value = null;
         /** Desabilita todos os controles de navegação e edição de hora/minuto. */
         this.disabled = false;
@@ -89,9 +121,31 @@ export class TimePicker {
             this.timeDraft = { ...this.timeDraft, [type]: value };
         };
     }
+    handleReferenceDateChange(newValue) {
+        const normalizedReferenceDate = this.normalizeDateProp(newValue, 'referenceDate', new Date());
+        const receivedTime = newValue instanceof Date && !Number.isNaN(newValue.getTime()) ? newValue.getTime() : null;
+        if (normalizedReferenceDate.getTime() !== receivedTime)
+            this.referenceDate = normalizedReferenceDate;
+    }
+    handleValueChange(newValue) {
+        const normalizedValue = this.normalizeDateProp(newValue, 'value', null);
+        const receivedTime = newValue instanceof Date && !Number.isNaN(newValue.getTime()) ? newValue.getTime() : null;
+        if ((normalizedValue?.getTime() ?? null) !== receivedTime)
+            this.value = normalizedValue;
+    }
     componentWillLoad() {
+        this.referenceDate = this.normalizeDateProp(this.referenceDate, 'referenceDate', new Date());
+        this.value = this.normalizeDateProp(this.value, 'value', null);
         this.referenceDate = resolveSsrLocalDate(this.el, this.referenceDate);
     }
+    normalizeDateProp(value, propertyName, fallback) {
+        if (value === null && fallback === null)
+            return null;
+        if (value instanceof Date && !Number.isNaN(value.getTime()))
+            return toDate(value);
+        reportInvalidPropValue(this.el, propertyName, value, 'Informe uma instância de Date válida.', `Aplicando fallback ${fallback === null ? 'null' : 'new Date()'}.`);
+        return fallback === null ? null : toDate(fallback);
+    }
     /**
      * Emite o estado consolidado para manter hora, minuto e data sincronizados.
      *
@@ -338,7 +392,7 @@ export class TimePicker {
         return (h("div", { class: "time-field", part: "field" }, this.renderNavigationButton(nextAction), h("input", { type: "text", inputmode: "numeric", maxLength: 2, value: this.timeDraft[type] ?? this.getTimeFieldValue(type), "aria-label": this.getTimeFieldAriaLabel(type), onInput: this.getTimeInputChangeHandler(type), onBlur: this.getTimeInputCommitHandler(type), onKeyDown: this.getTimeInputKeydownHandler(type), disabled: this.disabled, part: "input" }), this.renderNavigationButton(prevAction)));
     }
     render() {
-        return (h(Host, { key: '59ed47bc0825e6dc4c9568aefd5effe81d151525' }, h("div", { key: 'c8acccd2dfe328626346731c7c3f02984db60f4f', class: "br-time-picker", part: "container" }, this.renderTimePicker())));
+        return (h(Host, { key: 'c89413711940ab403593c5e7a61a7cce26e2fc98' }, h("div", { key: '98688b192d54e60106f8420dd932a709470b5379', class: "br-time-picker", part: "container" }, this.renderTimePicker())));
     }
     static get is() { return "br-time-picker"; }
     static get encapsulation() { return "shadow"; }
@@ -370,8 +424,11 @@ export class TimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Data de refer\u00EAncia usada para exibir e ajustar hora e minuto."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst timePicker = document.querySelector('br-time-picker');\ntimePicker.referenceDate = new Date(2026, 8, 7, 9);\n```"
+                        }],
+                    "text": "Data usada como refer\u00EAncia para a navega\u00E7\u00E3o de hora e minuto, sem representar necessariamente a sele\u00E7\u00E3o.\nRecebe uma inst\u00E2ncia de `Date` por property binding; valores inv\u00E1lidos usam a data atual."
                 },
                 "getter": false,
                 "setter": false,
@@ -393,8 +450,11 @@ export class TimePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Valor atualmente selecionado pelo usu\u00E1rio, ou `null` quando vazio."
+                    "tags": [{
+                            "name": "example",
+                            "text": "```js\nconst timePicker = document.querySelector('br-time-picker');\ntimePicker.value = new Date(2026, 8, 7, 14, 30);\n```"
+                        }],
+                    "text": "Data que cont\u00E9m a hora e o minuto efetivamente selecionados, ou `null` quando vazio.\nRecebe uma inst\u00E2ncia de `Date` por property binding; datas inv\u00E1lidas usam `null`."
                 },
                 "getter": false,
                 "setter": false,
@@ -453,4 +513,13 @@ export class TimePicker {
             }];
     }
     static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "referenceDate",
+                "methodName": "handleReferenceDateChange"
+            }, {
+                "propName": "value",
+                "methodName": "handleValueChange"
+            }];
+    }
 }