@vaadin/date-picker 25.2.7 → 25.3.0-alpha10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/custom-elements.json +551 -9
  2. package/package.json +13 -13
  3. package/src/styles/vaadin-date-picker-overlay-content-base-styles.js +9 -0
  4. package/src/vaadin-date-metadata-controller.d.ts +94 -0
  5. package/src/vaadin-date-metadata-controller.js +276 -0
  6. package/src/vaadin-date-picker-helper.d.ts +17 -0
  7. package/src/vaadin-date-picker-helper.js +90 -5
  8. package/src/vaadin-date-picker-mixin.d.ts +93 -0
  9. package/src/vaadin-date-picker-mixin.js +140 -7
  10. package/src/vaadin-date-picker-overlay-content-mixin.js +164 -58
  11. package/src/vaadin-date-picker-overlay-content.js +5 -1
  12. package/src/vaadin-date-picker-overlay.js +1 -0
  13. package/src/vaadin-date-picker-year.js +4 -1
  14. package/src/vaadin-date-picker.d.ts +10 -1
  15. package/src/vaadin-date-picker.js +4 -0
  16. package/src/vaadin-month-calendar-mixin.js +55 -29
  17. package/src/vaadin-month-calendar.js +1 -0
  18. package/web-types.json +37 -10
  19. package/web-types.lit.json +19 -5
package/web-types.json CHANGED
@@ -1,18 +1,27 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/web-types",
3
3
  "name": "@vaadin/date-picker",
4
- "version": "25.2.7",
4
+ "version": "25.3.0-alpha10",
5
5
  "description-markup": "markdown",
6
6
  "contributions": {
7
7
  "html": {
8
8
  "elements": [
9
9
  {
10
10
  "name": "vaadin-date-picker",
11
- "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```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\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\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`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",
11
+ "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```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",
12
12
  "attributes": [
13
+ {
14
+ "name": "accessible-description-ref",
15
+ "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
16
+ "value": {
17
+ "type": [
18
+ "string"
19
+ ]
20
+ }
21
+ },
13
22
  {
14
23
  "name": "accessible-name",
15
- "description": "String used to label the component to screen reader users.",
24
+ "description": "String used to label the component for screen reader users.",
16
25
  "value": {
17
26
  "type": [
18
27
  "string"
@@ -21,7 +30,7 @@
21
30
  },
22
31
  {
23
32
  "name": "accessible-name-ref",
24
- "description": "Id of the element used as label of the component to screen reader users.",
33
+ "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
25
34
  "value": {
26
35
  "type": [
27
36
  "string"
@@ -213,9 +222,7 @@
213
222
  "description": "The theme variants to apply to the component.",
214
223
  "value": {
215
224
  "type": [
216
- "string",
217
- "null",
218
- "undefined"
225
+ "string"
219
226
  ]
220
227
  }
221
228
  },
@@ -240,9 +247,18 @@
240
247
  ],
241
248
  "js": {
242
249
  "properties": [
250
+ {
251
+ "name": "accessibleDescriptionRef",
252
+ "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
253
+ "value": {
254
+ "type": [
255
+ "string"
256
+ ]
257
+ }
258
+ },
243
259
  {
244
260
  "name": "accessibleName",
245
- "description": "String used to label the component to screen reader users.",
261
+ "description": "String used to label the component for screen reader users.",
246
262
  "value": {
247
263
  "type": [
248
264
  "string"
@@ -251,7 +267,7 @@
251
267
  },
252
268
  {
253
269
  "name": "accessibleNameRef",
254
- "description": "Id of the element used as label of the component to screen reader users.",
270
+ "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
255
271
  "value": {
256
272
  "type": [
257
273
  "string"
@@ -303,6 +319,17 @@
303
319
  ]
304
320
  }
305
321
  },
322
+ {
323
+ "name": "dateMetadataProvider",
324
+ "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()`.",
325
+ "value": {
326
+ "type": [
327
+ "DatePickerDateMetadataProvider",
328
+ "null",
329
+ "undefined"
330
+ ]
331
+ }
332
+ },
306
333
  {
307
334
  "name": "disabled",
308
335
  "description": "If true, the user cannot interact with this element.",
@@ -332,7 +359,7 @@
332
359
  },
333
360
  {
334
361
  "name": "i18n",
335
- "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides all properties, or\njust the individual properties you want to change.\n\nThe object has the following JSON structure and default values:\n\n```js\n{\n // An array with the full names of months starting\n // with January.\n monthNames: [\n 'January', 'February', 'March', 'April', 'May',\n 'June', 'July', 'August', 'September',\n 'October', 'November', 'December'\n ],\n\n // An array of weekday names starting with Sunday. Used\n // in screen reader announcements.\n weekdays: [\n 'Sunday', 'Monday', 'Tuesday', 'Wednesday',\n 'Thursday', 'Friday', 'Saturday'\n ],\n\n // An array of short weekday names starting with Sunday.\n // Displayed in the calendar.\n weekdaysShort: [\n 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'\n ],\n\n // An integer indicating the first day of the week\n // (0 = Sunday, 1 = Monday, etc.).\n firstDayOfWeek: 0,\n\n // Translation of the Today shortcut button text.\n today: 'Today',\n\n // Translation of the Cancel button text.\n cancel: 'Cancel',\n\n // Used for adjusting the year value when parsing dates with short years.\n // The year values between 0 and 99 are evaluated and adjusted.\n // Example: for a referenceDate of 1970-10-30;\n // dateToBeParsed: 40-10-30, result: 1940-10-30\n // dateToBeParsed: 80-10-30, result: 1980-10-30\n // dateToBeParsed: 10-10-30, result: 2010-10-30\n // Supported date format: ISO 8601 `\"YYYY-MM-DD\"` (default)\n // The default value is the current date.\n referenceDate: '',\n\n // A function to format given `Object` as\n // date string. Object is in the format `{ day: ..., month: ..., year: ... }`\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n formatDate: d => {\n // returns a string representation of the given\n // object in 'MM/DD/YYYY' -format\n },\n\n // A function to parse the given text to an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n // Must properly parse (at least) text formatted by `formatDate`.\n // Setting the property to null will disable keyboard input feature.\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n parseDate: text => {\n // Parses a string in 'MM/DD/YY', 'MM/DD' or 'DD' -format to\n // an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n }\n\n // A function to format given `monthName` and\n // `fullYear` integer as calendar title string.\n formatTitle: (monthName, fullYear) => {\n return monthName + ' ' + fullYear;\n }\n}\n```",
362
+ "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides all properties, or\njust the individual properties you want to change.\n\nThe object has the following JSON structure and default values:\n\n```js\n{\n // An array with the full names of months starting\n // with January.\n monthNames: [\n 'January', 'February', 'March', 'April', 'May',\n 'June', 'July', 'August', 'September',\n 'October', 'November', 'December'\n ],\n\n // An array of weekday names starting with Sunday. Used\n // in screen reader announcements.\n weekdays: [\n 'Sunday', 'Monday', 'Tuesday', 'Wednesday',\n 'Thursday', 'Friday', 'Saturday'\n ],\n\n // An array of short weekday names starting with Sunday.\n // Displayed in the calendar.\n weekdaysShort: [\n 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'\n ],\n\n // An integer indicating the first day of the week\n // (0 = Sunday, 1 = Monday, etc.).\n firstDayOfWeek: 0,\n\n // Translation of the Today shortcut button text.\n today: 'Today',\n\n // Translation of the Cancel button text.\n cancel: 'Cancel',\n\n // Accessible name of the overlay content, announced by screen readers\n // when the overlay opens.\n dialogAccessibleName: 'Calendar',\n\n // Used for adjusting the year value when parsing dates with short years.\n // The year values between 0 and 99 are evaluated and adjusted.\n // Example: for a referenceDate of 1970-10-30;\n // dateToBeParsed: 40-10-30, result: 1940-10-30\n // dateToBeParsed: 80-10-30, result: 1980-10-30\n // dateToBeParsed: 10-10-30, result: 2010-10-30\n // Supported date format: ISO 8601 `\"YYYY-MM-DD\"` (default)\n // The default value is the current date.\n referenceDate: '',\n\n // A function to format given `Object` as\n // date string. Object is in the format `{ day: ..., month: ..., year: ... }`\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n formatDate: d => {\n // returns a string representation of the given\n // object in 'MM/DD/YYYY' -format\n },\n\n // A function to parse the given text to an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n // Must properly parse (at least) text formatted by `formatDate`.\n // Setting the property to null will disable keyboard input feature.\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n parseDate: text => {\n // Parses a string in 'MM/DD/YY', 'MM/DD' or 'DD' -format to\n // an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n }\n\n // A function to format given `monthName` and\n // `fullYear` integer as calendar title string.\n formatTitle: (monthName, fullYear) => {\n return monthName + ' ' + fullYear;\n }\n}\n```",
336
363
  "value": {
337
364
  "type": [
338
365
  "Object"
package/web-types.lit.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/web-types",
3
3
  "name": "@vaadin/date-picker",
4
- "version": "25.2.7",
4
+ "version": "25.3.0-alpha10",
5
5
  "description-markup": "markdown",
6
6
  "framework": "lit",
7
7
  "framework-config": {
@@ -16,19 +16,26 @@
16
16
  "elements": [
17
17
  {
18
18
  "name": "vaadin-date-picker",
19
- "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```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\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\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`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",
19
+ "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```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",
20
20
  "extension": true,
21
21
  "attributes": [
22
+ {
23
+ "name": ".accessibleDescriptionRef",
24
+ "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
25
+ "value": {
26
+ "kind": "expression"
27
+ }
28
+ },
22
29
  {
23
30
  "name": ".accessibleName",
24
- "description": "String used to label the component to screen reader users.",
31
+ "description": "String used to label the component for screen reader users.",
25
32
  "value": {
26
33
  "kind": "expression"
27
34
  }
28
35
  },
29
36
  {
30
37
  "name": ".accessibleNameRef",
31
- "description": "Id of the element used as label of the component to screen reader users.",
38
+ "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
32
39
  "value": {
33
40
  "kind": "expression"
34
41
  }
@@ -68,6 +75,13 @@
68
75
  "kind": "expression"
69
76
  }
70
77
  },
78
+ {
79
+ "name": ".dateMetadataProvider",
80
+ "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()`.",
81
+ "value": {
82
+ "kind": "expression"
83
+ }
84
+ },
71
85
  {
72
86
  "name": "?disabled",
73
87
  "description": "If true, the user cannot interact with this element.",
@@ -91,7 +105,7 @@
91
105
  },
92
106
  {
93
107
  "name": ".i18n",
94
- "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides all properties, or\njust the individual properties you want to change.\n\nThe object has the following JSON structure and default values:\n\n```js\n{\n // An array with the full names of months starting\n // with January.\n monthNames: [\n 'January', 'February', 'March', 'April', 'May',\n 'June', 'July', 'August', 'September',\n 'October', 'November', 'December'\n ],\n\n // An array of weekday names starting with Sunday. Used\n // in screen reader announcements.\n weekdays: [\n 'Sunday', 'Monday', 'Tuesday', 'Wednesday',\n 'Thursday', 'Friday', 'Saturday'\n ],\n\n // An array of short weekday names starting with Sunday.\n // Displayed in the calendar.\n weekdaysShort: [\n 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'\n ],\n\n // An integer indicating the first day of the week\n // (0 = Sunday, 1 = Monday, etc.).\n firstDayOfWeek: 0,\n\n // Translation of the Today shortcut button text.\n today: 'Today',\n\n // Translation of the Cancel button text.\n cancel: 'Cancel',\n\n // Used for adjusting the year value when parsing dates with short years.\n // The year values between 0 and 99 are evaluated and adjusted.\n // Example: for a referenceDate of 1970-10-30;\n // dateToBeParsed: 40-10-30, result: 1940-10-30\n // dateToBeParsed: 80-10-30, result: 1980-10-30\n // dateToBeParsed: 10-10-30, result: 2010-10-30\n // Supported date format: ISO 8601 `\"YYYY-MM-DD\"` (default)\n // The default value is the current date.\n referenceDate: '',\n\n // A function to format given `Object` as\n // date string. Object is in the format `{ day: ..., month: ..., year: ... }`\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n formatDate: d => {\n // returns a string representation of the given\n // object in 'MM/DD/YYYY' -format\n },\n\n // A function to parse the given text to an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n // Must properly parse (at least) text formatted by `formatDate`.\n // Setting the property to null will disable keyboard input feature.\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n parseDate: text => {\n // Parses a string in 'MM/DD/YY', 'MM/DD' or 'DD' -format to\n // an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n }\n\n // A function to format given `monthName` and\n // `fullYear` integer as calendar title string.\n formatTitle: (monthName, fullYear) => {\n return monthName + ' ' + fullYear;\n }\n}\n```",
108
+ "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides all properties, or\njust the individual properties you want to change.\n\nThe object has the following JSON structure and default values:\n\n```js\n{\n // An array with the full names of months starting\n // with January.\n monthNames: [\n 'January', 'February', 'March', 'April', 'May',\n 'June', 'July', 'August', 'September',\n 'October', 'November', 'December'\n ],\n\n // An array of weekday names starting with Sunday. Used\n // in screen reader announcements.\n weekdays: [\n 'Sunday', 'Monday', 'Tuesday', 'Wednesday',\n 'Thursday', 'Friday', 'Saturday'\n ],\n\n // An array of short weekday names starting with Sunday.\n // Displayed in the calendar.\n weekdaysShort: [\n 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'\n ],\n\n // An integer indicating the first day of the week\n // (0 = Sunday, 1 = Monday, etc.).\n firstDayOfWeek: 0,\n\n // Translation of the Today shortcut button text.\n today: 'Today',\n\n // Translation of the Cancel button text.\n cancel: 'Cancel',\n\n // Accessible name of the overlay content, announced by screen readers\n // when the overlay opens.\n dialogAccessibleName: 'Calendar',\n\n // Used for adjusting the year value when parsing dates with short years.\n // The year values between 0 and 99 are evaluated and adjusted.\n // Example: for a referenceDate of 1970-10-30;\n // dateToBeParsed: 40-10-30, result: 1940-10-30\n // dateToBeParsed: 80-10-30, result: 1980-10-30\n // dateToBeParsed: 10-10-30, result: 2010-10-30\n // Supported date format: ISO 8601 `\"YYYY-MM-DD\"` (default)\n // The default value is the current date.\n referenceDate: '',\n\n // A function to format given `Object` as\n // date string. Object is in the format `{ day: ..., month: ..., year: ... }`\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n formatDate: d => {\n // returns a string representation of the given\n // object in 'MM/DD/YYYY' -format\n },\n\n // A function to parse the given text to an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n // Must properly parse (at least) text formatted by `formatDate`.\n // Setting the property to null will disable keyboard input feature.\n // Note: The argument month is 0-based. This means that January = 0 and December = 11.\n parseDate: text => {\n // Parses a string in 'MM/DD/YY', 'MM/DD' or 'DD' -format to\n // an `Object` in the format `{ day: ..., month: ..., year: ... }`.\n }\n\n // A function to format given `monthName` and\n // `fullYear` integer as calendar title string.\n formatTitle: (monthName, fullYear) => {\n return monthName + ' ' + fullYear;\n }\n}\n```",
95
109
  "value": {
96
110
  "kind": "expression"
97
111
  }