@govbr-ds/webcomponents 2.4.0 → 2.5.0

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

@@ -2,14 +2,16 @@
  * Construído por SERPRO
  * © https://serpro.gov.br/ - MIT License.
  */
-import { Host, h } from "@stencil/core";
+import { Fragment, Host, h } from "@stencil/core";
 import { addDays } from "date-fns/addDays";
 import { addMonths } from "date-fns/addMonths";
+import { addYears } from "date-fns/addYears";
 import { compareAsc } from "date-fns/compareAsc";
 import { eachDayOfInterval } from "date-fns/eachDayOfInterval";
 import { endOfMonth } from "date-fns/endOfMonth";
 import { endOfWeek } from "date-fns/endOfWeek";
 import { format } from "date-fns/format";
+import { getDaysInMonth } from "date-fns/getDaysInMonth";
 import { isAfter } from "date-fns/isAfter";
 import { isBefore } from "date-fns/isBefore";
 import { isSameDay } from "date-fns/isSameDay";
@@ -24,22 +26,30 @@ import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../../shared/utils/event";
 import { resolveSsrLocalDate } from "../../../shared/utils/ssr-date";
 import { DATETIME_PICKER_LOCALE, NAVIGATION_ACTION } from "../datetime-picker-constants";
-import { getMonthLabels, getWeekdayLabels, resolveDateFnsLocale } from "./date-picker-locale";
+import { getMonthLabels, getWeekdayFullNames, getWeekdayLabels, resolveDateFnsLocale } from "./date-picker-locale";
 import { normalizeLocale, normalizeWeekStartsOn } from "./date-picker-props-validation";
+/** Formato da chave local de dia usada em `data-date` e nas buscas de datas bloqueadas. */
+const DAY_KEY_FORMAT = 'yyyy-MM-dd';
 /**
- * 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.
+ * Calendário usado pelo `br-datetime-picker`. Também pode ser usado sozinho, quando a tela precisa de um calendário sempre visível.
  *
- * ### Papel na composição
+ * Usado sozinho, ele não tem campo de texto nem participa de formulário: a aplicação lê a seleção e cuida da validação.
  *
- * Exibe a grade mensal, 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.
+ * ```html
+ * <br-date-picker id="agenda"></br-date-picker>
+ * ```
  *
- * ### Regra de uso e relacionamento
+ * ```js
+ * const calendario = document.querySelector('#agenda');
+ * calendario.addEventListener('change', () => console.log(calendario.value));
+ * ```
  *
- * 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.
+ * - `value`: data selecionada (`Date`).
+ * - `referenceDate`: mês exibido.
+ * - `disabledDates`: datas que não podem ser escolhidas.
+ * - `selectionMode="range"`: seleção de intervalo, lida em `rangeValue`.
  *
- * 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).
+ * Para mudar o idioma, veja "Idiomas" na documentação do `br-datetime-picker`.
  *
  * @part container - Parte para o container base do calendário.
  * @part header - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).
@@ -116,6 +126,11 @@ export class DatePicker {
          * @internal
          */
         this.shouldFocusDate = false;
+        /**
+         * Chaves `yyyy-MM-dd` das datas bloqueadas, para consulta O(1) por célula.
+         * @internal
+         */
+        this.disabledDateKeysCache = new Set();
         /**
          * Handler de mudança do seletor de mês.
          * @param event - evento de mudança do `<select>`
@@ -131,8 +146,7 @@ export class DatePicker {
                 console.warn(`Índice de mês inválido selecionado: ${select.value}`);
                 return;
             }
-            const date = set(this.baseDate, { month: monthIndex, date: 1 });
-            this.emitDateStateChange(date);
+            this.navigateToMonth(set(this.baseDate, { month: monthIndex, date: 1 }));
         };
         /**
          * Trata cliques nos botões de navegação do calendário.
@@ -178,11 +192,7 @@ export class DatePicker {
                 console.warn(`Ano inválido digitado: ${input.value}`);
                 return;
             }
-            const date = set(this.baseDate, { year, month: this.baseDate.getMonth(), date: 1 });
-            const range = this.selectionMode === 'range' && this.rangeStart !== null && this.rangeEnd !== null
-                ? { start: this.rangeStart, end: this.rangeEnd }
-                : undefined;
-            this.emitDateStateChange(date, this.value, range);
+            this.navigateToMonth(set(this.baseDate, { year, month: this.baseDate.getMonth(), date: 1 }));
         };
         /**
          * Trata cliques com um handler compartilhado, lendo a data local da célula.
@@ -195,7 +205,7 @@ export class DatePicker {
                 console.warn('Célula de dia clicada sem data-date definido');
                 return;
             }
-            const date = parse(cell.dataset.date, 'yyyy-MM-dd', this.baseDate);
+            const date = parse(cell.dataset.date, DAY_KEY_FORMAT, this.baseDate);
             if (Number.isNaN(date.getTime())) {
                 console.warn(`Data inválida na célula de dia: ${cell.dataset.date}`);
                 return;
@@ -204,7 +214,10 @@ export class DatePicker {
         };
         /**
          * Gerencia navegação por teclado dentro da grade de dias.
-         * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown, Home/End, Enter/Space.
+         * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown (mês), Shift+PageUp/PageDown (ano),
+         * Home/End, Enter/Space.
+         *
+         * Permanece ativo em datas bloqueadas para que o foco não fique preso nelas; somente a seleção é ignorada.
          * @param event - evento de teclado
          * @returns void
          * @internal
@@ -234,7 +247,7 @@ export class DatePicker {
             if (targetEl && targetEl.dataset?.date !== undefined) {
                 const dateKey = targetEl.dataset.date;
                 event.preventDefault();
-                current = parse(dateKey, 'yyyy-MM-dd', new Date());
+                current = parse(dateKey, DAY_KEY_FORMAT, new Date());
             }
             else {
                 event.preventDefault();
@@ -261,10 +274,10 @@ export class DatePicker {
                     next = addDays(current, 7);
                     break;
                 case 'PageUp':
-                    next = addMonths(current, -1);
+                    next = event.shiftKey ? addYears(current, -1) : addMonths(current, -1);
                     break;
                 case 'PageDown':
-                    next = addMonths(current, 1);
+                    next = event.shiftKey ? addYears(current, 1) : addMonths(current, 1);
                     break;
                 case 'Home':
                     next = startOfWeek(current, { weekStartsOn: this.weekStartsOn });
@@ -297,10 +310,12 @@ export class DatePicker {
     /**
      * Observador para a prop `value` — atualiza `focusedDate` quando a seleção externa muda.
      * @param {Date | null} newValue - novo valor de seleção (ou `null`)
+     * @param {Date | null} oldValue - valor anterior da seleção
      * @internal
      */
-    handleValueChange(newValue) {
-        if (newValue !== null) {
+    handleValueChange(newValue, oldValue) {
+        // Reatribuições com o mesmo instante (ex.: navegação entre meses) não devem mover o foco.
+        if (newValue !== null && newValue.getTime() !== oldValue?.getTime()) {
             this.focusedDate = toDate(newValue);
         }
     }
@@ -341,7 +356,7 @@ export class DatePicker {
             return;
         this.shouldFocusDate = false;
         const normalizedDate = this.getNormalizedFocusedDate();
-        const dateKey = format(normalizedDate, 'yyyy-MM-dd');
+        const dateKey = format(normalizedDate, DAY_KEY_FORMAT);
         const cell = this.el.shadowRoot?.querySelector(`[data-date="${dateKey}"]`);
         cell?.focus();
     }
@@ -461,11 +476,7 @@ export class DatePicker {
         if (this.disabled) {
             return;
         }
-        const date = set(subMonths(this.baseDate, 1), { date: 1 });
-        const range = this.selectionMode === 'range' && this.rangeStart !== null && this.rangeEnd !== null
-            ? { start: this.rangeStart, end: this.rangeEnd }
-            : undefined;
-        this.emitDateStateChange(date, this.value, range);
+        this.navigateToMonth(set(subMonths(this.baseDate, 1), { date: 1 }));
     }
     /**
      * Incrementa o mês exibido e preserva seleção/intervalo quando aplicável.
@@ -475,11 +486,28 @@ export class DatePicker {
         if (this.disabled) {
             return;
         }
-        const date = set(addMonths(this.baseDate, 1), { date: 1 });
+        this.navigateToMonth(set(addMonths(this.baseDate, 1), { date: 1 }));
+    }
+    /**
+     * Exibe o mês informado preservando a seleção, o intervalo completo e o dia em foco.
+     *
+     * O foco vai para a data selecionada quando ela pertence ao novo mês; caso
+     * contrário, mantém o mesmo dia do mês, limitado ao último dia disponível
+     * (ex.: 31/01 → 28/02).
+     *
+     * @param monthDate - primeiro dia do mês de destino
+     * @internal
+     */
+    navigateToMonth(monthDate) {
+        const value = this.value;
+        this.focusedDate =
+            value !== null && isSameMonth(value, monthDate)
+                ? value
+                : set(monthDate, { date: Math.min(this.focusedDate.getDate(), getDaysInMonth(monthDate)) });
         const range = this.selectionMode === 'range' && this.rangeStart !== null && this.rangeEnd !== null
             ? { start: this.rangeStart, end: this.rangeEnd }
             : undefined;
-        this.emitDateStateChange(date, this.value, range);
+        this.emitDateStateChange(monthDate, value, range);
     }
     /**
      * Verifica se uma data está indisponível para seleção.
@@ -488,7 +516,22 @@ export class DatePicker {
      * @internal
      */
     isDateDisabled(date) {
-        return this.disabledDates.some((disabledDate) => isSameDay(disabledDate, date));
+        return this.disabledDateKeys.has(format(date, DAY_KEY_FORMAT));
+    }
+    /**
+     * Chaves locais das datas bloqueadas, recalculadas somente quando `disabledDates` é substituída.
+     * Entradas inválidas são ignoradas.
+     * @internal
+     */
+    get disabledDateKeys() {
+        if (this.disabledDateKeysSource !== this.disabledDates) {
+            this.disabledDateKeysSource = this.disabledDates;
+            this.disabledDateKeysCache = new Set((this.disabledDates ?? [])
+                .map((disabledDate) => toDate(disabledDate))
+                .filter((disabledDate) => !Number.isNaN(disabledDate.getTime()))
+                .map((disabledDate) => format(disabledDate, DAY_KEY_FORMAT)));
+        }
+        return this.disabledDateKeysCache;
     }
     /**
      * Data base usada para todos os cálculos de calendário.
@@ -510,25 +553,19 @@ export class DatePicker {
     /**
      * Constrói o rótulo acessível da célula de dia, incluindo estado (selecionado/início/fim).
      * @param date - dia representado pela célula
+     * @param state - estado já calculado da célula
      * @returns string para `aria-label`
      * @internal
      */
-    getDayCellAriaLabel(date) {
+    getDayCellAriaLabel(date, state) {
         const fullDate = format(date, "d 'de' MMMM 'de' yyyy", { locale: this.dateFnsLocale });
-        const isSelected = this.selectionMode === 'single' && this.value !== null && isSameDay(date, this.value);
-        const isRangeStart = this.selectionMode === 'range' && this.rangeStart !== null && isSameDay(date, this.rangeStart);
-        const isRangeEnd = this.selectionMode === 'range' && this.rangeEnd !== null && isSameDay(date, this.rangeEnd);
-        const isBetween = this.selectionMode === 'range' &&
-            this.rangeStart !== null &&
-            this.rangeEnd !== null &&
-            this.isDateBetweenRange(date, this.rangeStart, this.rangeEnd);
-        if (isSelected)
+        if (state.isSelected)
             return `${fullDate}, selecionado`;
-        if (isRangeStart)
+        if (state.isRangeStart)
             return `${fullDate}, início do intervalo`;
-        if (isRangeEnd)
+        if (state.isRangeEnd)
             return `${fullDate}, fim do intervalo`;
-        if (isBetween)
+        if (state.isInRange)
             return `${fullDate}, no intervalo selecionado`;
         return fullDate;
     }
@@ -540,28 +577,41 @@ export class DatePicker {
         return resolveDateFnsLocale(this.locale);
     }
     /**
-     * Calcula o mapa de classes CSS da célula do dia.
+     * Calcula uma única vez o estado de seleção da célula, compartilhado por classes, ARIA e foco.
      * @param date - dia da grade
      * @param today - instante atual compartilhado pela renderização da grade
+     * @returns estado da célula
+     * @internal
+     */
+    getDayCellState(date, today) {
+        const isRange = this.selectionMode === 'range';
+        const { value, rangeStart, rangeEnd } = this;
+        return {
+            isToday: isSameDay(date, today),
+            isOutsideMonth: !isSameMonth(date, this.baseDate),
+            isSelected: !isRange && value !== null && isSameDay(date, value),
+            isRangeStart: isRange && rangeStart !== null && isSameDay(date, rangeStart),
+            isRangeEnd: isRange && rangeEnd !== null && isSameDay(date, rangeEnd),
+            isInRange: isRange && rangeStart !== null && rangeEnd !== null && this.isDateBetweenRange(date, rangeStart, rangeEnd),
+        };
+    }
+    /**
+     * Calcula o mapa de classes CSS da célula do dia.
+     * @param state - estado já calculado da célula
+     * @param disabled - indica se a célula está bloqueada
      * @returns mapa de classes booleanas
      * @internal
      */
-    getDayCssClasses(date, today) {
-        const selected = this.value;
-        const rangeStart = this.rangeStart;
-        const rangeEnd = this.rangeEnd;
-        const hasRange = rangeStart !== null && rangeEnd !== null;
-        const isRangeStart = rangeStart !== null && isSameDay(date, rangeStart);
-        const isRangeEnd = rangeEnd !== null && isSameDay(date, rangeEnd);
-        const isBetweenRange = hasRange && this.isDateBetweenRange(date, rangeStart, rangeEnd);
+    getDayCssClasses(state, disabled) {
         return {
             day: true,
-            'outside-month': !isSameMonth(date, this.baseDate),
-            today: isSameDay(date, today),
-            selected: this.selectionMode === 'single' && selected !== null && isSameDay(date, selected),
-            'range-start': this.selectionMode === 'range' && isRangeStart,
-            'range-end': this.selectionMode === 'range' && isRangeEnd,
-            'in-range': this.selectionMode === 'range' && isBetweenRange,
+            'outside-month': state.isOutsideMonth,
+            today: state.isToday,
+            selected: state.isSelected,
+            'range-start': state.isRangeStart,
+            'range-end': state.isRangeEnd,
+            'in-range': state.isInRange,
+            disabled,
         };
     }
     /**
@@ -705,7 +755,7 @@ export class DatePicker {
      */
     renderCalendar() {
         const monthLabel = format(this.baseDate, "MMMM 'de' yyyy", { locale: this.dateFnsLocale });
-        return (h("div", { class: "calendar", role: "grid", "aria-label": `Calendário de ${monthLabel}`, part: "calendar" }, this.renderWeekdays(), this.renderMonthGrid()));
+        return (h(Fragment, null, h("div", { class: "visually-hidden", "aria-live": "polite" }, monthLabel), h("div", { class: "calendar", role: "grid", "aria-label": `Calendário de ${monthLabel}`, part: "calendar" }, this.renderWeekdays(), this.renderMonthGrid())));
     }
     /**
      * Renderiza os rótulos dos dias da semana.
@@ -714,7 +764,8 @@ export class DatePicker {
      */
     renderWeekdays() {
         const labels = this.getWeekdayLabels();
-        return (h("div", { class: "weekdays", role: "row", tabIndex: -1, part: "weekdays" }, labels.map((label, index) => (h("div", { key: `weekday-${index}`, class: "weekday", role: "columnheader", tabIndex: -1, "aria-label": label, part: "weekday" }, label)))));
+        const fullNames = getWeekdayFullNames(this.locale, this.weekStartsOn);
+        return (h("div", { class: "weekdays", role: "row", tabIndex: -1, part: "weekdays" }, labels.map((label, index) => (h("div", { key: `weekday-${index}`, class: "weekday", role: "columnheader", tabIndex: -1, "aria-label": fullNames[index], part: "weekday" }, label)))));
     }
     /**
      * Renderiza a grade de dias do mês atual.
@@ -727,7 +778,7 @@ export class DatePicker {
         const normalizedFocusedDate = this.getNormalizedFocusedDate(interval);
         const today = new Date();
         const weeks = Array.from({ length: Math.ceil(dates.length / 7) }, (_, index) => dates.slice(index * 7, index * 7 + 7));
-        return (h("div", { class: "monthdays", role: "rowgroup", part: "grid" }, weeks.map((week) => (h("div", { key: `week-${format(week[0], 'yyyy-MM-dd')}`, class: "week", role: "row", tabIndex: -1 }, week.map((date) => this.renderDayCell(date, normalizedFocusedDate, today)))))));
+        return (h("div", { class: "monthdays", role: "rowgroup", part: "grid" }, weeks.map((week) => (h("div", { key: `week-${format(week[0], DAY_KEY_FORMAT)}`, class: "week", role: "row", tabIndex: -1 }, week.map((date) => this.renderDayCell(date, normalizedFocusedDate, today)))))));
     }
     /**
      * Renderiza uma célula de dia com estado visual apropriado.
@@ -738,17 +789,15 @@ export class DatePicker {
      * @internal
      */
     renderDayCell(date, normalizedFocusedDate, today) {
-        const dateKey = format(date, 'yyyy-MM-dd');
-        const disabled = this.disabled || this.isDateDisabled(date);
-        const isSelected = this.selectionMode === 'single' && this.value !== null && isSameDay(date, this.value);
-        const isRangeStart = this.selectionMode === 'range' && this.rangeStart !== null && isSameDay(date, this.rangeStart);
-        const isRangeEnd = this.selectionMode === 'range' && this.rangeEnd !== null && isSameDay(date, this.rangeEnd);
-        const isActiveDay = isSelected || isRangeStart || isRangeEnd;
+        const dateKey = format(date, DAY_KEY_FORMAT);
+        const disabled = this.disabled || this.disabledDateKeys.has(dateKey);
+        const state = this.getDayCellState(date, today);
+        const isActiveDay = state.isSelected || state.isRangeStart || state.isRangeEnd;
         const isFocused = isSameDay(date, normalizedFocusedDate);
-        return (h("div", { key: dateKey, role: "gridcell", tabIndex: this.disabled ? undefined : isFocused ? 0 : -1, "data-date": dateKey, class: { ...this.getDayCssClasses(date, today), disabled }, onClick: disabled ? undefined : this.handleDayCellClick, onKeyDown: disabled ? undefined : this.handleGridKeydown, "aria-label": this.getDayCellAriaLabel(date), "aria-selected": isActiveDay ? 'true' : 'false', "aria-disabled": disabled ? 'true' : null, part: "day" }, this.getDayWithLeadingZero(date)));
+        return (h("div", { key: dateKey, role: "gridcell", tabIndex: this.disabled ? undefined : isFocused ? 0 : -1, "data-date": dateKey, class: this.getDayCssClasses(state, disabled), onClick: disabled ? undefined : this.handleDayCellClick, onKeyDown: this.handleGridKeydown, "aria-label": this.getDayCellAriaLabel(date, state), "aria-selected": isActiveDay ? 'true' : 'false', "aria-current": state.isToday ? 'date' : null, "aria-disabled": disabled ? 'true' : null, part: "day" }, this.getDayWithLeadingZero(date)));
     }
     render() {
-        return (h(Host, { key: '652b18891338dd9d009e87fb2383dc3c1c78c6ee' }, h("div", { key: '3c441b0df40d69767ee4c3e8166e9403988def5d', class: "br-date-picker", part: "container" }, this.renderCalendarHeader(), this.renderCalendar())));
+        return (h(Host, { key: 'd909c9c84061f6b456a0350e2ab3fe6e50cc5d83' }, h("div", { key: 'aba7fc5f0b7bce2a9aa2d95bae9897f138dd8146', class: "br-date-picker", part: "container" }, this.renderCalendarHeader(), this.renderCalendar())));
     }
     static get is() { return "br-date-picker"; }
     static get encapsulation() { return "shadow"; }

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

@@ -17,19 +17,9 @@ import { DATETIME_RANGE_ORDER_MESSAGE } from "../datetime-picker-constants";
 import { INPUT_FORMAT_CONFIG } from "./datetime-input-constants";
 import { normalizeDatetimeInputMode, normalizeDatetimeInputReferenceDate, normalizeDatetimeInputValue, } from "./datetime-input-props-validation";
 /**
- * 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.
+ * Campo de texto com máscara usado pelo `br-datetime-picker`. Interpreta a data ou a hora digitada e abre o calendário pelo botão do campo.
  *
- * ### Papel na composição
- *
- * 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
- *
- * 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).
+ * É criado pelo `br-datetime-picker`; não é preciso declará-lo. Para um campo de data em formulário, use o `br-datetime-picker`.
  *
  * @see https://www.gov.br/ds/components/datetime?tab=designer
  * @part container - Container do campo.
@@ -721,7 +711,7 @@ export class DatetimeInput {
      * Renderização principal do componente.
      */
     render() {
-        return (h(Host, { key: '40033b7b73bd1760cf07c5b4797a86e918fde54b' }, h("div", { key: '31e968efbb7a6f43acb8a67fb225d6e0159af7f9', class: this.getCssClassMap(), part: "container" }, this.renderInputField())));
+        return (h(Host, { key: 'dd5b4fa7df2b33edc9c262b4d7cf0d161ae195b8' }, h("div", { key: '83035393364d795eeb46f7a9f03309e33d53aa42', class: this.getCssClassMap(), part: "container" }, this.renderInputField())));
     }
     static get is() { return "br-datetime-input"; }
     static get encapsulation() { return "shadow"; }

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

@@ -17,42 +17,38 @@ import { DATETIME_PICKER_LOCALE, DATETIME_PICKER_MODE, DATETIME_RANGE_ORDER_MESS
 import { hasDatetimePickerMissingValue, parseDatetimePickerSerializedRange, parseDatetimePickerSerializedValue, serializeDatetimePickerFormValue, } from "./datetime-picker-form-associated";
 import { normalizeDatetimePickerDisabledDates, normalizeDatetimePickerInitialMoment, normalizeDatetimePickerMode, normalizeDatetimePickerSelectionMode, normalizeDatetimePickerWeekStartsOn, } from "./datetime-picker-props-validation";
 /**
- * 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.
+ * O `br-datetime-picker` é um campo para informar data, hora ou data e hora. A pessoa pode digitar ou escolher no calendário e nos controles de horário.
  *
- * ### Para que serve
+ * Escolha o tipo em `mode`: `date`, `time` ou `datetime`. Para início e fim, use `selection-mode="range"`.
  *
- * - 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`.
+ * ```html
+ * <br-datetime-picker mode="date" name="nascimento" required></br-datetime-picker>
  *
- * ### Quando utilizar
+ * <br-datetime-picker mode="date" selection-mode="range" name="periodo"></br-datetime-picker>
+ * ```
  *
- * - 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.
+ * ### Ler o valor
  *
- * ### Composição e Subcomponentes
+ * | Onde | Formato |
+ * | --- | --- |
+ * | `value` | `Date` (ou `null`) |
+ * | `rangeValue` | `{ start, end }` com `Date` |
+ * | `serialized-value` e envio do formulário | `2026-05-20` (data), `14:30` (hora), `2026-05-20T14:30:00-03:00` (data e hora), `início/fim` (intervalo) |
  *
- * | Componente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `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`. |
+ * Atribua valores do tipo `Date` pelo JavaScript (`picker.value = new Date()`), não por atributo. Para restringir datas, use `min`, `max` e `disabled-dates`.
  *
- * O slot `feedback` recebe conteúdo declarativo de validação, normalmente um `br-message`; não substitui os seletores internos.
+ * ### Quando usar
  *
- * ### Como os subcomponentes se relacionam
+ * - Formulários que pedem uma data, um horário ou um período.
  *
- * 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.
+ * ### Quando evitar
  *
- * `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.
+ * - Para só exibir uma data: use texto formatado.
+ * - Para escolher várias datas soltas: o componente aceita uma data ou um intervalo.
  *
- * 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`.
+ * O calendário (`br-date-picker`), os controles de horário (`br-time-picker`) e o campo de texto (`br-datetime-input`) são criados pelo próprio componente; não é preciso declará-los.
  *
- * 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).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/datetimepicker?tab=designer).
  *
  * @category Formulários
  * @status stable
@@ -1082,7 +1078,7 @@ export class DatetimePicker {
         }
         this.restoreSingleStateFromSerialized(serializedValue);
     }
-    /** Atualiza os nomes canônicos sem emitir eventos adicionais ou criar ciclos de watchers. */
+    /** Atualiza os nomes padrão sem emitir eventos adicionais ou criar ciclos de watchers. */
     syncCanonicalValues() {
         const nextSerializedValue = this.getSerializedValue();
         const nextValueAsDate = this.cloneDate(this.value);
@@ -1494,7 +1490,7 @@ export class DatetimePicker {
             this.inputValidationMessage ||
             this.validatorMessage ||
             (this.inputValidationPending ? '' : this.getRangeOrderValidationMessage());
-        return (h(Host, { key: '0640504e844713daaf31d7c8a34b96fb48bcf499', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || validationMessage ? this.feedbackId : null, "aria-errormessage": validationMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '7512ed8a4437a99d6d0702351af659bfa1d270b0', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: '80a8d3a717ceacc4dfb6bd0ac4850b61e3b2d311', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !validationMessage }, h("slot", { key: '41a8e4fad5edaa3729d63b7ee469f248a53129a1', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && validationMessage ? (h("br-message", { state: "danger", "attr:message": validationMessage, feedback: true })) : null)));
+        return (h(Host, { key: '84fb00b49ddc94c38ccb60d6473008ef6f966c0a', onKeyDown: this.handlePickerKeydown, "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || validationMessage ? this.feedbackId : null, "aria-errormessage": validationMessage || this.hasFeedbackSlot ? this.feedbackId : null }, h("div", { key: '4c16fee0aa4a44ceb5b4097a3189ab9a427f00a3', class: this.getCssClassMap(), part: "container" }, this.renderInputField(), this.renderPickerContent()), h("div", { key: '1906aed19809ab4a5da12bef5d5a71fbe807be1b', id: this.feedbackId, part: "feedback", hidden: !this.hasFeedbackSlot && !validationMessage }, h("slot", { key: 'b3544c63edfcaf84f48f91e4105874ff7ebe4b01', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && validationMessage ? (h("br-message", { state: "danger", "attr:message": validationMessage, feedback: true })) : null)));
     }
     static get is() { return "br-datetime-picker"; }
     static get encapsulation() { return "shadow"; }
@@ -2053,7 +2049,7 @@ export class DatetimePicker {
                             "name": "type",
                             "text": "{CustomEvent<DatetimePickerChangeDetail>}"
                         }],
-                    "text": "Evento p\u00FAblico can\u00F4nico emitido quando a sele\u00E7\u00E3o muda.\n\nPayload (`DatetimePickerChangeDetail`):\n- `mode`: DatetimePickerMode \u2014 modo atual do componente (`date` | `time` | `datetime`).\n- `selectionMode`: DatetimePickerSelectionMode \u2014 `single` ou `range`.\n- `value`: Date | null | DatetimePickerDateRange \u2014 sele\u00E7\u00E3o atual (tipo depende de `selectionMode`).\n- `serializedValue`: string | undefined \u2014 representa\u00E7\u00E3o serializada para integra\u00E7\u00E3o com formul\u00E1rios."
+                    "text": "Evento emitido quando a sele\u00E7\u00E3o muda.\n\nPayload (`DatetimePickerChangeDetail`):\n- `mode`: DatetimePickerMode \u2014 modo atual do componente (`date` | `time` | `datetime`).\n- `selectionMode`: DatetimePickerSelectionMode \u2014 `single` ou `range`.\n- `value`: Date | null | DatetimePickerDateRange \u2014 sele\u00E7\u00E3o atual (tipo depende de `selectionMode`).\n- `serializedValue`: string | undefined \u2014 representa\u00E7\u00E3o serializada para integra\u00E7\u00E3o com formul\u00E1rios."
                 },
                 "complexType": {
                     "original": "DatetimePickerChangeDetail",

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

@@ -16,19 +16,9 @@ import { resolveSsrLocalDate } from "../../../shared/utils/ssr-date";
 import { NAVIGATION_ACTION } from "../datetime-picker-constants";
 import { INPUT_TIME_TYPE } from "./time-picker-constants";
 /**
- * O `br-time-picker` é o subcomponente de ajuste de horas e minutos do `br-datetime-picker`.
+ * Controles de hora e minuto usados pelo `br-datetime-picker`. Em um intervalo, o componente cria um controle para o início e outro para o fim.
  *
- * ### Papel na composição
- *
- * 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
- *
- * 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).
+ * Para um campo de horário em formulário, use `<br-datetime-picker mode="time">`. Usado sozinho, ele não participa de formulário: leia o horário em `value` e trate a validação na aplicação.
  *
  * @part container - Container base do seletor de horários.
  * @part timer - Grupo que contém os campos de hora e minuto.
@@ -45,7 +35,7 @@ export class TimePicker {
          */
         this.referenceDate = new Date();
         /**
-         * Valor canônico selecionado pelo usuário.
+         * Valor selecionado pelo usuário.
          *
          * @default null
          */
@@ -440,7 +430,7 @@ export class TimePicker {
      * @returns {JSX.Element}
      */
     render() {
-        return (h(Host, { key: '1957a00098311a26b250bad62c885fc636072b30' }, h("div", { key: '0dd334340ba7da6cbc53d72183b862770d275856', class: "br-time-picker", part: "container" }, this.renderTimePicker())));
+        return (h(Host, { key: 'e81125092811d06b37cdd61d562998de83020880' }, h("div", { key: 'df218ea0cc8424f55ed0689e5479ef47cdbee74c', class: "br-time-picker", part: "container" }, this.renderTimePicker())));
     }
     static get is() { return "br-time-picker"; }
     static get encapsulation() { return "shadow"; }
@@ -502,7 +492,7 @@ export class TimePicker {
                             "name": "default",
                             "text": "null"
                         }],
-                    "text": "Valor can\u00F4nico selecionado pelo usu\u00E1rio."
+                    "text": "Valor selecionado pelo usu\u00E1rio."
                 },
                 "getter": false,
                 "setter": false,

package/dist/collection/components/divider/divider.js

@@ -12,31 +12,27 @@ const DIVIDER_BORDER_STYLES = ['dashed', 'solid'];
 const DIVIDER_COLOR_MODES = ['light', 'dark'];
 const DIVIDER_ALIGNS = ['start', 'center', 'end'];
 /**
- * O componente `br-divider` é o elemento separador visual e semântico do GovBR-DS, utilizado para demarcar limites claros entre seções, listas de conteúdos ou áreas temáticas da página.
+ * O `br-divider` é uma linha que separa seções ou grupos de conteúdo. Pode ser horizontal ou vertical e ter um texto no meio.
  *
- * ### Para que serve
+ * ```html
+ * <br-divider></br-divider>
  *
- * - **Separação visual estruturada:** Cria linhas divisórias sutis horizontais ou verticais para organizar blocos de informação com espaçamentos padronizados.
- * - **Rotulação intermediária:** Permite incluir texto (ex.: "ou"), ícones ou outros elementos centralizados ao longo da linha divisória através do slot padrão.
- * - **Variações visuais:** Suporta estilos contínuos, tracejados (`dashed`) e diferentes densidades para se adequar ao leiaute.
+ * <br-divider>ou</br-divider>
  *
- * ### Quando utilizar
+ * <br-divider orientation="vertical" thickness="medium" border-style="dashed"></br-divider>
+ * ```
  *
- * - **Utilize quando:**
- *   - Houver necessidade de indicar explicitamente o término de um bloco temático e o início de outro.
- *   - Separar alternativas com um divisor textual (ex.: "Entrar com conta Gov.BR" --- ou --- "Entrar com certificado digital").
- *   - Dividir colunas de rodapés, menus laterais ou cabeçalhos.
- * - **Evite e prefira outro componente quando:**
- *   - Os espaçamentos em branco (margens e paddings) já forem suficientes para garantir a percepção de separação sem sobrecarregar visualmente a tela.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Marcar o fim de um bloco e o início de outro.
+ * - Separar alternativas, como "Entrar com gov.br" ou "Entrar com certificado digital".
  *
- * O `br-divider` é um componente autônomo e de apresentação:
- * - `default`: Slot opcional para texto ou elemento centralizado intercalado na linha do divisor.
+ * ### Quando evitar
  *
- * 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/divider?tab=designer).
+ * - Quando o espaço em branco já separa bem o conteúdo.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/divider?tab=designer).
  *
-
  * @category Layout, Estrutura
  * @status stable
  * @slot default - Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados).
@@ -273,7 +269,7 @@ export class Divider {
         return h("hr", { class: this.getCssClassMap(), part: "divider" });
     }
     render() {
-        return (h(Host, { key: '95bf9293cff4f5a5fe90f1e621151282127cd733', class: this.effectiveOrientation === 'vertical' ? 'vertical' : undefined }, this.hasContent
+        return (h(Host, { key: '5bb8579f8b756513982809583bfb73068deb3c00', class: this.effectiveOrientation === 'vertical' ? 'vertical' : undefined }, this.hasContent
             ? this.renderDefaultSlotDivider()
             : [
                 h("slot", { onSlotchange: (event) => (this.hasContent = hasAssignedSlotContent(event.currentTarget)) }),
@@ -430,7 +426,7 @@ export class Divider {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Esquema de cor can\u00F4nico. Quando informado, tem preced\u00EAncia sobre `isDarkMode`; valores inv\u00E1lidos usam `light`."
+                    "text": "Esquema de cor padr\u00E3o. Quando informado, tem preced\u00EAncia sobre `isDarkMode`; valores inv\u00E1lidos usam `light`."
                 },
                 "getter": false,
                 "setter": false,