@vaadin/date-picker 25.3.0-alpha1 → 25.3.0-alpha11

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

@@ -18,6 +18,49 @@ export interface DatePickerDate {
   year: number;
 }
 
+/**
+ * A range of dates that `dateMetadataProvider` is asked about.
+ * It can span several months and always covers whole months.
+ */
+export interface DatePickerDateRange {
+  /**
+   * The first date of the range (inclusive), as an ISO 8601 date.
+   */
+  start: string;
+  /**
+   * The last date of the range (inclusive), as an ISO 8601 date.
+   */
+  end: string;
+}
+
+/**
+ * Metadata for a single date, returned by `dateMetadataProvider`.
+ */
+export interface DatePickerDateMetadata {
+  /**
+   * The date the metadata applies to in ISO 8601 format.
+   */
+  date: string;
+  /**
+   * Whether the date cannot be selected.
+   */
+  disabled?: boolean;
+  /**
+   * Part names to add to the date, so a theme can style it with `::part()`. A single name, or
+   * several separated by spaces. Do not use built-in names like `disabled` and `selected`.
+   */
+  part?: string;
+}
+
+/**
+ * A function called with the range of dates the calendar is about to render, returning
+ * the metadata for the dates in that range. It can return a `Promise` to load the metadata
+ * asynchronously, and `null` or `undefined` when no date in the range has metadata.
+ */
+export type DatePickerDateMetadataProvider = (
+  range: DatePickerDateRange,
+) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[] | null | undefined> | null | undefined;
+
 export interface DatePickerI18n {
   /**
    * An array with the full names of months starting
@@ -47,6 +90,11 @@ export interface DatePickerI18n {
    * Translation of the Cancel button text.
    */
   cancel?: string;
+  /**
+   * Accessible name of the overlay content, announced by screen readers when
+   * the overlay opens.
+   */
+  dialogAccessibleName?: string;
   /**
    * Used for adjusting the year value when parsing dates with short years.
    * The year values between 0 and 99 are evaluated and adjusted.
@@ -174,6 +222,10 @@ export declare class DatePickerMixinClass {
    *   // 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;
@@ -233,9 +285,52 @@ export declare class DatePickerMixinClass {
    * A function to be used to determine whether the user can select a given date.
    * 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.
    */
   isDateDisabled: (date: DatePickerDate) => boolean;
 
+  /**
+   * 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' },
+   * ]
+   * ```
+   *
+   * 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.
+   *
+   * 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.
+   *
+   * 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 one clears the cache and re-fetches
+   * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
+   */
+  dateMetadataProvider: DatePickerDateMetadataProvider | null | undefined;
+
   /**
    * Opens the dropdown.
    */
@@ -245,4 +340,9 @@ export declare class DatePickerMixinClass {
    * Closes the dropdown.
    */
   close(): void;
+
+  /**
+   * Clears the `dateMetadataProvider` cache and reloads the date metadata.
+   */
+  clearCache(): void;
 }

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

@@ -8,13 +8,16 @@ import { DelegateFocusMixin } from '@vaadin/a11y-base/src/delegate-focus-mixin.j
 import { 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';
 import { VirtualKeyboardController } from '@vaadin/field-base/src/virtual-keyboard-controller.js';
+import { DateMetadataController } from './vaadin-date-metadata-controller.js';
 import {
   dateAllowed,
   dateEquals,
+  dateSelectable,
   extractDateParts,
   formatISODate,
   getAdjustedYear,
@@ -42,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);
@@ -59,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) {
@@ -202,12 +206,59 @@ 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: {
           type: Function,
         },
 
+        /**
+         * 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' },
+         * ]
+         * ```
+         *
+         * 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.
+         *
+         * 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.
+         *
+         * 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 one clears the cache and re-fetches
+         * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
+         *
+         * @type {DatePickerDateMetadataProvider | null | undefined}
+         */
+        dateMetadataProvider: {
+          type: Function,
+        },
+
         /**
          * The earliest date that can be selected. All earlier dates will be disabled.
          * @type {Date | undefined}
@@ -272,7 +323,7 @@ export const DatePickerMixin = (subclass) =>
     }
 
     static get constraints() {
-      return [...super.constraints, 'min', 'max'];
+      return [...super.constraints, 'min', 'max', 'dateMetadataProvider'];
     }
 
     constructor() {
@@ -280,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);
     }
 
     /**
@@ -322,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;
@@ -444,6 +502,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);
@@ -486,6 +549,28 @@ export const DatePickerMixin = (subclass) =>
       this.$.overlay.close();
     }
 
+    /**
+     * Clears the `dateMetadataProvider` cache and reloads the date metadata.
+     */
+    clearCache() {
+      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();
+      }
+      this.__ensureSelectedDateLoaded();
+    }
+
     /** @private */
     __ensureContent() {
       if (this._overlayContent) {
@@ -578,7 +663,14 @@ export const DatePickerMixin = (subclass) =>
       const inputValue = this._inputElementValue;
       const inputValid = !inputValue || (!!this._selectedDate && inputValue === this.__formatDate(this._selectedDate));
       const isDateValid =
-        !this._selectedDate || dateAllowed(this._selectedDate, this._minDate, this._maxDate, this.isDateDisabled);
+        !this._selectedDate ||
+        dateSelectable(
+          this._selectedDate,
+          this._minDate,
+          this._maxDate,
+          this.isDateDisabled,
+          this._dateMetadataController,
+        );
 
       let inputValidity = true;
       if (this.inputElement && this.inputElement.checkValidity) {
@@ -588,6 +680,47 @@ export const DatePickerMixin = (subclass) =>
       return inputValid && isDateValid && inputValidity;
     }
 
+    /**
+     * 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
+     */
+    __ensureSelectedDateLoaded() {
+      const controller = this._dateMetadataController;
+      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);
+      }
+    }
+
+    /**
+     * 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
+     */
+    __onDateMetadataChanged() {
+      const controller = this._dateMetadataController;
+
+      // Only the open overlay has a spinner to update and a today button to re-evaluate.
+      if (this._overlayContent) {
+        this._overlayContent.loading = controller.isLoading();
+        this._overlayContent.updateTodayButton();
+      }
+
+      // 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();
+      }
+    }
+
     /**
      * Override method inherited from `FocusMixin`
      * to not call `_setFocused(true)` when focus
@@ -775,6 +908,8 @@ export const DatePickerMixin = (subclass) =>
       this._ignoreFocusedDateChange = true;
       this._focusedDate = selectedDate;
       this._ignoreFocusedDateChange = false;
+
+      this.__ensureSelectedDateLoaded();
     }
 
     /** @private */
@@ -845,6 +980,8 @@ export const DatePickerMixin = (subclass) =>
       enteredDate,
     ) {
       if (overlayContent) {
+        // Reuse the date-picker's controller so the overlay shares the same cache.
+        overlayContent._dateMetadataController = this._dateMetadataController;
         overlayContent.i18n = effectiveI18n;
         overlayContent.label = label;
         overlayContent.minDate = minDate;
@@ -860,11 +997,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);
       }
     }
 
@@ -964,6 +1097,8 @@ export const DatePickerMixin = (subclass) =>
 
     /** @protected */
     _onOverlayClosed() {
+      this._overlayContent?.cancelLoadVisibleDateMetadata();
+
       // Reset `aria-hidden` state.
       if (this.__showOthers) {
         this.__showOthers();