@vaadin/date-picker 25.2.7 → 25.3.0-alpha10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/date-picker",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -35,21 +35,21 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "~25.2.7",
-    "@vaadin/button": "~25.2.7",
-    "@vaadin/component-base": "~25.2.7",
-    "@vaadin/field-base": "~25.2.7",
-    "@vaadin/input-container": "~25.2.7",
-    "@vaadin/overlay": "~25.2.7",
-    "@vaadin/vaadin-themable-mixin": "~25.2.7",
+    "@vaadin/a11y-base": "25.3.0-alpha10",
+    "@vaadin/button": "25.3.0-alpha10",
+    "@vaadin/component-base": "25.3.0-alpha10",
+    "@vaadin/field-base": "25.3.0-alpha10",
+    "@vaadin/input-container": "25.3.0-alpha10",
+    "@vaadin/overlay": "25.3.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "~25.2.7",
-    "@vaadin/chai-plugins": "~25.2.7",
-    "@vaadin/test-runner-commands": "~25.2.7",
+    "@vaadin/aura": "25.3.0-alpha10",
+    "@vaadin/chai-plugins": "25.3.0-alpha10",
+    "@vaadin/test-runner-commands": "25.3.0-alpha10",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "~25.2.7",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha10",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -57,5 +57,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "14be1af674f3968cce68c6eb4742340694c4a949"
+  "gitHead": "f2833abdf9b613fa0d0ed216830e3f4de87b7dac"
 }

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

@@ -17,6 +17,7 @@ export const overlayContentStyles = css`
     height: 100%;
     outline: none;
     overflow: hidden;
+    position: relative;
   }
 
   :host([desktop]) {
@@ -49,6 +50,14 @@ export const overlayContentStyles = css`
     display: none !important;
   }
 
+  [part='loader'] {
+    position: absolute;
+    z-index: 1;
+    inset-block-start: var(--vaadin-date-picker-month-header-font-size, 0.9375rem);
+    inset-inline: 0;
+    margin-inline: auto;
+  }
+
   ::slotted([slot='months']) {
     --vaadin-infinite-scroller-item-height: round(
       var(--vaadin-date-picker-month-header-font-size, 0.9375rem) + 0.75rem +

package/src/vaadin-date-metadata-controller.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { ReactiveController, ReactiveControllerHost, ReactiveElement } from 'lit';
+import type { DatePickerDateMetadata, DatePickerDateMetadataProvider } from './vaadin-date-picker-mixin.js';
+
+/**
+ * A reactive controller that resolves the metadata (currently the disabled state)
+ * for the dates shown by the date-picker's `dateMetadataProvider`.
+ *
+ * The provider is called for a range of months and 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 }`.
+ *
+ * `ARCHITECTURE.md` in this package records the reasoning behind the request,
+ * caching, notification and failure behavior.
+ */
+export class DateMetadataController implements ReactiveController {
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement & ReactiveControllerHost;
+
+  /**
+   * The provider function, or `null` when none is set.
+   */
+  provider: DatePickerDateMetadataProvider | null;
+
+  constructor(host: HTMLElement & ReactiveControllerHost, onChange?: () => void);
+
+  hostConnected(): void;
+
+  /**
+   * Registers an element to be re-rendered whenever the resolved metadata or the
+   * loading state changes. The element must render from its bindings, and must not be
+   * the one whose own observer triggers a load. It stays registered for the
+   * controller's lifetime.
+   */
+  subscribe(element: ReactiveElement): void;
+
+  /**
+   * Whether any month range is currently being fetched.
+   */
+  isLoading(): boolean;
+
+  /**
+   * Sets the provider function and clears the cache. Passing the same provider again
+   * is a no-op, so callers should keep a stable reference.
+   */
+  setProvider(provider: DatePickerDateMetadataProvider | null | undefined): void;
+
+  /**
+   * Clears the cache and invalidates any in-flight requests.
+   */
+  clearCache(): void;
+
+  /**
+   * Whether the provider has answered for the month containing the given date.
+   * A month whose request failed is not loaded and will be requested again.
+   */
+  isMonthLoaded(date: Date | null | undefined): boolean;
+
+  /**
+   * Whether the month containing the given date is currently being fetched. A month
+   * that has not been asked about is not pending, so this reports the same state as
+   * `isLoading()` does for the whole cache.
+   */
+  isMonthPending(date: Date | null | undefined): boolean;
+
+  /**
+   * The metadata resolved for the given date, or `undefined` when the date has
+   * no metadata or its month has not been resolved yet. Returns the entry the
+   * provider supplied, which the caller must not modify.
+   */
+  getMetadata(date: Date | null | undefined): DatePickerDateMetadata | undefined;
+
+  /**
+   * Whether the given date is disabled by its metadata.
+   */
+  isDateDisabled(date: Date | null | undefined): boolean;
+
+  /**
+   * Ensures the provider has been consulted for the inclusive range between the
+   * given dates, rounded out to whole blocks of months. Months already loaded or in
+   * flight are skipped, and the ones left over are requested with a single call.
+   *
+   * Each call that finds a missing month issues its own request, so a caller that
+   * loads on scroll should debounce.
+   */
+  ensureRangeLoaded(startDate: Date | null | undefined, endDate: Date | null | undefined): void;
+}

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

@@ -0,0 +1,276 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { microTask } from '@vaadin/component-base/src/async.js';
+import { Debouncer } from '@vaadin/component-base/src/debounce.js';
+import { issueWarning } from '@vaadin/component-base/src/warnings.js';
+import {
+  createDate,
+  extractDateParts,
+  lastOfMonth,
+  monthDate,
+  monthIndex,
+  monthIndexOf,
+} from './vaadin-date-picker-helper.js';
+
+// Counted from January of year 0, so a block is one calendar year.
+const BLOCK_MONTHS = 12;
+
+function blockStart(month) {
+  return Math.floor(month / BLOCK_MONTHS) * BLOCK_MONTHS;
+}
+
+const PENDING_MONTH = Object.freeze({ pending: true });
+
+function isValidEntry(entry) {
+  if (!entry || !Number.isInteger(entry.year) || !Number.isInteger(entry.month) || !Number.isInteger(entry.day)) {
+    return false;
+  }
+  const date = createDate(entry.year, entry.month, entry.day);
+  return date.getFullYear() === entry.year && date.getMonth() === entry.month && date.getDate() === entry.day;
+}
+
+function groupEntriesByMonth(months, entries) {
+  const result = new Map(months.map((month) => [month, new Map()]));
+
+  if (Array.isArray(entries)) {
+    entries.forEach((entry) => {
+      if (isValidEntry(entry)) {
+        result.get(monthIndexOf(entry.year, entry.month))?.set(entry.day, entry);
+      } else {
+        issueWarning('Ignored `dateMetadataProvider` entries with an invalid year, month (0-11) or day.');
+      }
+    });
+  } else if (entries != null) {
+    issueWarning('Expected `dateMetadataProvider` to return an array of date metadata objects.');
+  }
+
+  return result;
+}
+
+/**
+ * A reactive controller that resolves the metadata (currently the disabled state)
+ * for the dates shown by the date-picker's `dateMetadataProvider`.
+ *
+ * The provider is called for a range of months and 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 }`.
+ *
+ * `ARCHITECTURE.md` in this package records the reasoning behind the request,
+ * caching, notification and failure behavior.
+ */
+export class DateMetadataController {
+  /**
+   * The controller host element.
+   * @type {import('lit').ReactiveControllerHost & HTMLElement}
+   */
+  host;
+
+  /**
+   * The provider function, or `null` when none is set.
+   * @type {Function | null}
+   */
+  provider = null;
+
+  /** @type {(() => void) | undefined} */
+  #onChange;
+
+  /**
+   * What is known about each month, keyed by month index: a shared marker while its request is in
+   * flight, or a record holding the resolved entries by day. A month is absent until it is loaded,
+   * and absent again if its request failed.
+   * @type {Map<number, { pending: boolean, entries?: Map<number, object> }>}
+   */
+  #months = new Map();
+
+  /** @type {Set<import('lit').ReactiveElement>} */
+  #subscribers = new Set();
+
+  #requestId = 0;
+
+  /** @type {import('@vaadin/component-base/src/debounce.js').Debouncer} */
+  #notifyDebouncer;
+
+  constructor(host, onChange) {
+    this.host = host;
+    this.#onChange = onChange;
+  }
+
+  hostConnected() {
+    this.#notify();
+  }
+
+  /**
+   * Registers an element to be re-rendered whenever the resolved metadata or the
+   * loading state changes. The element must render from its bindings, and must not be
+   * the one whose own observer triggers a load. It stays registered for the
+   * controller's lifetime.
+   *
+   * @param {import('lit').ReactiveElement} element
+   */
+  subscribe(element) {
+    this.#subscribers.add(element);
+  }
+
+  /**
+   * Whether any month range is currently being fetched.
+   * @return {boolean}
+   */
+  isLoading() {
+    for (const { pending } of this.#months.values()) {
+      if (pending) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Sets the provider function and clears the cache. Passing the same provider again
+   * is a no-op, so callers should keep a stable reference.
+   *
+   * @param {Function | null | undefined} provider
+   */
+  setProvider(provider) {
+    const next = provider ?? null;
+    if (this.provider === next) {
+      return;
+    }
+    this.provider = next;
+    this.clearCache();
+  }
+
+  /**
+   * Clears the cache and invalidates any in-flight requests.
+   */
+  clearCache() {
+    this.#months.clear();
+    this.#requestId += 1;
+    this.#notify();
+  }
+
+  /**
+   * Whether the provider has answered for the month containing the given date.
+   * A month whose request failed is not loaded and will be requested again.
+   * @param {Date | null | undefined} date
+   * @return {boolean}
+   */
+  isMonthLoaded(date) {
+    return !!this.#resolvedMonth(date);
+  }
+
+  /**
+   * Whether the month containing the given date is currently being fetched. A month
+   * that has not been asked about is not pending, so this reports the same state as
+   * `isLoading()` does for the whole cache.
+   * @param {Date | null | undefined} date
+   * @return {boolean}
+   */
+  isMonthPending(date) {
+    return !!date && !!this.#months.get(monthIndex(date))?.pending;
+  }
+
+  /**
+   * The metadata resolved for the given date, or `undefined` when the date has
+   * no metadata or its month has not been resolved yet. Returns the entry the
+   * provider supplied, which the caller must not modify.
+   * @param {Date | null | undefined} date
+   * @return {object | undefined}
+   */
+  getMetadata(date) {
+    return this.#resolvedMonth(date)?.entries.get(date.getDate());
+  }
+
+  /**
+   * Whether the given date is disabled by its metadata.
+   * @param {Date | null | undefined} date
+   * @return {boolean}
+   */
+  isDateDisabled(date) {
+    return !!this.getMetadata(date)?.disabled;
+  }
+
+  /**
+   * Ensures the provider has been consulted for the inclusive range between the
+   * given dates, rounded out to whole blocks of months. Months already loaded or in
+   * flight are skipped, and the ones left over are requested with a single call.
+   *
+   * Each call that finds a missing month issues its own request, so a caller that
+   * loads on scroll should debounce.
+   *
+   * @param {Date | null | undefined} startDate
+   * @param {Date | null | undefined} endDate
+   */
+  ensureRangeLoaded(startDate, endDate) {
+    if (!this.provider || !startDate || !endDate) {
+      return;
+    }
+
+    const first = blockStart(monthIndex(startDate));
+    const last = blockStart(monthIndex(endDate)) + BLOCK_MONTHS - 1;
+
+    const months = [];
+    for (let month = first; month <= last; month++) {
+      if (!this.#months.has(month)) {
+        months.push(month);
+      }
+    }
+
+    if (months.length > 0) {
+      this.#loadMonths(months);
+    }
+  }
+
+  #resolvedMonth(date) {
+    const month = date && this.#months.get(monthIndex(date));
+    return month && !month.pending ? month : undefined;
+  }
+
+  async #loadMonths(months) {
+    const requestId = this.#requestId;
+    months.forEach((month) => this.#months.set(month, PENDING_MONTH));
+    this.#notify();
+
+    const range = {
+      start: extractDateParts(monthDate(months[0])),
+      end: extractDateParts(lastOfMonth(monthDate(months.at(-1)))),
+    };
+
+    let entries;
+    try {
+      const data = await this.provider(range);
+      entries = groupEntriesByMonth(months, data);
+    } catch (error) {
+      console.error(error);
+    }
+
+    if (requestId !== this.#requestId) {
+      return;
+    }
+
+    months.forEach((month) => {
+      if (entries) {
+        this.#months.set(month, { pending: false, entries: entries.get(month) });
+      } else {
+        this.#months.delete(month);
+      }
+    });
+
+    this.#notify();
+  }
+
+  #notify() {
+    this.#subscribers.forEach((element) => element.requestUpdate());
+
+    if (this.#onChange) {
+      this.#notifyDebouncer = Debouncer.debounce(this.#notifyDebouncer, microTask, () => {
+        if (this.host.isConnected) {
+          this.#onChange();
+        }
+      });
+    }
+  }
+}

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

@@ -3,6 +3,7 @@
  * Copyright (c) 2016 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import type { DateMetadataController } from './vaadin-date-metadata-controller.js';
 import type { DatePickerDate } from './vaadin-date-picker-mixin.js';
 
 /**
@@ -31,6 +32,21 @@ declare function dateAllowed(
   isDateDisabled: (date: DatePickerDate) => boolean | null,
 ): boolean;
 
+/**
+ * Check if the given date can be selected: allowed by `dateAllowed` and not reported as disabled
+ * by the date metadata controller. This is narrower than `dateAllowed`, which decides what can be
+ * focused: a disabled date is still focusable, it just cannot be selected.
+ *
+ * @returns True if the date can be selected
+ */
+declare function dateSelectable(
+  date: Date,
+  min: Date | null,
+  max: Date | null,
+  isDateDisabled: (date: DatePickerDate) => boolean | null,
+  controller?: DateMetadataController | null,
+): boolean;
+
 /**
  * Get closest date from array of dates.
  *
@@ -66,6 +82,7 @@ export {
   getISOWeekNumber,
   dateEquals,
   dateAllowed,
+  dateSelectable,
   getClosestDate,
   extractDateParts,
   dateAfterXMonths,

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

@@ -4,6 +4,79 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
+/**
+ * Create a date at midnight in local time. Unlike `new Date(year, month, day)`,
+ * this supports years below 100, which the constructor maps into the 20th
+ * century. The month is assigned before the day so that the initial day of month
+ * (1) always exists in the target month.
+ *
+ * @param {number} year
+ * @param {number} month Zero-based month, may be out of range to shift the year
+ * @param {number} day May be `0` to select the last day of the previous month
+ * @return {Date}
+ */
+export function createDate(year, month, day) {
+  const date = new Date(0, 0); // Wrong date (1900-01-01), but with midnight in local time
+  date.setFullYear(year);
+  date.setMonth(month);
+  date.setDate(day);
+  return date;
+}
+
+/**
+ * Get the first day of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {Date}
+ */
+export function firstOfMonth(date) {
+  return createDate(date.getFullYear(), date.getMonth(), 1);
+}
+
+/**
+ * Get the last day of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {Date}
+ */
+export function lastOfMonth(date) {
+  return createDate(date.getFullYear(), date.getMonth() + 1, 0);
+}
+
+/**
+ * Get the index of a month, counted from January of year 0. Reduces a month to a single
+ * integer, so a lookup builds no key and two months are adjacent when their indexes are.
+ *
+ * @param {number} year
+ * @param {number} month Zero-based month
+ * @return {number}
+ */
+export function monthIndexOf(year, month) {
+  return year * 12 + month;
+}
+
+/**
+ * Get the index of the month the given date is in.
+ *
+ * @param {!Date} date
+ * @return {number}
+ */
+export function monthIndex(date) {
+  return monthIndexOf(date.getFullYear(), date.getMonth());
+}
+
+/**
+ * Get the first day of the month with the given index, inverting `monthIndexOf`. Counting from
+ * January of year 0 also inverts negative indexes, since `createDate` normalizes a month outside
+ * 0-11 into the year.
+ *
+ * @param {number} index
+ * @return {Date}
+ */
+export function monthDate(index) {
+  return createDate(0, index, 1);
+}
+
 /**
  * Get ISO 8601 week number for the given date.
  *
@@ -106,6 +179,22 @@ export function dateAllowed(date, min, max, isDateDisabled) {
   return (!min || date >= min) && (!max || date <= max) && !dateIsDisabled;
 }
 
+/**
+ * Check if the given date can be selected: allowed by `dateAllowed` and not reported as disabled
+ * by the date metadata controller. This is narrower than `dateAllowed`, which decides what can be
+ * focused: a disabled date is still focusable, it just cannot be selected.
+ *
+ * @param {!Date} date The date to check
+ * @param {Date | null} min Range start
+ * @param {Date | null} max Range end
+ * @param {function(!DatePickerDate): boolean} isDateDisabled Callback to check if the date is disabled
+ * @param {DateMetadataController | null} [controller] The date metadata controller
+ * @return {boolean} True if the date can be selected
+ */
+export function dateSelectable(date, min, max, isDateDisabled, controller) {
+  return dateAllowed(date, min, max, isDateDisabled) && !controller?.isDateDisabled(date);
+}
+
 /**
  * Get closest date from array of dates.
  *
@@ -185,11 +274,7 @@ export function parseDate(str) {
     return undefined;
   }
 
-  const date = new Date(0, 0); // Wrong date (1900-01-01), but with midnight in local time
-  date.setFullYear(parseInt(parts[1], 10));
-  date.setMonth(parseInt(parts[2], 10) - 1);
-  date.setDate(parseInt(parts[3], 10));
-  return date;
+  return createDate(parseInt(parts[1], 10), parseInt(parts[2], 10) - 1, parseInt(parts[3], 10));
 }
 
 /**