@vaadin/combo-box 25.3.0-dev.1fa5a51482 → 25.3.0-rc1

package/src/vaadin-combo-box-items-mixin.d.ts

@@ -6,6 +6,8 @@
 import type { Constructor } from '@open-wc/dedupe-mixin';
 import type { ComboBoxBaseMixinClass } from './vaadin-combo-box-base-mixin.js';
 
+export type ComboBoxPartialMatchMode = 'first-match' | 'none' | 'only-match';
+
 export declare function ComboBoxItemsMixin<TItem, T extends Constructor<HTMLElement>>(
   base: T,
 ): Constructor<ComboBoxBaseMixinClass> & Constructor<ComboBoxItemsMixinClass<TItem>> & T;
@@ -57,4 +59,47 @@ export declare class ComboBoxItemsMixinClass<TItem> {
    * @attr {string} item-value-path
    */
   itemValuePath: string;
+
+  /**
+   * Path for the id of the item. If `items` is an array of objects,
+   * the `itemIdPath` is used to compare and identify the same item
+   * in the selection and in `filteredItems` (items given by the
+   * `dataProvider` callback).
+   * @attr {string} item-id-path
+   */
+  itemIdPath: string | null | undefined;
+
+  /**
+   * Controls which item is automatically set to be selected, for
+   * example on Enter, when the typed filter only partially matches
+   * its label. The item that will be selected is highlighted in the
+   * dropdown while typing:
+   *
+   * - `none` (default): an item is automatically set to be selected only when the filter matches its label exactly.
+   * - `first-match`: the first item in the filtered results is automatically set to be selected.
+   * - `only-match`: the item is automatically set to be selected when filtering narrows the results to a single item.
+   *
+   * In general, an exact match is always set to be selected and takes
+   * precedence over partial matches, regardless of the mode.
+   *
+   * A partial match is only applied while the dropdown is open. For
+   * example, when auto-open is disabled with `autoOpenDisabled`, typing
+   * does not highlight a match or set it to be selected until the
+   * dropdown is opened.
+   *
+   * This feature cannot be used together with custom values, because a
+   * partial match is also a valid custom value. A partial match is not
+   * applied when custom values are allowed with `allowCustomValue`.
+   *
+   * @attr {none|first-match|only-match} partial-match-mode
+   */
+  partialMatchMode: ComboBoxPartialMatchMode;
+
+  /**
+   * Requests an update for the content of items.
+   * While performing the update, it invokes the renderer (passed in the `renderer` property) once an item.
+   *
+   * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
+   */
+  requestContentUpdate(): void;
 }

package/src/vaadin-combo-box-items-mixin.js

@@ -111,6 +111,47 @@ export const ComboBoxItemsMixin = (superClass) =>
           value: 'value',
           sync: true,
         },
+
+        /**
+         * Path for the id of the item. If `items` is an array of objects,
+         * the `itemIdPath` is used to compare and identify the same item
+         * in the selection and in `filteredItems` (items given by the
+         * `dataProvider` callback).
+         * @attr {string} item-id-path
+         */
+        itemIdPath: {
+          type: String,
+          sync: true,
+        },
+
+        /**
+         * Controls which item is automatically set to be selected, for
+         * example on Enter, when the typed filter only partially matches
+         * its label. The item that will be selected is highlighted in the
+         * dropdown while typing:
+         *
+         * - `none` (default): an item is automatically set to be selected only when the filter matches its label exactly.
+         * - `first-match`: the first item in the filtered results is automatically set to be selected.
+         * - `only-match`: the item is automatically set to be selected when filtering narrows the results to a single item.
+         *
+         * In general, an exact match is always set to be selected and takes
+         * precedence over partial matches, regardless of the mode.
+         *
+         * A partial match is only applied while the dropdown is open. For
+         * example, when auto-open is disabled with `autoOpenDisabled`, typing
+         * does not highlight a match or set it to be selected until the
+         * dropdown is opened.
+         *
+         * This feature cannot be used together with custom values, because a
+         * partial match is also a valid custom value. A partial match is not
+         * applied when custom values are allowed with `allowCustomValue`.
+         *
+         * @attr {none|first-match|only-match} partial-match-mode
+         */
+        partialMatchMode: {
+          type: String,
+          value: 'none',
+        },
       };
     }
 
@@ -130,6 +171,39 @@ export const ComboBoxItemsMixin = (superClass) =>
       }
     }
 
+    /**
+     * Requests an update for the content of items.
+     * While performing the update, it invokes the renderer (passed in the `renderer` property) once an item.
+     *
+     * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
+     */
+    requestContentUpdate() {
+      if (!this._scroller) {
+        return;
+      }
+
+      this._scroller.requestContentUpdate();
+
+      this._getItemElements().forEach((item) => {
+        item.requestContentUpdate();
+      });
+    }
+
+    /**
+     * Override method from `ComboBoxBaseMixin` to deselect
+     * dropdown item by requesting content update on clear.
+     * @param {Event} event
+     * @protected
+     * @override
+     */
+    _onClearButtonClick(event) {
+      super._onClearButtonClick(event);
+
+      if (this.opened) {
+        this.requestContentUpdate();
+      }
+    }
+
     /**
      * Override an event listener from `ComboBoxBaseMixin` to handle
      * batched setting of both `opened` and `filter` properties.
@@ -161,6 +235,22 @@ export const ComboBoxItemsMixin = (superClass) =>
       this.setProperties(props);
     }
 
+    /**
+     * Override method from `ComboBoxBaseMixin` to focus the item matching
+     * the filter when the dropdown is opened after typing, which is possible
+     * when `autoOpenDisabled` is enabled.
+     *
+     * @protected
+     * @override
+     */
+    _onOpened() {
+      super._onOpened();
+
+      if (this.filter && this._focusedIndex === -1) {
+        this._focusedIndex = this.__getItemIndexByFilter(this._dropdownItems);
+      }
+    }
+
     /**
      * Override method from `ComboBoxBaseMixin` to handle item label path.
      * @protected
@@ -187,6 +277,26 @@ export const ComboBoxItemsMixin = (superClass) =>
       return value;
     }
 
+    /**
+     * Override method from `ComboBoxBaseMixin` to compare object items
+     * by the value at `itemIdPath` instead of by identity.
+     * @param {unknown} item
+     * @param {unknown} other
+     * @return {boolean}
+     * @protected
+     * @override
+     */
+    _isSameItem(item, other) {
+      if (this.itemIdPath && item && other) {
+        const id = get(this.itemIdPath, item);
+        if (id !== undefined) {
+          return id === get(this.itemIdPath, other);
+        }
+      }
+
+      return super._isSameItem(item, other);
+    }
+
     /** @private */
     _itemLabelPathChanged(itemLabelPath) {
       if (typeof itemLabelPath !== 'string') {
@@ -231,12 +341,44 @@ export const ComboBoxItemsMixin = (superClass) =>
     }
 
     /**
-     * Provide items to be rendered in the dropdown.
-     * Override to provide actual implementation.
+     * Provide items to be rendered in the dropdown. Override this method
+     * to change the items to render, e.g. to show custom items.
+     *
+     * @param {Array} newItems
      * @protected
      */
-    _setDropdownItems() {
-      // To be implemented
+    _setDropdownItems(newItems) {
+      const oldItems = this._dropdownItems;
+      this._dropdownItems = newItems;
+
+      // Store the currently focused item if any. The focused index preserves
+      // in the case when more filtered items are loading but it is reset
+      // when the user types in a filter query.
+      const focusedItem = oldItems ? oldItems[this._focusedIndex] : null;
+
+      // When both the previously-focused entry and the new entry at the
+      // same index are placeholders (e.g. the Flow connector mid-scroll
+      // re-pushing `_setDropdownItems`), preserve `_focusedIndex` until
+      // a follow-up call lands a real item at that position.
+      if (
+        oldItems &&
+        oldItems[this._focusedIndex] instanceof ComboBoxPlaceholder &&
+        newItems[this._focusedIndex] instanceof ComboBoxPlaceholder
+      ) {
+        return;
+      }
+
+      // Try to first set focus on the item that had been focused before `newItems` were updated
+      // if it is still present in the `newItems` array. Otherwise, set the focused index
+      // depending on the selected item or the filter query.
+      const focusedItemIndex = this.__getItemIndexByValue(newItems, this._getItemValue(focusedItem));
+      if (focusedItemIndex > -1) {
+        this._focusedIndex = focusedItemIndex;
+      } else {
+        // When the user filled in something that is different from the current value = filtering is enabled,
+        // set the focused index to the item that matches the filter query.
+        this._focusedIndex = this.__getItemIndexByFilter(newItems);
+      }
     }
 
     /** @private */
@@ -282,4 +424,25 @@ export const ComboBoxItemsMixin = (superClass) =>
         return this._getItemLabel(item).toString().toLowerCase() === label.toString().toLowerCase();
       });
     }
+
+    /** @private */
+    __getItemIndexByFilter(items) {
+      // An item whose label matches the filter exactly takes precedence.
+      const exactMatchIndex = this.__getItemIndexByLabel(items, this.filter);
+      if (exactMatchIndex > -1) {
+        return exactMatchIndex;
+      }
+
+      if (!this.opened || !items || items.length === 0 || !this.filter || this.allowCustomValue) {
+        return -1;
+      }
+
+      if (this.partialMatchMode === 'first-match' || (this.partialMatchMode === 'only-match' && items.length === 1)) {
+        // Skip an item that is not yet loaded. Once the item is loaded,
+        // the focused index is updated again.
+        return items[0] instanceof ComboBoxPlaceholder ? -1 : 0;
+      }
+
+      return -1;
+    }
   };

package/src/vaadin-combo-box-mixin.d.ts

@@ -78,21 +78,4 @@ export declare class ComboBoxMixinClass<TItem> {
    * The selected item from the `items` array.
    */
   selectedItem: TItem | null | undefined;
-
-  /**
-   * Path for the id of the item. If `items` is an array of objects,
-   * the `itemIdPath` is used to compare and identify the same item
-   * in `selectedItem` and `filteredItems` (items given by the
-   * `dataProvider` callback).
-   * @attr {string} item-id-path
-   */
-  itemIdPath: string | null | undefined;
-
-  /**
-   * Requests an update for the content of items.
-   * While performing the update, it invokes the renderer (passed in the `renderer` property) once an item.
-   *
-   * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
-   */
-  requestContentUpdate(): void;
 }

package/src/vaadin-combo-box-mixin.js

@@ -5,7 +5,6 @@
  */
 import { ValidateMixin } from '@vaadin/field-base/src/validate-mixin.js';
 import { ComboBoxItemsMixin } from './vaadin-combo-box-items-mixin.js';
-import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
 
 /**
  * Checks if the value is supported as an item value in this control.
@@ -79,33 +78,11 @@ export const ComboBoxMixin = (superClass) =>
         itemClassNameGenerator: {
           type: Object,
         },
-
-        /**
-         * Path for the id of the item. If `items` is an array of objects,
-         * the `itemIdPath` is used to compare and identify the same item
-         * in `selectedItem` and `filteredItems` (items given by the
-         * `dataProvider` callback).
-         * @attr {string} item-id-path
-         */
-        itemIdPath: {
-          type: String,
-          sync: true,
-        },
-
-        /** @private */
-        __keepOverlayOpened: {
-          type: Boolean,
-          sync: true,
-        },
       };
     }
 
     static get observers() {
-      return [
-        '_openedOrItemsChanged(opened, _dropdownItems, loading, __keepOverlayOpened)',
-        '_selectedItemChanged(selectedItem, itemValuePath, itemLabelPath)',
-        '_updateScroller(opened, _dropdownItems, _focusedIndex, _theme)',
-      ];
+      return ['_selectedItemChanged(selectedItem, itemValuePath, itemLabelPath)'];
     }
 
     /** @protected */
@@ -121,24 +98,6 @@ export const ComboBoxMixin = (superClass) =>
       this._lastCommittedValue = this.value;
     }
 
-    /**
-     * Requests an update for the content of items.
-     * While performing the update, it invokes the renderer (passed in the `renderer` property) once an item.
-     *
-     * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
-     */
-    requestContentUpdate() {
-      if (!this._scroller) {
-        return;
-      }
-
-      this._scroller.requestContentUpdate();
-
-      this._getItemElements().forEach((item) => {
-        item.requestContentUpdate();
-      });
-    }
-
     /**
      * @param {Object} props
      * @protected
@@ -146,51 +105,13 @@ export const ComboBoxMixin = (superClass) =>
     updated(props) {
       super.updated(props);
 
-      ['loading', 'itemIdPath', 'itemClassNameGenerator', 'renderer', 'selectedItem'].forEach((prop) => {
+      ['loading', 'itemClassNameGenerator', 'renderer', 'selectedItem'].forEach((prop) => {
         if (props.has(prop)) {
           this._scroller[prop] = this[prop];
         }
       });
     }
 
-    /** @private */
-    _updateScroller(opened, items, focusedIndex, theme) {
-      if (opened) {
-        this._scroller.style.maxHeight =
-          getComputedStyle(this).getPropertyValue(`--${this._tagNamePrefix}-overlay-max-height`) || '65vh';
-      }
-
-      const isClosing = this.hasAttribute('closing');
-
-      this._scroller.setProperties({
-        items: opened || isClosing ? items : [],
-        opened,
-        focusedIndex,
-        theme,
-      });
-    }
-
-    /** @private */
-    _openedOrItemsChanged(opened, items, loading, keepOverlayOpened) {
-      // Close the overlay if there are no items to display.
-      // See https://github.com/vaadin/vaadin-combo-box/pull/964
-      this._overlayOpened = opened && (keepOverlayOpened || loading || !!items?.length);
-    }
-
-    /**
-     * Override method from `ComboBoxBaseMixin` to deselect
-     * dropdown item by requesting content update on clear.
-     * @param {Event} event
-     * @protected
-     */
-    _onClearButtonClick(event) {
-      super._onClearButtonClick(event);
-
-      if (this.opened) {
-        this.requestContentUpdate();
-      }
-    }
-
     /**
      * Override method inherited from `InputMixin`
      * to revert the input value to value.
@@ -281,6 +202,8 @@ export const ComboBoxMixin = (superClass) =>
      * @override
      */
     _onOpened() {
+      super._onOpened();
+
       this.dispatchEvent(new CustomEvent('vaadin-combo-box-dropdown-opened', { bubbles: true, composed: true }));
 
       // _detectAndDispatchChange() should not consider value changes done before opening
@@ -497,20 +420,14 @@ export const ComboBoxMixin = (superClass) =>
     }
 
     /**
-     * Provide items to be rendered in the dropdown.
-     * Override this method to show custom items.
+     * Override method from `ComboBoxItemsMixin` to sync `selectedItem`
+     * based on `value` once a new set of items is available.
      *
      * @protected
      * @override
      */
     _setDropdownItems(newItems) {
-      const oldItems = this._dropdownItems;
-      this._dropdownItems = newItems;
-
-      // Store the currently focused item if any. The focused index preserves
-      // in the case when more filtered items are loading but it is reset
-      // when the user types in a filter query.
-      const focusedItem = oldItems ? oldItems[this._focusedIndex] : null;
+      super._setDropdownItems(newItems);
 
       // Try to sync `selectedItem` based on `value` once a new set of `filteredItems` is available
       // (as a result of external filtering or when they have been loaded by the data provider).
@@ -520,30 +437,6 @@ export const ComboBoxMixin = (superClass) =>
       if ((this.selectedItem === null || this.selectedItem === undefined) && valueIndex >= 0) {
         this.selectedItem = newItems[valueIndex];
       }
-
-      // When both the previously-focused entry and the new entry at the
-      // same index are placeholders (e.g. the Flow connector mid-scroll
-      // re-pushing `_setDropdownItems`), preserve `_focusedIndex` until
-      // a follow-up call lands a real item at that position.
-      if (
-        oldItems &&
-        oldItems[this._focusedIndex] instanceof ComboBoxPlaceholder &&
-        newItems[this._focusedIndex] instanceof ComboBoxPlaceholder
-      ) {
-        return;
-      }
-
-      // Try to first set focus on the item that had been focused before `newItems` were updated
-      // if it is still present in the `newItems` array. Otherwise, set the focused index
-      // depending on the selected item or the filter query.
-      const focusedItemIndex = this.__getItemIndexByValue(newItems, this._getItemValue(focusedItem));
-      if (focusedItemIndex > -1) {
-        this._focusedIndex = focusedItemIndex;
-      } else {
-        // When the user filled in something that is different from the current value = filtering is enabled,
-        // set the focused index to the item that matches the filter query.
-        this._focusedIndex = this.__getItemIndexByLabel(newItems, this.filter);
-      }
     }
 
     /**

package/src/vaadin-combo-box-overlay-mixin.js

@@ -8,16 +8,22 @@ import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin
 
 export const ComboBoxOverlayMixin = (superClass) =>
   class ComboBoxOverlayMixin extends PositionMixin(superClass) {
-    static get observers() {
-      return ['_setOverlayWidth(positionTarget, opened)'];
-    }
-
     constructor() {
       super();
 
       this.requiredVerticalSpace = 200;
     }
 
+    /** @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();
+      }
+    }
+
     /**
      * Override method inherited from `Overlay`
      * to not close on position target click.
@@ -49,13 +55,4 @@ export const ComboBoxOverlayMixin = (superClass) =>
     _updateOverlayWidth() {
       this.style.setProperty(`--_${this.localName}-default-width`, `${this.positionTarget.offsetWidth}px`);
     }
-
-    /** @private */
-    _setOverlayWidth(positionTarget, opened) {
-      if (positionTarget && opened) {
-        this._updateOverlayWidth();
-
-        this._updatePosition();
-      }
-    }
   };

package/src/vaadin-combo-box-overlay.js

@@ -22,7 +22,7 @@ import { ComboBoxOverlayMixin } from './vaadin-combo-box-overlay-mixin.js';
  * @extends HTMLElement
  * @private
  */
-export class ComboBoxOverlay extends ComboBoxOverlayMixin(
+class ComboBoxOverlay extends ComboBoxOverlayMixin(
   OverlayMixin(DirMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement))))),
 ) {
   static get is() {
@@ -45,3 +45,5 @@ export class ComboBoxOverlay extends ComboBoxOverlayMixin(
 }
 
 defineCustomElement(ComboBoxOverlay);
+
+export { ComboBoxOverlay };

package/src/vaadin-combo-box-placeholder.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright (c) 2015 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Placeholder object class representing items being loaded.
+ *
+ * @private
+ */
+declare class ComboBoxPlaceholder {
+  // Nominal brand: keeps structurally similar values from being assignable
+  // eslint-disable-next-line @typescript-eslint/no-unused-private-class-members
+  private __comboBoxPlaceholder: true;
+
+  toString(): string;
+}
+
+export { ComboBoxPlaceholder };

package/src/vaadin-combo-box-scroller-mixin.d.ts

@@ -17,11 +17,6 @@ export declare class ComboBoxScrollerMixinClass<TItem, TOwner> {
    */
   focusedIndex: number;
 
-  /**
-   * Path for the id of the item, used to detect whether the item is selected.
-   */
-  itemIdPath: string | null | undefined;
-
   /**
    * A full set of items to filter the visible options from.
    * Set to an empty array when combo-box is not opened.
@@ -78,7 +73,7 @@ export declare class ComboBoxScrollerMixinClass<TItem, TOwner> {
    */
   scrollIntoView(index: number, alignToCenter?: boolean): void;
 
-  protected _isItemSelected(item: TItem, selectedItem: TItem, itemIdPath: string | null | undefined): void;
+  protected _isItemSelected(item: TItem, selectedItem: TItem): boolean;
 
   protected _updateElement(el: HTMLElement, index: number): void;
 }

package/src/vaadin-combo-box-scroller-mixin.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2015 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { get } from '@vaadin/component-base/src/path-utils.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
 import { Virtualizer } from '@vaadin/component-base/src/virtualizer.js';
 import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
@@ -71,13 +71,6 @@ export const ComboBoxScrollerMixin = (superClass) =>
           observer: '__itemClassNameGeneratorChanged',
         },
 
-        /**
-         * Path for the id of the item, used to detect whether the item is selected.
-         */
-        itemIdPath: {
-          type: String,
-        },
-
         /**
          * Reference to the owner (combo-box owner), used by the item elements.
          */
@@ -243,16 +236,15 @@ export const ComboBoxScrollerMixin = (superClass) =>
     /**
      * @param {string | object} item
      * @param {string | object} selectedItem
-     * @param {string} itemIdPath
+     * @return {boolean}
      * @protected
      */
-    _isItemSelected(item, selectedItem, itemIdPath) {
+    _isItemSelected(item, selectedItem) {
       if (item instanceof ComboBoxPlaceholder) {
         return false;
-      } else if (itemIdPath && item !== undefined && selectedItem !== undefined) {
-        return get(itemIdPath, item) === get(itemIdPath, selectedItem);
       }
-      return item === selectedItem;
+
+      return this.owner._isSameItem(item, selectedItem);
     }
 
     /** @private */
@@ -366,7 +358,7 @@ export const ComboBoxScrollerMixin = (superClass) =>
     _updateElement(el, index) {
       const item = this.items[index];
       const focusedIndex = this.focusedIndex;
-      const selected = this._isItemSelected(item, this.selectedItem, this.itemIdPath);
+      const selected = this._isItemSelected(item, this.selectedItem);
 
       el.setProperties({
         item,
@@ -389,11 +381,7 @@ export const ComboBoxScrollerMixin = (superClass) =>
       el.setAttribute('aria-posinset', index + 1);
       el.setAttribute('aria-setsize', this.items.length);
 
-      if (this.theme) {
-        el.setAttribute('theme', this.theme);
-      } else {
-        el.removeAttribute('theme');
-      }
+      setOrRemoveAttribute(el, 'theme', this.theme);
 
       if (item instanceof ComboBoxPlaceholder) {
         this.__requestItemByIndex(index);

package/src/vaadin-combo-box-scroller.js

@@ -16,7 +16,7 @@ import { ComboBoxScrollerMixin } from './vaadin-combo-box-scroller-mixin.js';
  * @extends HTMLElement
  * @private
  */
-export class ComboBoxScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElement)) {
+class ComboBoxScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElement)) {
   static get is() {
     return 'vaadin-combo-box-scroller';
   }
@@ -36,3 +36,5 @@ export class ComboBoxScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElem
 }
 
 defineCustomElement(ComboBoxScroller);
+
+export { ComboBoxScroller };