@vaadin/date-picker 25.3.0-dev.1fa5a51482 → 25.3.0-rc1

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

@@ -5,9 +5,10 @@
  */
 import { hideOthers } from '@vaadin/a11y-base/src/aria-hidden.js';
 import { DelegateFocusMixin } from '@vaadin/a11y-base/src/delegate-focus-mixin.js';
-import { isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
+import { isElementFocused, isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
 import { KeyboardMixin } from '@vaadin/a11y-base/src/keyboard-mixin.js';
 import { isIOS } from '@vaadin/component-base/src/browser-utils.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { I18nMixin } from '@vaadin/component-base/src/i18n-mixin.js';
 import { MediaQueryController } from '@vaadin/component-base/src/media-query-controller.js';
 import { InputConstraintsMixin } from '@vaadin/field-base/src/input-constraints-mixin.js';
@@ -16,6 +17,7 @@ import { DateMetadataController } from './vaadin-date-metadata-controller.js';
 import {
   dateAllowed,
   dateEquals,
+  dateSelectable,
   extractDateParts,
   formatISODate,
   getAdjustedYear,
@@ -43,6 +45,7 @@ export const datePickerI18nDefaults = Object.freeze({
   firstDayOfWeek: 0,
   today: 'Today',
   cancel: 'Cancel',
+  dialogAccessibleName: 'Calendar',
   referenceDate: '',
   formatDate(d) {
     const yearStr = String(d.year).replace(/\d+/u, (y) => '0000'.substr(y.length) + y);
@@ -60,7 +63,7 @@ export const datePickerI18nDefaults = Object.freeze({
       date = parseInt(parts[1]);
       year = parseInt(parts[2]);
       if (parts[2].length < 3 && year >= 0) {
-        const usedReferenceDate = this.referenceDate ? parseDate(this.referenceDate) : new Date();
+        const usedReferenceDate = parseDate(this.referenceDate) || new Date();
         year = getAdjustedYear(usedReferenceDate, year, month, date);
       }
     } else if (parts.length === 2) {
@@ -203,6 +206,10 @@ export const DatePickerMixin = (subclass) =>
          * Receives a `DatePickerDate` object of the date to be selected and should return a
          * boolean.
          *
+         * The function is called once per date and has to answer synchronously. Use
+         * `dateMetadataProvider` when the answer has to be loaded first, or when dates also need
+         * custom part names. A date is disabled when either of the two disables it.
+         *
          * @type {function(DatePickerDate): boolean | undefined}
          */
         isDateDisabled: {
@@ -210,33 +217,43 @@ export const DatePickerMixin = (subclass) =>
         },
 
         /**
-         * A batch function that fetches metadata for a range of dates the calendar is about to
-         * render. It receives a `DatePickerDateRange` object (`{ start, end }` of `DatePickerDate`)
-         * and returns, or resolves with, an array of metadata objects — a `DatePickerDate` extended
-         * with metadata fields such as `disabled` and custom `part` names, e.g.
-         * `{ year, month, day, disabled: true, part: 'busy' }` — for the dates that have metadata
-         * within that range.
+         * A function that provides metadata for the dates the calendar is about to render: whether they
+         * are disabled, and CSS `part` names for styling from outside using the `::part()` selector.
+         * Unlike `isDateDisabled`, which is called once per date, the metadata provider is called for
+         * a range of dates at a time, and again as the calendar renders further dates.
+         *
+         * It receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects
+         * for the dates in that range that have metadata. It can return a `Promise` to load the metadata
+         * asynchronously, and `null` or `undefined` when no date in the range has metadata.
+         *
+         * The returned array has the following structure:
+         *
+         * ```js
+         * [
+         *   // The date is an ISO 8601 string.
+         *   { date: '2026-01-01', disabled: true },
+         *
+         *   // Adds a custom part name to the date.
+         *   { date: '2026-01-02', part: 'busy' },
+         * ]
+         * ```
          *
-         * Unlike `isDateDisabled`, which is called once per date, this function is called for a
-         * range of dates at a time, and again as the calendar renders further dates. The size of
-         * the range is decided by the calendar and may span multiple months. It may return a
-         * `Promise`, in which case the affected dates render in a non-selectable pending state
-         * until it resolves.
+         * A date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or
+         * it is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in
+         * the field makes it invalid. The provider does not affect which date is focused when opening the
+         * overlay. Use `initialPosition` property to provide a selectable date.
          *
-         * `disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date
-         * is disabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its
-         * metadata marks it disabled. `part` names are added to the date cell's `part` attribute so
-         * a theme can style specific dates via `::part()`.
+         * While a returned `Promise` is pending, the dates it covers are not disabled yet and render with
+         * the `loading` part. If the function throws or rejects, corresponding dates are requested again
+         * the next time the user navigates.
          *
-         * Both `disabled` and `part` are returned by this one function, rather than by separate
-         * generators, so a single backend query (for example in Flow) can answer both at once
-         * instead of being split into two passes over the same data.
+         * The provider is used for validation also when the overlay is closed. Date is considered valid
+         * while the provider is pending, and is re-validated again after the metadata is loaded.
          *
-         * Keep a stable reference to the function. Assigning a new function resets the internal
-         * cache and re-fetches every visible range. To reload after the underlying data changes
-         * while keeping the same function, call `clearCache()`.
+         * Keep a stable reference to the function: assigning a new one clears the cache and re-fetches
+         * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
          *
-         * @type {function(DatePickerDateRange): Array<DatePickerDateMetadata> | Promise<Array<DatePickerDateMetadata>> | undefined}
+         * @type {DatePickerDateMetadataProvider | null | undefined}
          */
         dateMetadataProvider: {
           type: Function,
@@ -295,8 +312,7 @@ export const DatePickerMixin = (subclass) =>
       return [
         '_selectedDateChanged(_selectedDate, __effectiveI18n)',
         '_focusedDateChanged(_focusedDate, __effectiveI18n)',
-        '__updateOverlayContent(_overlayContent, __effectiveI18n, label, _minDate, _maxDate, _focusedDate, _selectedDate, showWeekNumbers, isDateDisabled, dateMetadataProvider, __enteredDate)',
-        '__dateMetadataProviderChanged(dateMetadataProvider)',
+        '__updateOverlayContent(_overlayContent, __effectiveI18n, label, _minDate, _maxDate, _focusedDate, _selectedDate, showWeekNumbers, isDateDisabled, __enteredDate)',
         '__updateOverlayContentTheme(_overlayContent, _theme)',
         '__updateOverlayContentFullScreen(_overlayContent, _fullscreen)',
       ];
@@ -307,7 +323,7 @@ export const DatePickerMixin = (subclass) =>
     }
 
     static get constraints() {
-      return [...super.constraints, 'min', 'max'];
+      return [...super.constraints, 'min', 'max', 'dateMetadataProvider'];
     }
 
     constructor() {
@@ -315,6 +331,9 @@ export const DatePickerMixin = (subclass) =>
 
       this._boundOnClick = this._onClick.bind(this);
       this._boundOnScroll = this._onScroll.bind(this);
+
+      this._dateMetadataController = new DateMetadataController(this, () => this.__onDateMetadataChanged());
+      this.addController(this._dateMetadataController);
     }
 
     /**
@@ -357,6 +376,10 @@ export const DatePickerMixin = (subclass) =>
      *   // Translation of the Cancel button text.
      *   cancel: 'Cancel',
      *
+     *   // Accessible name of the overlay content, announced by screen readers
+     *   // when the overlay opens.
+     *   dialogAccessibleName: 'Calendar',
+     *
      *   // Used for adjusting the year value when parsing dates with short years.
      *   // The year values between 0 and 99 are evaluated and adjusted.
      *   // Example: for a referenceDate of 1970-10-30;
@@ -436,7 +459,10 @@ export const DatePickerMixin = (subclass) =>
       super._onFocus(event);
 
       if (this._noInput && !isKeyboardActive()) {
+        // Blur to hide the virtual keyboard, but do not validate.
+        this.__ignoreInternalBlur = true;
         event.target.blur();
+        this.__ignoreInternalBlur = false;
       }
     }
 
@@ -447,6 +473,10 @@ export const DatePickerMixin = (subclass) =>
     _onBlur(event) {
       super._onBlur(event);
 
+      if (this.__ignoreInternalBlur) {
+        return;
+      }
+
       if (!this.opened) {
         this.__commitParsedOrFocusedDate();
 
@@ -472,13 +502,6 @@ export const DatePickerMixin = (subclass) =>
 
       this.addController(new VirtualKeyboardController(this));
 
-      // Owns the cache of dates resolved by `dateMetadataProvider`. It lives on the date-picker
-      // rather than the overlay content so validation works even when the overlay is never opened.
-      // The open overlay reads the same controller to render months and show the loading spinner.
-      this._dateMetadataController = new DateMetadataController(this, () => this.__onDateMetadataChanged());
-      this.addController(this._dateMetadataController);
-      this._dateMetadataController.setProvider(this.dateMetadataProvider);
-
       this._overlayElement = this.$.overlay;
     }
 
@@ -486,6 +509,11 @@ export const DatePickerMixin = (subclass) =>
     updated(props) {
       super.updated(props);
 
+      if (props.has('dateMetadataProvider')) {
+        this._dateMetadataController.setProvider(this.dateMetadataProvider);
+        this.__reloadDateMetadata();
+      }
+
       if (props.has('showWeekNumbers') || props.has('__effectiveI18n')) {
         // Currently only supported for locales that start the week on Monday.
         this.toggleAttribute('week-numbers', this.showWeekNumbers && this.__effectiveI18n.firstDayOfWeek === 1);
@@ -529,22 +557,24 @@ export const DatePickerMixin = (subclass) =>
     }
 
     /**
-     * Clears the cached date metadata and reloads it from `dateMetadataProvider`. Call this when
-     * the data behind the provider has changed (for example a date became booked) so the calendar
-     * reflects it, without having to replace the provider function.
-     *
-     * The visible range is reloaded when the overlay is open, and the selected value is
-     * re-validated once its month resolves.
+     * Clears the `dateMetadataProvider` cache and reloads the date metadata.
      */
     clearCache() {
-      const controller = this._dateMetadataController;
-      if (!controller) {
-        return;
+      this._dateMetadataController.clearCache();
+      this.__reloadDateMetadata();
+    }
+
+    /**
+     * Asks for what the dropped cache was holding: the months the overlay is showing, and the month
+     * of the value being validated. Requested from here rather than from the controller's
+     * notification, which would turn a provider that keeps failing into an endless retry, since a
+     * failed month is dropped and so becomes missing again.
+     * @private
+     */
+    __reloadDateMetadata() {
+      if (this.opened) {
+        this._overlayContent?.loadVisibleDateMetadata();
       }
-      // Drops the cache and notifies, which re-renders the open overlay in the pending state and
-      // reloads its visible range (via __updateCalendars). Also reload the selected month so a
-      // value can be re-validated even while the overlay is closed.
-      controller.reset();
       this.__ensureSelectedDateLoaded();
     }
 
@@ -641,8 +671,13 @@ export const DatePickerMixin = (subclass) =>
       const inputValid = !inputValue || (!!this._selectedDate && inputValue === this.__formatDate(this._selectedDate));
       const isDateValid =
         !this._selectedDate ||
-        (dateAllowed(this._selectedDate, this._minDate, this._maxDate, this.isDateDisabled) &&
-          !this.__isDateDisabledByProvider(this._selectedDate));
+        dateSelectable(
+          this._selectedDate,
+          this._minDate,
+          this._maxDate,
+          this.isDateDisabled,
+          this._dateMetadataController,
+        );
 
       let inputValidity = true;
       if (this.inputElement && this.inputElement.checkValidity) {
@@ -653,90 +688,44 @@ export const DatePickerMixin = (subclass) =>
     }
 
     /**
-     * Returns true if the given date is known to be disabled by `dateMetadataProvider`. The
-     * result comes from the controller's cache of already-loaded ranges. The month containing a
-     * selected date is loaded on demand (see `_selectedDateChanged`), so a value typed while the
-     * overlay is closed is re-validated once the provider answers (see `__onDateMetadataChanged`).
-     * Until then the date is treated as allowed, matching the overlay's rendering.
+     * Asks the controller for the month holding the selected date, so a value that was set or typed
+     * without ever opening the overlay is still checked against the provider. Validation is re-run
+     * from the host callback once the month resolves.
      * @private
      */
-    __isDateDisabledByProvider(date) {
+    __ensureSelectedDateLoaded() {
       const controller = this._dateMetadataController;
-      return !!controller && !!controller.provider && controller.isDateDisabled(date);
-    }
-
-    /** @private */
-    __dateMetadataProviderChanged(dateMetadataProvider) {
-      // The controller is created in `ready()`; `setProvider` is called there for the initial value.
-      if (this._dateMetadataController) {
-        this._dateMetadataController.setProvider(dateMetadataProvider);
-        this.__ensureSelectedDateLoaded();
+      const awaiting = !!(controller?.provider && this._selectedDate && !controller.isMonthLoaded(this._selectedDate));
+      // Always assigned, so clearing the value or removing the provider while a request is in
+      // flight disarms the pending re-validation, and a later answer for some other month does not
+      // re-validate a value that never waited for it.
+      this.__awaitingProviderValidation = awaiting;
+      if (awaiting) {
+        controller.ensureRangeLoaded(this._selectedDate, this._selectedDate);
       }
     }
 
     /**
-     * Asks the controller to resolve the month containing the selected date, so that a value set
-     * or typed while the overlay is closed can be validated against the provider without opening
-     * the overlay. When the month resolves, `__onDateMetadataChanged` re-runs validation.
+     * Called by the date metadata controller, one microtask after its state changed
+     * and coalesced, so this never writes reactive state from inside an update. The
+     * rendered months refresh on their own because they subscribe to the controller.
      * @private
      */
-    __ensureSelectedDateLoaded() {
-      const controller = this._dateMetadataController;
-      if (controller?.provider && this._selectedDate && !controller.isMonthLoaded(this._selectedDate)) {
-        this.__awaitingProviderValidation = true;
-        controller.ensureRangeLoaded(this._selectedDate, this._selectedDate);
-      }
-    }
-
-    /** @private */
     __onDateMetadataChanged() {
       const controller = this._dateMetadataController;
-      // Push the new loading and cache state to the open overlay so it re-renders the months and
-      // updates the spinner. When the overlay is closed there is nothing to update.
+
+      // Only the open overlay has a spinner to update and a today button to re-evaluate.
       if (this._overlayContent) {
-        this._overlayContent.loading = controller.loading;
-        this._overlayContent._dateMetadataVersion += 1;
+        this._overlayContent.loading = controller.isLoading();
+        this._overlayContent.updateTodayButton();
       }
-      // Re-validate once the month containing the selected value has resolved, so a value typed
-      // while the picker was closed (autoOpenDisabled) is rejected as soon as the provider answers.
+
+      // Runs whether or not the overlay was ever opened, which is the case this exists for: a value
+      // set or typed with the overlay closed is reported invalid as soon as its month answers.
       if (this.__awaitingProviderValidation && this._selectedDate && controller.isMonthLoaded(this._selectedDate)) {
         this.__awaitingProviderValidation = false;
         this._requestValidation();
       }
-
-      this.__adjustInitialFocusForProvider();
-    }
-
-    /**
-     * Moves the overlay's initial focus off a date the provider turns out to disable, once the
-     * provider has answered for that month. Only touches the auto-picked initial date and only
-     * while the user has not navigated away, so disabled dates the user focuses on purpose (which
-     * stay keyboard-focusable) are left alone.
-     * @private
-     */
-    __adjustInitialFocusForProvider() {
-      const content = this._overlayContent;
-      const controller = this._dateMetadataController;
-      const initial = this.__initialFocusDate;
-      if (!content || !initial || !controller.provider) {
-        return;
-      }
-      // The user has moved focus; stop trying to adjust the initial date.
-      if (!dateEquals(content.focusedDate, initial)) {
-        this.__initialFocusDate = null;
-        return;
-      }
-      // Wait until the provider has answered for the initial month.
-      if (!controller.isMonthLoaded(initial)) {
-        return;
-      }
-      this.__initialFocusDate = null;
-      if (controller.isDateDisabled(initial)) {
-        const closest = content.__closestSelectableDate(initial);
-        if (closest) {
-          content.focusDate(closest);
-        }
-      }
     }
 
     /**
@@ -922,14 +911,12 @@ export const DatePickerMixin = (subclass) =>
         this._applyInputValue(selectedDate);
       }
 
-      // Preload the provider's answer for the selected month so the value can be validated even
-      // when the overlay is never opened.
-      this.__ensureSelectedDateLoaded();
-
       this.value = this._formatISO(selectedDate);
       this._ignoreFocusedDateChange = true;
       this._focusedDate = selectedDate;
       this._ignoreFocusedDateChange = false;
+
+      this.__ensureSelectedDateLoaded();
     }
 
     /** @private */
@@ -997,12 +984,10 @@ export const DatePickerMixin = (subclass) =>
       selectedDate,
       showWeekNumbers,
       isDateDisabled,
-      dateMetadataProvider,
       enteredDate,
     ) {
       if (overlayContent) {
-        // Share the date-picker's controller so the overlay renders from the same cache that
-        // validation uses. Assigned before the other properties, which trigger `__updateCalendars`.
+        // Reuse the date-picker's controller so the overlay shares the same cache.
         overlayContent._dateMetadataController = this._dateMetadataController;
         overlayContent.i18n = effectiveI18n;
         overlayContent.label = label;
@@ -1012,7 +997,6 @@ export const DatePickerMixin = (subclass) =>
         overlayContent.selectedDate = selectedDate;
         overlayContent.showWeekNumbers = showWeekNumbers;
         overlayContent.isDateDisabled = isDateDisabled;
-        overlayContent.dateMetadataProvider = dateMetadataProvider;
         overlayContent.enteredDate = enteredDate;
       }
     }
@@ -1020,11 +1004,7 @@ export const DatePickerMixin = (subclass) =>
     /** @private */
     __updateOverlayContentTheme(overlayContent, theme) {
       if (overlayContent) {
-        if (theme) {
-          overlayContent.setAttribute('theme', theme);
-        } else {
-          overlayContent.removeAttribute('theme');
-        }
+        setOrRemoveAttribute(overlayContent, 'theme', theme);
       }
     }
 
@@ -1061,12 +1041,6 @@ export const DatePickerMixin = (subclass) =>
       content.focusedDate = scrollFocusDate;
       this._ignoreFocusedDateChange = false;
 
-      // When opening without a selected value, remember the auto-picked initial date so it can be
-      // moved off a provider-disabled date once the provider answers (see __onDateMetadataChanged).
-      // A date the user selected themselves is left in place even if the provider disables it.
-      this.__initialFocusDate = this._selectedDate ? null : scrollFocusDate;
-      this.__adjustInitialFocusForProvider();
-
       window.addEventListener('scroll', this._boundOnScroll, true);
 
       if (this._focusOverlayOnOpen) {
@@ -1130,7 +1104,7 @@ export const DatePickerMixin = (subclass) =>
 
     /** @protected */
     _onOverlayClosed() {
-      this.__initialFocusDate = null;
+      this._overlayContent?.cancelLoadVisibleDateMetadata();
 
       // Reset `aria-hidden` state.
       if (this.__showOthers) {
@@ -1150,6 +1124,12 @@ export const DatePickerMixin = (subclass) =>
       if (!this.value && !this._keyboardActive) {
         this._requestValidation();
       }
+
+      // Focusout events while closing arrive with `opened` still true and keep the focused state.
+      // Clear it here unless focus was restored to the input, as at a wide viewport or on Esc.
+      if (!this.inputElement || !isElementFocused(this.inputElement)) {
+        this._setFocused(false);
+      }
     }
 
     /** @private */