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

package/package.json

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

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. The range and each returned entry identify
+ * a date by an ISO 8601 string, e.g. `{ date: '2026-01-01', 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,268 @@
+/**
+ * @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 { formatISODate, lastOfMonth, monthDate, monthIndex, parseDate } 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 });
+
+// The date of an entry, or `undefined` when its `date` is not one. Checked for being a string first,
+// since coercing another type to one can throw, and an entry comes from outside.
+function entryDate(entry) {
+  return typeof entry?.date === 'string' ? parseDate(entry.date) : undefined;
+}
+
+function groupEntriesByMonth(months, entries) {
+  const result = new Map(months.map((month) => [month, new Map()]));
+
+  if (Array.isArray(entries)) {
+    entries.forEach((entry) => {
+      const date = entryDate(entry);
+      if (date) {
+        result.get(monthIndex(date))?.set(date.getDate(), entry);
+      } else {
+        issueWarning('Ignored `dateMetadataProvider` entries whose `date` is not an ISO 8601 date.');
+      }
+    });
+  } 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. The range and each returned entry identify
+ * a date by an ISO 8601 string, e.g. `{ date: '2026-01-01', 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: formatISODate(monthDate(months[0])),
+      end: formatISODate(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,21 +3,88 @@
  * 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';
 
+/**
+ * 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 month Zero-based month, may be out of range to shift the year
+ * @param day May be `0` to select the last day of the previous month
+ */
+declare function createDate(year: number, month: number, day: number): Date;
+
+/**
+ * Get the first day of the month the given date is in.
+ */
+declare function firstOfMonth(date: Date): Date;
+
+/**
+ * Get the last day of the month the given date is in.
+ */
+declare function lastOfMonth(date: Date): Date;
+
+/**
+ * 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 month Zero-based month
+ */
+declare function monthIndexOf(year: number, month: number): number;
+
+/**
+ * Get the index of the month the given date is in.
+ */
+declare function monthIndex(date: Date): number;
+
+/**
+ * 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.
+ */
+declare function monthDate(index: number): Date;
+
 /**
  * Get ISO 8601 week number for the given date.
  *
  * @returns Week number
  */
-declare function getISOWeekNumber(Date: Date): number;
+declare function getISOWeekNumber(date: Date): number;
+
+/**
+ * Creates a new object with the same date, but sets the hours, minutes, seconds and milliseconds to 0.
+ *
+ * @param date in system timezone
+ * @returns The same date with time elements set to 0, in system timezone.
+ */
+declare function normalizeDate(date: Date): Date;
+
+/**
+ * Creates a new object with the same date, but sets the hours, minutes, seconds and milliseconds to 0.
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * @param date in UTC timezone
+ * @returns The same date with time elements set to 0, in UTC timezone.
+ */
+declare function normalizeUTCDate(date: Date): Date;
 
 /**
  * Check if two dates are equal.
  *
  * @returns True if the given date objects refer to the same date
  */
-declare function dateEquals(date1: Date | null, date2: Date | null): boolean;
+declare function dateEquals(date1: Date | null, date2: Date | null, normalizer?: (date: Date) => Date): boolean;
+
+/**
+ * Extracts the basic component parts of a date (day, month and year)
+ * to the expected format.
+ */
+declare function extractDateParts(date: Date): { day: number; month: number; year: number };
 
 /**
  * Check if the given date is in the range of allowed dates.
@@ -31,6 +98,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.
  *
@@ -39,36 +121,85 @@ declare function dateAllowed(
 declare function getClosestDate(date: Date, dates: Date[]): Date;
 
 /**
- * Extracts the basic component parts of a date (day, month and year)
- * to the expected format.
+ * Get difference in months between today and given months value.
  */
-declare function extractDateParts(date: Date): { day: number; month: number; year: number };
+declare function dateAfterXMonths(months: number): Date;
 
 /**
- * Get difference in months between today and given months value.
+ * Calculate the year of the date based on the provided reference date.
+ * Gets a two-digit year and returns a full year.
+ *
+ * @param year Should be in the range of [0, 99]
+ * @returns Adjusted year value
  */
-declare function dateAfterXMonths(months: number): number;
+declare function getAdjustedYear(referenceDate: Date, year: number, month?: number, day?: number): number;
 
 /**
- * Calculate the year of the date based on the provided reference date
- * Gets a two-digit year and returns a full year.
+ * Parse date string of one of the following date formats:
+ * - ISO 8601 `"YYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
+ *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed. Building it would carry the
+ * surplus into the next month or year and answer with a date that was never asked for.
+ *
+ * @param str Date string to parse
+ * @returns Parsed date in system timezone, or `undefined` when the string is not a date
  */
-declare function getAdjustedYear(referenceDate: Date, year: number, month?: number, day?: number): Date;
+declare function parseDate(str: string): Date | undefined;
 
 /**
  * Parse date string of one of the following date formats:
  * - ISO 8601 `"YYYY-MM-DD"`
- * - 6-digit extended ISO 8601 `"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`
+ * - Extended ISO 8601 with a signed year, e.g. `"+012026-MM-DD"` or `"-0001-MM-DD"`
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * A date that does not exist, such as `"2026-02-30"`, is not parsed, as in `parseDate`.
+ *
+ * @param str Date string to parse
+ * @returns Parsed date in UTC timezone, or `undefined` when the string is not a date
  */
-declare function parseDate(str: string): Date;
+declare function parseUTCDate(str: string): Date | undefined;
+
+/**
+ * Format a date instance in ISO 8601 (`"YYYY-MM-DD"`) or 6-digit extended ISO
+ * 8601 (`"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`) format.
+ *
+ * @param date in system timezone
+ */
+declare function formatISODate(date: Date): string;
+
+/**
+ * Format a date instance in ISO 8601 (`"YYYY-MM-DD"`) or 6-digit extended ISO
+ * 8601 (`"+YYYYYY-MM-DD"`, `"-YYYYYY-MM-DD"`) format.
+ *
+ * Uses UTC date components to allow handling date instances independently of
+ * the system time-zone.
+ *
+ * @param date in UTC timezone
+ */
+declare function formatUTCISODate(date: Date): string;
 
 export {
+  createDate,
+  firstOfMonth,
+  lastOfMonth,
+  monthIndexOf,
+  monthIndex,
+  monthDate,
   getISOWeekNumber,
+  normalizeDate,
+  normalizeUTCDate,
   dateEquals,
+  extractDateParts,
   dateAllowed,
+  dateSelectable,
   getClosestDate,
-  extractDateParts,
   dateAfterXMonths,
   getAdjustedYear,
   parseDate,
+  parseUTCDate,
+  formatISODate,
+  formatUTCISODate,
 };