@vaadin/date-picker 25.3.0-alpha8 → 25.3.0-alpha9

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

@@ -18,6 +18,44 @@ export interface DatePickerDate {
   year: number;
 }
 
+/**
+ * A range of dates the provider is asked about. Always covers whole months: `start` is the first
+ * day of a month and `end` the last day of a month, so a provider may group its query by month.
+ */
+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.
+ */
+export interface DatePickerDateMetadata extends DatePickerDate {
+  /**
+   * 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 show, returning or resolving
+ * with the metadata for the dates in that range.
+ */
+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 +85,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 +217,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;
@@ -236,6 +283,44 @@ 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` and returns, or resolves with, an array of
+   * `DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as
+   * `disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata
+   * within that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is
+   * January and 11 is December.
+   *
+   * 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 several months, and may include months it already has
+   * metadata for, whose entries are then ignored.
+   *
+   * It may return a `Promise`, so the answer can come from a server. Until it resolves, the
+   * affected dates render with the `loading` part but stay selectable, and a loading spinner is
+   * shown. Nothing is disabled before the provider has actually reported it, so a slow provider
+   * does not make the calendar unusable. If it throws or rejects, the error is logged and the
+   * affected months are requested again the next time the user navigates.
+   *
+   * `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. That decides what the calendar renders as disabled, what can be selected, and
+   * whether the field is valid.
+   *
+   * A value is checked against the provider even if the overlay is never opened, which loads the
+   * month holding it. Until that month answers the value is valid, and it is re-validated once the
+   * answer arrives, so `checkValidity()` can report a value as valid and then invalid.
+   *
+   * `part` from the metadata adds part names to the date, so a theme can style specific dates with
+   * `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several separated
+   * by spaces. Do not use built-in names like `disabled` and `selected`.
+   *
+   * Keep a stable reference to the function. Assigning a new function clears the cache and
+   * re-fetches every visible range. To re-fetch while keeping the same function, because the data
+   * behind it changed, call `clearCache()`.
+   */
+  dateMetadataProvider: DatePickerDateMetadataProvider | null | undefined;
+
   /**
    * Opens the dropdown.
    */
@@ -245,4 +330,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);
@@ -208,6 +212,48 @@ 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` and returns, or resolves with, an array of
+         * `DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as
+         * `disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata
+         * within that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is
+         * January and 11 is December.
+         *
+         * 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 several months, and may include months it
+         * already has metadata for, whose entries are then ignored.
+         *
+         * It may return a `Promise`, so the answer can come from a server. Until it resolves, the
+         * affected dates render with the `loading` part but stay selectable, and a loading spinner
+         * is shown. Nothing is disabled before the provider has actually reported it, so a slow
+         * provider does not make the calendar unusable. If it throws or rejects, the error is logged
+         * and the affected months are requested again the next time the user navigates.
+         *
+         * `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. That decides what the calendar renders as disabled, what can be
+         * selected, and whether the field is valid.
+         *
+         * A value is checked against the provider even if the overlay is never opened, which loads the
+         * month holding it. Until that month answers the value is valid, and it is re-validated once
+         * the answer arrives, so `checkValidity()` can report a value as valid and then invalid.
+         *
+         * `part` from the metadata adds part names to the date, so a theme can style specific dates
+         * with `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several
+         * separated by spaces. Do not use built-in names like `disabled` and `selected`.
+         *
+         * Keep a stable reference to the function. Assigning a new function clears the cache and
+         * re-fetches every visible range. To re-fetch while keeping the same function, because the
+         * data behind it changed, call `clearCache()`.
+         *
+         * @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 +318,7 @@ export const DatePickerMixin = (subclass) =>
     }
 
     static get constraints() {
-      return [...super.constraints, 'min', 'max'];
+      return [...super.constraints, 'min', 'max', 'dateMetadataProvider'];
     }
 
     constructor() {
@@ -280,6 +326,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 +371,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 +497,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 +544,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 +658,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 +675,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 +903,8 @@ export const DatePickerMixin = (subclass) =>
       this._ignoreFocusedDateChange = true;
       this._focusedDate = selectedDate;
       this._ignoreFocusedDateChange = false;
+
+      this.__ensureSelectedDateLoaded();
     }
 
     /** @private */
@@ -845,6 +975,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 +992,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 +1092,8 @@ export const DatePickerMixin = (subclass) =>
 
     /** @protected */
     _onOverlayClosed() {
+      this._overlayContent?.cancelLoadVisibleDateMetadata();
+
       // Reset `aria-hidden` state.
       if (this.__showOthers) {
         this.__showOthers();

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

@@ -5,10 +5,22 @@
  */
 import { timeOut } from '@vaadin/component-base/src/async.js';
 import { Debouncer } from '@vaadin/component-base/src/debounce.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { addListener } from '@vaadin/component-base/src/gestures.js';
 import { MediaQueryController } from '@vaadin/component-base/src/media-query-controller.js';
 import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
-import { dateAfterXMonths, dateAllowed, dateEquals, getClosestDate } from './vaadin-date-picker-helper.js';
+import {
+  createDate,
+  dateAfterXMonths,
+  dateAllowed,
+  dateEquals,
+  dateSelectable,
+  firstOfMonth,
+  getClosestDate,
+  lastOfMonth,
+  monthDate,
+  monthIndex,
+} from './vaadin-date-picker-helper.js';
 
 export const DatePickerOverlayContentMixin = (superClass) =>
   class DatePickerOverlayContentMixin extends superClass {
@@ -106,6 +118,17 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           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.
+         * @protected
+         */
+        loading: {
+          type: Boolean,
+          value: false,
+          reflectToAttribute: true,
+        },
+
         enteredDate: {
           type: Date,
           sync: true,
@@ -124,6 +147,18 @@ export const DatePickerOverlayContentMixin = (superClass) =>
           type: Object,
         },
 
+        /**
+         * The date-picker's date metadata controller, assigned by the host. Declared as a property,
+         * and a dependency of `__updateCalendarsConfig` below, so that the calendars are handed it
+         * and subscribed whenever it arrives, rather than relying on the host assigning it before
+         * the properties that happen to trigger that observer.
+         * @protected
+         */
+        _dateMetadataController: {
+          type: Object,
+          sync: true,
+        },
+
         calendars: {
           type: Array,
           value: () => [],
@@ -138,14 +173,47 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     static get observers() {
       return [
-        '__updateCalendarsConfig(calendars, i18n, minDate, maxDate, showWeekNumbers, isDateDisabled, _theme)',
+        '__updateCalendarsConfig(calendars, i18n, minDate, maxDate, showWeekNumbers, isDateDisabled, _theme, _dateMetadataController)',
         '__updateCalendarsState(calendars, selectedDate, focusedDate, enteredDate, _ignoreTaps)',
         '__updateCancelButton(_cancelButton, i18n)',
-        '__updateTodayButton(_todayButton, i18n, minDate, maxDate, isDateDisabled)',
         '__updateYears(years, selectedDate, _theme)',
       ];
     }
 
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      this.cancelLoadVisibleDateMetadata();
+    }
+
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('loading')) {
+        setOrRemoveAttribute(this, 'aria-busy', this.loading);
+      }
+
+      if (props.has('i18n')) {
+        setOrRemoveAttribute(this, 'aria-label', this.i18n?.dialogAccessibleName);
+      }
+
+      if (props.has('calendars') || props.has('_dateMetadataController')) {
+        this.loadVisibleDateMetadata();
+      }
+
+      if (
+        props.has('_todayButton') ||
+        props.has('i18n') ||
+        props.has('minDate') ||
+        props.has('maxDate') ||
+        props.has('isDateDisabled')
+      ) {
+        this.updateTodayButton();
+      }
+    }
+
     /**
      * Whether to scroll to a sub-month position when scrolling to a date.
      * This is active if the month scroller is not large enough to fit a
@@ -292,14 +360,44 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       }
     }
 
-    /** @private */
-    __updateTodayButton(todayButton, i18n, minDate, maxDate, isDateDisabled) {
+    /**
+     * Applies the today button's label and whether today can be selected.
+     */
+    updateTodayButton() {
+      const todayButton = this._todayButton;
       if (todayButton) {
-        todayButton.textContent = i18n?.today;
-        todayButton.disabled = !this._isTodayAllowed(minDate, maxDate, isDateDisabled);
+        todayButton.textContent = this.i18n?.today;
+        todayButton.disabled = !this._isTodayAllowed();
       }
     }
 
+    /**
+     * Requests the date metadata for the months currently rendered. Months already loaded or in flight
+     * are skipped.
+     */
+    loadVisibleDateMetadata() {
+      const controller = this._dateMetadataController;
+      if (!controller) {
+        return;
+      }
+      // Reduced to month indexes so the outermost months can be picked with plain arithmetic.
+      const indexes = (this.calendars ?? [])
+        .map((calendar) => calendar.month)
+        .filter(Boolean)
+        .map((month) => monthIndex(month));
+      if (indexes.length === 0) {
+        return;
+      }
+      controller.ensureRangeLoaded(monthDate(Math.min(...indexes)), monthDate(Math.max(...indexes)));
+    }
+
+    /**
+     * Drops a date metadata load that navigating has scheduled but that has not run yet.
+     */
+    cancelLoadVisibleDateMetadata() {
+      this._loadDateMetadataDebouncer?.cancel();
+    }
+
     /**
      * Config that changes rarely (locale, allowed range, week numbers, theme).
      * Split from the interaction state below so a keyboard/selection update
@@ -307,24 +405,43 @@ export const DatePickerOverlayContentMixin = (superClass) =>
      * @private
      */
     // eslint-disable-next-line @typescript-eslint/max-params
-    __updateCalendarsConfig(calendars, i18n, minDate, maxDate, showWeekNumbers, isDateDisabled, theme) {
+    __updateCalendarsConfig(
+      calendars,
+      i18n,
+      minDate,
+      maxDate,
+      showWeekNumbers,
+      isDateDisabled,
+      theme,
+      dateMetadataController,
+    ) {
       if (calendars?.length) {
         calendars.forEach((calendar) => {
           calendar.i18n = i18n;
           calendar.minDate = minDate;
           calendar.maxDate = maxDate;
           calendar.isDateDisabled = isDateDisabled;
+          calendar._dateMetadataController = dateMetadataController;
+          // Subscribe to controller updates (subscribing again is a no-op).
+          dateMetadataController?.subscribe(calendar);
           calendar.showWeekNumbers = showWeekNumbers;
 
-          if (theme) {
-            calendar.setAttribute('theme', theme);
-          } else {
-            calendar.removeAttribute('theme');
-          }
+          setOrRemoveAttribute(calendar, 'theme', theme);
         });
       }
     }
 
+    /**
+     * Debounced variant used while navigating, so a continuous scroll triggers one load once it
+     * settles instead of a request per intermediate position.
+     * @private
+     */
+    __scheduleLoadVisibleDateMetadata() {
+      this._loadDateMetadataDebouncer = Debouncer.debounce(this._loadDateMetadataDebouncer, timeOut.after(200), () =>
+        this.loadVisibleDateMetadata(),
+      );
+    }
+
     /**
      * Interaction state that changes often (focus, selection, entered date, taps).
      * @private
@@ -346,11 +463,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
         years.forEach((year) => {
           year.selectedDate = selectedDate;
 
-          if (theme) {
-            year.setAttribute('theme', theme);
-          } else {
-            year.removeAttribute('theme');
-          }
+          setOrRemoveAttribute(year, 'theme', theme);
         });
       }
     }
@@ -360,7 +473,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
      * @protected
      */
     _selectDate(dateToSelect) {
-      if (!this._dateAllowed(dateToSelect)) {
+      if (!this._dateSelectable(dateToSelect)) {
         return false;
       }
       this.selectedDate = dateToSelect;
@@ -426,11 +539,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
      * @private
      */
     _calculateWeekScrollOffset(date) {
-      // Get first day of month
-      const temp = new Date(0, 0);
-      temp.setFullYear(date.getFullYear());
-      temp.setMonth(date.getMonth());
-      temp.setDate(1);
+      const temp = firstOfMonth(date);
       // Determine week (=row index) of date within the month
       let week = 0;
       while (temp.getDate() < date.getDate()) {
@@ -458,12 +567,14 @@ export const DatePickerOverlayContentMixin = (superClass) =>
       const monthPosition = this._monthScroller.position;
       this._visibleMonthIndex = Math.floor(monthPosition);
       this._yearScroller.position = (monthPosition + this._originDate.getMonth()) / 12;
+      this.__scheduleLoadVisibleDateMetadata();
     }
 
     /** @private */
     _repositionMonthScroller() {
       this._monthScroller.position = this._yearScroller.position * 12 - this._originDate.getMonth();
       this._visibleMonthIndex = Math.floor(this._monthScroller.position);
+      this.__scheduleLoadVisibleDateMetadata();
     }
 
     /** @private */
@@ -630,8 +741,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _differenceInMonths(date1, date2) {
-      const months = (date1.getFullYear() - date2.getFullYear()) * 12;
-      return months - date2.getMonth() + date1.getMonth();
+      return monthIndex(date1) - monthIndex(date2);
     }
 
     /** @private */
@@ -859,13 +969,11 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _getDateDiff(months, days) {
-      const date = new Date(0, 0);
-      date.setFullYear(this.focusedDate.getFullYear());
-      date.setMonth(this.focusedDate.getMonth() + months);
-      if (days) {
-        date.setDate(this.focusedDate.getDate() + days);
-      }
-      return date;
+      return createDate(
+        this.focusedDate.getFullYear(),
+        this.focusedDate.getMonth() + months,
+        days ? this.focusedDate.getDate() + days : 1,
+      );
     }
 
     /** @private */
@@ -895,16 +1003,7 @@ export const DatePickerOverlayContentMixin = (superClass) =>
 
     /** @private */
     _moveFocusInsideMonth(focusedDate, property) {
-      const dateToFocus = new Date(0, 0);
-      dateToFocus.setFullYear(focusedDate.getFullYear());
-
-      if (property === 'minDate') {
-        dateToFocus.setMonth(focusedDate.getMonth());
-        dateToFocus.setDate(1);
-      } else {
-        dateToFocus.setMonth(focusedDate.getMonth() + 1);
-        dateToFocus.setDate(0);
-      }
+      const dateToFocus = property === 'minDate' ? firstOfMonth(focusedDate) : lastOfMonth(focusedDate);
 
       if (this._dateAllowed(dateToFocus)) {
         this.focusDate(dateToFocus);
@@ -923,17 +1022,18 @@ export const DatePickerOverlayContentMixin = (superClass) =>
     }
 
     /** @private */
-    _isTodayAllowed(min, max, isDateDisabled) {
-      return this._dateAllowed(this._getTodayMidnight(), min, max, isDateDisabled);
+    _dateSelectable(date) {
+      return dateSelectable(date, this.minDate, this.maxDate, this.isDateDisabled, this._dateMetadataController);
+    }
+
+    /** @private */
+    _isTodayAllowed() {
+      return this._dateSelectable(this._getTodayMidnight());
     }
 
     /** @private */
     _getTodayMidnight() {
       const today = new Date();
-      const todayMidnight = new Date(0, 0);
-      todayMidnight.setFullYear(today.getFullYear());
-      todayMidnight.setMonth(today.getMonth());
-      todayMidnight.setDate(today.getDate());
-      return todayMidnight;
+      return createDate(today.getFullYear(), today.getMonth(), today.getDate());
     }
   };