@govbr-ds/webcomponents 2.3.0 → 2.5.0

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

@@ -2,49 +2,54 @@
  * 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";
 import { isSameMonth } from "date-fns/isSameMonth";
 import { parse } from "date-fns/parse";
 import { set } from "date-fns/set";
+import { startOfDay } from "date-fns/startOfDay";
 import { startOfMonth } from "date-fns/startOfMonth";
 import { startOfWeek } from "date-fns/startOfWeek";
 import { subMonths } from "date-fns/subMonths";
 import { toDate } from "date-fns/toDate";
 import { dispatchNativeFormEvent } from "../../../shared/utils/event";
-import { reportInvalidPropValue } from "../../../shared/utils/prop-warning";
-import { resolveAllowedPropValue } from "../../../shared/utils/props";
 import { resolveSsrLocalDate } from "../../../shared/utils/ssr-date";
 import { DATETIME_PICKER_LOCALE, NAVIGATION_ACTION } from "../datetime-picker-constants";
-import { isValidDatetimePickerDateRange, normalizeDatetimePickerDisabledDates, } from "../datetime-picker-props-validation";
-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';
 /**
- * Subcomponente de calendário visual do GovBR-DS, projetado para seleção interativa de datas individuais ou intervalos.
+ * Calendário usado pelo `br-datetime-picker`. Também pode ser usado sozinho, quando a tela precisa de um calendário sempre visível.
  *
- * ### Papel na composição
+ * Usado sozinho, ele não tem campo de texto nem participa de formulário: a aplicação lê a seleção e cuida da validação.
  *
- * - Exibe a grade mensal navegável com suporte a seleção de dia, navegação entre meses e anos, e destaque para a data atual e intervalos.
- * - Implementa navegação acessível por teclado WAI-ARIA Grid (setas direcionais para dias e semanas).
+ * ```html
+ * <br-date-picker id="agenda"></br-date-picker>
+ * ```
  *
- * ### Regra de uso e relacionamento
+ * ```js
+ * const calendario = document.querySelector('#agenda');
+ * calendario.addEventListener('change', () => console.log(calendario.value));
+ * ```
  *
- * Geralmente exibido dentro da superfície suspensa coordenada pelo `br-datetime-picker`. Pode ser declarado isoladamente quando a interface demandar um calendário estático permanentemente embutido na página (inline calendar).
+ * - `value`: data selecionada (`Date`).
+ * - `referenceDate`: mês exibido.
+ * - `disabledDates`: datas que não podem ser escolhidas.
+ * - `selectionMode="range"`: seleção de intervalo, lida em `rangeValue`.
  *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).
- *
-
- * @category Formulários, Seleção
- * @status stable
+ * Para mudar o idioma, veja "Idiomas" na documentação do `br-datetime-picker`.
  *
  * @part container - Parte para o container base do calendário.
  * @part header - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).
@@ -58,73 +63,78 @@ import { normalizeLocale, normalizeWeekStartsOn } from "./date-picker-props-vali
  */
 export class DatePicker {
     constructor() {
-        /** Data com foco atual na navegação por teclado do calendário. */
-        this.focusedDate = new Date();
-        /** Datas inválidas são removidas da lista antes da comparação com o calendário. */
-        this.normalizedDisabledDates = [];
-        /** Define o índice do dia em que a semana começa na interface do calendário. */
+        /**
+         * Índice do dia em que a semana começa na interface do calendário.
+         * @default 0
+         */
         this.weekStartsOn = 0;
         /**
-         * Data usada como base visual para o mês atualmente exibido, sem alterar a seleção.
-         * Recebe uma instância de `Date` por property binding; valores inválidos usam a data atual.
-         *
-         * @example
-         * ```js
-         * const calendar = document.querySelector('br-date-picker');
-         * calendar.referenceDate = new Date(2026, 8, 1);
-         * ```
+         * Data usada como base visual para o mês atualmente exibido.
+         * @default new Date()
          */
         this.referenceDate = new Date();
         /**
-         * Data efetivamente selecionada, ou `null` quando não há seleção; é diferente de `referenceDate`, que controla apenas o mês visível.
-         * Recebe uma instância de `Date` por property binding; datas inválidas usam `null`.
-         *
-         * @example
-         * ```js
-         * const calendar = document.querySelector('br-date-picker');
-         * calendar.value = new Date(2026, 8, 7);
-         * ```
+         * Data atualmente selecionada pelo usuário, ou `null` quando não há seleção.
+         * @default null
          */
         this.value = null;
-        /** Define se a seleção ocorre por data única ou por intervalo. Valores inválidos usam `single`. */
+        /**
+         * Define se a seleção ocorre por data única ou por intervalo.
+         * @default 'single'
+         */
         this.selectionMode = 'single';
-        /** Data inicial selecionada quando o calendário opera no modo de intervalo. */
+        /**
+         * Data inicial selecionada quando o calendário opera no modo de intervalo.
+         * @default null
+         */
         this.rangeStart = null;
-        /** Data final selecionada quando o calendário opera no modo de intervalo. */
+        /**
+         * Data final selecionada quando o calendário opera no modo de intervalo.
+         * @default null
+         */
         this.rangeEnd = null;
-        /** Desabilita a interação do calendário quando ativo. */
+        /**
+         * Desabilita a interação do calendário quando `true`.
+         * @default false
+         */
         this.disabled = false;
         /**
          * Lista de datas indisponíveis para seleção no calendário.
-         * Recebe instâncias de `Date` por property binding; datas inválidas são ignoradas.
-         *
-         * @example
-         * ```js
-         * const calendar = document.querySelector('br-date-picker');
-         * calendar.disabledDates = [new Date(2026, 8, 7), new Date(2026, 8, 8)];
-         * ```
+         * @default []
          */
         this.disabledDates = [];
-        /** Locale usado para gerar nomes de meses e dias da semana. */
+        /**
+         * Locale usado para gerar nomes de meses e dias da semana.
+         * @default DATETIME_PICKER_LOCALE.DEFAULT
+         */
         this.locale = DATETIME_PICKER_LOCALE.DEFAULT;
         /**
-         * Define se o calendário deve manter um número fixo de linhas (6 semanas = 42 dias)
-         * ou variar conforme o mês.
-         *
-         * Quando `true`, o calendário sempre exibe 6 semanas completas.
-         * Quando `false`, o calendário adapta-se ao mês, exibindo apenas as semanas necessárias.
-         *
+         * Se `true`, o calendário sempre exibe 6 semanas (42 dias); caso contrário, adapta-se ao mês.
          * @default false
          */
         this.fixedRowCount = false;
-        /** Sinaliza ao componentDidRender que deve mover o foco para a célula atual. */
+        /**
+         * Data atualmente com foco para navegação por teclado.
+         * Usada para controlar qual célula do calendário recebe `tabindex=0`.
+         * @type {Date}
+         * @default new Date()
+         * @internal
+         */
+        this.focusedDate = new Date();
+        /**
+         * Sinaliza ao `componentDidRender` que o foco deve ser movido para a célula atual.
+         * @internal
+         */
         this.shouldFocusDate = false;
-        /** Mantém handlers estáveis por data para evitar recriação a cada renderização. */
-        this.dayClickHandlers = new WeakMap();
         /**
-         * Atualiza o mês exibido a partir da seleção do usuário.
-         *
-         * @param event - Mudança do `<select>` de mês.
+         * 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>`
+         * @internal
          */
         this.handleMonthChange = (event) => {
             if (this.disabled) {
@@ -136,16 +146,21 @@ 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 }));
         };
         /**
-         * Executa a ação de navegação associada ao botão clicado.
-         *
-         * @param event - Clique no botão de navegação.
+         * Trata cliques nos botões de navegação do calendário.
+         * @param event - evento de clique
+         * @internal
          */
         this.handleNavigationClick = (event) => {
-            const action = event.currentTarget.dataset.action;
+            if (this.disabled) {
+                return;
+            }
+            const actionFromPath = event
+                .composedPath()
+                .find((target) => target instanceof HTMLElement && target.dataset.action !== undefined);
+            const action = (actionFromPath?.dataset.action ?? event.currentTarget?.dataset.action);
             if (action === undefined) {
                 console.warn('Botão de navegação clicado sem data-action definido');
                 return;
@@ -162,9 +177,10 @@ export class DatePicker {
             }
         };
         /**
-         * Atualiza o ano exibido a partir do valor digitado.
-         *
-         * @param event - Mudança do campo de ano.
+         * Handler de alteração do campo ano.
+         * Valida o ano antes de aplicar a mudança.
+         * @param event - evento de mudança do input de ano
+         * @internal
          */
         this.handleYearChange = (event) => {
             if (this.disabled) {
@@ -176,23 +192,35 @@ 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.effectiveSelectionMode === '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 }));
         };
         /**
-         * Gerencia a navegação por teclado dentro da grade de dias.
-         *
-         * Teclas suportadas:
-         * - `ArrowLeft` / `ArrowRight`: avança ou recua um dia.
-         * - `ArrowUp` / `ArrowDown`: avança ou recua sete dias (linha inteira).
-         * - `PageUp` / `PageDown`: navega entre meses.
-         * - `Home` / `End`: primeiro ou último dia da semana atual.
-         * - `Enter` / `Space`: seleciona o dia com foco.
+         * Trata cliques com um handler compartilhado, lendo a data local da célula.
+         * @param event - evento de clique da célula
+         * @internal
+         */
+        this.handleDayCellClick = (event) => {
+            const cell = event.currentTarget;
+            if (!(cell instanceof HTMLElement) || cell.dataset.date === undefined) {
+                console.warn('Célula de dia clicada sem data-date definido');
+                return;
+            }
+            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;
+            }
+            this.handleDayClick(date);
+        };
+        /**
+         * Gerencia navegação por teclado dentro da grade de dias.
+         * Teclas suportadas: ArrowLeft/Right/Up/Down, PageUp/PageDown (mês), Shift+PageUp/PageDown (ano),
+         * Home/End, Enter/Space.
          *
-         * @param event - Evento de teclado disparado na grade.
+         * 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
          */
         this.handleGridKeydown = (event) => {
             const HANDLED_KEYS = [
@@ -209,12 +237,22 @@ export class DatePicker {
             ];
             if (!HANDLED_KEYS.includes(event.key))
                 return;
-            const target = event.target;
-            const dateKey = target.dataset?.date;
-            if (dateKey === undefined)
-                return;
-            event.preventDefault();
-            const current = parse(dateKey, 'yyyy-MM-dd', new Date());
+            // O `event.target` pode ser um nó interno (texto) ou o foco pode estar
+            // em um container; tentamos localizar a célula com `data-date`.
+            const targetEl = event.target?.closest?.('[data-date]');
+            // Se encontrarmos a célula, usamos sua data; caso contrário, usamos a
+            // data atualmente focada (`focusedDate`) como fallback. Em ambos os casos
+            // prevenimos o comportamento padrão para manter consistência.
+            let current;
+            if (targetEl && targetEl.dataset?.date !== undefined) {
+                const dateKey = targetEl.dataset.date;
+                event.preventDefault();
+                current = parse(dateKey, DAY_KEY_FORMAT, new Date());
+            }
+            else {
+                event.preventDefault();
+                current = this.getNormalizedFocusedDate();
+            }
             if (event.key === 'Enter' || event.key === ' ') {
                 if (!this.isDateDisabled(current)) {
                     this.handleDayClick(current);
@@ -236,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 });
@@ -253,47 +291,43 @@ export class DatePicker {
             this.moveFocusTo(next);
         };
     }
-    get effectiveSelectionMode() {
-        return resolveAllowedPropValue(this.el, 'selectionMode', this.selectionMode, ['single', 'range'], 'single');
-    }
+    /**
+     * Observador para a prop `rangeValue` — sincroniza `rangeStart` e `rangeEnd`.
+     * @param {DatetimePickerDateRange | undefined} newValue - novo intervalo controlado recebido (`undefined` quando não fornecido)
+     * @internal
+     */
     handleRangeValueChange(newValue) {
         if (!newValue)
             return;
-        if (!isValidDatetimePickerDateRange(newValue)) {
-            reportInvalidPropValue(this.el, 'rangeValue', newValue, 'Informe um objeto com `start` e `end` como Date válido ou null.', 'Ignorando o intervalo inválido e mantendo o último intervalo efetivo.');
-            return;
-        }
         this.rangeStart = newValue.start;
         this.rangeEnd = newValue.end;
     }
     /**
      * Sincroniza `focusedDate` quando o valor selecionado muda externamente.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {Date | null} newValue - Novo valor recebido via prop.
      */
-    handleValueChange(newValue) {
-        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;
-            return;
-        }
-        this.focusedDate = toDate(normalizedValue ?? this.referenceDate);
-    }
-    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;
-            return;
+    /**
+     * 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, 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);
         }
-        if (this.value === null)
-            this.focusedDate = toDate(normalizedReferenceDate);
     }
     /**
      * Revalida a configuração quando o início da semana muda.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {number} newValue - Novo valor recebido via prop.
+     */
+    /**
+     * Observador para `weekStartsOn` — revalida a configuração quando alterada externamente.
+     * @param {number} newValue - novo índice do início da semana
+     * @internal
      */
     handleWeekStartsOnChange(newValue) {
         this.ensureValidWeekStartsOn(newValue);
@@ -301,42 +335,35 @@ export class DatePicker {
     /**
      * Revalida o locale quando a prop muda.
      *
-     * @param newValue - Novo valor recebido via prop.
+     * @param {string} newValue - Novo valor recebido via prop.
+     */
+    /**
+     * Observador para `locale` — revalida/normaliza o locale informado.
+     * @param {string} newValue - nova string de locale
+     * @internal
      */
     handleLocaleChange(newValue) {
         this.ensureValidLocale(newValue);
     }
-    handleDisabledDatesChange(newValue) {
-        this.normalizedDisabledDates = normalizeDatetimePickerDisabledDates(newValue, 'br-date-picker');
-    }
-    /**
-     * Normaliza os valores públicos antes da primeira renderização.
-     */
     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);
         this.ensureValidWeekStartsOn();
         this.ensureValidLocale();
-        this.handleDisabledDatesChange(this.disabledDates);
         this.focusedDate = toDate(this.value ?? this.referenceDate);
     }
-    /**
-     * Move o foco para a célula correspondente ao `focusedDate` após re-renderização.
-     */
     componentDidRender() {
         if (!this.shouldFocusDate)
             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();
     }
     /**
-     * Garante que o valor de `weekStartsOn` esteja dentro do domínio suportado.
-     *
+     * Valida e normaliza `weekStartsOn`.
      * @param value - Valor bruto informado pelo consumidor.
+     * @internal
      */
     ensureValidWeekStartsOn(value = this.weekStartsOn) {
         const normalizedWeekStartsOn = normalizeWeekStartsOn(value);
@@ -344,18 +371,10 @@ export class DatePicker {
             this.weekStartsOn = normalizedWeekStartsOn;
         }
     }
-    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);
-    }
     /**
-     * Garante que o locale informado seja suportado.
-     *
+     * Valida e normaliza o `locale` informado.
      * @param value - Valor bruto informado pelo consumidor.
+     * @internal
      */
     ensureValidLocale(value = this.locale) {
         const normalizedLocale = normalizeLocale(value);
@@ -364,16 +383,20 @@ export class DatePicker {
         }
     }
     /**
-     * Emite o estado consolidado do componente para manter a navegação sincronizada.
+     * Emite `dateStateChange` atualizando `referenceDate`, `value` e `range`.
+     * Zera segundos/milissegundos para consistência.
      *
-     * @param nextReferenceDate - Nova data de referência após a interação.
-     * @param nextValue - Valor selecionado final; por padrão, mantém a seleção atual.
+     * @param nextReferenceDate - nova data de referência
+     * @param nextValue - data selecionada ou `null` (por padrão, mantém `this.value`)
+     * @param nextRange - intervalo de datas quando aplicável
+     * @internal
      */
     emitDateStateChange(nextReferenceDate, nextValue = this.value, nextRange = undefined) {
         // Garantir segundos zerados (componente não manipula segundos)
         const normalizedReference = set(nextReferenceDate, { seconds: 0, milliseconds: 0 });
         const normalizedValue = nextValue === null ? null : set(nextValue, { seconds: 0, milliseconds: 0 });
         const valueChanged = this.value?.getTime() !== normalizedValue?.getTime();
+        this.referenceDate = normalizedReference;
         this.value = normalizedValue;
         this.dateStateChange.emit({
             referenceDate: normalizedReference,
@@ -388,10 +411,10 @@ export class DatePicker {
         }
     }
     /**
-     * Resolve o ícone usado em cada ação de navegação.
-     *
-     * @param action - Ação de navegação representada pelo botão.
-     * @returns Nome do ícone ou um fallback quando a ação não é reconhecida.
+     * Resolve o nome do ícone para a ação de navegação.
+     * @param action - Ação de navegação
+     * @returns Nome do ícone
+     * @internal
      */
     getIconForAction(action) {
         switch (action) {
@@ -404,9 +427,9 @@ export class DatePicker {
         }
     }
     /**
-     * Aplica a data clicada preservando hora e minuto da referência atual.
-     *
-     * @param date - Dia selecionado no calendário.
+     * Trata o clique numa célula de dia: aplica seleção ou atualiza intervalo.
+     * @param date - dia clicado
+     * @internal
      */
     handleDayClick(date) {
         if (this.disabled || this.isDateDisabled(date)) {
@@ -418,13 +441,17 @@ export class DatePicker {
             seconds: 0,
             milliseconds: 0,
         });
-        if (this.effectiveSelectionMode === 'range') {
+        if (this.selectionMode === 'range') {
             this.handleRangeDayClick(newDate);
             return;
         }
         this.emitDateStateChange(newDate, newDate);
     }
-    /** Atualiza o intervalo selecionado com base no clique atual. */
+    /**
+     * Atualiza o intervalo selecionado no modo `range`.
+     * @param clickedDate - data clicada pelo usuário
+     * @internal
+     */
     handleRangeDayClick(clickedDate) {
         const start = this.rangeStart;
         const end = this.rangeEnd;
@@ -441,153 +468,205 @@ export class DatePicker {
             end: normalizedEnd,
         });
     }
-    /** Decrementa o mês mantendo o primeiro dia do mês exibido e preservando a seleção de range. */
+    /**
+     * Decrementa o mês exibido e preserva seleção/intervalo quando aplicável.
+     * @internal
+     */
     decreaseMonth() {
         if (this.disabled) {
             return;
         }
-        const date = set(subMonths(this.baseDate, 1), { date: 1 });
-        const range = this.effectiveSelectionMode === '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 mantendo o primeiro dia do mês exibido e preservando a seleção de range. */
+    /**
+     * Incrementa o mês exibido e preserva seleção/intervalo quando aplicável.
+     * @internal
+     */
     increaseMonth() {
         if (this.disabled) {
             return;
         }
-        const date = set(addMonths(this.baseDate, 1), { date: 1 });
-        const range = this.effectiveSelectionMode === 'range' && this.rangeStart !== null && this.rangeEnd !== null
+        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);
     }
-    /** Indica se um dia está indisponível para seleção. */
+    /**
+     * Verifica se uma data está indisponível para seleção.
+     * @param date - data a verificar
+     * @returns `true` se a data estiver na lista de `disabledDates`
+     * @internal
+     */
     isDateDisabled(date) {
-        return this.normalizedDisabledDates.some((disabledDate) => isSameDay(disabledDate, date));
+        return this.disabledDateKeys.has(format(date, DAY_KEY_FORMAT));
     }
-    /** Data base usada para todos os cálculos de calendário. */
+    /**
+     * Chaves locais das datas bloqueadas, recalculadas somente quando `disabledDates` é substituída.
+     * Entradas inválidas são ignoradas.
+     * @internal
+     */
+    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.
+     * @returns data de referência interna
+     * @internal
+     */
     get baseDate() {
         return this.referenceDate;
     }
     /**
-     * Recupera um handler estável para a célula do dia informado.
-     *
-     * @param date - Dia representado pela célula.
-     * @returns Função de clique reutilizável.
-     */
-    getDayClickHandler(date) {
-        let handler = this.dayClickHandlers.get(date);
-        if (handler === undefined) {
-            handler = () => this.handleDayClick(date);
-            this.dayClickHandlers.set(date, handler);
-        }
-        return handler;
-    }
-    /** Formata o dia exibido com zero à esquerda. */
+     * Formata o dia exibido com zero à esquerda (ex: '01', '09').
+     * @param date - data a formatar
+     * @returns string com dois dígitos do dia
+     * @internal
+     */
     getDayWithLeadingZero(date) {
         return format(date, 'dd');
     }
     /**
-     * Constrói o rótulo acessível completo da célula de dia.
-     *
-     * @param date - Dia representado pela célula.
-     * @returns Texto anunciado pelo leitor de tela, incluindo estado de seleção.
+     * Constrói o rótulo acessível da célula de dia, incluindo estado (selecionado/início/fim).
+     * @param date - dia representado pela célula
+     * @param state - estado já calculado da célula
+     * @returns string para `aria-label`
+     * @internal
      */
-    getDayCellAriaLabel(date) {
+    getDayCellAriaLabel(date, state) {
         const fullDate = format(date, "d 'de' MMMM 'de' yyyy", { locale: this.dateFnsLocale });
-        const isSelected = this.effectiveSelectionMode === 'single' && this.value !== null && isSameDay(date, this.value);
-        const isRangeStart = this.effectiveSelectionMode === 'range' && this.rangeStart !== null && isSameDay(date, this.rangeStart);
-        const isRangeEnd = this.effectiveSelectionMode === 'range' && this.rangeEnd !== null && isSameDay(date, this.rangeEnd);
-        const isBetween = this.effectiveSelectionMode === '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;
     }
-    /** Locale do date-fns derivado da prop pública do componente. */
+    /**
+     * Locale do `date-fns` derivado da prop pública `locale`.
+     * @internal
+     */
     get dateFnsLocale() {
         return resolveDateFnsLocale(this.locale);
     }
     /**
-     * Calcula as classes CSS da célula do dia com base em seleção, mês e data atual.
-     *
-     * @param date - Dia da grade do calendário.
-     */
-    getDayCssClasses(date) {
-        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);
+     * 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(state, disabled) {
         return {
             day: true,
-            'outside-month': !isSameMonth(date, this.baseDate),
-            today: isSameDay(date, toDate(new Date())),
-            selected: this.effectiveSelectionMode === 'single' && selected !== null && isSameDay(date, selected),
-            'range-start': this.effectiveSelectionMode === 'range' && isRangeStart,
-            'range-end': this.effectiveSelectionMode === 'range' && isRangeEnd,
-            'in-range': this.effectiveSelectionMode === '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,
         };
     }
-    /** Normaliza os limites do intervalo para garantir ordem cronológica. */
+    /**
+     * Normaliza os limites do intervalo garantindo ordem cronológica (start <= end).
+     * @param start - data de início
+     * @param end - data de fim
+     * @returns tupla [start, end] na ordem correta
+     * @internal
+     */
     normalizeRangeBounds(start, end) {
         return compareAsc(start, end) <= 0 ? [start, end] : [end, start];
     }
-    /** Verifica se uma data está estritamente entre início e fim do intervalo. */
+    /**
+     * Verifica se uma data está estritamente entre `start` e `end`.
+     * @param date - data a verificar
+     * @param start - início do intervalo
+     * @param end - fim do intervalo
+     * @returns `true` se `start < date < end`
+     * @internal
+     */
     isDateBetweenRange(date, start, end) {
         return isAfter(date, start) && isBefore(date, end);
     }
-    /** Gera a sequência completa de dias visíveis na grade do mês. */
-    getMonthViewDates() {
+    /**
+     * Calcula os limites da grade do mês, respeitando `fixedRowCount`, sem gerar suas datas.
+     * @returns limites inclusivos da grade
+     * @internal
+     */
+    getMonthViewInterval() {
         const start = startOfWeek(startOfMonth(this.baseDate), { weekStartsOn: this.weekStartsOn });
-        let end = endOfWeek(endOfMonth(this.baseDate), { weekStartsOn: this.weekStartsOn });
-        // Se fixedRowCount está ativo, garante sempre 6 semanas (42 dias)
-        if (this.fixedRowCount) {
-            // Calcula o número de semanas que seriam normalmente geradas
-            const normalizedDates = eachDayOfInterval({ start, end });
-            const currentWeekCount = Math.ceil(normalizedDates.length / 7);
-            const targetWeekCount = 6;
-            // Se não houver 6 semanas, estende o final para alcançar 42 dias
-            if (currentWeekCount < targetWeekCount) {
-                const daysToAdd = (targetWeekCount - currentWeekCount) * 7;
-                end = addDays(end, daysToAdd);
-            }
-        }
-        return eachDayOfInterval({ start, end });
+        const end = this.fixedRowCount
+            ? addDays(start, 41)
+            : endOfWeek(endOfMonth(this.baseDate), { weekStartsOn: this.weekStartsOn });
+        return { start, end };
     }
     /**
-     * Retorna o `focusedDate` normalizado para estar sempre dentro da grade visível.
-     *
-     * Se `focusedDate` não estiver visível no mês atual, retorna o primeiro dia
-     * da grade do mês para garantir que sempre haja um elemento com `tabIndex={0}`.
-     *
-     * @returns Data focada normalizada ou primeiro dia da grade.
+     * Retorna o `focusedDate` normalizado para estar dentro da grade visível.
+     * Se não estiver visível, retorna o primeiro dia da grade.
+     * @param interval - limites da grade atual; calculados quando não fornecidos
+     * @returns data normalizada para foco
+     * @internal
      */
-    getNormalizedFocusedDate() {
-        const visibleDates = this.getMonthViewDates();
-        const isInCurrentMonth = visibleDates.some((d) => isSameDay(d, this.focusedDate));
-        if (isInCurrentMonth) {
+    getNormalizedFocusedDate(interval = this.getMonthViewInterval()) {
+        const focusedDay = startOfDay(this.focusedDate).getTime();
+        const isVisible = focusedDay >= interval.start.getTime() && focusedDay <= interval.end.getTime();
+        if (isVisible) {
             return this.focusedDate;
         }
-        return visibleDates[0] ?? this.focusedDate;
+        return interval.start;
     }
     /**
-     * Constrói o rótulo acessível dos botões de navegação do mês.
-     *
-     * @param action - Ação associada ao botão.
-     * @returns Texto acessível exibido para leitores de tela.
+     * Constrói o rótulo acessível para os botões de navegação.
+     * @param action - ação de navegação
+     * @returns rótulo para `aria-label`
+     * @internal
      */
     getNavigationAriaLabel(action) {
         switch (action) {
@@ -599,78 +678,126 @@ export class DatePicker {
                 return 'Navegar';
         }
     }
-    /** Retorna os rótulos das semanas conforme locale e início da semana. */
+    /**
+     * Retorna os rótulos dos dias da semana conforme `locale` e `weekStartsOn`.
+     * @internal
+     */
     getWeekdayLabels() {
         return getWeekdayLabels(this.locale, this.weekStartsOn);
     }
-    /** Retorna os rótulos dos meses no locale atual. */
+    /**
+     * Retorna os rótulos dos meses no locale atual.
+     * @internal
+     */
     getMonthLabels() {
         return getMonthLabels(this.locale);
     }
     /**
-     * Renderiza um botão consistente de navegação do calendário.
-     *
-     * @param action - Ação executada pelo botão.
+     * Move o foco de teclado para a data informada e atualiza `referenceDate` se necessário.
+     * @param date - data alvo do foco
+     * @returns void
+     * @internal
+     */
+    moveFocusTo(date) {
+        this.focusedDate = date;
+        this.shouldFocusDate = true;
+        if (!isSameMonth(date, this.baseDate)) {
+            this.emitDateStateChange(date, this.value);
+        }
+    }
+    /**
+     * Renderiza um botão de navegação consistente para o calendário.
+     * @param action - ação do botão
+     * @returns elemento JSX do botão de navegação
+     * @internal
      */
     renderNavigationButton(action) {
-        return (h("br-button", { emphasis: "tertiary", density: "small", shape: "circle", disabled: this.disabled, "data-action": action, "aria-label": this.getNavigationAriaLabel(action), onClick: this.handleNavigationClick }, h("br-icon", { iconName: this.getIconForAction(action), width: "20", height: "20", "aria-hidden": "true" })));
+        return (h("br-button", { type: "button", emphasis: "tertiary", density: "small", shape: "circle", disabled: this.disabled, "data-action": action, "aria-label": this.getNavigationAriaLabel(action), onClick: this.handleNavigationClick }, h("br-icon", { iconName: this.getIconForAction(action), width: "20", height: "20", "aria-hidden": "true" })));
     }
-    /** Renderiza o cabeçalho do calendário com navegação, mês e ano. */
+    /**
+     * Renderiza o cabeçalho do calendário (navegação, mês e ano).
+     * @returns elemento JSX do cabeçalho
+     * @internal
+     */
     renderCalendarHeader() {
         return (h("div", { class: "header", part: "header" }, this.renderNavigationButton(NAVIGATION_ACTION.PREVIOUS_MONTH), this.renderMonthSelection(), this.renderYearSelection(), this.renderNavigationButton(NAVIGATION_ACTION.NEXT_MONTH)));
     }
-    /** Renderiza a seleção de mês com label acessível. */
+    /**
+     * Renderiza o seletor de mês com rótulo acessível.
+     * @returns elemento JSX do seletor de mês
+     * @internal
+     */
     renderMonthSelection() {
         return (h("label", { class: "month-selection" }, h("span", { class: "visually-hidden" }, "Selecionar m\u00EAs"), h("select", { onChange: this.handleMonthChange, "aria-label": "Selecionar m\u00EAs", disabled: this.disabled, part: "month-select" }, this.getMonthLabels().map(this.renderMonthOption, this))));
     }
-    /** Renderiza o campo de ano com label acessível. */
+    /**
+     * Renderiza o campo de ano com rótulo acessível.
+     * @returns elemento JSX do campo de ano
+     * @internal
+     */
     renderYearSelection() {
         return (h("label", { class: "year-selection" }, h("span", { class: "visually-hidden" }, "Selecionar ano"), h("input", { type: "number", value: this.referenceDate.getFullYear(), onChange: this.handleYearChange, "aria-label": "Selecionar ano", disabled: this.disabled, part: "year-input" })));
     }
-    /** Renderiza uma opção do seletor de meses. */
+    /**
+     * Renderiza uma opção do seletor de meses.
+     * @param month - label do mês
+     * @param index - índice do mês (0-11)
+     * @returns elemento `<option>` para o mês
+     * @internal
+     */
     renderMonthOption(month, index) {
         return (h("option", { key: `month-${index}`, value: index, selected: index === this.referenceDate.getMonth() }, month));
     }
-    /** Renderiza a estrutura principal do calendário. */
+    /**
+     * Renderiza a estrutura principal do calendário (grade e cabeçalho).
+     * @returns elemento JSX com a grade do calendário
+     * @internal
+     */
     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 a linha de rótulos dos dias da semana. */
+    /**
+     * Renderiza os rótulos dos dias da semana.
+     * @returns elemento JSX com os cabeçalhos das colunas dos dias
+     * @internal
+     */
     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 com os dias do mês atual. */
+    /**
+     * Renderiza a grade de dias do mês atual.
+     * @returns elemento JSX contendo semanas e dias
+     * @internal
+     */
     renderMonthGrid() {
-        const dates = this.getMonthViewDates();
+        const interval = this.getMonthViewInterval();
+        const dates = eachDayOfInterval(interval);
+        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", onKeyDown: this.handleGridKeydown, part: "grid" }, weeks.map((week) => (h("div", { key: `week-${format(week[0], 'yyyy-MM-dd')}`, class: "week", role: "row", tabIndex: -1 }, week.map(this.renderDayCell, this))))));
+        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)))))));
     }
     /**
-     * Move o foco de teclado para a data informada, navegando de mês quando necessário.
-     *
-     * @param date - Data de destino do foco.
+     * Renderiza uma célula de dia com estado visual apropriado.
+     * @param date - data representada pela célula
+     * @param normalizedFocusedDate - data de foco normalizada para a grade atual
+     * @param today - instante atual compartilhado pela renderização da grade
+     * @returns elemento JSX da célula de dia
+     * @internal
      */
-    moveFocusTo(date) {
-        this.focusedDate = date;
-        this.shouldFocusDate = true;
-        if (!isSameMonth(date, this.baseDate)) {
-            this.emitDateStateChange(date, this.value);
-        }
-    }
-    /** Renderiza uma célula de dia com estado visual apropriado. */
-    renderDayCell(date) {
-        const disabled = this.disabled || this.isDateDisabled(date);
-        const isSelected = this.effectiveSelectionMode === 'single' && this.value !== null && isSameDay(date, this.value);
-        const isRangeStart = this.effectiveSelectionMode === 'range' && this.rangeStart !== null && isSameDay(date, this.rangeStart);
-        const isRangeEnd = this.effectiveSelectionMode === 'range' && this.rangeEnd !== null && isSameDay(date, this.rangeEnd);
-        const isActiveDay = isSelected || isRangeStart || isRangeEnd;
-        const isFocused = isSameDay(date, this.getNormalizedFocusedDate());
-        return (h("div", { key: format(date, 'yyyy-MM-dd'), role: "gridcell", tabIndex: this.disabled ? undefined : isFocused ? 0 : -1, "data-date": format(date, 'yyyy-MM-dd'), class: { ...this.getDayCssClasses(date), disabled }, onClick: disabled ? undefined : this.getDayClickHandler(date), 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)));
+    renderDayCell(date, normalizedFocusedDate, today) {
+        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(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: 'bf83467d8324a00d3e1d3dc8912bdc732e33ea77' }, h("div", { key: 'e6501b7d8765b032c3681d3d44937631f342bb15', 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"; }
@@ -704,8 +831,11 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Define o \u00EDndice do dia em que a semana come\u00E7a na interface do calend\u00E1rio."
+                    "tags": [{
+                            "name": "default",
+                            "text": "0"
+                        }],
+                    "text": "\u00CDndice do dia em que a semana come\u00E7a na interface do calend\u00E1rio."
                 },
                 "getter": false,
                 "setter": false,
@@ -730,10 +860,10 @@ export class DatePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst calendar = document.querySelector('br-date-picker');\ncalendar.referenceDate = new Date(2026, 8, 1);\n```"
+                            "name": "default",
+                            "text": "new Date()"
                         }],
-                    "text": "Data usada como base visual para o m\u00EAs atualmente exibido, sem alterar a sele\u00E7\u00E3o.\nRecebe uma inst\u00E2ncia de `Date` por property binding; valores inv\u00E1lidos usam a data atual."
+                    "text": "Data usada como base visual para o m\u00EAs atualmente exibido."
                 },
                 "getter": false,
                 "setter": false,
@@ -756,10 +886,10 @@ export class DatePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst calendar = document.querySelector('br-date-picker');\ncalendar.value = new Date(2026, 8, 7);\n```"
+                            "name": "default",
+                            "text": "null"
                         }],
-                    "text": "Data efetivamente selecionada, ou `null` quando n\u00E3o h\u00E1 sele\u00E7\u00E3o; \u00E9 diferente de `referenceDate`, que controla apenas o m\u00EAs vis\u00EDvel.\nRecebe uma inst\u00E2ncia de `Date` por property binding; datas inv\u00E1lidas usam `null`."
+                    "text": "Data atualmente selecionada pelo usu\u00E1rio, ou `null` quando n\u00E3o h\u00E1 sele\u00E7\u00E3o."
                 },
                 "getter": false,
                 "setter": false,
@@ -783,8 +913,11 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Define se a sele\u00E7\u00E3o ocorre por data \u00FAnica ou por intervalo. Valores inv\u00E1lidos usam `single`."
+                    "tags": [{
+                            "name": "default",
+                            "text": "'single'"
+                        }],
+                    "text": "Define se a sele\u00E7\u00E3o ocorre por data \u00FAnica ou por intervalo."
                 },
                 "getter": false,
                 "setter": false,
@@ -808,7 +941,10 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "default",
+                            "text": "null"
+                        }],
                     "text": "Data inicial selecionada quando o calend\u00E1rio opera no modo de intervalo."
                 },
                 "getter": false,
@@ -831,7 +967,10 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "default",
+                            "text": "null"
+                        }],
                     "text": "Data final selecionada quando o calend\u00E1rio opera no modo de intervalo."
                 },
                 "getter": false,
@@ -857,10 +996,10 @@ export class DatePicker {
                 "optional": true,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst calendar = document.querySelector('br-date-picker');\ncalendar.selectionMode = 'range';\ncalendar.rangeValue = { start: new Date(2026, 8, 7), end: new Date(2026, 8, 12) };\n```"
+                            "name": "default",
+                            "text": "undefined"
                         }],
-                    "text": "Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualiza\u00E7\u00E3o.\nDeve conter datas v\u00E1lidas ou `null`; valores inv\u00E1lidos s\u00E3o ignorados. Passe o objeto por property binding."
+                    "text": "Intervalo controlado no modo `range`.\nQuando definido, mant\u00E9m `rangeStart` e `rangeEnd` sincronizados."
                 },
                 "getter": false,
                 "setter": false
@@ -876,8 +1015,11 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Desabilita a intera\u00E7\u00E3o do calend\u00E1rio quando ativo."
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Desabilita a intera\u00E7\u00E3o do calend\u00E1rio quando `true`."
                 },
                 "getter": false,
                 "setter": false,
@@ -902,10 +1044,10 @@ export class DatePicker {
                 "optional": false,
                 "docs": {
                     "tags": [{
-                            "name": "example",
-                            "text": "```js\nconst calendar = document.querySelector('br-date-picker');\ncalendar.disabledDates = [new Date(2026, 8, 7), new Date(2026, 8, 8)];\n```"
+                            "name": "default",
+                            "text": "[]"
                         }],
-                    "text": "Lista de datas indispon\u00EDveis para sele\u00E7\u00E3o no calend\u00E1rio.\nRecebe inst\u00E2ncias de `Date` por property binding; datas inv\u00E1lidas s\u00E3o ignoradas."
+                    "text": "Lista de datas indispon\u00EDveis para sele\u00E7\u00E3o no calend\u00E1rio."
                 },
                 "getter": false,
                 "setter": false,
@@ -922,7 +1064,10 @@ export class DatePicker {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "default",
+                            "text": "DATETIME_PICKER_LOCALE.DEFAULT"
+                        }],
                     "text": "Locale usado para gerar nomes de meses e dias da semana."
                 },
                 "getter": false,
@@ -946,7 +1091,7 @@ export class DatePicker {
                             "name": "default",
                             "text": "false"
                         }],
-                    "text": "Define se o calend\u00E1rio deve manter um n\u00FAmero fixo de linhas (6 semanas = 42 dias)\nou variar conforme o m\u00EAs.\n\nQuando `true`, o calend\u00E1rio sempre exibe 6 semanas completas.\nQuando `false`, o calend\u00E1rio adapta-se ao m\u00EAs, exibindo apenas as semanas necess\u00E1rias."
+                    "text": "Se `true`, o calend\u00E1rio sempre exibe 6 semanas (42 dias); caso contr\u00E1rio, adapta-se ao m\u00EAs."
                 },
                 "getter": false,
                 "setter": false,
@@ -958,8 +1103,7 @@ export class DatePicker {
     }
     static get states() {
         return {
-            "focusedDate": {},
-            "normalizedDisabledDates": {}
+            "focusedDate": {}
         };
     }
     static get events() {
@@ -970,12 +1114,27 @@ export class DatePicker {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Evento emitido quando a data de refer\u00EAncia ou a sele\u00E7\u00E3o mudam."
+                    "tags": [{
+                            "name": "property",
+                            "text": "{Date} referenceDate - Data de refer\u00EAncia atual do calend\u00E1rio (segundos/milissegundos zerados)."
+                        }, {
+                            "name": "property",
+                            "text": "{(Date|null)} value - Data selecionada ou `null` quando nenhuma sele\u00E7\u00E3o."
+                        }, {
+                            "name": "property",
+                            "text": "{{start: Date, end: (Date|null)}=} range - Intervalo selecionado quando `selectionMode === 'range'`.\n\nConsumidores usam este evento para sincronizar UI externas e integra\u00E7\u00E3o com formul\u00E1rios."
+                        }, {
+                            "name": "event",
+                            "text": "dateStateChange"
+                        }, {
+                            "name": "type",
+                            "text": "{EventEmitter<DatetimePickerDateState>}"
+                        }],
+                    "text": "Emite o estado consolidado do componente quando h\u00E1 mudan\u00E7a de refer\u00EAncia/sele\u00E7\u00E3o.\n\nPayload (DatetimePickerDateState):"
                 },
                 "complexType": {
                     "original": "DatetimePickerDateState",
-                    "resolved": "{ referenceDate: Date; value: Date; range?: DatetimePickerDateRange; rangeDates?: DatetimePickerRangeDateState[]; }",
+                    "resolved": "{ referenceDate: Date; value: Date; range?: DatetimePickerDateRange; rangeDates?: DatetimePickerRangeDateState[]; origin?: string; }",
                     "references": {
                         "DatetimePickerDateState": {
                             "location": "import",
@@ -995,18 +1154,12 @@ export class DatePicker {
             }, {
                 "propName": "value",
                 "methodName": "handleValueChange"
-            }, {
-                "propName": "referenceDate",
-                "methodName": "handleReferenceDateChange"
             }, {
                 "propName": "weekStartsOn",
                 "methodName": "handleWeekStartsOnChange"
             }, {
                 "propName": "locale",
                 "methodName": "handleLocaleChange"
-            }, {
-                "propName": "disabledDates",
-                "methodName": "handleDisabledDatesChange"
             }];
     }
 }