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

package/package.json

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

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

@@ -50,9 +50,6 @@ export const overlayContentStyles = css`
     display: none !important;
   }
 
-  /* Loading spinner shown while data is being loaded (currently while the disabled dates provider
-     resolves). Positioned over the month scroller, which paints its own transformed layers, so
-     grid stacking is not enough. */
   [part='loader'] {
     position: absolute;
     z-index: 1;

package/src/styles/vaadin-month-calendar-base-styles.js

@@ -10,6 +10,9 @@ export const monthCalendarStyles = css`
   :host {
     display: block;
     padding: var(--vaadin-date-picker-month-padding, var(--vaadin-padding-s));
+    -webkit-tap-highlight-color: transparent;
+    -webkit-user-select: none;
+    user-select: none;
   }
 
   [part='month-header'] {

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

@@ -3,73 +3,92 @@
  * 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 } from 'lit';
-import type { DatePickerDateMetadata, DatePickerDateRange } from './vaadin-date-picker-mixin.js';
-
-export type DateMetadataProvider = (
-  range: DatePickerDateRange,
-) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[]>;
+import type { ReactiveController, ReactiveControllerHost, ReactiveElement } from 'lit';
+import type { DatePickerDateMetadata, DatePickerDateMetadataProvider } from './vaadin-date-picker-mixin.js';
 
 /**
- * A reactive controller that resolves the metadata (disabled state, custom part
- * names, ...) for the dates shown by the date-picker's `dateMetadataProvider`.
- * It calls the provider once for a range of months, caches the resolved months
- * so scrolling back and forth does not re-fetch, and prefetches a buffer of
- * months around the requested range.
+ * 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 declare class DateMetadataController implements ReactiveController {
-  constructor(host: ReactiveControllerHost, onChange: () => void);
+export class DateMetadataController implements ReactiveController {
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement & ReactiveControllerHost;
 
   /**
    * The provider function, or `null` when none is set.
    */
-  provider: DateMetadataProvider | null;
+  provider: DatePickerDateMetadataProvider | null;
+
+  constructor(host: HTMLElement & ReactiveControllerHost, onChange?: () => void);
+
+  hostConnected(): void;
 
   /**
-   * Whether any month range is currently being fetched.
+   * 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.
    */
-  readonly loading: boolean;
+  subscribe(element: ReactiveElement): void;
 
-  hostDisconnected(): 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. Callers should keep a stable provider reference.
+   * 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: DateMetadataProvider | null | undefined): void;
+  setProvider(provider: DatePickerDateMetadataProvider | null | undefined): void;
 
   /**
    * Clears the cache and invalidates any in-flight requests.
    */
-  reset(): void;
+  clearCache(): void;
 
   /**
-   * Whether the month containing the given date has been fully resolved.
+   * 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): boolean;
+  isMonthLoaded(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.
+   * 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.
    */
-  getMetadata(date: Date): DatePickerDateMetadata | undefined;
+  isMonthPending(date: Date | null | undefined): boolean;
 
   /**
-   * Whether the given date is disabled by the provider. Only returns `true` for
-   * dates in an already-resolved month.
+   * 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.
    */
-  isDateDisabled(date: Date): boolean;
+  getMetadata(date: Date | null | undefined): DatePickerDateMetadata | undefined;
 
   /**
-   * Whether the given date cannot be selected yet: it is disabled by the
-   * provider, or its month has not been resolved. Returns `false` when no
-   * provider is set.
+   * Whether the given date is disabled by its metadata.
    */
-  isDateBlocked(date: Date): boolean;
+  isDateDisabled(date: Date | null | undefined): boolean;
 
   /**
    * Ensures the provider has been consulted for the inclusive range between the
-   * given dates, expanded by a prefetch buffer of months on each side.
+   * 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, endDate: Date): void;
+  ensureRangeLoaded(startDate: Date | null | undefined, endDate: Date | null | undefined): void;
 }

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

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