@vaadin/date-picker 25.3.0-alpha10 → 25.3.0-alpha12

package/custom-elements.json

@@ -23,7 +23,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A reactive controller that resolves the metadata (currently the disabled state)\nfor the dates shown by the date-picker's `dateMetadataProvider`.\n\nThe provider is called for a range of months and may return an array\nsynchronously or a `Promise`, so results from a server (Flow) or a remote\navailability service can be awaited. Each returned entry is a `DatePickerDate`\nextended with metadata fields, e.g. `{ year, month, day, disabled: true }`.\n\n`ARCHITECTURE.md` in this package records the reasoning behind the request,\ncaching, notification and failure behavior.",
+          "description": "A reactive controller that resolves the metadata (currently the disabled state)\nfor the dates shown by the date-picker's `dateMetadataProvider`.\n\nThe provider is called for a range of months and may return an array\nsynchronously or a `Promise`, so results from a server (Flow) or a remote\navailability service can be awaited. The range and each returned entry identify\na date by an ISO 8601 string, e.g. `{ date: '2026-01-01', disabled: true }`.\n\n`ARCHITECTURE.md` in this package records the reasoning behind the request,\ncaching, notification and failure behavior.",
           "name": "DateMetadataController",
           "members": [
             {
@@ -616,7 +616,7 @@
               }
             }
           ],
-          "description": "Parse date string of one of the following date formats:\n- ISO 8601 `\"YYYY-MM-DD\"`\n- 6-digit extended ISO 8601 `\"+YYYYYY-MM-DD\"`, `\"-YYYYYY-MM-DD\"`",
+          "description": "Parse date string of one of the following date formats:\n- ISO 8601 `\"YYYY-MM-DD\"`\n- Extended ISO 8601 with a signed year, e.g. `\"+012026-MM-DD\"` or `\"-0001-MM-DD\"`\n\nA date that does not exist, such as `\"2026-02-30\"`, is not parsed. Building it would carry the\nsurplus into the next month or year and answer with a date that was never asked for.",
           "return": {
             "type": {
               "text": "Date"
@@ -635,7 +635,7 @@
               }
             }
           ],
-          "description": "Parse date string of one of the following date formats:\n- ISO 8601 `\"YYYY-MM-DD\"`\n- 6-digit extended ISO 8601 `\"+YYYYYY-MM-DD\"`, `\"-YYYYYY-MM-DD\"`\n\nUses UTC date components to allow handling date instances independently of\nthe system time-zone.",
+          "description": "Parse date string of one of the following date formats:\n- ISO 8601 `\"YYYY-MM-DD\"`\n- Extended ISO 8601 with a signed year, e.g. `\"+012026-MM-DD\"` or `\"-0001-MM-DD\"`\n\nUses UTC date components to allow handling date instances independently of\nthe system time-zone.\n\nA date that does not exist, such as `\"2026-02-30\"`, is not parsed, as in `parseDate`.",
           "return": {
             "type": {
               "text": "Date"
@@ -921,7 +921,7 @@
               "type": {
                 "text": "DatePickerDateMetadataProvider | null | undefined"
               },
-              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+              "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
               "attribute": "date-metadata-provider"
             },
             {
@@ -983,7 +983,7 @@
               "type": {
                 "text": "function(DatePickerDate): boolean | undefined"
               },
-              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
               "attribute": "is-date-disabled"
             },
             {
@@ -1142,7 +1142,7 @@
               "type": {
                 "text": "DatePickerDateMetadataProvider | null | undefined"
               },
-              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+              "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
               "fieldName": "dateMetadataProvider"
             },
             {
@@ -1194,7 +1194,7 @@
               "type": {
                 "text": "function(DatePickerDate): boolean | undefined"
               },
-              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
               "fieldName": "isDateDisabled"
             },
             {
@@ -2320,7 +2320,7 @@
               "type": {
                 "text": "DatePickerDateMetadataProvider | null | undefined"
               },
-              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+              "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
               "attribute": "date-metadata-provider",
               "inheritedFrom": {
                 "name": "DatePickerMixin",
@@ -2418,7 +2418,7 @@
               "type": {
                 "text": "function(DatePickerDate): boolean | undefined"
               },
-              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
               "attribute": "is-date-disabled",
               "inheritedFrom": {
                 "name": "DatePickerMixin",
@@ -2771,7 +2771,7 @@
               "type": {
                 "text": "DatePickerDateMetadataProvider | null | undefined"
               },
-              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+              "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
               "fieldName": "dateMetadataProvider",
               "inheritedFrom": {
                 "name": "DatePickerMixin",
@@ -2855,7 +2855,7 @@
               "type": {
                 "text": "function(DatePickerDate): boolean | undefined"
               },
-              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
               "fieldName": "isDateDisabled",
               "inheritedFrom": {
                 "name": "DatePickerMixin",

package/package.json

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

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

@@ -12,8 +12,8 @@ import type { DatePickerDateMetadata, DatePickerDateMetadataProvider } from './v
  *
  * 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 }`.
+ * 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.

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

@@ -6,14 +6,7 @@
 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';
+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;
@@ -24,12 +17,10 @@ function blockStart(month) {
 
 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;
+// 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) {
@@ -37,10 +28,11 @@ function groupEntriesByMonth(months, entries) {
 
   if (Array.isArray(entries)) {
     entries.forEach((entry) => {
-      if (isValidEntry(entry)) {
-        result.get(monthIndexOf(entry.year, entry.month))?.set(entry.day, entry);
+      const date = entryDate(entry);
+      if (date) {
+        result.get(monthIndex(date))?.set(date.getDate(), entry);
       } else {
-        issueWarning('Ignored `dateMetadataProvider` entries with an invalid year, month (0-11) or day.');
+        issueWarning('Ignored `dateMetadataProvider` entries whose `date` is not an ISO 8601 date.');
       }
     });
   } else if (entries != null) {
@@ -56,8 +48,8 @@ function groupEntriesByMonth(months, entries) {
  *
  * 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 }`.
+ * 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.
@@ -235,8 +227,8 @@ export class DateMetadataController {
     this.#notify();
 
     const range = {
-      start: extractDateParts(monthDate(months[0])),
-      end: extractDateParts(lastOfMonth(monthDate(months.at(-1)))),
+      start: formatISODate(monthDate(months[0])),
+      end: formatISODate(lastOfMonth(monthDate(months.at(-1)))),
     };
 
     let entries;

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

@@ -260,47 +260,66 @@ export function getAdjustedYear(referenceDate, year, month = 0, day = 1) {
   return adjustedYear;
 }
 
+const ISO_DATE = /^([-+]\d{1,6}|\d{2,4})-(\d{1,2})-(\d{1,2})$/u;
+
+// The parts of a date string in a format the parsers accept, as written.
+function parseParts(str) {
+  // Parsing with RegExp to ensure correct format
+  const parts = ISO_DATE.exec(str);
+  if (!parts) {
+    return undefined;
+  }
+
+  return { year: parseInt(parts[1], 10), month: parseInt(parts[2], 10) - 1, day: parseInt(parts[3], 10) };
+}
+
 /**
  * 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"`
+ *
+ * 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 {!string} str Date string to parse
  * @return {Date} Parsed date in system timezone
  */
 export function parseDate(str) {
-  // Parsing with RegExp to ensure correct format
-  const parts = /^([-+]\d{1}|\d{2,4}|[-+]\d{6})-(\d{1,2})-(\d{1,2})$/u.exec(str);
+  const parts = parseParts(str);
   if (!parts) {
     return undefined;
   }
 
-  return createDate(parseInt(parts[1], 10), parseInt(parts[2], 10) - 1, parseInt(parts[3], 10));
+  const date = createDate(parts.year, parts.month, parts.day);
+
+  return date.getMonth() === parts.month && date.getDate() === parts.day ? 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 {!string} str Date string to parse
  * @return {Date} Parsed date in UTC timezone
  */
 export function parseUTCDate(str) {
-  // Parsing with RegExp to ensure correct format
-  const parts = /^([-+]\d{1}|\d{2,4}|[-+]\d{6})-(\d{1,2})-(\d{1,2})$/u.exec(str);
+  const parts = parseParts(str);
   if (!parts) {
     return undefined;
   }
 
   const date = new Date(Date.UTC(0, 0)); // Wrong date (1900-01-01), but with midnight in UTC
-  date.setUTCFullYear(parseInt(parts[1], 10));
-  date.setUTCMonth(parseInt(parts[2], 10) - 1);
-  date.setUTCDate(parseInt(parts[3], 10));
+  date.setUTCFullYear(parts.year);
+  date.setUTCMonth(parts.month);
+  date.setUTCDate(parts.day);
 
-  return date;
+  return date.getUTCMonth() === parts.month && date.getUTCDate() === parts.day ? date : undefined;
 }
 
 function formatISODateBase(dateParts) {

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

@@ -19,24 +19,28 @@ export interface DatePickerDate {
 }
 
 /**
- * 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.
+ * A range of dates that `dateMetadataProvider` is asked about.
+ * It can span several months and always covers whole months.
  */
 export interface DatePickerDateRange {
   /**
-   * The first date of the range (inclusive).
+   * The first date of the range (inclusive), as an ISO 8601 date.
    */
-  start: DatePickerDate;
+  start: string;
   /**
-   * The last date of the range (inclusive).
+   * The last date of the range (inclusive), as an ISO 8601 date.
    */
-  end: DatePickerDate;
+  end: string;
 }
 
 /**
- * Metadata resolved on demand for a single date.
+ * Metadata for a single date, returned by `dateMetadataProvider`.
  */
-export interface DatePickerDateMetadata extends DatePickerDate {
+export interface DatePickerDateMetadata {
+  /**
+   * The date the metadata applies to in ISO 8601 format.
+   */
+  date: string;
   /**
    * Whether the date cannot be selected.
    */
@@ -49,8 +53,9 @@ export interface DatePickerDateMetadata extends DatePickerDate {
 }
 
 /**
- * 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.
+ * A function called with the range of dates the calendar is about to render, returning
+ * the metadata for the dates in that range. It can return a `Promise` to load the metadata
+ * asynchronously, and `null` or `undefined` when no date in the range has metadata.
  */
 export type DatePickerDateMetadataProvider = (
   range: DatePickerDateRange,
@@ -280,47 +285,49 @@ export declare class DatePickerMixinClass {
    * A function to be used to determine whether the user can select a given date.
    * Receives a `DatePickerDate` object of the date to be selected and should return a
    * boolean.
+   *
+   * The function is called once per date and has to answer synchronously. Use
+   * `dateMetadataProvider` when the answer has to be loaded first, or when dates also need
+   * custom part names. A date is disabled when either of the two disables it.
    */
   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.
+   * A function that provides metadata for the dates the calendar is about to render: whether they
+   * are disabled, and CSS `part` names for styling from outside using the `::part()` selector.
+   * Unlike `isDateDisabled`, which is called once per date, the metadata provider is called for
+   * a range of dates at a time, and again as the calendar renders further dates.
    *
-   * 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 receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects
+   * for the dates in that range that have metadata. It can return a `Promise` to load the metadata
+   * asynchronously, and `null` or `undefined` when no date in the range has metadata.
    *
-   * 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.
+   * The returned array has the following structure:
    *
-   * `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.
+   * ```js
+   * [
+   *   // The date is an ISO 8601 string.
+   *   { date: '2026-01-01', disabled: true },
+   *
+   *   // Adds a custom part name to the date.
+   *   { date: '2026-01-02', part: 'busy' },
+   * ]
+   * ```
    *
-   * The date focused when the overlay opens is not moved if the provider reports it disabled. Use
-   * `initialPosition` to open on a date that can be selected.
+   * A date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or
+   * it is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in
+   * the field makes it invalid. The provider does not affect which date is focused when opening the
+   * overlay. Use `initialPosition` property to provide a selectable date.
    *
-   * 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.
+   * While a returned `Promise` is pending, the dates it covers are not disabled yet and render with
+   * the `loading` part. If the function throws or rejects, corresponding dates are requested again
+   * the next time the user navigates.
    *
-   * `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`.
+   * The provider is used for validation also when the overlay is closed. Date is considered valid
+   * while the provider is pending, and is re-validated again after the metadata is loaded.
    *
-   * 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()`.
+   * Keep a stable reference to the function: assigning a new one clears the cache and re-fetches
+   * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
    */
   dateMetadataProvider: DatePickerDateMetadataProvider | null | undefined;
 

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

@@ -63,7 +63,7 @@ export const datePickerI18nDefaults = Object.freeze({
       date = parseInt(parts[1]);
       year = parseInt(parts[2]);
       if (parts[2].length < 3 && year >= 0) {
-        const usedReferenceDate = this.referenceDate ? parseDate(this.referenceDate) : new Date();
+        const usedReferenceDate = parseDate(this.referenceDate) || new Date();
         year = getAdjustedYear(usedReferenceDate, year, month, date);
       }
     } else if (parts.length === 2) {
@@ -206,6 +206,10 @@ export const DatePickerMixin = (subclass) =>
          * Receives a `DatePickerDate` object of the date to be selected and should return a
          * boolean.
          *
+         * The function is called once per date and has to answer synchronously. Use
+         * `dateMetadataProvider` when the answer has to be loaded first, or when dates also need
+         * custom part names. A date is disabled when either of the two disables it.
+         *
          * @type {function(DatePickerDate): boolean | undefined}
          */
         isDateDisabled: {
@@ -213,43 +217,41 @@ export const DatePickerMixin = (subclass) =>
         },
 
         /**
-         * 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.
+         * A function that provides metadata for the dates the calendar is about to render: whether they
+         * are disabled, and CSS `part` names for styling from outside using the `::part()` selector.
+         * Unlike `isDateDisabled`, which is called once per date, the metadata provider is called for
+         * a range of dates at a time, and again as the calendar renders further dates.
+         *
+         * It receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects
+         * for the dates in that range that have metadata. It can return a `Promise` to load the metadata
+         * asynchronously, and `null` or `undefined` when no date in the range has metadata.
          *
-         * 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.
+         * The returned array has the following structure:
          *
-         * 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.
+         * ```js
+         * [
+         *   // The date is an ISO 8601 string.
+         *   { date: '2026-01-01', disabled: true },
          *
-         * `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.
+         *   // Adds a custom part name to the date.
+         *   { date: '2026-01-02', part: 'busy' },
+         * ]
+         * ```
          *
-         * The date focused when the overlay opens is not moved if the provider reports it disabled.
-         * Use `initialPosition` to open on a date that can be selected.
+         * A date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or
+         * it is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in
+         * the field makes it invalid. The provider does not affect which date is focused when opening the
+         * overlay. Use `initialPosition` property to provide a selectable date.
          *
-         * 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.
+         * While a returned `Promise` is pending, the dates it covers are not disabled yet and render with
+         * the `loading` part. If the function throws or rejects, corresponding dates are requested again
+         * the next time the user navigates.
          *
-         * `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`.
+         * The provider is used for validation also when the overlay is closed. Date is considered valid
+         * while the provider is pending, and is re-validated again after the metadata is loaded.
          *
-         * 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()`.
+         * Keep a stable reference to the function: assigning a new one clears the cache and re-fetches
+         * visible range. Call `clearCache()` to re-fetch when the data behind the same function changed.
          *
          * @type {DatePickerDateMetadataProvider | null | undefined}
          */

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha10",
+  "version": "25.3.0-alpha12",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -321,7 +321,7 @@
               },
               {
                 "name": "dateMetadataProvider",
-                "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+                "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
                 "value": {
                   "type": [
                     "DatePickerDateMetadataProvider",
@@ -386,7 +386,7 @@
               },
               {
                 "name": "isDateDisabled",
-                "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+                "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
                 "value": {
                   "type": [
                     "function DatePickerDate: boolean",

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/date-picker",
-  "version": "25.3.0-alpha10",
+  "version": "25.3.0-alpha12",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -77,7 +77,7 @@
             },
             {
               "name": ".dateMetadataProvider",
-              "description": "A batch function that fetches metadata for a range of dates the calendar is about to\nrender. It receives a `DatePickerDateRange` and returns, or resolves with, an array of\n`DatePickerDateMetadata` objects — a `DatePickerDate` extended with metadata such as\n`disabled`, e.g. `{ year, month, day, disabled: true }` — for the dates that have metadata\nwithin that range. Dates it does not mention have no metadata. `month` is 0-based: 0 is\nJanuary and 11 is December.\n\nUnlike `isDateDisabled`, which is called once per date, this function is called for a\nrange of dates at a time, and again as the calendar renders further dates. The size of the\nrange is decided by the calendar and may span several months, and may include months it\nalready has metadata for, whose entries are then ignored.\n\nIt may return a `Promise`, so the answer can come from a server. Until it resolves, the\naffected dates render with the `loading` part but stay selectable, and a loading spinner\nis shown. Nothing is disabled before the provider has actually reported it, so a slow\nprovider does not make the calendar unusable. If it throws or rejects, the error is logged\nand the affected months are requested again the next time the user navigates.\n\n`disabled` from the metadata is combined with `min`, `max` and `isDateDisabled`: a date is\ndisabled if it is out of the min/max range, or `isDateDisabled` returns `true`, or its\nmetadata marks it disabled. That decides what the calendar renders as disabled, what can be\nselected, and whether the field is valid.\n\nThe date focused when the overlay opens is not moved if the provider reports it disabled.\nUse `initialPosition` to open on a date that can be selected.\n\nA value is checked against the provider even if the overlay is never opened, which loads the\nmonth holding it. Until that month answers the value is valid, and it is re-validated once\nthe answer arrives, so `checkValidity()` can report a value as valid and then invalid.\n\n`part` from the metadata adds part names to the date, so a theme can style specific dates\nwith `::part()` — e.g. `{ year, month, day, part: 'busy' }`. Give a single name or several\nseparated by spaces. Do not use built-in names like `disabled` and `selected`.\n\nKeep a stable reference to the function. Assigning a new function clears the cache and\nre-fetches every visible range. To re-fetch while keeping the same function, because the\ndata behind it changed, call `clearCache()`.",
+              "description": "A function that provides metadata for the dates the calendar is about to render: whether they\nare disabled, and CSS `part` names for styling from outside using the `::part()` selector.\nUnlike `isDateDisabled`, which is called once per date, the metadata provider is called for\na range of dates at a time, and again as the calendar renders further dates.\n\nIt receives a `DatePickerDateRange` and returns an array of `DatePickerDateMetadata` objects\nfor the dates in that range that have metadata. It can return a `Promise` to load the metadata\nasynchronously, and `null` or `undefined` when no date in the range has metadata.\n\nThe returned array has the following structure:\n\n```js\n[\n  // The date is an ISO 8601 string.\n  { date: '2026-01-01', disabled: true },\n\n  // Adds a custom part name to the date.\n  { date: '2026-01-02', part: 'busy' },\n]\n```\n\nA date is disabled if its metadata marks it disabled, or `isDateDisabled` returns `true`, or\nit is outside `min` and `max`. Disabled dates are not selectable, and typing a disabled date in\nthe field makes it invalid. The provider does not affect which date is focused when opening the\noverlay. Use `initialPosition` property to provide a selectable date.\n\nWhile a returned `Promise` is pending, the dates it covers are not disabled yet and render with\nthe `loading` part. If the function throws or rejects, corresponding dates are requested again\nthe next time the user navigates.\n\nThe provider is used for validation also when the overlay is closed. Date is considered valid\nwhile the provider is pending, and is re-validated again after the metadata is loaded.\n\nKeep a stable reference to the function: assigning a new one clears the cache and re-fetches\nvisible range. Call `clearCache()` to re-fetch when the data behind the same function changed.",
               "value": {
                 "kind": "expression"
               }
@@ -126,7 +126,7 @@
             },
             {
               "name": ".isDateDisabled",
-              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.",
+              "description": "A function to be used to determine whether the user can select a given date.\nReceives a `DatePickerDate` object of the date to be selected and should return a\nboolean.\n\nThe function is called once per date and has to answer synchronously. Use\n`dateMetadataProvider` when the answer has to be loaded first, or when dates also need\ncustom part names. A date is disabled when either of the two disables it.",
               "value": {
                 "kind": "expression"
               }