feat: add date metadata provider to date-picker

dev/date-picker.html

@@ -29,5 +29,46 @@
       picker.isDateDisabled = isDateDisabled;
       picker.min = '2023-11-01';
     </script>
+
+    <h3>Date metadata provider</h3>
+    <p>
+      Metadata for each date is loaded on demand (a spinner is shown while loading) via
+      <code>dateMetadataProvider</code>. Mondays and the 20th of each month are <code>disabled</code>; the 10th and 25th
+      are enabled but tagged with a custom <code>part</code> name (<code>busy</code>) and styled orange. Results are
+      cached and prefetched around the visible months, so scrolling back and forth does not re-fetch.
+    </p>
+
+    <!-- Custom part names are styled from plain page CSS. The month calendars render in the light
+         DOM, so `vaadin-month-calendar::part()` reaches the date cells without registerStyles. -->
+    <style>
+      vaadin-month-calendar::part(busy) {
+        color: var(--vaadin-warning-contrast, #a05a00);
+        background: var(--vaadin-warning-color-10pct, rgba(255, 153, 0, 0.15));
+      }
+    </style>
+
+    <vaadin-date-picker id="date-metadata-provider" label="Reservation date"></vaadin-date-picker>
+
+    <script type="module">
+      document.querySelector('#date-metadata-provider').dateMetadataProvider = ({ start, end }) =>
+        new Promise((resolve) => {
+          setTimeout(() => {
+            const metadata = [];
+            const first = new Date(start.year, start.month, start.day);
+            const last = new Date(end.year, end.month, end.day);
+            const days = Math.round((last - first) / (24 * 60 * 60 * 1000));
+            for (let i = 0; i <= days; i++) {
+              const date = new Date(first.getFullYear(), first.getMonth(), first.getDate() + i);
+              const entry = { year: date.getFullYear(), month: date.getMonth(), day: date.getDate() };
+              if (date.getDay() === 1 || date.getDate() === 20) {
+                metadata.push({ ...entry, disabled: true });
+              } else if (date.getDate() === 10 || date.getDate() === 25) {
+                metadata.push({ ...entry, part: 'busy' });
+              }
+            }
+            resolve(metadata);
+          }, 600);
+        });
+    </script>
   </body>
 </html>

packages/date-picker/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,17 @@ 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;
+    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 +

packages/date-picker/src/vaadin-date-metadata-controller.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 } from 'lit';
+import type { DatePickerDateMetadata, DatePickerDateRange } from './vaadin-date-picker-mixin.js';
+
+export type DateMetadataProvider = (
+  range: DatePickerDateRange,
+) => DatePickerDateMetadata[] | Promise<DatePickerDateMetadata[]>;
+
+/**
+ * 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.
+ */
+export declare class DateMetadataController implements ReactiveController {
+  constructor(host: ReactiveControllerHost, onChange: () => void);
+
+  /**
+   * The provider function, or `null` when none is set.
+   */
+  provider: DateMetadataProvider | null;
+
+  /**
+   * Whether any month range is currently being fetched.
+   */
+  readonly loading: boolean;
+
+  hostDisconnected(): void;
+
+  /**
+   * Sets the provider function and clears the cache. Passing the same provider
+   * again is a no-op. Callers should keep a stable provider reference.
+   */
+  setProvider(provider: DateMetadataProvider | null | undefined): void;
+
+  /**
+   * Clears the cache and invalidates any in-flight requests.
+   */
+  reset(): void;
+
+  /**
+   * Whether the month containing the given date has been fully resolved.
+   */
+  isMonthLoaded(date: Date): boolean;
+
+  /**
+   * The metadata resolved for the given date, or `undefined` when the date has
+   * no metadata or its month has not been resolved yet.
+   */
+  getMetadata(date: Date): DatePickerDateMetadata | undefined;
+
+  /**
+   * Whether the given date is disabled by the provider. Only returns `true` for
+   * dates in an already-resolved month.
+   */
+  isDateDisabled(date: Date): boolean;
+
+  /**
+   * 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.
+   */
+  isDateBlocked(date: Date): 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.
+   */
+  ensureRangeLoaded(startDate: Date, endDate: Date): void;
+}