@vaadin/time-picker 25.3.0-dev.3a3c2d7d2a → 25.3.0-rc1

package/custom-elements.json

@@ -74,7 +74,7 @@
               }
             }
           ],
-          "description": "A function to validate the time object based on the given step.",
+          "description": "A function to validate the time object based on the given step.\n\nReturns a new object, so that a time object owned by the caller, such as one\nreturned by the `i18n.parseTime` function, is left as it is.",
           "return": {
             "type": {
               "text": "object | undefined"
@@ -122,6 +122,20 @@
           "description": "A mixin providing common time-picker functionality.",
           "name": "TimePickerMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "accessibleDescriptionRef",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "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.",
+              "attribute": "accessible-description-ref",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "package": "@vaadin/field-base/src/field-mixin.js"
+              }
+            },
             {
               "kind": "field",
               "name": "accessibleName",
@@ -129,7 +143,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "attribute": "accessible-name",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -143,7 +157,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "attribute": "accessible-name-ref",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -236,7 +250,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "attribute": "clear-button-visible",
               "inheritedFrom": {
                 "name": "ClearButtonMixin",
@@ -301,7 +315,7 @@
               "type": {
                 "text": "Object"
               },
-              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.",
+              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.\n\nNOTE: these functions only apply to the text shown in the input field and\nin the dropdown. The `value`, `min` and `max` properties always use the\nISO 8601 format, and are never passed to `parseTime`, so implementations\ndo not need to accept ISO 8601 input.",
               "attribute": "i18n",
               "inheritedFrom": {
                 "name": "I18nMixin",
@@ -545,12 +559,24 @@
             }
           ],
           "attributes": [
+            {
+              "name": "accessible-description-ref",
+              "type": {
+                "text": "string"
+              },
+              "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.",
+              "fieldName": "accessibleDescriptionRef",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "package": "@vaadin/field-base/src/field-mixin.js"
+              }
+            },
             {
               "name": "accessible-name",
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "fieldName": "accessibleName",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -562,7 +588,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "fieldName": "accessibleNameRef",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -622,7 +648,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "fieldName": "clearButtonVisible",
               "inheritedFrom": {
                 "name": "ClearButtonMixin",
@@ -884,9 +910,23 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<vaadin-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`--vaadin-time-picker-overlay-width`     | Width of the overlay       | `auto`\n`--vaadin-time-picker-overlay-max-height`| Max height of the overlay  | `65vh`\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`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\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).\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-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`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\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                |\n:--------------------------------------------------|\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| `--vaadin-item-overlay-padding`                  |\n| `--vaadin-time-picker-overlay-max-height`        |\n| `--vaadin-time-picker-overlay-width`             |\n\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).\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": "TimePicker",
           "members": [
+            {
+              "kind": "field",
+              "name": "accessibleDescriptionRef",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "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.",
+              "attribute": "accessible-description-ref",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "package": "@vaadin/field-base/src/field-mixin.js"
+              }
+            },
             {
               "kind": "field",
               "name": "accessibleName",
@@ -894,7 +934,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "attribute": "accessible-name",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -908,7 +948,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "attribute": "accessible-name-ref",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1001,7 +1041,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "attribute": "clear-button-visible",
               "inheritedFrom": {
                 "name": "ClearButtonMixin",
@@ -1066,7 +1106,7 @@
               "type": {
                 "text": "Object"
               },
-              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.",
+              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.\n\nNOTE: these functions only apply to the text shown in the input field and\nin the dropdown. The `value`, `min` and `max` properties always use the\nISO 8601 format, and are never passed to `parseTime`, so implementations\ndo not need to accept ISO 8601 input.",
               "attribute": "i18n",
               "inheritedFrom": {
                 "name": "I18nMixin",
@@ -1345,41 +1385,25 @@
               "name": "value-changed"
             }
           ],
-          "mixins": [
-            {
-              "name": "TimePickerMixin",
-              "module": "src/vaadin-time-picker-mixin.js"
-            },
-            {
-              "name": "ThemableMixin",
-              "package": "@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js"
-            },
-            {
-              "name": "ElementMixin",
-              "package": "@vaadin/component-base/src/element-mixin.js"
-            },
+          "attributes": [
             {
-              "name": "PolylitMixin",
-              "package": "@vaadin/component-base/src/polylit-mixin.js"
+              "name": "accessible-description-ref",
+              "type": {
+                "text": "string"
+              },
+              "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.",
+              "fieldName": "accessibleDescriptionRef",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "package": "@vaadin/field-base/src/field-mixin.js"
+              }
             },
-            {
-              "name": "LumoInjectionMixin",
-              "package": "@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "vaadin-time-picker",
-          "customElement": true,
-          "attributes": [
             {
               "name": "accessible-name",
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "fieldName": "accessibleName",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1391,7 +1415,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "fieldName": "accessibleNameRef",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1451,7 +1475,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "fieldName": "clearButtonVisible",
               "inheritedFrom": {
                 "name": "ClearButtonMixin",
@@ -1650,6 +1674,13 @@
                 "module": "src/vaadin-time-picker-mixin.js"
               }
             },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "The theme variants to apply to the component.",
+              "name": "theme"
+            },
             {
               "name": "title",
               "type": {
@@ -1674,7 +1705,35 @@
                 "module": "src/vaadin-time-picker-mixin.js"
               }
             }
-          ]
+          ],
+          "mixins": [
+            {
+              "name": "TimePickerMixin",
+              "module": "src/vaadin-time-picker-mixin.js"
+            },
+            {
+              "name": "ThemableMixin",
+              "package": "@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js"
+            },
+            {
+              "name": "ElementMixin",
+              "package": "@vaadin/component-base/src/element-mixin.js"
+            },
+            {
+              "name": "PolylitMixin",
+              "package": "@vaadin/component-base/src/polylit-mixin.js"
+            },
+            {
+              "name": "LumoInjectionMixin",
+              "package": "@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vaadin-time-picker",
+          "customElement": true
         }
       ],
       "exports": [

package/package.json

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

package/src/vaadin-time-picker-helper.d.ts

@@ -25,6 +25,9 @@ export function parseISOTime(timeString: string): TimePickerTime | undefined;
 
 /**
  * A function to validate the time object based on the given step.
+ *
+ * Returns a new object, so that a time object owned by the caller, such as one
+ * returned by the `i18n.parseTime` function, is left as it is.
  */
 export function validateTime(
   timeObject: TimePickerTime | undefined,

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

@@ -75,17 +75,25 @@ function getStepSegment(stepValue) {
 /**
  * A function to validate the time object based on the given step.
  *
+ * Returns a new object, so that a time object owned by the caller, such as one
+ * returned by the `i18n.parseTime` function, is left as it is.
+ *
  * @param {object} timeObject
  * @param {number} step
  * @return {object | undefined}
  */
 export function validateTime(timeObject, step) {
-  if (timeObject) {
-    const stepSegment = getStepSegment(step);
-    timeObject.hours = parseInt(timeObject.hours);
-    timeObject.minutes = parseInt(timeObject.minutes || 0);
-    timeObject.seconds = stepSegment < 3 ? undefined : parseInt(timeObject.seconds || 0);
-    timeObject.milliseconds = stepSegment < 4 ? undefined : parseInt(timeObject.milliseconds || 0);
+  if (!timeObject) {
+    return timeObject;
   }
-  return timeObject;
+
+  const stepSegment = getStepSegment(step);
+
+  return {
+    ...timeObject,
+    hours: parseInt(timeObject.hours),
+    minutes: parseInt(timeObject.minutes || 0),
+    seconds: stepSegment < 3 ? undefined : parseInt(timeObject.seconds || 0),
+    milliseconds: stepSegment < 4 ? undefined : parseInt(timeObject.milliseconds || 0),
+  };
 }

package/src/vaadin-time-picker-item.js

@@ -34,12 +34,11 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-time-picker-item
  * @private
  */
-export class TimePickerItem extends ComboBoxItemMixin(
-  ThemableMixin(DirMixin(PolylitMixin(LumoInjectionMixin(LitElement)))),
-) {
+class TimePickerItem extends ComboBoxItemMixin(ThemableMixin(DirMixin(PolylitMixin(LumoInjectionMixin(LitElement))))) {
   static get is() {
     return 'vaadin-time-picker-item';
   }
@@ -60,3 +59,5 @@ export class TimePickerItem extends ComboBoxItemMixin(
 }
 
 defineCustomElement(TimePickerItem);
+
+export { TimePickerItem };

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

@@ -129,6 +129,11 @@ export declare class TimePickerMixinClass {
    *
    * NOTE: `formatTime` and `parseTime` must be implemented in a
    * compatible manner to ensure the component works properly.
+   *
+   * NOTE: these functions only apply to the text shown in the input field and
+   * in the dropdown. The `value`, `min` and `max` properties always use the
+   * ISO 8601 format, and are never passed to `parseTime`, so implementations
+   * do not need to accept ISO 8601 input.
    */
   i18n: TimePickerI18n;
 }

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

@@ -95,7 +95,6 @@ export const TimePickerMixin = (superClass) =>
         _comboBoxValue: {
           type: String,
           sync: true,
-          observer: '__comboBoxValueChanged',
         },
 
         /** @private */
@@ -106,12 +105,7 @@ export const TimePickerMixin = (superClass) =>
     }
 
     static get observers() {
-      return [
-        '_openedOrItemsChanged(opened, _dropdownItems)',
-        '_updateScroller(opened, _dropdownItems, _focusedIndex, _theme)',
-        '__updateAriaAttributes(_dropdownItems, opened, inputElement)',
-        '__updateDropdownItems(__effectiveI18n, min, max, step)',
-      ];
+      return ['__updateAriaAttributes(_dropdownItems, opened, inputElement)'];
     }
 
     static get defaultI18n() {
@@ -169,6 +163,11 @@ export const TimePickerMixin = (superClass) =>
      * NOTE: `formatTime` and `parseTime` must be implemented in a
      * compatible manner to ensure the component works properly.
      *
+     * NOTE: these functions only apply to the text shown in the input field and
+     * in the dropdown. The `value`, `min` and `max` properties always use the
+     * ISO 8601 format, and are never passed to `parseTime`, so implementations
+     * do not need to accept ISO 8601 input.
+     *
      * @type {!TimePickerI18n}
      */
     get i18n() {
@@ -229,9 +228,25 @@ export const TimePickerMixin = (superClass) =>
     updated(props) {
       super.updated(props);
 
-      // Update selected item in the scroller
-      if (props.has('_comboBoxValue') && this._dropdownItems) {
-        this._scroller.selectedItem = this._dropdownItems.find((item) => item.value === this._comboBoxValue);
+      if (['__effectiveI18n', 'min', 'max', 'step'].some((prop) => props.has(prop))) {
+        this.__updateDropdownItems();
+      }
+
+      if (props.has('step')) {
+        const time = this.__getTimeObject(this.value);
+        this.value = formatISOTime(time);
+        // Always update the input value, even if the component value hasn't
+        // changed, so that the text matches the step interval. For example,
+        // if the step is 3600 "10:00:50" should become "10:00".
+        this.__updateInputValue(time);
+      }
+
+      if (props.has('__effectiveI18n') && this.value) {
+        this.__updateInputValue(this.__getTimeObject(this.value));
+      }
+
+      if (props.has('value') || props.has('_dropdownItems')) {
+        this._scroller.selectedItem = this._dropdownItems?.find((item) => item.value === this.value);
       }
     }
 
@@ -244,7 +259,7 @@ export const TimePickerMixin = (superClass) =>
     checkValidity() {
       return !!(
         this.inputElement.checkValidity() &&
-        (!this.value || this._timeAllowed(this.__effectiveI18n.parseTime(this.value))) &&
+        (!this.value || this._timeAllowed(parseISOTime(this.value))) &&
         (!this._comboBoxValue || this.__effectiveI18n.parseTime(this._comboBoxValue))
       );
     }
@@ -258,27 +273,6 @@ export const TimePickerMixin = (superClass) =>
       return item ? item.label : '';
     }
 
-    /** @private */
-    _updateScroller(opened, items, focusedIndex, theme) {
-      if (opened) {
-        this._scroller.style.maxHeight =
-          getComputedStyle(this).getPropertyValue(`--${this._tagNamePrefix}-overlay-max-height`) || '65vh';
-      }
-
-      this._scroller.setProperties({
-        items: opened ? items : [],
-        opened,
-        focusedIndex,
-        theme,
-      });
-    }
-
-    /** @private */
-    _openedOrItemsChanged(opened, items) {
-      // Close the overlay if there are no items to display.
-      this._overlayOpened = opened && !!items?.length;
-    }
-
     /**
      * Override method from `ComboBoxBaseMixin` to commit value on overlay closing.
      * @protected
@@ -304,8 +298,7 @@ export const TimePickerMixin = (superClass) =>
      * @override
      */
     _onClearAction() {
-      this._comboBoxValue = '';
-      this._inputElementValue = '';
+      this.__setValueFromText('');
 
       this.__commitValueChange();
     }
@@ -319,14 +312,12 @@ export const TimePickerMixin = (superClass) =>
       if (this._focusedIndex > -1) {
         // Commit value based on focused index
         const focusedItem = this._dropdownItems[this._focusedIndex];
-        const itemValue = this._getItemLabel(focusedItem);
-        this._inputElementValue = itemValue;
-        this._comboBoxValue = itemValue;
+        this.__setValueFromTime(parseISOTime(focusedItem.value));
         this._focusedIndex = -1;
-      } else if (this._inputElementValue === '' || this._inputElementValue === undefined) {
-        this._comboBoxValue = '';
-      } else {
-        this._comboBoxValue = this._inputElementValue;
+      } else if (this._inputElementValue !== this._comboBoxValue) {
+        // Committing text that did not change would parse and format it again,
+        // and set the value from the result, so skip it.
+        this.__setValueFromText(this._inputElementValue || '');
       }
 
       this.__commitValueChange();
@@ -334,19 +325,6 @@ export const TimePickerMixin = (superClass) =>
       this._clearSelectionRange();
     }
 
-    /**
-     * Override method from `ComboBoxBaseMixin` to handle loading.
-     * @protected
-     * @override
-     */
-    _closeOrCommit() {
-      if (!this.opened) {
-        this._commitValue();
-      } else {
-        this.close();
-      }
-    }
-
     /**
      * Override method from `ComboBoxBaseMixin` to handle reverting value.
      * @protected
@@ -365,7 +343,7 @@ export const TimePickerMixin = (superClass) =>
     _setFocused(focused) {
       super._setFocused(focused);
 
-      if (!focused) {
+      if (!focused && !this._closeOnBlurIsPrevented) {
         // Do not validate when focusout is caused by document
         // losing focus, which happens on browser tab switch.
         if (document.hasFocus()) {
@@ -406,12 +384,12 @@ export const TimePickerMixin = (superClass) =>
       const objWithStep = this.__addStep(this.__getMsec(this.__memoValue), step, true);
       this.__memoValue = objWithStep;
 
-      // Setting `_comboBoxValue` property triggers the synchronous
-      // observer where the value can be parsed again, so we set
-      // this flag to ensure it does not alter the value.
-      this.__useMemo = true;
-      this._comboBoxValue = this.__effectiveI18n.formatTime(objWithStep);
-      this.__useMemo = false;
+      // Only commit when the formatted text changes, so that a step finer than
+      // the formatter can show does not move the value on its own, see #6397.
+      const text = this.__effectiveI18n.formatTime(objWithStep) || '';
+      if (text !== this._comboBoxValue) {
+        this.__setValueFromTime(objWithStep);
+      }
 
       this.__commitValueChange();
     }
@@ -461,6 +439,15 @@ export const TimePickerMixin = (superClass) =>
       return result;
     }
 
+    /**
+     * Returning Object in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
+     * from an ISO 8601 time, stripped to the resolution defined by the step.
+     * @private
+     */
+    __getTimeObject(timeString) {
+      return validateTime(parseISOTime(timeString), this.step);
+    }
+
     /**
      * Returning seconds from Object in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
      * @private
@@ -507,24 +494,11 @@ export const TimePickerMixin = (superClass) =>
     }
 
     /** @private */
-    __updateDropdownItems(effectiveI18n, min, max, step) {
-      const minTimeObj = validateTime(parseISOTime(min || MIN_ALLOWED_TIME), step);
-      const minSec = this.__getSec(minTimeObj);
+    __updateDropdownItems() {
+      const minSec = this.__getSec(this.__getTimeObject(this.min || MIN_ALLOWED_TIME));
+      const maxSec = this.__getSec(this.__getTimeObject(this.max || MAX_ALLOWED_TIME));
 
-      const maxTimeObj = validateTime(parseISOTime(max || MAX_ALLOWED_TIME), step);
-      const maxSec = this.__getSec(maxTimeObj);
-
-      this._dropdownItems = this.__generateDropdownList(minSec, maxSec, step);
-
-      if (step !== this.__oldStep) {
-        this.__oldStep = step;
-        const parsedObj = validateTime(parseISOTime(this.value), step);
-        this.__updateValue(parsedObj);
-      }
-
-      if (this.value) {
-        this._comboBoxValue = effectiveI18n.formatTime(effectiveI18n.parseTime(this.value));
-      }
+      this._dropdownItems = this.__generateDropdownList(minSec, maxSec, this.step);
     }
 
     /** @private */
@@ -560,7 +534,7 @@ export const TimePickerMixin = (superClass) =>
         const timeObj = validateTime(this.__addStep(time * 1000, step), step);
         time += step;
         const formatted = this.__effectiveI18n.formatTime(timeObj);
-        generatedList.push({ label: formatted, value: formatted });
+        generatedList.push({ label: formatted, value: formatISOTime(timeObj) });
       }
 
       return generatedList;
@@ -572,8 +546,9 @@ export const TimePickerMixin = (superClass) =>
      * @override
      */
     _valueChanged(value, oldValue) {
-      const parsedObj = (this.__memoValue = parseISOTime(value));
-      const newValue = formatISOTime(parsedObj) || '';
+      // Strip value to the step resolution before marking as committed.
+      const parsedObj = (this.__memoValue = this.__getTimeObject(value));
+      const newValue = formatISOTime(parsedObj);
 
       // Mark value set programmatically by the user
       // as committed for the change event detection.
@@ -588,64 +563,67 @@ export const TimePickerMixin = (superClass) =>
       } else if (value !== newValue) {
         // Value can be parsed (e.g. 12 -> 12:00), adjust.
         this.value = newValue;
-      } else if (this.__keepInvalidInput) {
-        // User input could not be parsed and was reset
-        // to empty string, do not update input value.
-        delete this.__keepInvalidInput;
-      } else {
+      } else if (!this.__keepCommittedValue) {
         this.__updateInputValue(parsedObj);
       }
 
       this._toggleHasValue(this._hasValue);
     }
 
-    /** @private */
-    __comboBoxValueChanged(value, oldValue) {
-      if (value === '' && oldValue === undefined) {
-        return;
-      }
+    /**
+     * Sets the value without marking it as committed, so that
+     * `__commitValueChange()` can still detect the change and
+     * fire an event for it.
+     *
+     * @param {string} value
+     * @private
+     */
+    __setUncommittedValue(value) {
+      this.__keepCommittedValue = true;
+      this.value = value;
+      this.__keepCommittedValue = false;
+    }
 
-      const parsedObj = this.__useMemo ? this.__memoValue : this.__effectiveI18n.parseTime(value);
-      const newValue = this.__effectiveI18n.formatTime(parsedObj) || '';
+    /**
+     * Sets the value and the input text from the given time,
+     * stripped to the resolution defined by the step.
+     *
+     * @param {!TimePickerTime} time
+     * @private
+     */
+    __setValueFromTime(time) {
+      const stripped = validateTime(time, this.step);
+      this.__setUncommittedValue(formatISOTime(stripped));
+      this.__updateInputValue(stripped);
+    }
 
-      if (parsedObj) {
-        if (value !== newValue) {
-          this._comboBoxValue = newValue;
-        } else {
-          this.__keepCommittedValue = true;
-          this.__updateValue(parsedObj);
-          this.__keepCommittedValue = false;
-        }
-      } else {
-        // If the user input can not be parsed, set a flag
-        // that prevents `__valueChanged` from removing the input
-        // after setting the value property to an empty string below.
-        if (this.value !== '' && value !== '') {
-          this.__keepInvalidInput = true;
-        }
+    /**
+     * Sets the value from the given text. When the text can not be parsed as a
+     * time, the value is set to an empty string and the text is left in the
+     * input for the user to correct.
+     *
+     * @param {string} text
+     * @private
+     */
+    __setValueFromText(text) {
+      // Skip parsing an empty field to not call custom `i18n.parseTime` for it.
+      const parsed = text ? this.__effectiveI18n.parseTime(text) : undefined;
 
-        this.__keepCommittedValue = true;
-        this.value = '';
-        this.__keepCommittedValue = false;
+      if (parsed) {
+        this.__setValueFromTime(parsed);
+        return;
       }
-    }
-
-    /** @private */
-    __updateValue(obj) {
-      const timeString = formatISOTime(validateTime(obj, this.step)) || '';
-      this.value = timeString;
 
-      // Always strip the input value to match the step interval, even
-      // if the component value hasn't changed. For example, if the step
-      // is 3600 "10:00:50" should become "10:00".
-      this.__updateInputValue(obj);
+      this.__setUncommittedValue('');
+      this._inputElementValue = text;
+      this._comboBoxValue = text;
     }
 
     /** @private */
     __updateInputValue(obj) {
-      const timeString = this.__effectiveI18n.formatTime(validateTime(obj, this.step)) || '';
-      this._inputElementValue = timeString;
-      this._comboBoxValue = timeString;
+      const text = this.__effectiveI18n.formatTime(obj) || '';
+      this._inputElementValue = text;
+      this._comboBoxValue = text;
     }
 
     /**
@@ -656,12 +634,12 @@ export const TimePickerMixin = (superClass) =>
      * @protected
      */
     _timeAllowed(time) {
-      const parsedMin = this.__effectiveI18n.parseTime(this.min || MIN_ALLOWED_TIME);
-      const parsedMax = this.__effectiveI18n.parseTime(this.max || MAX_ALLOWED_TIME);
+      const parsedMin = parseISOTime(this.min || MIN_ALLOWED_TIME);
+      const parsedMax = parseISOTime(this.max || MAX_ALLOWED_TIME);
 
       return (
-        (!this.__getMsec(parsedMin) || this.__getMsec(time) >= this.__getMsec(parsedMin)) &&
-        (!this.__getMsec(parsedMax) || this.__getMsec(time) <= this.__getMsec(parsedMax))
+        (!parsedMin || this.__getMsec(time) >= this.__getMsec(parsedMin)) &&
+        (!parsedMax || this.__getMsec(time) <= this.__getMsec(parsedMax))
       );
     }
 

package/src/vaadin-time-picker-overlay.js

@@ -19,8 +19,9 @@ import { timePickerOverlayStyles } from './styles/vaadin-time-picker-overlay-bas
  *
  * @extends HTMLElement
  * @private
+ * @attr {string} theme - The theme variants to apply to the component.
  */
-export class TimePickerOverlay extends ComboBoxOverlayMixin(
+class TimePickerOverlay extends ComboBoxOverlayMixin(
   OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))))),
 ) {
   static get is() {
@@ -44,3 +45,5 @@ export class TimePickerOverlay extends ComboBoxOverlayMixin(
 }
 
 defineCustomElement(TimePickerOverlay);
+
+export { TimePickerOverlay };

package/src/vaadin-time-picker-scroller.js

@@ -16,7 +16,7 @@ import { timePickerScrollerStyles } from './styles/vaadin-time-picker-scroller-b
  * @extends HTMLElement
  * @private
  */
-export class TimePickerScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElement)) {
+class TimePickerScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElement)) {
   static get is() {
     return 'vaadin-time-picker-scroller';
   }
@@ -36,3 +36,5 @@ export class TimePickerScroller extends ComboBoxScrollerMixin(PolylitMixin(LitEl
 }
 
 defineCustomElement(TimePickerScroller);
+
+export { TimePickerScroller };

package/src/vaadin-time-picker.d.ts

@@ -72,14 +72,6 @@ export interface TimePickerEventMap extends HTMLElementEventMap, TimePickerCusto
  *
  * ### Styling
  *
- * The following custom properties are available for styling:
- *
- * Custom property                          | Description                | Default
- * -----------------------------------------|----------------------------|---------
- * `--vaadin-field-default-width`           | Default width of the field | `12em`
- * `--vaadin-time-picker-overlay-width`     | Width of the overlay       | `auto`
- * `--vaadin-time-picker-overlay-max-height`| Max height of the overlay  | `65vh`
- *
  * The following shadow DOM parts are available for styling:
  *
  * Part name            | Description
@@ -111,6 +103,48 @@ export interface TimePickerEventMap extends HTMLElementEventMap, TimePickerCusto
  * `readonly`           | Set when the element is readonly
  * `opened`             | Set when the overlay is opened
  *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                                |
+ * :--------------------------------------------------|
+ * | `--vaadin-field-default-width`                   |
+ * | `--vaadin-input-field-background`                |
+ * | `--vaadin-input-field-border-color`              |
+ * | `--vaadin-input-field-border-radius`             |
+ * | `--vaadin-input-field-border-width`              |
+ * | `--vaadin-input-field-bottom-end-radius`         |
+ * | `--vaadin-input-field-bottom-start-radius`       |
+ * | `--vaadin-input-field-button-text-color`         |
+ * | `--vaadin-input-field-container-gap`             |
+ * | `--vaadin-input-field-disabled-background`       |
+ * | `--vaadin-input-field-disabled-text-color`       |
+ * | `--vaadin-input-field-error-color`               |
+ * | `--vaadin-input-field-error-font-size`           |
+ * | `--vaadin-input-field-error-font-weight`         |
+ * | `--vaadin-input-field-error-line-height`         |
+ * | `--vaadin-input-field-gap`                       |
+ * | `--vaadin-input-field-helper-color`              |
+ * | `--vaadin-input-field-helper-font-size`          |
+ * | `--vaadin-input-field-helper-font-weight`        |
+ * | `--vaadin-input-field-helper-line-height`        |
+ * | `--vaadin-input-field-label-color`               |
+ * | `--vaadin-input-field-label-font-size`           |
+ * | `--vaadin-input-field-label-font-weight`         |
+ * | `--vaadin-input-field-label-line-height`         |
+ * | `--vaadin-input-field-padding`                   |
+ * | `--vaadin-input-field-placeholder-color`         |
+ * | `--vaadin-input-field-required-indicator`        |
+ * | `--vaadin-input-field-required-indicator-color`  |
+ * | `--vaadin-input-field-top-end-radius`            |
+ * | `--vaadin-input-field-top-start-radius`          |
+ * | `--vaadin-input-field-value-color`               |
+ * | `--vaadin-input-field-value-font-size`           |
+ * | `--vaadin-input-field-value-font-weight`         |
+ * | `--vaadin-input-field-value-line-height`         |
+ * | `--vaadin-item-overlay-padding`                  |
+ * | `--vaadin-time-picker-overlay-max-height`        |
+ * | `--vaadin-time-picker-overlay-width`             |
+ *
  * ### Internal components
  *
  * In addition to `<vaadin-time-picker>` itself, the following internal

package/src/vaadin-time-picker.js

@@ -32,14 +32,6 @@ import { TimePickerMixin } from './vaadin-time-picker-mixin.js';
  *
  * ### Styling
  *
- * The following custom properties are available for styling:
- *
- * Custom property                          | Description                | Default
- * -----------------------------------------|----------------------------|---------
- * `--vaadin-field-default-width`           | Default width of the field | `12em`
- * `--vaadin-time-picker-overlay-width`     | Width of the overlay       | `auto`
- * `--vaadin-time-picker-overlay-max-height`| Max height of the overlay  | `65vh`
- *
  * The following shadow DOM parts are available for styling:
  *
  * Part name            | Description
@@ -71,6 +63,48 @@ import { TimePickerMixin } from './vaadin-time-picker-mixin.js';
  * `readonly`           | Set when the element is readonly
  * `opened`             | Set when the overlay is opened
  *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                                |
+ * :--------------------------------------------------|
+ * | `--vaadin-field-default-width`                   |
+ * | `--vaadin-input-field-background`                |
+ * | `--vaadin-input-field-border-color`              |
+ * | `--vaadin-input-field-border-radius`             |
+ * | `--vaadin-input-field-border-width`              |
+ * | `--vaadin-input-field-bottom-end-radius`         |
+ * | `--vaadin-input-field-bottom-start-radius`       |
+ * | `--vaadin-input-field-button-text-color`         |
+ * | `--vaadin-input-field-container-gap`             |
+ * | `--vaadin-input-field-disabled-background`       |
+ * | `--vaadin-input-field-disabled-text-color`       |
+ * | `--vaadin-input-field-error-color`               |
+ * | `--vaadin-input-field-error-font-size`           |
+ * | `--vaadin-input-field-error-font-weight`         |
+ * | `--vaadin-input-field-error-line-height`         |
+ * | `--vaadin-input-field-gap`                       |
+ * | `--vaadin-input-field-helper-color`              |
+ * | `--vaadin-input-field-helper-font-size`          |
+ * | `--vaadin-input-field-helper-font-weight`        |
+ * | `--vaadin-input-field-helper-line-height`        |
+ * | `--vaadin-input-field-label-color`               |
+ * | `--vaadin-input-field-label-font-size`           |
+ * | `--vaadin-input-field-label-font-weight`         |
+ * | `--vaadin-input-field-label-line-height`         |
+ * | `--vaadin-input-field-padding`                   |
+ * | `--vaadin-input-field-placeholder-color`         |
+ * | `--vaadin-input-field-required-indicator`        |
+ * | `--vaadin-input-field-required-indicator-color`  |
+ * | `--vaadin-input-field-top-end-radius`            |
+ * | `--vaadin-input-field-top-start-radius`          |
+ * | `--vaadin-input-field-value-color`               |
+ * | `--vaadin-input-field-value-font-size`           |
+ * | `--vaadin-input-field-value-font-weight`         |
+ * | `--vaadin-input-field-value-line-height`         |
+ * | `--vaadin-item-overlay-padding`                  |
+ * | `--vaadin-time-picker-overlay-max-height`        |
+ * | `--vaadin-time-picker-overlay-width`             |
+ *
  * ### Internal components
  *
  * In addition to `<vaadin-time-picker>` itself, the following internal
@@ -103,6 +137,7 @@ import { TimePickerMixin } from './vaadin-time-picker-mixin.js';
  * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  * @fires {CustomEvent} validated - Fired whenever the field is validated.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-time-picker
  * @extends HTMLElement
  */

package/web-types.json

@@ -1,18 +1,27 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/time-picker",
-  "version": "25.3.0-dev.3a3c2d7d2a",
+  "version": "25.3.0-rc1",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-time-picker",
-          "description": "`<vaadin-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`--vaadin-time-picker-overlay-width`     | Width of the overlay       | `auto`\n`--vaadin-time-picker-overlay-max-height`| Max height of the overlay  | `65vh`\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`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\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-dev.3a3c2d7d2a/#/elements/vaadin-item).\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-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`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\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                |\n:--------------------------------------------------|\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| `--vaadin-item-overlay-padding`                  |\n| `--vaadin-time-picker-overlay-max-height`        |\n| `--vaadin-time-picker-overlay-width`             |\n\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-rc1/#/elements/vaadin-item).\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",
           "attributes": [
+            {
+              "name": "accessible-description-ref",
+              "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.",
+              "value": {
+                "type": [
+                  "string"
+                ]
+              }
+            },
             {
               "name": "accessible-name",
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "value": {
                 "type": [
                   "string"
@@ -21,7 +30,7 @@
             },
             {
               "name": "accessible-name-ref",
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "value": {
                 "type": [
                   "string"
@@ -66,7 +75,7 @@
             },
             {
               "name": "clear-button-visible",
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "value": {
                 "type": [
                   "boolean"
@@ -213,9 +222,7 @@
               "description": "The theme variants to apply to the component.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             },
@@ -240,9 +247,18 @@
           ],
           "js": {
             "properties": [
+              {
+                "name": "accessibleDescriptionRef",
+                "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.",
+                "value": {
+                  "type": [
+                    "string"
+                  ]
+                }
+              },
               {
                 "name": "accessibleName",
-                "description": "String used to label the component to screen reader users.",
+                "description": "String used to label the component for screen reader users.",
                 "value": {
                   "type": [
                     "string"
@@ -251,7 +267,7 @@
               },
               {
                 "name": "accessibleNameRef",
-                "description": "Id of the element used as label of the component to screen reader users.",
+                "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
                 "value": {
                   "type": [
                     "string"
@@ -296,7 +312,7 @@
               },
               {
                 "name": "clearButtonVisible",
-                "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+                "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
                 "value": {
                   "type": [
                     "boolean"
@@ -332,7 +348,7 @@
               },
               {
                 "name": "i18n",
-                "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.",
+                "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.\n\nNOTE: these functions only apply to the text shown in the input field and\nin the dropdown. The `value`, `min` and `max` properties always use the\nISO 8601 format, and are never passed to `parseTime`, so implementations\ndo not need to accept ISO 8601 input.",
                 "value": {
                   "type": [
                     "Object"

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/time-picker",
-  "version": "25.3.0-dev.3a3c2d7d2a",
+  "version": "25.3.0-rc1",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,19 +16,26 @@
       "elements": [
         {
           "name": "vaadin-time-picker",
-          "description": "`<vaadin-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`--vaadin-time-picker-overlay-width`     | Width of the overlay       | `auto`\n`--vaadin-time-picker-overlay-max-height`| Max height of the overlay  | `65vh`\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`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\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-dev.3a3c2d7d2a/#/elements/vaadin-item).\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-time-picker>` is a Web Component providing a time-selection field.\n\n```html\n<vaadin-time-picker></vaadin-time-picker>\n```\n```js\ntimePicker.value = '14:30';\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`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\nThe following custom CSS properties are available for styling:\n\nCustom CSS property                                |\n:--------------------------------------------------|\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| `--vaadin-item-overlay-padding`                  |\n| `--vaadin-time-picker-overlay-max-height`        |\n| `--vaadin-time-picker-overlay-width`             |\n\n### Internal components\n\nIn addition to `<vaadin-time-picker>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-time-picker-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/25.3.0-rc1/#/elements/vaadin-item).\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",
           "extension": true,
           "attributes": [
+            {
+              "name": ".accessibleDescriptionRef",
+              "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": ".accessibleName",
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "value": {
                 "kind": "expression"
               }
             },
             {
               "name": ".accessibleNameRef",
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "value": {
                 "kind": "expression"
               }
@@ -63,7 +70,7 @@
             },
             {
               "name": "?clearButtonVisible",
-              "description": "Set to true to display the clear icon which clears the input.\n\nIt is up to the component to choose where to place the clear icon:\nin the Shadow DOM or in the light DOM. In any way, a reference to\nthe clear icon element should be provided via the `clearElement` getter.",
+              "description": "Set to true to display the clear icon which clears the input.\nThis also enables clearing the input when pressing Esc key.",
               "value": {
                 "kind": "expression"
               }
@@ -91,7 +98,7 @@
             },
             {
               "name": ".i18n",
-              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.",
+              "description": "The object used to localize this component. To change the default\nlocalization, replace this with an object that provides both the\ntime parsing and formatting functions.\n\nThe object has the following JSON structure:\n\n```js\n{\n  // A function to format given `Object` as\n  // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`\n  formatTime: (time) => {\n    // returns a string representation of the given\n    // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats\n  },\n\n  // A function to parse the given text to an `Object` in the format\n  // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.\n  // Must properly parse (at least) text\n  // formatted by `formatTime`.\n  parseTime: text => {\n    // Parses a string in object/string that can be formatted by`formatTime`.\n  }\n}\n```\n\nNOTE: `formatTime` and `parseTime` must be implemented in a\ncompatible manner to ensure the component works properly.\n\nNOTE: these functions only apply to the text shown in the input field and\nin the dropdown. The `value`, `min` and `max` properties always use the\nISO 8601 format, and are never passed to `parseTime`, so implementations\ndo not need to accept ISO 8601 input.",
               "value": {
                 "kind": "expression"
               }