@vaadin/select 24.0.0-alpha12 → 24.0.0-alpha13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/select",
-  "version": "24.0.0-alpha12",
+  "version": "24.0.0-alpha13",
   "publishConfig": {
     "access": "public"
   },
@@ -38,21 +38,21 @@
   ],
   "dependencies": {
     "@polymer/polymer": "^3.2.0",
-    "@vaadin/button": "24.0.0-alpha12",
-    "@vaadin/component-base": "24.0.0-alpha12",
-    "@vaadin/field-base": "24.0.0-alpha12",
-    "@vaadin/input-container": "24.0.0-alpha12",
-    "@vaadin/item": "24.0.0-alpha12",
-    "@vaadin/list-box": "24.0.0-alpha12",
-    "@vaadin/lit-renderer": "24.0.0-alpha12",
-    "@vaadin/overlay": "24.0.0-alpha12",
-    "@vaadin/vaadin-lumo-styles": "24.0.0-alpha12",
-    "@vaadin/vaadin-material-styles": "24.0.0-alpha12",
-    "@vaadin/vaadin-themable-mixin": "24.0.0-alpha12"
+    "@vaadin/button": "24.0.0-alpha13",
+    "@vaadin/component-base": "24.0.0-alpha13",
+    "@vaadin/field-base": "24.0.0-alpha13",
+    "@vaadin/input-container": "24.0.0-alpha13",
+    "@vaadin/item": "24.0.0-alpha13",
+    "@vaadin/list-box": "24.0.0-alpha13",
+    "@vaadin/lit-renderer": "24.0.0-alpha13",
+    "@vaadin/overlay": "24.0.0-alpha13",
+    "@vaadin/vaadin-lumo-styles": "24.0.0-alpha13",
+    "@vaadin/vaadin-material-styles": "24.0.0-alpha13",
+    "@vaadin/vaadin-themable-mixin": "24.0.0-alpha13"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.3.2",
+    "@vaadin/testing-helpers": "^0.4.0",
     "lit": "^2.0.0",
     "sinon": "^13.0.2"
   },
@@ -60,5 +60,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "7e29eee4d522fb7b03ac8e7e385e9057d71c79ce"
+  "gitHead": "a423ad309c12b4e4f847737ee9f491f83ea60ff0"
 }

package/src/vaadin-select-item.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
+import { ItemMixin } from '@vaadin/item/src/vaadin-item-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+/**
+ * An element used internally by `<vaadin-select>`. Not intended to be used separately.
+ */
+declare class SelectItem extends ItemMixin(DirMixin(ThemableMixin(HTMLElement))) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-select-item': SelectItem;
+  }
+}
+
+export { SelectItem };

package/src/vaadin-select-item.js

@@ -3,18 +3,51 @@
  * Copyright (c) 2017 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { Item } from '@vaadin/item/src/vaadin-item.js';
+import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
+import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
+import { ItemMixin } from '@vaadin/item/src/vaadin-item-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
  * An element used internally by `<vaadin-select>`. Not intended to be used separately.
  *
- * @extends Item
+ * @extends HTMLElement
+ * @mixes DirMixin
+ * @mixes ItemMixin
+ * @mixes ThemableMixin
  * @protected
  */
-class SelectItem extends Item {
+class SelectItem extends ItemMixin(ThemableMixin(DirMixin(PolymerElement))) {
   static get is() {
     return 'vaadin-select-item';
   }
+
+  static get template() {
+    return html`
+      <style>
+        :host {
+          display: inline-block;
+        }
+
+        :host([hidden]) {
+          display: none !important;
+        }
+      </style>
+      <span part="checkmark" aria-hidden="true"></span>
+      <div part="content">
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  /** @protected */
+  ready() {
+    super.ready();
+
+    this.setAttribute('role', 'option');
+  }
 }
 
 customElements.define(SelectItem.is, SelectItem);
+
+export { SelectItem };

package/src/vaadin-select-list-box.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
+import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
+import { ListMixin } from '@vaadin/component-base/src/list-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+/**
+ * An element used internally by `<vaadin-select>`. Not intended to be used separately.
+ */
+declare class SelectListBox extends ListMixin(DirMixin(ThemableMixin(ControllerMixin(HTMLElement)))) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-select-list-box': SelectListBox;
+  }
+}
+
+export { SelectListBox };

package/src/vaadin-select-list-box.js

@@ -3,18 +3,77 @@
  * Copyright (c) 2017 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { ListBox } from '@vaadin/list-box/src/vaadin-list-box.js';
+import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
+import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
+import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
+import { ListMixin } from '@vaadin/component-base/src/list-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
  * An element used internally by `<vaadin-select>`. Not intended to be used separately.
  *
- * @extends ListBox
+ * @extends HTMLElement
+ * @mixes ControllerMixin
+ * @mixes DirMixin
+ * @mixes ListMixin
+ * @mixes ThemableMixin
  * @protected
  */
-class SelectListBox extends ListBox {
+class SelectListBox extends ListMixin(ThemableMixin(DirMixin(ControllerMixin(PolymerElement)))) {
   static get is() {
     return 'vaadin-select-list-box';
   }
+
+  static get template() {
+    return html`
+      <style>
+        :host {
+          display: flex;
+        }
+
+        :host([hidden]) {
+          display: none !important;
+        }
+
+        [part='items'] {
+          height: 100%;
+          width: 100%;
+          overflow-y: auto;
+          -webkit-overflow-scrolling: touch;
+        }
+      </style>
+      <div part="items">
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  static get properties() {
+    return {
+      // We don't need to define this property since super default is vertical,
+      // but we don't want it to be modified, or be shown in the API docs.
+      /** @private */
+      orientation: {
+        readOnly: true,
+      },
+    };
+  }
+
+  /**
+   * @return {!HTMLElement}
+   * @protected
+   * @override
+   */
+  get _scrollerElement() {
+    return this.shadowRoot.querySelector('[part="items"]');
+  }
+
+  /** @protected */
+  ready() {
+    super.ready();
+
+    this.setAttribute('role', 'listbox');
+  }
 }
 
 customElements.define(SelectListBox.is, SelectListBox);

package/src/vaadin-select.js

@@ -447,8 +447,6 @@ class Select extends OverlayClassMixin(
         true,
       );
 
-      menuElement.setAttribute('role', 'listbox');
-
       // Store the menu element reference
       this.__lastMenuElement = menuElement;
     }
@@ -458,7 +456,6 @@ class Select extends OverlayClassMixin(
   __initMenuItems(menuElement) {
     if (menuElement.items) {
       this._items = menuElement.items;
-      this._items.forEach((item) => item.setAttribute('role', 'option'));
     }
   }
 
@@ -594,8 +591,7 @@ class Select extends OverlayClassMixin(
     // Store reference to the original item
     labelItem._sourceItem = selected;
 
-    this.__initValueItemElement(labelItem);
-    this.focusElement.appendChild(labelItem);
+    this.__appendValueItemElement(labelItem, this.focusElement);
 
     // Ensure the item gets proper styles
     labelItem.selected = true;
@@ -621,10 +617,13 @@ class Select extends OverlayClassMixin(
 
   /**
    * @param {!HTMLElement} itemElement
+   * @param {!HTMLElement} parent
    * @private
    */
-  __initValueItemElement(itemElement) {
+  __appendValueItemElement(itemElement, parent) {
+    parent.appendChild(itemElement);
     itemElement.removeAttribute('tabindex');
+    itemElement.removeAttribute('aria-selected');
     itemElement.removeAttribute('role');
     itemElement.setAttribute('id', this._itemId);
   }
@@ -646,8 +645,7 @@ class Select extends OverlayClassMixin(
     if (!selected) {
       if (this.placeholder) {
         const item = this.__createItemElement({ label: this.placeholder });
-        this.__initValueItemElement(item);
-        valueButton.appendChild(item);
+        this.__appendValueItemElement(item, valueButton);
         valueButton.setAttribute('placeholder', '');
       }
     } else {

package/theme/lumo/vaadin-select-styles.js

@@ -6,10 +6,16 @@
 import '@vaadin/vaadin-lumo-styles/sizing.js';
 import '@vaadin/vaadin-lumo-styles/style.js';
 import '@vaadin/vaadin-lumo-styles/font-icons.js';
+import { item } from '@vaadin/item/theme/lumo/vaadin-item-styles.js';
+import { listBox } from '@vaadin/list-box/theme/lumo/vaadin-list-box-styles.js';
 import { inputFieldShared } from '@vaadin/vaadin-lumo-styles/mixins/input-field-shared.js';
 import { menuOverlay } from '@vaadin/vaadin-lumo-styles/mixins/menu-overlay.js';
 import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+registerStyles('vaadin-select-item', item, { moduleId: 'lumo-select-item' });
+
+registerStyles('vaadin-select-list-box', listBox, { moduleId: 'lumo-select-list-box' });
+
 const select = css`
   :host(:not([theme*='align'])) ::slotted([slot='value']) {
     text-align: start;

package/theme/lumo/vaadin-select.js

@@ -4,8 +4,6 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import '@vaadin/input-container/theme/lumo/vaadin-input-container.js';
-import '@vaadin/item/theme/lumo/vaadin-item.js';
-import '@vaadin/list-box/theme/lumo/vaadin-list-box.js';
 import '@vaadin/overlay/theme/lumo/vaadin-overlay.js';
 import './vaadin-select-styles.js';
 import '../../src/vaadin-select.js';

package/theme/material/vaadin-select-styles.js

@@ -4,10 +4,16 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import '@vaadin/vaadin-material-styles/font-icons.js';
+import { item } from '@vaadin/item/theme/material/vaadin-item-styles.js';
+import { listBox } from '@vaadin/list-box/theme/material/vaadin-list-box-styles.js';
 import { inputFieldShared } from '@vaadin/vaadin-material-styles/mixins/input-field-shared.js';
 import { menuOverlay } from '@vaadin/vaadin-material-styles/mixins/menu-overlay.js';
 import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+registerStyles('vaadin-select-item', item, { moduleId: 'material-select-item' });
+
+registerStyles('vaadin-select-list-box', listBox, { moduleId: 'material-select-list-box' });
+
 const select = css`
   :host {
     display: inline-flex;

package/theme/material/vaadin-select.js

@@ -4,8 +4,6 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import '@vaadin/input-container/theme/material/vaadin-input-container.js';
-import '@vaadin/item/theme/material/vaadin-item.js';
-import '@vaadin/list-box/theme/material/vaadin-list-box.js';
 import '@vaadin/overlay/theme/material/vaadin-overlay.js';
 import './vaadin-select-styles.js';
 import '../../src/vaadin-select.js';

package/web-types.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/select",
-  "version": "24.0.0-alpha12",
+  "version": "24.0.0-alpha13",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-select",
-          "description": "`<vaadin-select>` is a Web Component for selecting values from a list of items.\n\n### Items\n\nUse the `items` property to define possible options for the select:\n\n```html\n<vaadin-select id=\"select\"></vaadin-select>\n```\n```js\nconst select = document.querySelector('#select');\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc' },\n  { label: 'Rating: high to low', value: 'rating-desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\n### Rendering\n\nAlternatively, the content of the select can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `select` arguments.\nGenerate DOM content, append it to the `root` element and control the state\nof the host element by accessing `select`.\n\n```js\nconst select = document.querySelector('#select');\nselect.renderer = function(root, select) {\n  const listBox = document.createElement('vaadin-list-box');\n  // append 3 <vaadin-item> elements\n  ['Jose', 'Manolo', 'Pedro'].forEach(function(name) {\n    const item = document.createElement('vaadin-item');\n    item.textContent = name;\n    item.setAttribute('label', name)\n    listBox.appendChild(item);\n  });\n\n  // update the content\n  root.appendChild(listBox);\n};\n```\n\nRenderer is called on initialization of new select and on its opening.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n* Hint: By setting the `label` property of inner vaadin-items you will\nbe able to change the visual representation of the selected value in the input part.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                    | Description                  | Target element          | Default\n-----------------------------------|------------------------------|----------------------------------\n`--vaadin-field-default-width`     | Default width of the field   | :host                   | `12em`\n`--vaadin-select-text-field-width` | Effective width of the field | `vaadin-select-overlay` |\n\n`<vaadin-select>` provides mostly the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.\nSee [`<vaadin-text-field>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-text-field) for the styling documentation.\n\n\nIn addition to `<vaadin-text-field>` parts, the following parts are available for theming:\n\nPart name       | Description\n----------------|----------------\n`toggle-button` | The toggle button\n\nIn addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:\n\nAttribute | Description                 | Part name\n----------|-----------------------------|-----------\n`opened`  | Set when the select is open | :host\n\nThere are two exceptions in terms of styling compared to `<vaadin-text-field>`:\n- the `clear-button` shadow DOM part does not exist in `<vaadin-select>`.\n- the `input-prevented` state attribute is not supported by `<vaadin-select>`.\n\n### Internal components\n\nIn addition to `<vaadin-select>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-select-overlay>` - has the same API as [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-overlay).\n- `<vaadin-select-value-button>` - has the same API as [`<vaadin-button>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-button).\n- [`<vaadin-input-container>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-input-container) - an internal element wrapping the button.\n\nNote: the `theme` attribute value set on `<vaadin-select>` is\npropagated to the internal components listed above.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.",
+          "description": "`<vaadin-select>` is a Web Component for selecting values from a list of items.\n\n### Items\n\nUse the `items` property to define possible options for the select:\n\n```html\n<vaadin-select id=\"select\"></vaadin-select>\n```\n```js\nconst select = document.querySelector('#select');\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc' },\n  { label: 'Rating: high to low', value: 'rating-desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\n### Rendering\n\nAlternatively, the content of the select can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `select` arguments.\nGenerate DOM content, append it to the `root` element and control the state\nof the host element by accessing `select`.\n\n```js\nconst select = document.querySelector('#select');\nselect.renderer = function(root, select) {\n  const listBox = document.createElement('vaadin-list-box');\n  // append 3 <vaadin-item> elements\n  ['Jose', 'Manolo', 'Pedro'].forEach(function(name) {\n    const item = document.createElement('vaadin-item');\n    item.textContent = name;\n    item.setAttribute('label', name)\n    listBox.appendChild(item);\n  });\n\n  // update the content\n  root.appendChild(listBox);\n};\n```\n\nRenderer is called on initialization of new select and on its opening.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n* Hint: By setting the `label` property of inner vaadin-items you will\nbe able to change the visual representation of the selected value in the input part.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                    | Description                  | Target element          | Default\n-----------------------------------|------------------------------|----------------------------------\n`--vaadin-field-default-width`     | Default width of the field   | :host                   | `12em`\n`--vaadin-select-text-field-width` | Effective width of the field | `vaadin-select-overlay` |\n\n`<vaadin-select>` provides mostly the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.\nSee [`<vaadin-text-field>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-text-field) for the styling documentation.\n\n\nIn addition to `<vaadin-text-field>` parts, the following parts are available for theming:\n\nPart name       | Description\n----------------|----------------\n`toggle-button` | The toggle button\n\nIn addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:\n\nAttribute | Description                 | Part name\n----------|-----------------------------|-----------\n`opened`  | Set when the select is open | :host\n\nThere are two exceptions in terms of styling compared to `<vaadin-text-field>`:\n- the `clear-button` shadow DOM part does not exist in `<vaadin-select>`.\n- the `input-prevented` state attribute is not supported by `<vaadin-select>`.\n\n### Internal components\n\nIn addition to `<vaadin-select>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-select-overlay>` - has the same API as [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-overlay).\n- `<vaadin-select-value-button>` - has the same API as [`<vaadin-button>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-button).\n- [`<vaadin-input-container>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-input-container) - an internal element wrapping the button.\n\nNote: the `theme` attribute value set on `<vaadin-select>` is\npropagated to the internal components listed above.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.",
           "attributes": [
             {
               "name": "label",

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/select",
-  "version": "24.0.0-alpha12",
+  "version": "24.0.0-alpha13",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,7 +16,7 @@
       "elements": [
         {
           "name": "vaadin-select",
-          "description": "`<vaadin-select>` is a Web Component for selecting values from a list of items.\n\n### Items\n\nUse the `items` property to define possible options for the select:\n\n```html\n<vaadin-select id=\"select\"></vaadin-select>\n```\n```js\nconst select = document.querySelector('#select');\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc' },\n  { label: 'Rating: high to low', value: 'rating-desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\n### Rendering\n\nAlternatively, the content of the select can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `select` arguments.\nGenerate DOM content, append it to the `root` element and control the state\nof the host element by accessing `select`.\n\n```js\nconst select = document.querySelector('#select');\nselect.renderer = function(root, select) {\n  const listBox = document.createElement('vaadin-list-box');\n  // append 3 <vaadin-item> elements\n  ['Jose', 'Manolo', 'Pedro'].forEach(function(name) {\n    const item = document.createElement('vaadin-item');\n    item.textContent = name;\n    item.setAttribute('label', name)\n    listBox.appendChild(item);\n  });\n\n  // update the content\n  root.appendChild(listBox);\n};\n```\n\nRenderer is called on initialization of new select and on its opening.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n* Hint: By setting the `label` property of inner vaadin-items you will\nbe able to change the visual representation of the selected value in the input part.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                    | Description                  | Target element          | Default\n-----------------------------------|------------------------------|----------------------------------\n`--vaadin-field-default-width`     | Default width of the field   | :host                   | `12em`\n`--vaadin-select-text-field-width` | Effective width of the field | `vaadin-select-overlay` |\n\n`<vaadin-select>` provides mostly the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.\nSee [`<vaadin-text-field>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-text-field) for the styling documentation.\n\n\nIn addition to `<vaadin-text-field>` parts, the following parts are available for theming:\n\nPart name       | Description\n----------------|----------------\n`toggle-button` | The toggle button\n\nIn addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:\n\nAttribute | Description                 | Part name\n----------|-----------------------------|-----------\n`opened`  | Set when the select is open | :host\n\nThere are two exceptions in terms of styling compared to `<vaadin-text-field>`:\n- the `clear-button` shadow DOM part does not exist in `<vaadin-select>`.\n- the `input-prevented` state attribute is not supported by `<vaadin-select>`.\n\n### Internal components\n\nIn addition to `<vaadin-select>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-select-overlay>` - has the same API as [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-overlay).\n- `<vaadin-select-value-button>` - has the same API as [`<vaadin-button>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-button).\n- [`<vaadin-input-container>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha12/#/elements/vaadin-input-container) - an internal element wrapping the button.\n\nNote: the `theme` attribute value set on `<vaadin-select>` is\npropagated to the internal components listed above.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.",
+          "description": "`<vaadin-select>` is a Web Component for selecting values from a list of items.\n\n### Items\n\nUse the `items` property to define possible options for the select:\n\n```html\n<vaadin-select id=\"select\"></vaadin-select>\n```\n```js\nconst select = document.querySelector('#select');\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc' },\n  { label: 'Rating: high to low', value: 'rating-desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\n### Rendering\n\nAlternatively, the content of the select can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `select` arguments.\nGenerate DOM content, append it to the `root` element and control the state\nof the host element by accessing `select`.\n\n```js\nconst select = document.querySelector('#select');\nselect.renderer = function(root, select) {\n  const listBox = document.createElement('vaadin-list-box');\n  // append 3 <vaadin-item> elements\n  ['Jose', 'Manolo', 'Pedro'].forEach(function(name) {\n    const item = document.createElement('vaadin-item');\n    item.textContent = name;\n    item.setAttribute('label', name)\n    listBox.appendChild(item);\n  });\n\n  // update the content\n  root.appendChild(listBox);\n};\n```\n\nRenderer is called on initialization of new select and on its opening.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n* Hint: By setting the `label` property of inner vaadin-items you will\nbe able to change the visual representation of the selected value in the input part.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                    | Description                  | Target element          | Default\n-----------------------------------|------------------------------|----------------------------------\n`--vaadin-field-default-width`     | Default width of the field   | :host                   | `12em`\n`--vaadin-select-text-field-width` | Effective width of the field | `vaadin-select-overlay` |\n\n`<vaadin-select>` provides mostly the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.\nSee [`<vaadin-text-field>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-text-field) for the styling documentation.\n\n\nIn addition to `<vaadin-text-field>` parts, the following parts are available for theming:\n\nPart name       | Description\n----------------|----------------\n`toggle-button` | The toggle button\n\nIn addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:\n\nAttribute | Description                 | Part name\n----------|-----------------------------|-----------\n`opened`  | Set when the select is open | :host\n\nThere are two exceptions in terms of styling compared to `<vaadin-text-field>`:\n- the `clear-button` shadow DOM part does not exist in `<vaadin-select>`.\n- the `input-prevented` state attribute is not supported by `<vaadin-select>`.\n\n### Internal components\n\nIn addition to `<vaadin-select>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-select-overlay>` - has the same API as [`<vaadin-overlay>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-overlay).\n- `<vaadin-select-value-button>` - has the same API as [`<vaadin-button>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-button).\n- [`<vaadin-input-container>`](https://cdn.vaadin.com/vaadin-web-components/24.0.0-alpha13/#/elements/vaadin-input-container) - an internal element wrapping the button.\n\nNote: the `theme` attribute value set on `<vaadin-select>` is\npropagated to the internal components listed above.\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/custom-theme/styling-components) documentation.",
           "extension": true,
           "attributes": [
             {