@vaadin/date-picker 25.3.0-dev.3a3c2d7d2a → 25.3.0

package/src/vaadin-date-picker-overlay-content-mixin.js

@@ -5,10 +5,22 @@
  */
 import { timeOut } from '@vaadin/component-base/src/async.js';
 import { Debouncer } from '@vaadin/component-base/src/debounce.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { addListener } from '@vaadin/component-base/src/gestures.js';
 import { MediaQueryController } from '@vaadin/component-base/src/media-query-controller.js';
 import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
-import { dateAfterXMonths, dateAllowed, dateEquals, getClosestDate } from './vaadin-date-picker-helper.js';
+import {
+  createDate,
+  dateAfterXMonths,
+  dateAllowed,
+  dateEquals,
+  dateSelectable,
+  firstOfMonth,
+  getClosestDate,
+  lastOfMonth,
+  monthDate,
+  monthIndex,
+} from './vaadin-date-picker-helper.js';
 
 export const DatePickerOverlayContentMixin = (superClass) =>
   class DatePickerOverlayContentMixin extends superClass {
@@ -106,19 +118,10 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           type: Function,
         },
 
-        /**
-         * A batch function that is consulted for a range of dates the calendar is about to render
-         * and returns, or resolves with, an array of `DatePickerDate` objects to disable.
-         *
-         * @type {function(DatePickerDateRange): Array<DatePickerDate> | Promise<Array<DatePickerDate>> | undefined}
-         */
-        disabledDatesProvider: {
-          type: Function,
-        },
-
         /**
          * Reflected while data is being loaded, so the overlay can show a loading spinner.
-         * Currently set while the disabled dates provider is resolving.
+         * Currently set while the date metadata provider is resolving.
+         * @protected
          */
         loading: {
           type: Boolean,
@@ -126,17 +129,6 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           reflectToAttribute: true,
         },
 
-        /**
-         * Bumped whenever the disabled dates controller's cache or loading state changes, to
-         * re-run `__updateCalendars` and push the new state to the rendered months.
-         * @private
-         */
-        _disabledDatesVersion: {
-          type: Number,
-          value: 0,
-          attribute: false,
-        },
-
         enteredDate: {
           type: Date,
           sync: true,
@@ -155,6 +147,18 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           type: Object,
         },
 
+        /**
+         * The date-picker's date metadata controller, assigned by the host. Declared as a property,
+         * and a dependency of `__updateCalendarsConfig` below, so that the calendars are handed it
+         * and subscribed whenever it arrives, rather than relying on the host assigning it before
+         * the properties that happen to trigger that observer.
+         * @protected
+         */
+        _dateMetadataController: {
+          type: Object,
+          sync: true,
+        },
+
         calendars: {
           type: Array,
           value: () => [],
@@ -169,14 +173,47 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     static get observers() {
       return [
-        '__updateCalendars(calendars, i18n, minDate, maxDate, selectedDate, focusedDate, showWeekNumbers, _ignoreTaps, _theme, isDateDisabled, _disabledDatesVersion, enteredDate)',
-        '__loadingChanged(loading)',
+        '__updateCalendarsConfig(calendars, i18n, minDate, maxDate, showWeekNumbers, isDateDisabled, _theme, _dateMetadataController)',
+        '__updateCalendarsState(calendars, selectedDate, focusedDate, enteredDate, _ignoreTaps)',
         '__updateCancelButton(_cancelButton, i18n)',
-        '__updateTodayButton(_todayButton, i18n, minDate, maxDate, isDateDisabled, _disabledDatesVersion)',
         '__updateYears(years, selectedDate, _theme)',
       ];
     }
 
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      this.cancelLoadVisibleDateMetadata();
+    }
+
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('loading')) {
+        setOrRemoveAttribute(this, 'aria-busy', this.loading);
+      }
+
+      if (props.has('i18n')) {
+        setOrRemoveAttribute(this, 'aria-label', this.i18n?.dialogAccessibleName);
+      }
+
+      if (props.has('calendars') || props.has('_dateMetadataController')) {
+        this.loadVisibleDateMetadata();
+      }
+
+      if (
+        props.has('_todayButton') ||
+        props.has('i18n') ||
+        props.has('minDate') ||
+        props.has('maxDate') ||
+        props.has('isDateDisabled')
+      ) {
+        this.updateTodayButton();
+      }
+    }
+
     /**
      * Whether to scroll to a sub-month position when scrolling to a date.
      * This is active if the month scroller is not large enough to fit a
@@ -231,6 +268,8 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     reset() {
       this._closeYearScroller();
+      this._monthScroller?.reset();
+      this._yearScroller?.reset();
     }
 
     /**
@@ -323,39 +362,60 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       }
     }
 
-    /** @private */
-    __updateTodayButton(todayButton, i18n, minDate, maxDate, isDateDisabled) {
+    /**
+     * Applies the today button's label and whether today can be selected.
+     */
+    updateTodayButton() {
+      const todayButton = this._todayButton;
       if (todayButton) {
-        todayButton.textContent = i18n?.today;
-        todayButton.disabled = !this._isTodayAllowed(minDate, maxDate, isDateDisabled);
+        todayButton.textContent = this.i18n?.today;
+        todayButton.disabled = !this._isTodayAllowed();
       }
     }
 
-    /** @private */
-    __loadingChanged(loading) {
-      // Mark the calendar region as busy while data is being loaded so assistive technology knows
-      // the content is still updating.
-      if (loading) {
-        this.setAttribute('aria-busy', 'true');
-      } else {
-        this.removeAttribute('aria-busy');
+    /**
+     * Requests the date metadata for the months currently rendered. Months already loaded or in flight
+     * are skipped.
+     */
+    loadVisibleDateMetadata() {
+      const controller = this._dateMetadataController;
+      if (!controller) {
+        return;
       }
+      // Reduced to month indexes so the outermost months can be picked with plain arithmetic.
+      const indexes = (this.calendars ?? [])
+        .map((calendar) => calendar.month)
+        .filter(Boolean)
+        .map((month) => monthIndex(month));
+      if (indexes.length === 0) {
+        return;
+      }
+      controller.ensureRangeLoaded(monthDate(Math.min(...indexes)), monthDate(Math.max(...indexes)));
     }
 
+    /**
+     * Drops a date metadata load that navigating has scheduled but that has not run yet.
+     */
+    cancelLoadVisibleDateMetadata() {
+      this._loadDateMetadataDebouncer?.cancel();
+    }
+
+    /**
+     * Config that changes rarely (locale, allowed range, week numbers, theme).
+     * Split from the interaction state below so a keyboard/selection update
+     * does not re-assign every config property on every calendar.
+     * @private
+     */
     // eslint-disable-next-line @typescript-eslint/max-params
-    __updateCalendars(
+    __updateCalendarsConfig(
       calendars,
       i18n,
       minDate,
       maxDate,
-      selectedDate,
-      focusedDate,
       showWeekNumbers,
-      ignoreTaps,
-      theme,
       isDateDisabled,
-      disabledDatesVersion,
-      enteredDate,
+      theme,
+      dateMetadataController,
     ) {
       if (calendars?.length) {
         calendars.forEach((calendar) => {
@@ -363,60 +423,40 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           calendar.minDate = minDate;
           calendar.maxDate = maxDate;
           calendar.isDateDisabled = isDateDisabled;
-          calendar.disabledDatesController = this._disabledDatesController;
-          calendar.__disabledDatesVersion = disabledDatesVersion;
-          calendar.focusedDate = focusedDate;
-          calendar.selectedDate = selectedDate;
+          calendar._dateMetadataController = dateMetadataController;
+          // Subscribe to controller updates (subscribing again is a no-op).
+          dateMetadataController?.subscribe(calendar);
           calendar.showWeekNumbers = showWeekNumbers;
-          calendar.ignoreTaps = ignoreTaps;
-          calendar.enteredDate = enteredDate;
 
-          if (theme) {
-            calendar.setAttribute('theme', theme);
-          } else {
-            calendar.removeAttribute('theme');
-          }
+          setOrRemoveAttribute(calendar, 'theme', theme);
         });
-
-        this.__ensureVisibleDisabledDatesLoaded();
       }
     }
 
     /**
-     * Asks the disabled dates controller to load the range of months currently rendered by the
-     * scroller. The controller expands the range with a prefetch buffer and skips months that are
-     * already loaded or in flight, so one request covers the whole visible range.
+     * Debounced variant used while navigating, so a continuous scroll triggers one load once it
+     * settles instead of a request per intermediate position.
      * @private
      */
-    __ensureVisibleDisabledDatesLoaded() {
-      const controller = this._disabledDatesController;
-      if (!controller?.provider || !this.calendars || this.calendars.length === 0) {
-        return;
-      }
-      const indexes = this.calendars
-        .map((calendar) => calendar.month)
-        .filter(Boolean)
-        .map((month) => month.getFullYear() * 12 + month.getMonth());
-      if (indexes.length === 0) {
-        return;
-      }
-      const min = Math.min(...indexes);
-      const max = Math.max(...indexes);
-      controller.ensureRangeLoaded(
-        new Date(Math.floor(min / 12), min % 12, 1),
-        new Date(Math.floor(max / 12), max % 12, 1),
+    __scheduleLoadVisibleDateMetadata() {
+      this._loadDateMetadataDebouncer = Debouncer.debounce(this._loadDateMetadataDebouncer, timeOut.after(200), () =>
+        this.loadVisibleDateMetadata(),
       );
     }
 
     /**
-     * Debounced variant used on scroll, so a continuous scroll only triggers one load once it
-     * settles instead of a request per intermediate position.
+     * Interaction state that changes often (focus, selection, entered date, taps).
      * @private
      */
-    __scheduleVisibleDisabledDatesLoad() {
-      this._loadDisabledDatesDebouncer = Debouncer.debounce(this._loadDisabledDatesDebouncer, timeOut.after(200), () =>
-        this.__ensureVisibleDisabledDatesLoaded(),
-      );
+    __updateCalendarsState(calendars, selectedDate, focusedDate, enteredDate, ignoreTaps) {
+      if (calendars?.length) {
+        calendars.forEach((calendar) => {
+          calendar.focusedDate = focusedDate;
+          calendar.selectedDate = selectedDate;
+          calendar.enteredDate = enteredDate;
+          calendar.ignoreTaps = ignoreTaps;
+        });
+      }
     }
 
     /** @private */
@@ -425,11 +465,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
         years.forEach((year) => {
           year.selectedDate = selectedDate;
 
-          if (theme) {
-            year.setAttribute('theme', theme);
-          } else {
-            year.removeAttribute('theme');
-          }
+          setOrRemoveAttribute(year, 'theme', theme);
         });
       }
     }
@@ -439,12 +475,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
      * @protected
      */
     _selectDate(dateToSelect) {
-      if (!this._dateAllowed(dateToSelect)) {
-        return false;
-      }
-      // Block dates disabled by the provider, or in a month whose provider result has not loaded
-      // yet, so they cannot be selected via keyboard or the today button either.
-      if (this._disabledDatesController?.isDateBlocked(dateToSelect)) {
+      if (!this._dateSelectable(dateToSelect)) {
         return false;
       }
       this.selectedDate = dateToSelect;
@@ -510,11 +541,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
      * @private
      */
     _calculateWeekScrollOffset(date) {
-      // Get first day of month
-      const temp = new Date(0, 0);
-      temp.setFullYear(date.getFullYear());
-      temp.setMonth(date.getMonth());
-      temp.setDate(1);
+      const temp = firstOfMonth(date);
       // Determine week (=row index) of date within the month
       let week = 0;
       while (temp.getDate() < date.getDate()) {
@@ -542,17 +569,14 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       const monthPosition = this._monthScroller.position;
       this._visibleMonthIndex = Math.floor(monthPosition);
       this._yearScroller.position = (monthPosition + this._originDate.getMonth()) / 12;
-      // Called from every navigation path (month scroll, year click, reveal), so this is the
-      // single place to keep the disabled dates loaded for the newly visible months. Debounced
-      // so a continuous scroll only triggers one load once it settles.
-      this.__scheduleVisibleDisabledDatesLoad();
+      this.__scheduleLoadVisibleDateMetadata();
     }
 
     /** @private */
     _repositionMonthScroller() {
       this._monthScroller.position = this._yearScroller.position * 12 - this._originDate.getMonth();
       this._visibleMonthIndex = Math.floor(this._monthScroller.position);
-      this.__scheduleVisibleDisabledDatesLoad();
+      this.__scheduleLoadVisibleDateMetadata();
     }
 
     /** @private */
@@ -719,8 +743,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _differenceInMonths(date1, date2) {
-      const months = (date1.getFullYear() - date2.getFullYear()) * 12;
-      return months - date2.getMonth() + date1.getMonth();
+      return monthIndex(date1) - monthIndex(date2);
     }
 
     /** @private */
@@ -926,33 +949,6 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       this.focusDate(getClosestDate(focus, [this.minDate, this.maxDate]));
     }
 
-    /**
-     * Returns the nearest date to the given one that can actually be selected: inside min/max, not
-     * disabled by `isDateDisabled`, and not disabled by a resolved `disabledDatesProvider`. Scans a
-     * year in both directions and returns `undefined` if none is found, so the caller can leave the
-     * focus untouched.
-     * @private
-     */
-    __closestSelectableDate(date) {
-      const controller = this._disabledDatesController;
-      const isSelectable = (candidate) =>
-        this._dateAllowed(candidate) && !(controller?.provider && controller.isDateDisabled(candidate));
-
-      if (isSelectable(date)) {
-        return date;
-      }
-      for (let offset = 1; offset <= 366; offset++) {
-        for (const direction of [1, -1]) {
-          const candidate = new Date(date);
-          candidate.setDate(candidate.getDate() + offset * direction);
-          if (isSelectable(candidate)) {
-            return candidate;
-          }
-        }
-      }
-      return undefined;
-    }
-
     /** @private */
     _focusAllowedDate(dateToFocus, diff, keepMonth) {
       // For this check we do consider the isDateDisabled function because disabled dates are allowed to be focused, just not outside min/max
@@ -975,13 +971,11 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _getDateDiff(months, days) {
-      const date = new Date(0, 0);
-      date.setFullYear(this.focusedDate.getFullYear());
-      date.setMonth(this.focusedDate.getMonth() + months);
-      if (days) {
-        date.setDate(this.focusedDate.getDate() + days);
-      }
-      return date;
+      return createDate(
+        this.focusedDate.getFullYear(),
+        this.focusedDate.getMonth() + months,
+        days ? this.focusedDate.getDate() + days : 1,
+      );
     }
 
     /** @private */
@@ -1011,16 +1005,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _moveFocusInsideMonth(focusedDate, property) {
-      const dateToFocus = new Date(0, 0);
-      dateToFocus.setFullYear(focusedDate.getFullYear());
-
-      if (property === 'minDate') {
-        dateToFocus.setMonth(focusedDate.getMonth());
-        dateToFocus.setDate(1);
-      } else {
-        dateToFocus.setMonth(focusedDate.getMonth() + 1);
-        dateToFocus.setDate(0);
-      }
+      const dateToFocus = property === 'minDate' ? firstOfMonth(focusedDate) : lastOfMonth(focusedDate);
 
       if (this._dateAllowed(dateToFocus)) {
         this.focusDate(dateToFocus);
@@ -1039,22 +1024,18 @@ export const DatePickerOverlayContentMixin = (superClass) =>
     }
 
     /** @private */
-    _isTodayAllowed(min, max, isDateDisabled) {
-      const today = this._getTodayMidnight();
-      if (!this._dateAllowed(today, min, max, isDateDisabled)) {
-        return false;
-      }
-      // Today is not selectable while it is disabled by the provider or its month is still loading.
-      return !this._disabledDatesController?.isDateBlocked(today);
+    _dateSelectable(date) {
+      return dateSelectable(date, this.minDate, this.maxDate, this.isDateDisabled, this._dateMetadataController);
+    }
+
+    /** @private */
+    _isTodayAllowed() {
+      return this._dateSelectable(this._getTodayMidnight());
     }
 
     /** @private */
     _getTodayMidnight() {
       const today = new Date();
-      const todayMidnight = new Date(0, 0);
-      todayMidnight.setFullYear(today.getFullYear());
-      todayMidnight.setMonth(today.getMonth());
-      todayMidnight.setDate(today.getDate());
-      return todayMidnight;
+      return createDate(today.getFullYear(), today.getMonth(), today.getDate());
     }
   };

package/src/vaadin-date-picker-overlay-content.js

@@ -19,6 +19,7 @@ import { overlayContentStyles } from './styles/vaadin-date-picker-overlay-conten
 import { DatePickerOverlayContentMixin } from './vaadin-date-picker-overlay-content-mixin.js';
 
 /**
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-date-picker-overlay-content
  * @extends HTMLElement
  * @private

package/src/vaadin-date-picker-overlay.js

@@ -16,6 +16,7 @@ import { DatePickerOverlayMixin } from './vaadin-date-picker-overlay-mixin.js';
 /**
  * An element used internally by `<vaadin-date-picker>`. Not intended to be used separately.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-date-picker-overlay
  * @extends HTMLElement
  * @private

package/src/vaadin-date-picker-year.js

@@ -13,11 +13,12 @@ import { datePickerYearStyles } from './styles/vaadin-date-picker-year-base-styl
 /**
  * An element used internally by `<vaadin-date-picker>`. Not intended to be used separately.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-date-picker-year
  * @extends HTMLElement
  * @private
  */
-export class DatePickerYear extends ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))) {
+class DatePickerYear extends ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))) {
   static get is() {
     return 'vaadin-date-picker-year';
   }
@@ -63,3 +64,5 @@ export class DatePickerYear extends ThemableMixin(PolylitMixin(LumoInjectionMixi
 }
 
 defineCustomElement(DatePickerYear);
+
+export { DatePickerYear };

package/src/vaadin-date-picker.d.ts

@@ -7,7 +7,13 @@ import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { InputControlMixin } from '@vaadin/field-base/src/input-control-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { DatePickerMixin } from './vaadin-date-picker-mixin.js';
-export { DatePickerDate, DatePickerDateRange, DatePickerI18n } from './vaadin-date-picker-mixin.js';
+export {
+  DatePickerDate,
+  DatePickerDateMetadata,
+  DatePickerDateMetadataProvider,
+  DatePickerDateRange,
+  DatePickerI18n,
+} from './vaadin-date-picker-mixin.js';
 
 /**
  * Fired when the user commits a value change.
@@ -72,12 +78,6 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  *
  * ### Styling
  *
- * The following custom properties are available for styling:
- *
- * Custom property                | Description                | Default
- * -------------------------------|----------------------------|---------
- * `--vaadin-field-default-width` | Default width of the field | `12em`
- *
  * The following shadow DOM parts are available for styling:
  *
  * Part name            | Description
@@ -111,6 +111,69 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  * `opened`             | Set when the overlay is opened
  * `week-numbers`       | Set when week numbers are shown in the calendar
  *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                                        |
+ * :----------------------------------------------------------|
+ * | `--vaadin-date-picker-date-border-radius`                |
+ * | `--vaadin-date-picker-date-disabled-color`               |
+ * | `--vaadin-date-picker-date-height`                       |
+ * | `--vaadin-date-picker-date-selected-background`          |
+ * | `--vaadin-date-picker-date-selected-color`               |
+ * | `--vaadin-date-picker-date-today-color`                  |
+ * | `--vaadin-date-picker-date-width`                        |
+ * | `--vaadin-date-picker-month-header-color`                |
+ * | `--vaadin-date-picker-month-header-font-size`            |
+ * | `--vaadin-date-picker-month-header-font-weight`          |
+ * | `--vaadin-date-picker-month-padding`                     |
+ * | `--vaadin-date-picker-overlay-max-height`                |
+ * | `--vaadin-date-picker-overlay-width`                     |
+ * | `--vaadin-date-picker-toolbar-padding`                   |
+ * | `--vaadin-date-picker-week-divider-color`                |
+ * | `--vaadin-date-picker-week-number-color`                 |
+ * | `--vaadin-date-picker-week-number-font-size`             |
+ * | `--vaadin-date-picker-weekday-color`                     |
+ * | `--vaadin-date-picker-weekday-font-size`                 |
+ * | `--vaadin-date-picker-weekday-font-weight`               |
+ * | `--vaadin-date-picker-year-scroller-background`          |
+ * | `--vaadin-date-picker-year-scroller-border-color`        |
+ * | `--vaadin-date-picker-year-scroller-current-year-color`  |
+ * | `--vaadin-date-picker-year-scroller-width`               |
+ * | `--vaadin-field-default-width`                           |
+ * | `--vaadin-input-field-background`                        |
+ * | `--vaadin-input-field-border-color`                      |
+ * | `--vaadin-input-field-border-radius`                     |
+ * | `--vaadin-input-field-border-width`                      |
+ * | `--vaadin-input-field-bottom-end-radius`                 |
+ * | `--vaadin-input-field-bottom-start-radius`               |
+ * | `--vaadin-input-field-button-text-color`                 |
+ * | `--vaadin-input-field-container-gap`                     |
+ * | `--vaadin-input-field-disabled-background`               |
+ * | `--vaadin-input-field-disabled-text-color`               |
+ * | `--vaadin-input-field-error-color`                       |
+ * | `--vaadin-input-field-error-font-size`                   |
+ * | `--vaadin-input-field-error-font-weight`                 |
+ * | `--vaadin-input-field-error-line-height`                 |
+ * | `--vaadin-input-field-gap`                               |
+ * | `--vaadin-input-field-helper-color`                      |
+ * | `--vaadin-input-field-helper-font-size`                  |
+ * | `--vaadin-input-field-helper-font-weight`                |
+ * | `--vaadin-input-field-helper-line-height`                |
+ * | `--vaadin-input-field-label-color`                       |
+ * | `--vaadin-input-field-label-font-size`                   |
+ * | `--vaadin-input-field-label-font-weight`                 |
+ * | `--vaadin-input-field-label-line-height`                 |
+ * | `--vaadin-input-field-padding`                           |
+ * | `--vaadin-input-field-placeholder-color`                 |
+ * | `--vaadin-input-field-required-indicator`                |
+ * | `--vaadin-input-field-required-indicator-color`          |
+ * | `--vaadin-input-field-top-end-radius`                    |
+ * | `--vaadin-input-field-top-start-radius`                  |
+ * | `--vaadin-input-field-value-color`                       |
+ * | `--vaadin-input-field-value-font-size`                   |
+ * | `--vaadin-input-field-value-font-weight`                 |
+ * | `--vaadin-input-field-value-line-height`                 |
+ *
  * ### Internal components
  *
  * In addition to `<vaadin-date-picker>` itself, the following internal
@@ -128,6 +191,7 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  * ----------------------|--------------------
  * `years-toggle-button` | Fullscreen mode years scroller toggle
  * `toolbar`             | Toolbar with slotted buttons
+ * `loader`              | Loading spinner shown while the date metadata provider is resolving
  *
  * The following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:
  *
@@ -136,6 +200,7 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  * `desktop`       | Set when the overlay content is in desktop mode
  * `fullscreen`    | Set when the overlay content is in fullscreen mode
  * `years-visible` | Set when the year scroller is visible in fullscreen mode
+ * `loading`       | Set while the date metadata provider is resolving
  *
  * In order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:
  *
@@ -148,6 +213,7 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  * `week-number`         | Week number element
  * `date`                | Date element
  * `disabled`            | Disabled date element
+ * `loading`             | Date element in a month whose metadata is currently being fetched
  * `focused`             | Focused date element
  * `selected`            | Selected date element
  * `today`               | Date element corresponding to the current day