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

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

@@ -106,6 +106,38 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           type: Function,
         },
 
+        /**
+         * A batch function that fetches metadata (disabled state, custom part names, ...) for a
+         * range of dates the calendar is about to render. Returns, or resolves with, an array of
+         * `DatePickerDateMetadata` objects.
+         *
+         * @type {function(DatePickerDateRange): Array<DatePickerDateMetadata> | Promise<Array<DatePickerDateMetadata>> | undefined}
+         */
+        dateMetadataProvider: {
+          type: Function,
+        },
+
+        /**
+         * Reflected while data is being loaded, so the overlay can show a loading spinner.
+         * Currently set while the date metadata provider is resolving.
+         */
+        loading: {
+          type: Boolean,
+          value: false,
+          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
+         */
+        _dateMetadataVersion: {
+          type: Number,
+          value: 0,
+          attribute: false,
+        },
+
         enteredDate: {
           type: Date,
           sync: true,
@@ -138,9 +170,10 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     static get observers() {
       return [
-        '__updateCalendars(calendars, i18n, minDate, maxDate, selectedDate, focusedDate, showWeekNumbers, _ignoreTaps, _theme, isDateDisabled, enteredDate)',
+        '__updateCalendars(calendars, i18n, minDate, maxDate, selectedDate, focusedDate, showWeekNumbers, _ignoreTaps, _theme, isDateDisabled, _dateMetadataVersion, enteredDate)',
+        '__loadingChanged(loading)',
         '__updateCancelButton(_cancelButton, i18n)',
-        '__updateTodayButton(_todayButton, i18n, minDate, maxDate, isDateDisabled)',
+        '__updateTodayButton(_todayButton, i18n, minDate, maxDate, isDateDisabled, _dateMetadataVersion)',
         '__updateYears(years, selectedDate, _theme)',
       ];
     }
@@ -299,6 +332,17 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       }
     }
 
+    /** @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');
+      }
+    }
+
     // eslint-disable-next-line @typescript-eslint/max-params
     __updateCalendars(
       calendars,
@@ -311,6 +355,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       ignoreTaps,
       theme,
       isDateDisabled,
+      dateMetadataVersion,
       enteredDate,
     ) {
       if (calendars?.length) {
@@ -319,6 +364,8 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           calendar.minDate = minDate;
           calendar.maxDate = maxDate;
           calendar.isDateDisabled = isDateDisabled;
+          calendar.dateMetadataController = this._dateMetadataController;
+          calendar.__dateMetadataVersion = dateMetadataVersion;
           calendar.focusedDate = focusedDate;
           calendar.selectedDate = selectedDate;
           calendar.showWeekNumbers = showWeekNumbers;
@@ -331,7 +378,46 @@ export const DatePickerOverlayContentMixin = (superClass) =>
             calendar.removeAttribute('theme');
           }
         });
+
+        this.__ensureVisibleDateMetadataLoaded();
+      }
+    }
+
+    /**
+     * 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.
+     * @private
+     */
+    __ensureVisibleDateMetadataLoaded() {
+      const controller = this._dateMetadataController;
+      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),
+      );
+    }
+
+    /**
+     * Debounced variant used on scroll, so a continuous scroll only triggers one load once it
+     * settles instead of a request per intermediate position.
+     * @private
+     */
+    __scheduleVisibleDateMetadataLoad() {
+      this._loadDateMetadataDebouncer = Debouncer.debounce(this._loadDateMetadataDebouncer, timeOut.after(200), () =>
+        this.__ensureVisibleDateMetadataLoaded(),
+      );
     }
 
     /** @private */
@@ -357,6 +443,11 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       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._dateMetadataController?.isDateBlocked(dateToSelect)) {
+        return false;
+      }
       this.selectedDate = dateToSelect;
       this.dispatchEvent(
         new CustomEvent('date-selected', { detail: { date: dateToSelect }, bubbles: true, composed: true }),
@@ -452,12 +543,17 @@ 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.__scheduleVisibleDateMetadataLoad();
     }
 
     /** @private */
     _repositionMonthScroller() {
       this._monthScroller.position = this._yearScroller.position * 12 - this._originDate.getMonth();
       this._visibleMonthIndex = Math.floor(this._monthScroller.position);
+      this.__scheduleVisibleDateMetadataLoad();
     }
 
     /** @private */
@@ -831,6 +927,33 @@ 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 `dateMetadataProvider`. 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._dateMetadataController;
+      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
@@ -918,7 +1041,12 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _isTodayAllowed(min, max, isDateDisabled) {
-      return this._dateAllowed(this._getTodayMidnight(), 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._dateMetadataController?.isDateBlocked(today);
     }
 
     /** @private */

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

@@ -12,12 +12,14 @@ import { html, LitElement } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { loaderStyles } from '@vaadin/component-base/src/styles/loader-styles.js';
 import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { overlayContentStyles } from './styles/vaadin-date-picker-overlay-content-base-styles.js';
 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
@@ -30,7 +32,7 @@ class DatePickerOverlayContent extends DatePickerOverlayContentMixin(
   }
 
   static get styles() {
-    return overlayContentStyles;
+    return [loaderStyles, overlayContentStyles];
   }
 
   static get lumoInjector() {
@@ -43,6 +45,8 @@ class DatePickerOverlayContent extends DatePickerOverlayContentMixin(
       <slot name="months"></slot>
       <slot name="years"></slot>
 
+      <div part="loader" aria-hidden="true"></div>
+
       <div role="toolbar" part="toolbar">
         <slot name="today-button"></slot>
         <div

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,6 +13,7 @@ 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

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

@@ -7,7 +7,12 @@ 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, DatePickerI18n } from './vaadin-date-picker-mixin.js';
+export {
+  DatePickerDate,
+  DatePickerDateMetadata,
+  DatePickerDateRange,
+  DatePickerI18n,
+} from './vaadin-date-picker-mixin.js';
 
 /**
  * Fired when the user commits a value change.
@@ -148,12 +153,17 @@ export interface DatePickerEventMap extends HTMLElementEventMap, DatePickerCusto
  * `week-number`         | Week number element
  * `date`                | Date element
  * `disabled`            | Disabled date element
+ * `pending`             | Date element in a month whose date metadata provider result is still loading
  * `focused`             | Focused date element
  * `selected`            | Selected date element
  * `today`               | Date element corresponding to the current day
  * `past`                | Date element corresponding to the date in the past
  * `future`              | Date element corresponding to the date in the future
  *
+ * Custom part names returned per date by `dateMetadataProvider` (the `part` metadata field) are
+ * also added to the matching date elements, so specific dates can be styled with
+ * `vaadin-month-calendar::part(<name>)`.
+ *
  * In order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:
  *
  * Part name             | Description

package/src/vaadin-date-picker.js

@@ -92,6 +92,7 @@ import { DatePickerMixin } from './vaadin-date-picker-mixin.js';
  * ----------------------|--------------------
  * `years-toggle-button` | Fullscreen mode years scroller toggle
  * `toolbar`             | Toolbar with slotted buttons
+ * `loader`              | Loading spinner shown while data is being loaded, for example while the disabled dates provider resolves
  *
  * The following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:
  *
@@ -100,6 +101,7 @@ import { DatePickerMixin } from './vaadin-date-picker-mixin.js';
  * `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 data is being loaded, for example while the disabled dates provider resolves
  *
  * In order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:
  *
@@ -112,12 +114,17 @@ import { DatePickerMixin } from './vaadin-date-picker-mixin.js';
  * `week-number`         | Week number element
  * `date`                | Date element
  * `disabled`            | Disabled date element
+ * `pending`             | Date element in a month whose date metadata provider result is still loading
  * `focused`             | Focused date element
  * `selected`            | Selected date element
  * `today`               | Date element corresponding to the current day
  * `past`                | Date element corresponding to the date in the past
  * `future`              | Date element corresponding to the date in the future
  *
+ * Custom part names returned per date by `dateMetadataProvider` (the `part` metadata field) are
+ * also added to the matching date elements, so specific dates can be styled with
+ * `vaadin-month-calendar::part(<name>)`.
+ *
  * In order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:
  *
  * Part name             | Description
@@ -150,6 +157,7 @@ import { DatePickerMixin } from './vaadin-date-picker-mixin.js';
  * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  * @fires {CustomEvent} validated - Fired whenever the field is validated.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-date-picker
  * @extends HTMLElement
  */

package/src/vaadin-month-calendar-mixin.js

@@ -87,6 +87,28 @@ export const MonthCalendarMixin = (superClass) =>
           value: () => false,
         },
 
+        /**
+         * The shared controller that resolves and caches the dates disabled by the date-picker's
+         * `dateMetadataProvider`. Set by the overlay content; used to look up the disabled state
+         * of this month's dates.
+         * @type {object | undefined}
+         * @private
+         */
+        dateMetadataController: {
+          type: Object,
+          attribute: false,
+        },
+
+        /**
+         * Bumped by the overlay content whenever the controller's cache or loading state changes,
+         * to trigger a re-render of this month.
+         * @private
+         */
+        __dateMetadataVersion: {
+          type: Number,
+          attribute: false,
+        },
+
         enteredDate: {
           type: Date,
         },
@@ -100,7 +122,8 @@ export const MonthCalendarMixin = (superClass) =>
         /** @protected */
         _days: {
           type: Array,
-          computed: '__computeDays(month, i18n, minDate, maxDate, isDateDisabled)',
+          computed:
+            '__computeDays(month, i18n, minDate, maxDate, isDateDisabled, dateMetadataController, __dateMetadataVersion)',
         },
 
         /** @protected */
@@ -345,6 +368,10 @@ export const MonthCalendarMixin = (superClass) =>
         result.push('disabled');
       }
 
+      if (date && this.__isMonthLoading()) {
+        result.push('pending');
+      }
+
       if (dateEquals(date, focusedDate) && (hasFocus || dateEquals(date, enteredDate))) {
         result.push('focused');
       }
@@ -365,6 +392,13 @@ export const MonthCalendarMixin = (superClass) =>
         result.push('future');
       }
 
+      // Custom part names supplied per date by `dateMetadataProvider`, so a theme can style
+      // specific dates (e.g. mark a date as busy or almost fully booked) via `::part()`.
+      const part = date && this.dateMetadataController?.getMetadata(date)?.part;
+      if (part) {
+        result.push(...(Array.isArray(part) ? part : String(part).split(' ')).filter(Boolean));
+      }
+
       return result.join(' ');
     }
 
@@ -378,9 +412,24 @@ export const MonthCalendarMixin = (superClass) =>
       return String(this.__isDaySelected(date, selectedDate));
     }
 
+    /**
+     * Whether the provider result for the currently displayed month is still pending. The overlay
+     * drives loading for the whole visible range; here we only reflect the controller's state.
+     * @private
+     */
+    __isMonthLoading() {
+      const controller = this.dateMetadataController;
+      return !!controller?.provider && this.month !== undefined && !controller.isMonthLoaded(this.month);
+    }
+
     /** @private */
     __isDayDisabled(date, minDate, maxDate, isDateDisabled) {
-      return !dateAllowed(date, minDate, maxDate, isDateDisabled);
+      if (!dateAllowed(date, minDate, maxDate, isDateDisabled)) {
+        return true;
+      }
+      // A date is blocked while its month is pending (whole month non-selectable) or once the
+      // resolved provider result marks it disabled.
+      return !!this.dateMetadataController?.isDateBlocked(date);
     }
 
     /** @private */

package/src/vaadin-month-calendar.js

@@ -12,6 +12,7 @@ import { monthCalendarStyles } from './styles/vaadin-month-calendar-base-styles.
 import { MonthCalendarMixin } from './vaadin-month-calendar-mixin.js';
 
 /**
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-month-calendar
  * @extends HTMLElement
  * @private

package/web-types.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha6",
+  "version": "25.3.0-dev.1fa5a51482",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-date-picker",
-          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                | Description                | Default\n-------------------------------|----------------------------|---------\n`--vaadin-field-default-width` | Default width of the field | `12em`\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
+          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                | Description                | Default\n-------------------------------|----------------------------|---------\n`--vaadin-field-default-width` | Default width of the field | `12em`\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n`loader`              | Loading spinner shown while data is being loaded, for example while the disabled dates provider resolves\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n`loading`       | Set while data is being loaded, for example while the disabled dates provider resolves\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`pending`             | Date element in a month whose date metadata provider result is still loading\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nCustom part names returned per date by `dateMetadataProvider` (the `part` metadata field) are\nalso added to the matching date elements, so specific dates can be styled with\n`vaadin-month-calendar::part(<name>)`.\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
           "attributes": [
             {
               "name": "accessible-name",
@@ -213,9 +213,7 @@
               "description": "The theme variants to apply to the component.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -303,6 +301,17 @@
                   ]
                 }
               },
+              {
+                "name": "dateMetadataProvider",
+                "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` object (`{ start, end }` of `DatePickerDate`)\nand returns, or resolves with, an array of metadata objects — a `DatePickerDate` extended\nwith metadata fields such as `disabled` and custom `part` names, e.g.\n`{ year, month, day, disabled: true, part: 'busy' }` — for the dates that have metadata\nwithin that range.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of\nthe range is decided by the calendar and may span multiple months. It may return a\n`Promise`, in which case the affected dates render in a non-selectable pending state\nuntil it resolves.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date\nis disabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. `part` names are added to the date cell's `part` attribute so\na theme can style specific dates via `::part()`.\n\nBoth `disabled` and `part` are returned by this one function, rather than by separate\ngenerators, so a single backend query (for example in Flow) can answer both at once\ninstead of being split into two passes over the same data.\n\nKeep a stable reference to the function. Assigning a new function resets the internal\ncache and re-fetches every visible range. To reload after the underlying data changes\nwhile keeping the same function, call `clearCache()`.",
+                "value": {
+                  "type": [
+                    "function DatePickerDateRange: Array<DatePickerDateMetadata>",
+                    "Promise<Array<DatePickerDateMetadata>>",
+                    "undefined"
+                  ]
+                }
+              },
               {
                 "name": "disabled",
                 "description": "If true, the user cannot interact with this element.",

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha6",
+  "version": "25.3.0-dev.1fa5a51482",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,7 +16,7 @@
       "elements": [
         {
           "name": "vaadin-date-picker",
-          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                | Description                | Default\n-------------------------------|----------------------------|---------\n`--vaadin-field-default-width` | Default width of the field | `12em`\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
+          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                | Description                | Default\n-------------------------------|----------------------------|---------\n`--vaadin-field-default-width` | Default width of the field | `12em`\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n`loader`              | Loading spinner shown while data is being loaded, for example while the disabled dates provider resolves\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n`loading`       | Set while data is being loaded, for example while the disabled dates provider resolves\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`pending`             | Date element in a month whose date metadata provider result is still loading\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nCustom part names returned per date by `dateMetadataProvider` (the `part` metadata field) are\nalso added to the matching date elements, so specific dates can be styled with\n`vaadin-month-calendar::part(<name>)`.\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
           "extension": true,
           "attributes": [
             {
@@ -68,6 +68,13 @@
                 "kind": "expression"
               }
             },
+            {
+              "name": ".dateMetadataProvider",
+              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` object (`{ start, end }` of `DatePickerDate`)\nand returns, or resolves with, an array of metadata objects — a `DatePickerDate` extended\nwith metadata fields such as `disabled` and custom `part` names, e.g.\n`{ year, month, day, disabled: true, part: 'busy' }` — for the dates that have metadata\nwithin that range.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of\nthe range is decided by the calendar and may span multiple months. It may return a\n`Promise`, in which case the affected dates render in a non-selectable pending state\nuntil it resolves.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date\nis disabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. `part` names are added to the date cell's `part` attribute so\na theme can style specific dates via `::part()`.\n\nBoth `disabled` and `part` are returned by this one function, rather than by separate\ngenerators, so a single backend query (for example in Flow) can answer both at once\ninstead of being split into two passes over the same data.\n\nKeep a stable reference to the function. Assigning a new function resets the internal\ncache and re-fetches every visible range. To reload after the underlying data changes\nwhile keeping the same function, call `clearCache()`.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": "?disabled",
               "description": "If true, the user cannot interact with this element.",