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

package/src/vaadin-date-metadata-controller.js

@@ -0,0 +1,254 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { extractDateParts } from './vaadin-date-picker-helper.js';
+
+/**
+ * Number of months fetched before and after the requested range, so that
+ * scrolling a few months in either direction does not trigger a new request.
+ * Mirrors how the grid prefetches rows around the viewport.
+ */
+const PREFETCH_MONTHS = 6;
+
+function monthKey(date) {
+  return `${date.getFullYear()}-${date.getMonth()}`;
+}
+
+function dateKey(date) {
+  return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+}
+
+function firstOfMonth(date) {
+  return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+
+function lastOfMonth(date) {
+  return new Date(date.getFullYear(), date.getMonth() + 1, 0);
+}
+
+function addMonths(date, months) {
+  return new Date(date.getFullYear(), date.getMonth() + months, 1);
+}
+
+/**
+ * A reactive controller that resolves the metadata (disabled state, custom part
+ * names, ...) for the dates shown by the date-picker's `dateMetadataProvider`.
+ * It calls the provider once for a range of months (never one date at a time),
+ * caches the resolved months so scrolling back and forth does not re-fetch them,
+ * and prefetches a buffer of months around the requested range. While any
+ * request is in flight, {@link #loading} is `true` so the overlay can show a
+ * spinner.
+ *
+ * The provider may return an array synchronously or a `Promise`, so results
+ * from a server (Flow) or a remote availability service can be awaited. Each
+ * returned entry is a `DatePickerDate` extended with metadata fields, e.g.
+ * `{ year, month, day, disabled: true, part: 'busy' }`.
+ */
+export class DateMetadataController {
+  constructor(host, onChange) {
+    this.host = host;
+    this.__onChange = onChange;
+    this.provider = null;
+    this.__metadata = new Map();
+    this.__loadedMonths = new Set();
+    this.__pendingMonths = new Set();
+    this.__requestId = 0;
+  }
+
+  hostDisconnected() {
+    // Invalidate in-flight requests so their late results don't touch a
+    // detached host, and drop the pending (loading) state. The resolved cache
+    // is kept so reopening the overlay does not re-fetch.
+    this.__requestId += 1;
+    this.__pendingMonths = new Set();
+  }
+
+  /**
+   * Whether any month range is currently being fetched.
+   * @return {boolean}
+   */
+  get loading() {
+    return this.__pendingMonths.size > 0;
+  }
+
+  /**
+   * Sets the provider function and clears the cache. Passing the same provider
+   * again is a no-op, so the cache survives unrelated re-renders — callers
+   * should therefore keep a stable provider reference rather than passing a new
+   * function on every update, which would otherwise reset the cache and
+   * re-fetch every visible range.
+   */
+  setProvider(provider) {
+    if (this.provider === provider) {
+      return;
+    }
+    this.provider = provider;
+    this.reset();
+  }
+
+  /** Clears the cache and invalidates any in-flight requests. */
+  reset() {
+    this.__metadata = new Map();
+    this.__loadedMonths = new Set();
+    this.__pendingMonths = new Set();
+    this.__requestId += 1;
+    this.__notify();
+  }
+
+  /**
+   * Whether the month containing the given date has been fully resolved.
+   * @param {Date} date
+   * @return {boolean}
+   */
+  isMonthLoaded(date) {
+    return this.__loadedMonths.has(monthKey(date));
+  }
+
+  /**
+   * The metadata resolved for the given date, or `undefined` when the date has
+   * no metadata or its month has not been resolved yet.
+   * @param {Date} date
+   * @return {object | undefined}
+   */
+  getMetadata(date) {
+    return date ? this.__metadata.get(dateKey(date)) : undefined;
+  }
+
+  /**
+   * Whether the given date is disabled by the provider. Only returns `true` for
+   * dates in an already-resolved month.
+   * @param {Date} date
+   * @return {boolean}
+   */
+  isDateDisabled(date) {
+    return !!this.getMetadata(date)?.disabled;
+  }
+
+  /**
+   * Whether the given date cannot be selected yet: it is disabled by the
+   * provider, or its month has not been resolved so its state is still unknown.
+   * Returns `false` when no provider is set. Used to block selection and to
+   * render dates as non-selectable while their month is loading.
+   * @param {Date} date
+   * @return {boolean}
+   */
+  isDateBlocked(date) {
+    return !!this.provider && !!date && (this.isDateDisabled(date) || !this.isMonthLoaded(date));
+  }
+
+  /**
+   * Ensures the provider has been consulted for the inclusive range between the
+   * given dates, expanded by a prefetch buffer of months on each side. Months
+   * that are already loaded or in flight are skipped, and consecutive missing
+   * months are grouped into a single provider call.
+   *
+   * @param {Date} startDate
+   * @param {Date} endDate
+   */
+  ensureRangeLoaded(startDate, endDate) {
+    if (!this.provider || !startDate || !endDate) {
+      return;
+    }
+
+    const first = addMonths(firstOfMonth(startDate), -PREFETCH_MONTHS);
+    const last = addMonths(firstOfMonth(endDate), PREFETCH_MONTHS);
+
+    const monthsToLoad = [];
+    for (let month = first; month <= last; month = addMonths(month, 1)) {
+      const key = monthKey(month);
+      if (!this.__loadedMonths.has(key) && !this.__pendingMonths.has(key)) {
+        monthsToLoad.push(new Date(month));
+      }
+    }
+
+    if (monthsToLoad.length === 0) {
+      return;
+    }
+
+    this.__groupConsecutiveMonths(monthsToLoad).forEach((group) => this.__loadGroup(group));
+  }
+
+  /** @private */
+  __groupConsecutiveMonths(months) {
+    const groups = [];
+    months.forEach((month) => {
+      const group = groups.at(-1);
+      const previous = group?.at(-1);
+      if (previous && monthKey(addMonths(previous, 1)) === monthKey(month)) {
+        group.push(month);
+      } else {
+        groups.push([month]);
+      }
+    });
+    return groups;
+  }
+
+  /** @private */
+  __loadGroup(months) {
+    const requestId = this.__requestId;
+    months.forEach((month) => this.__pendingMonths.add(monthKey(month)));
+    this.__notify();
+
+    const range = {
+      start: extractDateParts(firstOfMonth(months[0])),
+      end: extractDateParts(lastOfMonth(months[months.length - 1])),
+    };
+
+    let result;
+    try {
+      result = this.provider(range);
+    } catch (error) {
+      // Treat a throwing provider the same as a rejected promise: clear the
+      // pending state and disable nothing, rather than letting the error
+      // propagate out of the scroll/render path that triggered the load.
+      console.error(error);
+      this.__resolveGroup(months, [], requestId);
+      return;
+    }
+
+    if (result && typeof result.then === 'function') {
+      result.then(
+        (dates) => this.__resolveGroup(months, dates, requestId),
+        (error) => {
+          console.error(error);
+          this.__resolveGroup(months, [], requestId);
+        },
+      );
+    } else {
+      this.__resolveGroup(months, result, requestId);
+    }
+  }
+
+  /** @private */
+  __resolveGroup(months, entries, requestId) {
+    // Ignore results from before the last reset (e.g. provider changed).
+    if (requestId !== this.__requestId) {
+      return;
+    }
+
+    if (Array.isArray(entries)) {
+      entries.forEach((entry) => {
+        if (entry) {
+          this.__metadata.set(`${entry.year}-${entry.month}-${entry.day}`, entry);
+        }
+      });
+    }
+
+    months.forEach((month) => {
+      const key = monthKey(month);
+      this.__pendingMonths.delete(key);
+      this.__loadedMonths.add(key);
+    });
+
+    this.__notify();
+  }
+
+  /** @private */
+  __notify() {
+    if (this.__onChange) {
+      this.__onChange();
+    }
+  }
+}

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

@@ -18,6 +18,34 @@ export interface DatePickerDate {
   year: number;
 }
 
+export interface DatePickerDateRange {
+  /**
+   * The first date of the range (inclusive).
+   */
+  start: DatePickerDate;
+  /**
+   * The last date of the range (inclusive).
+   */
+  end: DatePickerDate;
+}
+
+/**
+ * Metadata resolved on demand for a single date by `dateMetadataProvider`. Extends
+ * `DatePickerDate` with the date's metadata. Extra fields can be added and used by the
+ * synchronous generators (e.g. `isDateDisabled`) as context.
+ */
+export interface DatePickerDateMetadata extends DatePickerDate {
+  /**
+   * Whether the date cannot be selected.
+   */
+  disabled?: boolean;
+  /**
+   * Custom part name(s) added to the date cell's `part` attribute, so a theme can style the
+   * date via `::part()`. Either a single name or several separated by spaces.
+   */
+  part?: string;
+}
+
 export interface DatePickerI18n {
   /**
    * An array with the full names of months starting
@@ -236,6 +264,31 @@ export declare class DatePickerMixinClass {
    */
   isDateDisabled: (date: DatePickerDate) => boolean;
 
+  /**
+   * A batch function that fetches metadata for a range of dates the calendar is about to render.
+   * It receives a `DatePickerDateRange` object and returns, or resolves with, an array of
+   * `DatePickerDateMetadata` objects (a `DatePickerDate` extended with metadata such as
+   * `disabled` and custom `part` names) for the dates that have metadata within that range.
+   *
+   * 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.
+   *
+   * `disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is
+   * disabled if it is out of range, or `isDateDisabled` returns `true`, or its metadata marks it
+   * disabled. `part` names are added to the date cell so a theme can style it via `::part()`.
+   *
+   * 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.
+   *
+   * 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()`.
+   */
+  dateMetadataProvider: (range: DatePickerDateRange) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[]>;
+
   /**
    * Opens the dropdown.
    */
@@ -245,4 +298,11 @@ export declare class DatePickerMixinClass {
    * Closes the dropdown.
    */
   close(): void;
+
+  /**
+   * 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.
+   */
+  clearCache(): void;
 }

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

@@ -12,6 +12,7 @@ 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,
@@ -208,6 +209,39 @@ export const DatePickerMixin = (subclass) =>
           type: Function,
         },
 
+        /**
+         * 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.
+         *
+         * 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.
+         *
+         * `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()`.
+         *
+         * 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.
+         *
+         * 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()`.
+         *
+         * @type {function(DatePickerDateRange): Array<DatePickerDateMetadata> | Promise<Array<DatePickerDateMetadata>> | undefined}
+         */
+        dateMetadataProvider: {
+          type: Function,
+        },
+
         /**
          * The earliest date that can be selected. All earlier dates will be disabled.
          * @type {Date | undefined}
@@ -261,7 +295,8 @@ export const DatePickerMixin = (subclass) =>
       return [
         '_selectedDateChanged(_selectedDate, __effectiveI18n)',
         '_focusedDateChanged(_focusedDate, __effectiveI18n)',
-        '__updateOverlayContent(_overlayContent, __effectiveI18n, label, _minDate, _maxDate, _focusedDate, _selectedDate, showWeekNumbers, isDateDisabled, __enteredDate)',
+        '__updateOverlayContent(_overlayContent, __effectiveI18n, label, _minDate, _maxDate, _focusedDate, _selectedDate, showWeekNumbers, isDateDisabled, dateMetadataProvider, __enteredDate)',
+        '__dateMetadataProviderChanged(dateMetadataProvider)',
         '__updateOverlayContentTheme(_overlayContent, _theme)',
         '__updateOverlayContentFullScreen(_overlayContent, _fullscreen)',
       ];
@@ -437,6 +472,13 @@ 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 +528,26 @@ export const DatePickerMixin = (subclass) =>
       this.$.overlay.close();
     }
 
+    /**
+     * 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.
+     */
+    clearCache() {
+      const controller = this._dateMetadataController;
+      if (!controller) {
+        return;
+      }
+      // 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();
+    }
+
     /** @private */
     __ensureContent() {
       if (this._overlayContent) {
@@ -578,7 +640,9 @@ 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 ||
+        (dateAllowed(this._selectedDate, this._minDate, this._maxDate, this.isDateDisabled) &&
+          !this.__isDateDisabledByProvider(this._selectedDate));
 
       let inputValidity = true;
       if (this.inputElement && this.inputElement.checkValidity) {
@@ -588,6 +652,93 @@ export const DatePickerMixin = (subclass) =>
       return inputValid && isDateValid && inputValidity;
     }
 
+    /**
+     * 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.
+     * @private
+     */
+    __isDateDisabledByProvider(date) {
+      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();
+      }
+    }
+
+    /**
+     * 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.
+     * @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.
+      if (this._overlayContent) {
+        this._overlayContent.loading = controller.loading;
+        this._overlayContent._dateMetadataVersion += 1;
+      }
+      // 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.
+      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);
+        }
+      }
+    }
+
     /**
      * Override method inherited from `FocusMixin`
      * to not call `_setFocused(true)` when focus
@@ -771,6 +922,10 @@ 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;
@@ -842,9 +997,13 @@ 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`.
+        overlayContent._dateMetadataController = this._dateMetadataController;
         overlayContent.i18n = effectiveI18n;
         overlayContent.label = label;
         overlayContent.minDate = minDate;
@@ -853,6 +1012,7 @@ export const DatePickerMixin = (subclass) =>
         overlayContent.selectedDate = selectedDate;
         overlayContent.showWeekNumbers = showWeekNumbers;
         overlayContent.isDateDisabled = isDateDisabled;
+        overlayContent.dateMetadataProvider = dateMetadataProvider;
         overlayContent.enteredDate = enteredDate;
       }
     }
@@ -901,6 +1061,12 @@ 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) {
@@ -964,6 +1130,8 @@ export const DatePickerMixin = (subclass) =>
 
     /** @protected */
     _onOverlayClosed() {
+      this.__initialFocusDate = null;
+
       // Reset `aria-hidden` state.
       if (this.__showOthers) {
         this.__showOthers();