@vaadin/select 25.3.0-alpha1 → 25.3.0-alpha10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/select",
-  "version": "25.3.0-alpha1",
+  "version": "25.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -37,24 +37,24 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.3.0-alpha1",
-    "@vaadin/button": "25.3.0-alpha1",
-    "@vaadin/component-base": "25.3.0-alpha1",
-    "@vaadin/field-base": "25.3.0-alpha1",
-    "@vaadin/input-container": "25.3.0-alpha1",
-    "@vaadin/item": "25.3.0-alpha1",
-    "@vaadin/list-box": "25.3.0-alpha1",
-    "@vaadin/lit-renderer": "25.3.0-alpha1",
-    "@vaadin/overlay": "25.3.0-alpha1",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha1",
+    "@vaadin/a11y-base": "25.3.0-alpha10",
+    "@vaadin/button": "25.3.0-alpha10",
+    "@vaadin/component-base": "25.3.0-alpha10",
+    "@vaadin/field-base": "25.3.0-alpha10",
+    "@vaadin/input-container": "25.3.0-alpha10",
+    "@vaadin/item": "25.3.0-alpha10",
+    "@vaadin/list-box": "25.3.0-alpha10",
+    "@vaadin/lit-renderer": "25.3.0-alpha10",
+    "@vaadin/overlay": "25.3.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha1",
-    "@vaadin/chai-plugins": "25.3.0-alpha1",
-    "@vaadin/test-runner-commands": "25.3.0-alpha1",
+    "@vaadin/aura": "25.3.0-alpha10",
+    "@vaadin/chai-plugins": "25.3.0-alpha10",
+    "@vaadin/test-runner-commands": "25.3.0-alpha10",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha1",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha10",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -62,5 +62,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "5824d54c995945aafd50d30edc2cb763a58a18b6"
+  "gitHead": "f2833abdf9b613fa0d0ed216830e3f4de87b7dac"
 }

package/src/lit/renderer-directives.d.ts

@@ -52,6 +52,7 @@ export class SelectRendererDirective extends LitRendererDirective<Select, Select
  * @param renderer the renderer callback that returns a Lit template.
  * @param dependencies a single dependency or an array of dependencies
  *                     which trigger a re-render when changed.
+ * @deprecated Use a slotted `<vaadin-select-list-box>` or the `items` property instead
  */
 export declare function selectRenderer(
   renderer: SelectLitRenderer,

package/src/lit/renderer-directives.js

@@ -56,5 +56,6 @@ export class SelectRendererDirective extends LitRendererDirective {
  * @param renderer the renderer callback that returns a Lit template.
  * @param dependencies a single dependency or an array of dependencies
  *                     which trigger a re-render when changed.
+ * @deprecated Use a slotted `<vaadin-select-list-box>` or the `items` property instead
  */
 export const selectRenderer = directive(SelectRendererDirective);

package/src/vaadin-select-base-mixin.d.ts

@@ -13,7 +13,7 @@ import type { DelegateStateMixinClass } from '@vaadin/component-base/src/delegat
 import type { FieldMixinClass } from '@vaadin/field-base/src/field-mixin.js';
 import type { LabelMixinClass } from '@vaadin/field-base/src/label-mixin.js';
 import type { ValidateMixinClass } from '@vaadin/field-base/src/validate-mixin.js';
-import type { SelectItem, SelectRenderer } from './vaadin-select.js';
+import type { SelectItemData, SelectRenderer } from './vaadin-select.js';
 
 export declare function SelectBaseMixin<T extends Constructor<HTMLElement>>(
   base: T,
@@ -49,7 +49,7 @@ export declare class SelectBaseMixinClass {
    * Note: each item is rendered by default as the internal `<vaadin-select-item>` that is an extension of `<vaadin-item>`.
    * To render the item with a custom component, provide a tag name by the `component` property.
    */
-  items: SelectItem[] | null | undefined;
+  items: SelectItemData[] | null | undefined;
 
   /**
    * Set when the select is open
@@ -62,6 +62,8 @@ export declare class SelectBaseMixinClass {
    *
    * - `root` The internal container DOM element. Append your content to it.
    * - `select` The reference to the `<vaadin-select>` element.
+   *
+   * @deprecated Use a slotted `<vaadin-select-list-box>` or the `items` property instead
    */
   renderer: SelectRenderer | undefined;
 
@@ -110,6 +112,8 @@ export declare class SelectBaseMixinClass {
    * While performing the update, it invokes the renderer passed in the `renderer` property.
    *
    * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
+   *
+   * @deprecated This method is deprecated and will be removed in Vaadin 26
    */
   requestContentUpdate(): void;
 }

package/src/vaadin-select-base-mixin.js

@@ -3,10 +3,10 @@
  * Copyright (c) 2017 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { setAriaIDReference } from '@vaadin/a11y-base/src/aria-id-reference.js';
 import { DelegateFocusMixin } from '@vaadin/a11y-base/src/delegate-focus-mixin.js';
 import { KeyboardMixin } from '@vaadin/a11y-base/src/keyboard-mixin.js';
 import { DelegateStateMixin } from '@vaadin/component-base/src/delegate-state-mixin.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { MediaQueryController } from '@vaadin/component-base/src/media-query-controller.js';
 import { TooltipController } from '@vaadin/component-base/src/tooltip-controller.js';
 import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
@@ -37,11 +37,10 @@ export const SelectBaseMixin = (superClass) =>
          * Note: each item is rendered by default as the internal `<vaadin-select-item>` that is an extension of `<vaadin-item>`.
          * To render the item with a custom component, provide a tag name by the `component` property.
          *
-         * @type {!Array<!SelectItem>}
+         * @type {!Array<!SelectItemData>}
          */
         items: {
           type: Array,
-          observer: '__itemsChanged',
         },
 
         /**
@@ -62,7 +61,9 @@ export const SelectBaseMixin = (superClass) =>
          *
          * - `root` The internal container DOM element. Append your content to it.
          * - `select` The reference to the `<vaadin-select>` element.
+         *
          * @type {!SelectRenderer | undefined}
+         * @deprecated Use a slotted `<vaadin-select-list-box>` or the `items` property instead
          */
         renderer: {
           type: Object,
@@ -138,6 +139,15 @@ export const SelectBaseMixin = (superClass) =>
 
         /** @private */
         _items: Object,
+
+        /**
+         * The `<vaadin-select-list-box>` slotted directly into the overlay slot.
+         * @private
+         */
+        __slottedListBox: {
+          type: Object,
+          sync: true,
+        },
       };
     }
 
@@ -199,6 +209,38 @@ export const SelectBaseMixin = (superClass) =>
       if (props.has('_phone')) {
         this.toggleAttribute('phone', this._phone);
       }
+
+      if (props.has('items') || props.has('renderer') || props.has('__slottedListBox')) {
+        if (this.__slottedListBox && (this.items?.length || this.renderer)) {
+          throw new Error(
+            'A slotted <vaadin-select-list-box> cannot be used together with the "items" or "renderer" property.',
+          );
+        }
+      }
+
+      if (props.has('items')) {
+        this._overlayElement.requestContentUpdate();
+      }
+
+      if (props.has('__slottedListBox')) {
+        const slottedListBox = this.__slottedListBox;
+        if (slottedListBox) {
+          this._assignMenuElement(slottedListBox);
+        } else if (props.get('__slottedListBox')) {
+          this._menuElement = null;
+          this._items = null;
+          this.__lastMenuElement = null;
+        }
+      }
+
+      if (props.has('accessibleName')) {
+        this._srLabelController.setLabel(this.accessibleName);
+      }
+
+      // Validate when the required constraint is removed.
+      if (props.has('required') && this.required === false) {
+        this._requestValidation();
+      }
     }
 
     /**
@@ -206,6 +248,8 @@ export const SelectBaseMixin = (superClass) =>
      * While performing the update, it invokes the renderer passed in the `renderer` property.
      *
      * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
+     *
+     * @deprecated This method is deprecated and will be removed in Vaadin 26
      */
     requestContentUpdate() {
       if (!this._overlayElement) {
@@ -216,29 +260,14 @@ export const SelectBaseMixin = (superClass) =>
     }
 
     /**
-     * Override an observer from `FieldMixin`
-     * to validate when required is removed.
+     * Detects a `<vaadin-select-list-box>` slotted directly into the overlay
+     * slot (instead of the default one rendered into slotted `div` element).
      *
-     * @protected
-     * @override
-     */
-    _requiredChanged(required) {
-      super._requiredChanged(required);
-
-      if (required === false) {
-        this._requestValidation();
-      }
-    }
-
-    /**
-     * @param {SelectItem[] | undefined | null} newItems
-     * @param {SelectItem[] | undefined | null} oldItems
+     * @param {!Event} e
      * @private
      */
-    __itemsChanged(newItems, oldItems) {
-      if (newItems || oldItems) {
-        this.requestContentUpdate();
-      }
+    __onOverlaySlotChange(e) {
+      this.__slottedListBox = e.target.assignedElements().find((el) => el._hasVaadinListMixin);
     }
 
     /**
@@ -438,11 +467,7 @@ export const SelectBaseMixin = (superClass) =>
     /** @private */
     _updateAriaLive(ariaLive) {
       if (this.focusElement) {
-        if (ariaLive) {
-          this.focusElement.setAttribute('aria-live', 'polite');
-        } else {
-          this.focusElement.removeAttribute('aria-live');
-        }
+        setOrRemoveAttribute(this.focusElement, 'aria-live', ariaLive && 'polite');
       }
     }
 
@@ -467,7 +492,7 @@ export const SelectBaseMixin = (superClass) =>
     }
 
     /**
-     * @param {!SelectItem} item
+     * @param {!SelectItemData} item
      * @private
      */
     __createItemElement(item) {
@@ -503,44 +528,6 @@ export const SelectBaseMixin = (superClass) =>
       itemElement.setAttribute('id', this._itemId);
     }
 
-    /**
-     * @param {string} accessibleName
-     * @protected
-     */
-    _accessibleNameChanged(accessibleName) {
-      this._srLabelController.setLabel(accessibleName);
-      this._setCustomAriaLabelledBy(accessibleName ? this._srLabelController.defaultId : null);
-    }
-
-    /**
-     * @param {string} accessibleNameRef
-     * @protected
-     */
-    _accessibleNameRefChanged(accessibleNameRef) {
-      this._setCustomAriaLabelledBy(accessibleNameRef);
-    }
-
-    /**
-     * @param {string} ariaLabelledby
-     * @private
-     */
-    _setCustomAriaLabelledBy(ariaLabelledby) {
-      const labelId = this._getLabelIdWithItemId(ariaLabelledby);
-      this._fieldAriaController.setLabelId(labelId, true);
-    }
-
-    /**
-     * @param {string | null} labelId
-     * @returns string | null
-     * @private
-     */
-    _getLabelIdWithItemId(labelId) {
-      const selected = this._items ? this._items[this._menuElement.selected] : false;
-      const itemId = selected || this.placeholder ? this._itemId : '';
-
-      return labelId ? `${labelId} ${itemId}`.trim() : null;
-    }
-
     /** @private */
     __updateValueButton() {
       const valueButton = this.focusElement;
@@ -572,13 +559,7 @@ export const SelectBaseMixin = (superClass) =>
         delete this._selectedChanging;
       }
 
-      const labelledIdReferenceConfig =
-        selected || this.placeholder ? { newId: this._itemId } : { oldId: this._itemId };
-
-      setAriaIDReference(valueButton, 'aria-labelledby', labelledIdReferenceConfig);
-      if (this.accessibleName || this.accessibleNameRef) {
-        this._setCustomAriaLabelledBy(this.accessibleNameRef || this._srLabelController.defaultId);
-      }
+      this.__updateFieldAriaControllerLabelledBy();
     }
 
     /** @private */
@@ -674,4 +655,31 @@ export const SelectBaseMixin = (superClass) =>
       this.dispatchEvent(new CustomEvent('change', { bubbles: true }));
       this.__dispatchChangePending = false;
     }
+
+    /** @override */
+    __updateFieldAriaControllerLabel() {
+      // NO-OP
+    }
+
+    /** @override */
+    __updateFieldAriaControllerLabelledBy() {
+      let labelId;
+      if (this.accessibleNameRef) {
+        labelId = this.accessibleNameRef;
+      } else if (this.accessibleName) {
+        labelId = this._srLabelController.defaultId;
+      } else if (this.hasAttribute('has-label')) {
+        labelId = this._labelNode?.id;
+      }
+
+      const selectedItem = this._items?.[this._menuElement.selected];
+      const itemId = selectedItem || this.placeholder ? this._itemId : null;
+
+      const ids = [labelId, itemId].filter(Boolean);
+      if (ids.length > 0) {
+        this._fieldAriaController.setLabelledBy(ids.join(' '));
+      } else {
+        this._fieldAriaController.setLabelledBy(null);
+      }
+    }
   };

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

@@ -8,9 +8,51 @@ 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.
+ * `<vaadin-select-item>` is a Web Component for creating `<vaadin-select>` items.
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name    | Description
+ * -------------|----------------
+ * `checkmark`  | The graphical checkmark shown for a selected item
+ * `content`    | The element that wraps the slot
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute    | Description
+ * -------------|-------------
+ * `active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.
+ * `disabled`   | Set when the item is disabled.
+ * `focus-ring` | Set when the item is focused using the keyboard.
+ * `focused`    | Set when the item is focused.
+ * `selected`   | Set when the item is selected
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                |
+ * :----------------------------------|
+ * | `--vaadin-item-border-radius`    |
+ * | `--vaadin-item-checkmark-color`  |
+ * | `--vaadin-item-gap`              |
+ * | `--vaadin-item-height`           |
+ * | `--vaadin-item-padding`          |
+ * | `--vaadin-item-text-align`       |
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
-declare class SelectItem extends ItemMixin(DirMixin(ThemableMixin(HTMLElement))) {}
+declare class SelectItem extends ItemMixin(DirMixin(ThemableMixin(HTMLElement))) {
+  /**
+   * Submittable string value. The default value is the trimmed text content of the element.
+   */
+  value: string;
+
+  /**
+   * String that can be set to visually represent the selected item in `vaadin-select`.
+   */
+  label: string | undefined;
+}
 
 declare global {
   interface HTMLElementTagNameMap {

package/src/vaadin-select-item.js

@@ -13,11 +13,44 @@ import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
- * An element used internally by `<vaadin-select>`. Not intended to be used separately.
+ * `<vaadin-select-item>` is a Web Component for creating `<vaadin-select>` items.
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name    | Description
+ * -------------|----------------
+ * `checkmark`  | The graphical checkmark shown for a selected item
+ * `content`    | The element that wraps the slot
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute    | Description
+ * -------------|-------------
+ * `active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.
+ * `disabled`   | Set when the item is disabled.
+ * `focus-ring` | Set when the item is focused using the keyboard.
+ * `focused`    | Set when the item is focused.
+ * `selected`   | Set when the item is selected
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                |
+ * :----------------------------------|
+ * | `--vaadin-item-border-radius`    |
+ * | `--vaadin-item-checkmark-color`  |
+ * | `--vaadin-item-gap`              |
+ * | `--vaadin-item-height`           |
+ * | `--vaadin-item-padding`          |
+ * | `--vaadin-item-text-align`       |
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @prop {string} label - String that can be set to visually represent the selected item in `vaadin-select`.
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-select-item
  * @extends HTMLElement
- * @protected
  */
 class SelectItem extends ItemMixin(ThemableMixin(DirMixin(PolylitMixin(LumoInjectionMixin(LitElement))))) {
   static get is() {

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

@@ -8,7 +8,26 @@ import { DirMixin } from '@vaadin/component-base/src/dir-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.
+ * `<vaadin-select-list-box>` is a Web Component for wrapping `<vaadin-select>` items.
+ *
+ * ```html
+ * <vaadin-select>
+ *   <vaadin-select-list-box slot="overlay">
+ *     <vaadin-select-item value="foo">Foo</vaadin-select-item>
+ *     <vaadin-select-item value="bar">Bar</vaadin-select-item>
+ *   </vaadin-select-list-box>
+ * </vaadin-select>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name         | Description
+ * ------------------|------------------------
+ * `items`           | The items container
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
 declare class SelectListBox extends ListMixin(DirMixin(ThemableMixin(HTMLElement))) {}
 

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

@@ -13,11 +13,30 @@ import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
- * An element used internally by `<vaadin-select>`. Not intended to be used separately.
+ * `<vaadin-select-list-box>` is a Web Component for wrapping `<vaadin-select>` items.
  *
+ * ```html
+ * <vaadin-select>
+ *   <vaadin-select-list-box slot="overlay">
+ *     <vaadin-select-item value="foo">Foo</vaadin-select-item>
+ *     <vaadin-select-item value="bar">Bar</vaadin-select-item>
+ *   </vaadin-select-list-box>
+ * </vaadin-select>
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name         | Description
+ * ------------------|------------------------
+ * `items`           | The items container
+ *
+ * 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-select-list-box
  * @extends HTMLElement
- * @protected
  */
 class SelectListBox extends ListMixin(ThemableMixin(DirMixin(PolylitMixin(LumoInjectionMixin(LitElement))))) {
   static get is() {

package/src/vaadin-select-overlay-mixin.js

@@ -9,8 +9,14 @@ import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin
 
 export const SelectOverlayMixin = (superClass) =>
   class SelectOverlayMixin extends PositionMixin(OverlayMixin(DirMixin(superClass))) {
-    static get observers() {
-      return ['_updateOverlayWidth(opened, positionTarget)'];
+    /** @protected */
+    willUpdate(props) {
+      super.willUpdate(props);
+
+      // Update width here so that `PositionMixin` uses correct width in `updated()`.
+      if ((props.has('opened') || props.has('positionTarget')) && this.opened && this.positionTarget) {
+        this._updateOverlayWidth();
+      }
     }
 
     /** @protected */
@@ -21,12 +27,14 @@ export const SelectOverlayMixin = (superClass) =>
     }
 
     /**
-     * Override method from OverlayFocusMixin to use slotted div as content root.
+     * Override method from OverlayFocusMixin to use the content root that
+     * actually holds the focused item, so focus is restored on close.
+     *
      * @protected
      * @override
      */
     get _contentRoot() {
-      return this._rendererRoot;
+      return this.owner.__slottedListBox || this._rendererRoot;
     }
 
     /**
@@ -70,14 +78,17 @@ export const SelectOverlayMixin = (superClass) =>
 
     /** @protected */
     _getMenuElement() {
-      return Array.from(this._rendererRoot.children).find((el) => el.localName !== 'style');
+      const slot = this.owner.shadowRoot.querySelector('slot[name="overlay"]');
+      const assigned = slot.assignedElements();
+      return (
+        assigned.find((el) => el._hasVaadinListMixin) ||
+        assigned.flatMap((el) => [...el.children]).find((el) => el._hasVaadinListMixin)
+      );
     }
 
     /** @private */
-    _updateOverlayWidth(opened, positionTarget) {
-      if (opened && positionTarget) {
-        this.style.setProperty('--_vaadin-select-overlay-default-width', `${positionTarget.offsetWidth}px`);
-      }
+    _updateOverlayWidth() {
+      this.style.setProperty('--_vaadin-select-overlay-default-width', `${this.positionTarget.offsetWidth}px`);
     }
 
     requestContentUpdate() {

package/src/vaadin-select-overlay.js

@@ -15,11 +15,12 @@ import { SelectOverlayMixin } from './vaadin-select-overlay-mixin.js';
 /**
  * An element used internally by `<vaadin-select>`. Not intended to be used separately.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-select-overlay
  * @extends HTMLElement
  * @private
  */
-export class SelectOverlay extends SelectOverlayMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement)))) {
+class SelectOverlay extends SelectOverlayMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement)))) {
   static get is() {
     return 'vaadin-select-overlay';
   }
@@ -51,3 +52,5 @@ export class SelectOverlay extends SelectOverlayMixin(ThemableMixin(PolylitMixin
 }
 
 defineCustomElement(SelectOverlay);
+
+export { SelectOverlay };

package/src/vaadin-select-value-button.js

@@ -14,6 +14,7 @@ import { valueButton } from './styles/vaadin-select-value-button-base-styles.js'
 /**
  * An element used internally by `<vaadin-select>`. Not intended to be used separately.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-select-value-button
  * @extends HTMLElement
  * @protected