@vaadin/date-picker 25.3.0-alpha9 → 25.3.0-beta2

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\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\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"
             },
             {
@@ -2157,7 +2157,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                | Description                | Default\n-------------------------------|----------------------------|---------\n`--vaadin-field-default-width` | Default width of the field | `12em`\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n`loader`              | Loading spinner shown while the date metadata provider is resolving\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n`loading`       | Set while the date metadata provider is resolving\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`loading`             | Date element in a month whose metadata is currently being fetched\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
+          "description": "`<vaadin-date-picker>` is an input field that allows to enter a date by typing or by selecting from a calendar overlay.\n\n```html\n<vaadin-date-picker label=\"Birthday\"></vaadin-date-picker>\n```\n\n```js\ndatePicker.value = '2016-03-02';\n```\n\nWhen the selected `value` is changed, a `value-changed` event is triggered.\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and buttons\n`field-button`       | Set on both clear and toggle buttons\n`clear-button`       | The clear button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`has-tooltip`        | Set when the element has a slotted tooltip\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`week-numbers`       | Set when week numbers are shown in the calendar\n\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                        |\n:----------------------------------------------------------|\n| `--vaadin-date-picker-date-border-radius`                |\n| `--vaadin-date-picker-date-disabled-color`               |\n| `--vaadin-date-picker-date-height`                       |\n| `--vaadin-date-picker-date-selected-background`          |\n| `--vaadin-date-picker-date-selected-color`               |\n| `--vaadin-date-picker-date-today-color`                  |\n| `--vaadin-date-picker-date-width`                        |\n| `--vaadin-date-picker-month-header-color`                |\n| `--vaadin-date-picker-month-header-font-size`            |\n| `--vaadin-date-picker-month-header-font-weight`          |\n| `--vaadin-date-picker-month-padding`                     |\n| `--vaadin-date-picker-overlay-max-height`                |\n| `--vaadin-date-picker-overlay-width`                     |\n| `--vaadin-date-picker-toolbar-padding`                   |\n| `--vaadin-date-picker-week-divider-color`                |\n| `--vaadin-date-picker-week-number-color`                 |\n| `--vaadin-date-picker-week-number-font-size`             |\n| `--vaadin-date-picker-weekday-color`                     |\n| `--vaadin-date-picker-weekday-font-size`                 |\n| `--vaadin-date-picker-weekday-font-weight`               |\n| `--vaadin-date-picker-year-scroller-background`          |\n| `--vaadin-date-picker-year-scroller-border-color`        |\n| `--vaadin-date-picker-year-scroller-current-year-color`  |\n| `--vaadin-date-picker-year-scroller-width`               |\n| `--vaadin-field-default-width`                           |\n| `--vaadin-input-field-background`                        |\n| `--vaadin-input-field-border-color`                      |\n| `--vaadin-input-field-border-radius`                     |\n| `--vaadin-input-field-border-width`                      |\n| `--vaadin-input-field-bottom-end-radius`                 |\n| `--vaadin-input-field-bottom-start-radius`               |\n| `--vaadin-input-field-button-text-color`                 |\n| `--vaadin-input-field-container-gap`                     |\n| `--vaadin-input-field-disabled-background`               |\n| `--vaadin-input-field-disabled-text-color`               |\n| `--vaadin-input-field-error-color`                       |\n| `--vaadin-input-field-error-font-size`                   |\n| `--vaadin-input-field-error-font-weight`                 |\n| `--vaadin-input-field-error-line-height`                 |\n| `--vaadin-input-field-gap`                               |\n| `--vaadin-input-field-helper-color`                      |\n| `--vaadin-input-field-helper-font-size`                  |\n| `--vaadin-input-field-helper-font-weight`                |\n| `--vaadin-input-field-helper-line-height`                |\n| `--vaadin-input-field-label-color`                       |\n| `--vaadin-input-field-label-font-size`                   |\n| `--vaadin-input-field-label-font-weight`                 |\n| `--vaadin-input-field-label-line-height`                 |\n| `--vaadin-input-field-padding`                           |\n| `--vaadin-input-field-placeholder-color`                 |\n| `--vaadin-input-field-required-indicator`                |\n| `--vaadin-input-field-required-indicator-color`          |\n| `--vaadin-input-field-top-end-radius`                    |\n| `--vaadin-input-field-top-start-radius`                  |\n| `--vaadin-input-field-value-color`                       |\n| `--vaadin-input-field-value-font-size`                   |\n| `--vaadin-input-field-value-font-weight`                 |\n| `--vaadin-input-field-value-line-height`                 |\n\n### Internal components\n\nIn addition to `<vaadin-date-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-date-picker-overlay-content>`\n- `<vaadin-date-picker-month-scroller>`\n- `<vaadin-date-picker-year-scroller>`\n- `<vaadin-date-picker-year>`\n- `<vaadin-month-calendar>`\n\nIn order to style the overlay content, use `<vaadin-date-picker-overlay-content>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`years-toggle-button` | Fullscreen mode years scroller toggle\n`toolbar`             | Toolbar with slotted buttons\n`loader`              | Loading spinner shown while the date metadata provider is resolving\n\nThe following state attributes are available on the `<vaadin-date-picker-overlay-content>` element:\n\nAttribute       | Description\n----------------|-------------------------------------------------\n`desktop`       | Set when the overlay content is in desktop mode\n`fullscreen`    | Set when the overlay content is in fullscreen mode\n`years-visible` | Set when the year scroller is visible in fullscreen mode\n`loading`       | Set while the date metadata provider is resolving\n\nIn order to style the month calendar, use `<vaadin-month-calendar>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`month-header`        | Month title\n`weekdays`            | Weekday container\n`weekday`             | Weekday element\n`week-numbers`        | Week numbers container\n`week-number`         | Week number element\n`date`                | Date element\n`disabled`            | Disabled date element\n`loading`             | Date element in a month whose metadata is currently being fetched\n`focused`             | Focused date element\n`selected`            | Selected date element\n`today`               | Date element corresponding to the current day\n`past`                | Date element corresponding to the date in the past\n`future`              | Date element corresponding to the date in the future\n\nIn order to style year scroller elements, use `<vaadin-date-picker-year>` shadow DOM parts:\n\nPart name             | Description\n----------------------|--------------------\n`year-number`         | Year number\n`year-separator`      | Year separator\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.\n\n### Change events\n\nDepending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,\nthe component can fire either a `change` event or an `unparsable-change` event:\n\nValue change             | Event\n:------------------------|:------------------\nempty => parsable        | change\nempty => unparsable      | unparsable-change\nparsable => empty        | change\nparsable => parsable     | change\nparsable => unparsable   | change\nunparsable => empty      | unparsable-change\nunparsable => parsable   | change\nunparsable => unparsable | unparsable-change",
           "name": "DatePicker",
           "members": [
             {
@@ -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\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\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-alpha9",
+  "version": "25.3.0-beta2",
   "publishConfig": {
     "access": "public"
   },
@@ -35,21 +35,21 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.3.0-alpha9",
-    "@vaadin/button": "25.3.0-alpha9",
-    "@vaadin/component-base": "25.3.0-alpha9",
-    "@vaadin/field-base": "25.3.0-alpha9",
-    "@vaadin/input-container": "25.3.0-alpha9",
-    "@vaadin/overlay": "25.3.0-alpha9",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha9",
+    "@vaadin/a11y-base": "25.3.0-beta2",
+    "@vaadin/button": "25.3.0-beta2",
+    "@vaadin/component-base": "25.3.0-beta2",
+    "@vaadin/field-base": "25.3.0-beta2",
+    "@vaadin/input-container": "25.3.0-beta2",
+    "@vaadin/overlay": "25.3.0-beta2",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-beta2",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha9",
-    "@vaadin/chai-plugins": "25.3.0-alpha9",
-    "@vaadin/test-runner-commands": "25.3.0-alpha9",
+    "@vaadin/aura": "25.3.0-beta2",
+    "@vaadin/chai-plugins": "25.3.0-beta2",
+    "@vaadin/test-runner-commands": "25.3.0-beta2",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha9",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-beta2",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -57,5 +57,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "cb915ebde095ec5b94a87af93dd4530f51984c52"
+  "gitHead": "d97ccbec217b60c39f3c8b2dd52473c79a48c8c1"
 }

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

@@ -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.d.ts

@@ -6,19 +6,85 @@
 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.
@@ -55,37 +121,85 @@ declare function dateSelectable(
 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 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 parseDate(str: string): Date;
+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,
 };

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) {