@vaadin/combo-box 25.2.0-alpha9 → 25.2.0-beta1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/combo-box",
-  "version": "25.2.0-alpha9",
+  "version": "25.2.0-beta1",
   "publishConfig": {
     "access": "public"
   },
@@ -36,22 +36,22 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "25.2.0-alpha9",
-    "@vaadin/component-base": "25.2.0-alpha9",
-    "@vaadin/field-base": "25.2.0-alpha9",
-    "@vaadin/input-container": "25.2.0-alpha9",
-    "@vaadin/item": "25.2.0-alpha9",
-    "@vaadin/lit-renderer": "25.2.0-alpha9",
-    "@vaadin/overlay": "25.2.0-alpha9",
-    "@vaadin/vaadin-themable-mixin": "25.2.0-alpha9",
+    "@vaadin/a11y-base": "25.2.0-beta1",
+    "@vaadin/component-base": "25.2.0-beta1",
+    "@vaadin/field-base": "25.2.0-beta1",
+    "@vaadin/input-container": "25.2.0-beta1",
+    "@vaadin/item": "25.2.0-beta1",
+    "@vaadin/lit-renderer": "25.2.0-beta1",
+    "@vaadin/overlay": "25.2.0-beta1",
+    "@vaadin/vaadin-themable-mixin": "25.2.0-beta1",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.2.0-alpha9",
-    "@vaadin/chai-plugins": "25.2.0-alpha9",
-    "@vaadin/test-runner-commands": "25.2.0-alpha9",
+    "@vaadin/aura": "25.2.0-beta1",
+    "@vaadin/chai-plugins": "25.2.0-beta1",
+    "@vaadin/test-runner-commands": "25.2.0-beta1",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.2.0-alpha9",
+    "@vaadin/vaadin-lumo-styles": "25.2.0-beta1",
     "sinon": "^21.0.2"
   },
   "customElements": "custom-elements.json",
@@ -59,5 +59,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "a38a03e8a8be45821f39c14054c63634dafe08d0"
+  "gitHead": "471a23f60d1eb725f98a33f62cb9664d9c0a4163"
 }

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

@@ -12,14 +12,6 @@ import { InputMixin } from '@vaadin/field-base/src/input-mixin.js';
 import { VirtualKeyboardController } from '@vaadin/field-base/src/virtual-keyboard-controller.js';
 import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
 
-/**
- * @polymerMixin
- * @mixes DisabledMixin
- * @mixes FocusMixin
- * @mixes InputMixin
- * @mixes KeyboardMixin
- * @param {function(new:HTMLElement)} superClass
- */
 export const ComboBoxBaseMixin = (superClass) =>
   class ComboBoxMixinBaseClass extends KeyboardMixin(InputMixin(DisabledMixin(FocusMixin(superClass)))) {
     static get properties() {

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

@@ -6,9 +6,6 @@
 import { DataProviderController } from '@vaadin/component-base/src/data-provider-controller/data-provider-controller.js';
 import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
 
-/**
- * @polymerMixin
- */
 export const ComboBoxDataProviderMixin = (superClass) =>
   class DataProviderMixin extends superClass {
     static get properties() {

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

@@ -4,9 +4,6 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
-/**
- * @polymerMixin
- */
 export const ComboBoxItemMixin = (superClass) =>
   class ComboBoxItemMixinClass extends superClass {
     static get properties() {

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

@@ -35,9 +35,6 @@ import { ComboBoxItemMixin } from './vaadin-combo-box-item-mixin.js';
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
  * @customElement vaadin-combo-box-item
- * @mixes ComboBoxItemMixin
- * @mixes ThemableMixin
- * @mixes DirMixin
  * @private
  */
 export class ComboBoxItem extends ComboBoxItemMixin(

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

@@ -35,10 +35,6 @@ function findItemIndex(items, callback) {
   });
 }
 
-/**
- * @polymerMixin
- * @mixes ComboBoxBaseMixin
- */
 export const ComboBoxItemsMixin = (superClass) =>
   class ComboBoxItemsMixinClass extends ComboBoxBaseMixin(superClass) {
     static get properties() {

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

@@ -16,12 +16,6 @@ function isValidValue(value) {
   return value !== undefined && value !== null;
 }
 
-/**
- * @polymerMixin
- * @mixes ComboBoxItemsMixin
- * @mixes ValidateMixin
- * @param {function(new:HTMLElement)} superClass
- */
 export const ComboBoxMixin = (superClass) =>
   class ComboBoxMixinClass extends ValidateMixin(ComboBoxItemsMixin(superClass)) {
     static get properties() {
@@ -177,7 +171,7 @@ export const ComboBoxMixin = (superClass) =>
     _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 && items.length));
+      this._overlayOpened = opened && (keepOverlayOpened || loading || !!items?.length);
     }
 
     /**
@@ -552,43 +546,4 @@ export const ComboBoxMixin = (superClass) =>
 
       super._handleFocusOut();
     }
-
-    /**
-     * Fired when the value changes.
-     *
-     * @event value-changed
-     * @param {Object} detail
-     * @param {String} detail.value the combobox value
-     */
-
-    /**
-     * Fired when selected item changes.
-     *
-     * @event selected-item-changed
-     * @param {Object} detail
-     * @param {Object|String} detail.value the selected item. Type is the same as the type of `items`.
-     */
-
-    /**
-     * Fired when the user sets a custom value.
-     * @event custom-value-set
-     * @param {String} detail the custom value
-     */
-
-    /**
-     * Fired when the user commits a value change.
-     * @event change
-     */
-
-    /**
-     * Fired after the `vaadin-combo-box-overlay` opens.
-     *
-     * @event vaadin-combo-box-dropdown-opened
-     */
-
-    /**
-     * Fired after the `vaadin-combo-box-overlay` closes.
-     *
-     * @event vaadin-combo-box-dropdown-closed
-     */
   };

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

@@ -6,10 +6,6 @@
 import { isElementFocusable } from '@vaadin/a11y-base/src/focus-utils.js';
 import { PositionMixin } from '@vaadin/overlay/src/vaadin-overlay-position-mixin.js';
 
-/**
- * @polymerMixin
- * @mixes PositionMixin
- */
 export const ComboBoxOverlayMixin = (superClass) =>
   class ComboBoxOverlayMixin extends PositionMixin(superClass) {
     static get observers() {

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

@@ -19,10 +19,6 @@ import { ComboBoxOverlayMixin } from './vaadin-combo-box-overlay-mixin.js';
  *
  * @customElement vaadin-combo-box-overlay
  * @extends HTMLElement
- * @mixes ComboBoxOverlayMixin
- * @mixes DirMixin
- * @mixes OverlayMixin
- * @mixes ThemableMixin
  * @private
  */
 export class ComboBoxOverlay extends ComboBoxOverlayMixin(

package/src/vaadin-combo-box-scroll-to-index-mixin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2015 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+export declare function ComboBoxScrollToIndexMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<ComboBoxScrollToIndexMixinClass> & T;
+
+export declare class ComboBoxScrollToIndexMixinClass {
+  /**
+   * Scrolls the dropdown to the item at the given index and sets it as the
+   * focused (highlighted) item. Safe to call before the dropdown is opened
+   * or while the data provider is loading: the call is queued and executed
+   * once the overlay is open and not loading.
+   *
+   * Because this sets the focused item, closing the dropdown without an
+   * explicit selection change (e.g. via outside click or blur) will commit
+   * the focused item as `selectedItem`. In the typical use case (scroll to
+   * the currently selected item) this is a no-op; callers scrolling to a
+   * different index should be aware of this behavior.
+   *
+   * @param index Index of the item to scroll to
+   */
+  scrollToIndex(index: number): void;
+}

package/src/vaadin-combo-box-scroll-to-index-mixin.js

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright (c) 2015 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
+
+export const ComboBoxScrollToIndexMixin = (superClass) =>
+  class ScrollToIndexMixin extends superClass {
+    static get observers() {
+      return ['__clearPendingScrollOnFilter(filter)'];
+    }
+
+    /**
+     * Scrolls the dropdown to the item at the given index and sets it as the
+     * focused (highlighted) item. Safe to call before the dropdown is opened
+     * or while the data provider is loading: the call is queued and executed
+     * once the overlay is open and not loading.
+     *
+     * Because this sets the focused item, closing the dropdown without an
+     * explicit selection change (e.g. via outside click or blur) will commit
+     * the focused item as `selectedItem`. In the typical use case (scroll to
+     * the currently selected item) this is a no-op; callers scrolling to a
+     * different index should be aware of this behavior.
+     *
+     * @param {number} index Index of the item to scroll to
+     */
+    scrollToIndex(index) {
+      if (typeof index !== 'number' || Number.isNaN(index) || index < 0) {
+        return;
+      }
+
+      if (!this._overlayOpened || this.loading) {
+        this.__scrollToPendingIndex = index;
+        return;
+      }
+
+      if (!this._dropdownItems || index >= this._dropdownItems.length) {
+        return;
+      }
+
+      if (this._dropdownItems[index] instanceof ComboBoxPlaceholder) {
+        // The target item is on a page that has not been loaded yet. Request
+        // the page directly and queue the focus-index update for after the
+        // page loads (see `__onDataProviderPageLoaded` →
+        // `__scrollToPendingIndexIfNeeded`). Relying on `_scrollIntoView` to
+        // trigger the page load via the visible-placeholder `index-requested`
+        // chain is unreliable on reopen with cached data: the virtualizer
+        // has just been torn down by closing the overlay and its scroll API
+        // is a no-op while it rebuilds physical items.
+        this.__scrollToPendingIndex = index;
+        this.__dataProviderController.ensureFlatIndexLoaded(index);
+        return;
+      }
+
+      delete this.__scrollToPendingIndex;
+      this._focusedIndex = index;
+      requestAnimationFrame(() => {
+        if (this.isConnected) {
+          this._updateActiveDescendant(index);
+        }
+      });
+    }
+
+    /** @private */
+    __scrollToPendingIndexIfNeeded() {
+      if (this.__scrollToPendingIndex !== undefined && !this.loading) {
+        this.scrollToIndex(this.__scrollToPendingIndex);
+      }
+    }
+
+    /** @private */
+    __clearPendingScrollOnFilter() {
+      delete this.__scrollToPendingIndex;
+    }
+
+    /**
+     * Override method from `ComboBoxBaseMixin` to flush any pending
+     * `scrollToIndex` call after the overlay opens.
+     *
+     * @protected
+     * @override
+     */
+    _onOpened() {
+      super._onOpened();
+      this.__scrollToPendingIndexIfNeeded();
+    }
+
+    /**
+     * Override method from `ComboBoxDataProviderMixin` to flush any pending
+     * `scrollToIndex` call after a data-provider page lands.
+     *
+     * @private
+     * @override
+     */
+    __onDataProviderPageLoaded() {
+      super.__onDataProviderPageLoaded();
+      this.__scrollToPendingIndexIfNeeded();
+    }
+  };

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

@@ -8,9 +8,6 @@ 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';
 
-/**
- * @polymerMixin
- */
 export const ComboBoxScrollerMixin = (superClass) =>
   class ComboBoxScrollerMixin extends superClass {
     static get properties() {
@@ -262,6 +259,25 @@ export const ComboBoxScrollerMixin = (superClass) =>
         }
 
         this.requestContentUpdate();
+        return;
+      }
+
+      // Reset the DOM scrollTop and the virtualizer adapter's
+      // `_scrollPosition` cache. Without the cache reset, the adapter's
+      // ResizeObserver restores the prior offset when the overlay becomes
+      // visible again, leaving the next open stuck at the previous offset
+      // (or blank with dataProvider) until the user scrolls. The
+      // virtualizer's own `scrollToIndex` can't help — by the time this
+      // observer runs, `offsetHeight` is already 0 and its scroll API is
+      // a no-op. Guarded on `_scrollPosition > 0` so the reset is skipped
+      // when there is nothing to reset (e.g. the initial observer run
+      // before the dropdown has ever been opened); unconditionally
+      // touching `scrollTop` on connect can affect the outer document's
+      // scroll position (see the combo-box re-layout integration test).
+      const adapter = this.__virtualizer && this.__virtualizer.__adapter;
+      if (adapter && adapter._scrollPosition > 0) {
+        this.scrollTop = 0;
+        adapter._scrollPosition = 0;
       }
     }
 

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

@@ -14,7 +14,6 @@ import { ComboBoxScrollerMixin } from './vaadin-combo-box-scroller-mixin.js';
  *
  * @customElement vaadin-combo-box-scroller
  * @extends HTMLElement
- * @mixes ComboBoxScrollerMixin
  * @private
  */
 export class ComboBoxScroller extends ComboBoxScrollerMixin(PolylitMixin(LitElement)) {

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

@@ -24,6 +24,7 @@ import type { ComboBoxDataProviderMixinClass } from './vaadin-combo-box-data-pro
 import type { ComboBoxItemsMixinClass } from './vaadin-combo-box-items-mixin.js';
 import type { ComboBoxMixinClass } from './vaadin-combo-box-mixin.js';
 import type { ComboBoxDefaultItem } from './vaadin-combo-box-mixin.js';
+import type { ComboBoxScrollToIndexMixinClass } from './vaadin-combo-box-scroll-to-index-mixin.js';
 
 export {
   ComboBoxDataProvider,
@@ -225,6 +226,8 @@ export interface ComboBoxEventMap<TItem> extends HTMLElementEventMap {
  * @fires {CustomEvent} selected-item-changed - Fired when the `selectedItem` property changes.
  * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  * @fires {CustomEvent} validated - Fired whenever the field is validated.
+ * @fires {CustomEvent} vaadin-combo-box-dropdown-opened - Fired after the `vaadin-combo-box-overlay` opens.
+ * @fires {CustomEvent} vaadin-combo-box-dropdown-closed - Fired after the `vaadin-combo-box-overlay` closes.
  */
 declare class ComboBox<TItem = ComboBoxDefaultItem> extends HTMLElement {
   addEventListener<K extends keyof ComboBoxEventMap<TItem>>(
@@ -245,6 +248,7 @@ interface ComboBox<TItem = ComboBoxDefaultItem>
     ComboBoxDataProviderMixinClass<TItem>,
     ComboBoxItemsMixinClass<TItem>,
     ComboBoxMixinClass<TItem>,
+    ComboBoxScrollToIndexMixinClass,
     ComboBoxBaseMixinClass,
     ValidateMixinClass,
     PatternMixinClass,

package/src/vaadin-combo-box.js

@@ -23,6 +23,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
 import { comboBoxStyles } from './styles/vaadin-combo-box-base-styles.js';
 import { ComboBoxDataProviderMixin } from './vaadin-combo-box-data-provider-mixin.js';
 import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
+import { ComboBoxScrollToIndexMixin } from './vaadin-combo-box-scroll-to-index-mixin.js';
 
 /**
  * `<vaadin-combo-box>` is a web component for choosing a value from a filterable list of options
@@ -157,19 +158,17 @@ import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
  * @fires {CustomEvent} selected-item-changed - Fired when the `selectedItem` property changes.
  * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  * @fires {CustomEvent} validated - Fired whenever the field is validated.
+ * @fires {CustomEvent} vaadin-combo-box-dropdown-opened - Fired after the `vaadin-combo-box-overlay` opens.
+ * @fires {CustomEvent} vaadin-combo-box-dropdown-closed - Fired after the `vaadin-combo-box-overlay` closes.
  *
  * @customElement vaadin-combo-box
  * @extends HTMLElement
- * @mixes ElementMixin
- * @mixes ThemableMixin
- * @mixes InputControlMixin
- * @mixes PatternMixin
- * @mixes ComboBoxDataProviderMixin
- * @mixes ComboBoxMixin
  */
-class ComboBox extends ComboBoxDataProviderMixin(
-  ComboBoxMixin(
-    PatternMixin(InputControlMixin(ThemableMixin(ElementMixin(PolylitMixin(LumoInjectionMixin(LitElement)))))),
+class ComboBox extends ComboBoxScrollToIndexMixin(
+  ComboBoxDataProviderMixin(
+    ComboBoxMixin(
+      PatternMixin(InputControlMixin(ThemableMixin(ElementMixin(PolylitMixin(LumoInjectionMixin(LitElement)))))),
+    ),
   ),
 ) {
   static get is() {