@vaadin/combo-box 25.1.2 → 25.2.0-alpha10

package/package.json

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

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

@@ -177,7 +177,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 +552,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-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,103 @@
+/**
+ * @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';
+
+/**
+ * @polymerMixin
+ */
+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

@@ -262,6 +262,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.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,6 +158,8 @@ 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
@@ -166,10 +169,13 @@ import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
  * @mixes PatternMixin
  * @mixes ComboBoxDataProviderMixin
  * @mixes ComboBoxMixin
+ * @mixes ComboBoxScrollToIndexMixin
  */
-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() {