@vaadin/combo-box 23.1.2 → 23.2.0-dev.48e5e3967

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

@@ -12,6 +12,34 @@ 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';
 
+/**
+ * Checks if the value is supported as an item value in this control.
+ *
+ * @param {unknown} value
+ * @return {boolean}
+ */
+function isValidValue(value) {
+  return value !== undefined && value !== null;
+}
+
+/**
+ * Returns the index of the first item that satisfies the provided testing function
+ * ignoring placeholder items.
+ *
+ * @param {Array<ComboBoxItem | string>} items
+ * @param {Function} callback
+ * @return {number}
+ */
+function findItemIndex(items, callback) {
+  return items.findIndex((item) => {
+    if (item instanceof ComboBoxPlaceholder) {
+      return false;
+    }
+
+    return callback(item);
+  });
+}
+
 /**
  * @polymerMixin
  * @param {function(new:HTMLElement)} subclass
@@ -95,6 +123,7 @@ export const ComboBoxMixin = (subclass) =>
          */
         filteredItems: {
           type: Array,
+          observer: '_filteredItemsChanged',
         },
 
         /**
@@ -111,7 +140,6 @@ export const ComboBoxMixin = (subclass) =>
           type: Boolean,
           value: false,
           reflectToAttribute: true,
-          observer: '_loadingChanged',
         },
 
         /**
@@ -196,15 +224,21 @@ export const ComboBoxMixin = (subclass) =>
         _closeOnBlurIsPrevented: Boolean,
 
         /** @private */
-        __restoreFocusOnClose: Boolean,
+        _scroller: Object,
+
+        /** @private */
+        _overlayOpened: {
+          type: Boolean,
+          observer: '_overlayOpenedChanged',
+        },
       };
     }
 
     static get observers() {
       return [
-        '_filterChanged(filter, itemValuePath, itemLabelPath)',
-        '_filteredItemsChanged(filteredItems)',
         '_selectedItemChanged(selectedItem, itemValuePath, itemLabelPath)',
+        '_openedOrItemsChanged(opened, filteredItems, loading)',
+        '_updateScroller(_scroller, filteredItems, opened, loading, selectedItem, itemIdPath, _focusedIndex, renderer, theme)',
       ];
     }
 
@@ -213,13 +247,20 @@ export const ComboBoxMixin = (subclass) =>
       this._boundOnFocusout = this._onFocusout.bind(this);
       this._boundOverlaySelectedItemChanged = this._overlaySelectedItemChanged.bind(this);
       this._boundOnClearButtonMouseDown = this.__onClearButtonMouseDown.bind(this);
-      this._boundClose = this.close.bind(this);
-      this._boundOnOpened = this._onOpened.bind(this);
       this._boundOnClick = this._onClick.bind(this);
       this._boundOnOverlayTouchAction = this._onOverlayTouchAction.bind(this);
       this._boundOnTouchend = this._onTouchend.bind(this);
     }
 
+    /**
+     * Tag name prefix used by scroller and items.
+     * @protected
+     * @return {string}
+     */
+    get _tagNamePrefix() {
+      return 'vaadin-combo-box';
+    }
+
     /**
      * @return {string | undefined}
      * @protected
@@ -273,23 +314,19 @@ export const ComboBoxMixin = (subclass) =>
     ready() {
       super.ready();
 
+      this._initOverlay();
+      this._initScroller();
+
       this.addEventListener('focusout', this._boundOnFocusout);
 
       this._lastCommittedValue = this.value;
 
-      this.$.dropdown.addEventListener('selection-changed', this._boundOverlaySelectedItemChanged);
-
-      this.addEventListener('vaadin-combo-box-dropdown-closed', this._boundClose);
-      this.addEventListener('vaadin-combo-box-dropdown-opened', this._boundOnOpened);
       this.addEventListener('click', this._boundOnClick);
-
-      this.$.dropdown.addEventListener('vaadin-overlay-touch-action', this._boundOnOverlayTouchAction);
-
       this.addEventListener('touchend', this._boundOnTouchend);
 
       const bringToFrontListener = () => {
         requestAnimationFrame(() => {
-          this.$.dropdown.$.overlay.bringToFront();
+          this.$.overlay.bringToFront();
         });
       };
 
@@ -301,6 +338,14 @@ export const ComboBoxMixin = (subclass) =>
       this.addController(new VirtualKeyboardController(this));
     }
 
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      // Close the overlay on detach
+      this.close();
+    }
+
     /**
      * Requests an update for the content of items.
      * While performing the update, it invokes the renderer (passed in the `renderer` property) once an item.
@@ -308,11 +353,11 @@ export const ComboBoxMixin = (subclass) =>
      * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
      */
     requestContentUpdate() {
-      if (!this.$.dropdown._scroller) {
+      if (!this._scroller) {
         return;
       }
 
-      this.$.dropdown._scroller.requestContentUpdate();
+      this._scroller.requestContentUpdate();
 
       this._getItemElements().forEach((item) => {
         item.requestContentUpdate();
@@ -336,6 +381,128 @@ export const ComboBoxMixin = (subclass) =>
       this.opened = false;
     }
 
+    /**
+     * Override Polymer lifecycle callback to handle `filter` property change after
+     * the observer for `opened` property is triggered. This is needed when opening
+     * combo-box on user input to ensure the focused index is set correctly.
+     *
+     * @param {!Object} currentProps Current accessor values
+     * @param {?Object} changedProps Properties changed since the last call
+     * @param {?Object} oldProps Previous values for each changed property
+     * @protected
+     * @override
+     */
+    _propertiesChanged(currentProps, changedProps, oldProps) {
+      super._propertiesChanged(currentProps, changedProps, oldProps);
+
+      if (changedProps.filter !== undefined) {
+        this._filterChanged(changedProps.filter);
+      }
+    }
+
+    /** @private */
+    _initOverlay() {
+      const overlay = this.$.overlay;
+
+      // Store instance for detecting "dir" attribute on opening
+      overlay._comboBox = this;
+
+      overlay.addEventListener('touchend', this._boundOnOverlayTouchAction);
+      overlay.addEventListener('touchmove', this._boundOnOverlayTouchAction);
+
+      // Prevent blurring the input when clicking inside the overlay
+      overlay.addEventListener('mousedown', (e) => e.preventDefault());
+
+      // Preventing the default modal behavior of the overlay on input click
+      overlay.addEventListener('vaadin-overlay-outside-click', (e) => {
+        e.preventDefault();
+      });
+
+      // Manual two-way binding for the overlay "opened" property
+      overlay.addEventListener('opened-changed', (e) => {
+        this._overlayOpened = e.detail.value;
+      });
+    }
+
+    /**
+     * Create and initialize the scroller element.
+     * Override to provide custom host reference.
+     *
+     * @protected
+     */
+    _initScroller(host) {
+      const scrollerTag = `${this._tagNamePrefix}-scroller`;
+
+      const overlay = this.$.overlay;
+
+      overlay.renderer = (root) => {
+        if (!root.firstChild) {
+          root.appendChild(document.createElement(scrollerTag));
+        }
+      };
+
+      // Ensure the scroller is rendered
+      if (!this.opened) {
+        overlay.requestContentUpdate();
+      }
+
+      const scroller = overlay.querySelector(scrollerTag);
+
+      scroller.comboBox = host || this;
+      scroller.getItemLabel = this._getItemLabel.bind(this);
+      scroller.addEventListener('selection-changed', this._boundOverlaySelectedItemChanged);
+
+      // Trigger the observer to set properties
+      this._scroller = scroller;
+    }
+
+    /** @private */
+    // eslint-disable-next-line max-params
+    _updateScroller(scroller, items, opened, loading, selectedItem, itemIdPath, focusedIndex, renderer, theme) {
+      if (scroller) {
+        if (opened) {
+          scroller.style.maxHeight =
+            getComputedStyle(this).getPropertyValue(`--${this._tagNamePrefix}-overlay-max-height`) || '65vh';
+        }
+
+        scroller.setProperties({
+          items: opened ? items : [],
+          opened,
+          loading,
+          selectedItem,
+          itemIdPath,
+          focusedIndex,
+          renderer,
+          theme,
+        });
+      }
+    }
+
+    /** @protected */
+    _isOverlayHidden(items, loading) {
+      return !loading && !(items && items.length);
+    }
+
+    /** @private */
+    _openedOrItemsChanged(opened, items, loading) {
+      // Close the overlay if there are no items to display.
+      // See https://github.com/vaadin/vaadin-combo-box/pull/964
+      this._overlayOpened = !!(opened && (loading || (items && items.length)));
+    }
+
+    /** @private */
+    _overlayOpenedChanged(opened, wasOpened) {
+      if (opened) {
+        this.dispatchEvent(new CustomEvent('vaadin-combo-box-dropdown-opened', { bubbles: true, composed: true }));
+
+        this._onOpened();
+      } else if (wasOpened && this.filteredItems && this.filteredItems.length) {
+        this.close();
+
+        this.dispatchEvent(new CustomEvent('vaadin-combo-box-dropdown-closed', { bubbles: true, composed: true }));
+      }
+    }
+
     /** @private */
     _focusedIndexChanged(index, oldIndex) {
       if (oldIndex === undefined) {
@@ -374,7 +541,7 @@ export const ComboBoxMixin = (subclass) =>
           this.focus();
         }
 
-        this.__restoreFocusOnClose = true;
+        this.$.overlay.restoreFocusOnClose = true;
       } else {
         this._onClosed();
         if (this._openedWithFocusRing && this.hasAttribute('focused')) {
@@ -387,7 +554,7 @@ export const ComboBoxMixin = (subclass) =>
         input.setAttribute('aria-expanded', !!opened);
 
         if (opened) {
-          input.setAttribute('aria-controls', this.$.dropdown.scrollerId);
+          input.setAttribute('aria-controls', this._scroller.id);
         } else {
           input.removeAttribute('aria-controls');
         }
@@ -477,7 +644,7 @@ export const ComboBoxMixin = (subclass) =>
       super._onKeyDown(e);
 
       if (e.key === 'Tab') {
-        this.__restoreFocusOnClose = false;
+        this.$.overlay.restoreFocusOnClose = false;
       } else if (e.key === 'ArrowDown') {
         this._closeOnBlurIsPrevented = true;
         this._onArrowDown();
@@ -497,7 +664,11 @@ export const ComboBoxMixin = (subclass) =>
 
     /** @private */
     _getItemLabel(item) {
-      return this.$.dropdown.getItemLabel(item);
+      let label = item && this.itemLabelPath ? this.get(this.itemLabelPath, item) : undefined;
+      if (label === undefined || label === null) {
+        label = item ? item.toString() : '';
+      }
+      return label;
     }
 
     /** @private */
@@ -512,7 +683,7 @@ export const ComboBoxMixin = (subclass) =>
     /** @private */
     _onArrowDown() {
       if (this.opened) {
-        const items = this._getOverlayItems();
+        const items = this.filteredItems;
         if (items) {
           this._focusedIndex = Math.min(items.length - 1, this._focusedIndex + 1);
           this._prefillFocusedItemLabel();
@@ -528,7 +699,7 @@ export const ComboBoxMixin = (subclass) =>
         if (this._focusedIndex > -1) {
           this._focusedIndex = Math.max(0, this._focusedIndex - 1);
         } else {
-          const items = this._getOverlayItems();
+          const items = this.filteredItems;
           if (items) {
             this._focusedIndex = items.length - 1;
           }
@@ -543,7 +714,8 @@ export const ComboBoxMixin = (subclass) =>
     /** @private */
     _prefillFocusedItemLabel() {
       if (this._focusedIndex > -1) {
-        this._inputElementValue = this._getItemLabel(this.$.dropdown.focusedItem);
+        const focusedItem = this.filteredItems[this._focusedIndex];
+        this._inputElementValue = this._getItemLabel(focusedItem);
         this._markAllSelectionRange();
       }
     }
@@ -700,7 +872,7 @@ export const ComboBoxMixin = (subclass) =>
     _onOpened() {
       // Defer scroll position adjustment to improve performance.
       requestAnimationFrame(() => {
-        this.$.dropdown.adjustScrollPosition();
+        this._scrollIntoView(this._focusedIndex);
 
         // Set attribute after the items are rendered when overlay is opened for the first time.
         this._updateActiveDescendant(this._focusedIndex);
@@ -719,9 +891,8 @@ export const ComboBoxMixin = (subclass) =>
 
     /** @private */
     _commitValue() {
-      const items = this._getOverlayItems();
-      if (items && this._focusedIndex > -1) {
-        const focusedItem = items[this._focusedIndex];
+      if (this._focusedIndex > -1) {
+        const focusedItem = this.filteredItems[this._focusedIndex];
         if (this.selectedItem !== focusedItem) {
           this.selectedItem = focusedItem;
         }
@@ -734,18 +905,14 @@ export const ComboBoxMixin = (subclass) =>
           this.value = '';
         }
       } else {
-        const toLowerCase = (item) => item && item.toLowerCase && item.toLowerCase();
-
-        // Try to find an item whose label matches the input value. A matching item is searched from
-        // the filteredItems array (if available) and the selectedItem (if available).
-        const itemMatchingByLabel = [...(this.filteredItems || []), this.selectedItem].find((item) => {
-          return toLowerCase(this._getItemLabel(item)) === toLowerCase(this._inputElementValue);
-        });
+        // Try to find an item which label matches the input value.
+        const items = [...(this.filteredItems || []), this.selectedItem];
+        const itemMatchingInputValue = items[this.__getItemIndexByLabel(items, this._inputElementValue)];
 
         if (
           this.allowCustomValue &&
           // To prevent a repetitive input value being saved after pressing ESC and Tab.
-          !itemMatchingByLabel
+          !itemMatchingInputValue
         ) {
           const customValue = this._inputElementValue;
 
@@ -762,12 +929,11 @@ export const ComboBoxMixin = (subclass) =>
           });
           this.dispatchEvent(e);
           if (!e.defaultPrevented) {
-            this._selectItemForValue(customValue);
             this.value = customValue;
           }
-        } else if (!this.allowCustomValue && !this.opened && itemMatchingByLabel) {
+        } else if (!this.allowCustomValue && !this.opened && itemMatchingInputValue) {
           // An item matching by label was found, select it.
-          this.value = this._getItemValue(itemMatchingByLabel);
+          this.value = this._getItemValue(itemMatchingInputValue);
         } else {
           // Revert the input value
           this._inputElementValue = this.selectedItem ? this._getItemLabel(this.selectedItem) : this.value || '';
@@ -796,19 +962,27 @@ export const ComboBoxMixin = (subclass) =>
      * @override
      */
     _onInput(event) {
-      if (!this.opened && !this._isClearButton(event) && !this.autoOpenDisabled) {
-        this.open();
-      }
+      const filter = this._inputElementValue;
 
-      const value = this._inputElementValue;
-      if (this.filter === value) {
+      // When opening dropdown on user input, both `opened` and `filter` properties are set.
+      // Perform a batched property update instead of relying on sync property observers.
+      // This is necessary to avoid an extra data-provider request for loading first page.
+      const props = {};
+
+      if (this.filter === filter) {
         // Filter and input value might get out of sync, while keyboard navigating for example.
         // Afterwards, input value might be changed to the same value as used in filtering.
         // In situation like these, we need to make sure all the filter changes handlers are run.
-        this._filterChanged(this.filter, this.itemValuePath, this.itemLabelPath);
+        this._filterChanged(this.filter);
       } else {
-        this.filter = value;
+        props.filter = filter;
+      }
+
+      if (!this.opened && !this._isClearButton(event) && !this.autoOpenDisabled) {
+        props.opened = true;
       }
+
+      this.setProperties(props);
     }
 
     /**
@@ -831,13 +1005,11 @@ export const ComboBoxMixin = (subclass) =>
     }
 
     /** @private */
-    _filterChanged(filter, _itemValuePath, _itemLabelPath) {
-      if (filter === undefined) {
-        return;
-      }
-
+    _filterChanged(filter) {
       // Scroll to the top of the list whenever the filter changes.
-      this.$.dropdown._scrollIntoView(0);
+      this._scrollIntoView(0);
+
+      this._focusedIndex = -1;
 
       if (this.items) {
         this.filteredItems = this._filterItems(this.items, filter);
@@ -849,13 +1021,6 @@ export const ComboBoxMixin = (subclass) =>
       }
     }
 
-    /** @private */
-    _loadingChanged(loading) {
-      if (loading) {
-        this._focusedIndex = -1;
-      }
-    }
-
     /** @protected */
     _revertInputValue() {
       if (this.filter !== '') {
@@ -901,9 +1066,7 @@ export const ComboBoxMixin = (subclass) =>
         this._inputElementValue = this._getItemLabel(selectedItem);
       }
 
-      this.$.dropdown._selectedItem = selectedItem;
-      const items = this._getOverlayItems();
-      if (this.filteredItems && items) {
+      if (this.filteredItems) {
         this._focusedIndex = this.filteredItems.indexOf(selectedItem);
       }
     }
@@ -920,7 +1083,7 @@ export const ComboBoxMixin = (subclass) =>
         return;
       }
 
-      if (this._isValidValue(value)) {
+      if (isValidValue(value)) {
         if (this._getItemValue(this.selectedItem) !== value) {
           this._selectItemForValue(value);
         }
@@ -956,43 +1119,50 @@ export const ComboBoxMixin = (subclass) =>
 
       if (items) {
         this.filteredItems = items.slice(0);
-      } else if (this.__previousItems) {
+      } else if (oldItems) {
         // Only clear filteredItems if the component had items previously but got cleared
         this.filteredItems = null;
       }
+    }
 
-      const valueIndex = this._indexOfValue(this.value, items);
-      this._focusedIndex = valueIndex;
+    /** @private */
+    _filteredItemsChanged(filteredItems, oldFilteredItems) {
+      // 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 = oldFilteredItems ? oldFilteredItems[this._focusedIndex] : null;
+
+      // 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).
+      // When `value` is specified but `selectedItem` is not, it means that there was no item
+      // matching `value` at the moment `value` was set, so `selectedItem` has remained unsynced.
+      const valueIndex = this.__getItemIndexByValue(filteredItems, this.value);
+      if ((this.selectedItem === null || this.selectedItem === undefined) && valueIndex >= 0) {
+        this.selectedItem = filteredItems[valueIndex];
+      }
 
-      const item = valueIndex > -1 && items[valueIndex];
-      if (item) {
-        this.selectedItem = item;
+      // Try to first set focus on the item that had been focused before `filteredItems` were updated
+      // if it is still present in the `filteredItems` array. Otherwise, set the focused index
+      // depending on the selected item or the filter query.
+      const focusedItemIndex = this.__getItemIndexByValue(filteredItems, this._getItemValue(focusedItem));
+      if (focusedItemIndex > -1) {
+        this._focusedIndex = focusedItemIndex;
+      } else {
+        this.__setInitialFocusedIndex();
       }
-      this.__previousItems = items;
     }
 
     /** @private */
-    _filteredItemsChanged(filteredItems, _itemValuePath, _itemLabelPath) {
-      this._setOverlayItems(filteredItems);
-
-      // When the external filtering is used and `value` was provided before `filteredItems`,
-      // initialize the selected item with the current value here. This will also cause
-      // the input element value to sync. In other cases, the selected item is already initialized
-      // in other observers such as `valueChanged`, `_itemsChanged`.
-      const valueIndex = this._indexOfValue(this.value, filteredItems);
-      if (this.selectedItem === null && valueIndex >= 0) {
-        this._selectItemForValue(this.value);
-      }
-
+    __setInitialFocusedIndex() {
       const inputValue = this._inputElementValue;
       if (inputValue === undefined || inputValue === this._getItemLabel(this.selectedItem)) {
         // When the input element value is the same as the current value or not defined,
         // set the focused index to the item that matches the value.
-        this._focusedIndex = this.$.dropdown.indexOfLabel(this._getItemLabel(this.selectedItem));
+        this._focusedIndex = this.__getItemIndexByLabel(this.filteredItems, this._getItemLabel(this.selectedItem));
       } 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.$.dropdown.indexOfLabel(this.filter);
+        this._focusedIndex = this.__getItemIndexByLabel(this.filteredItems, this.filter);
       }
     }
 
@@ -1013,7 +1183,7 @@ export const ComboBoxMixin = (subclass) =>
 
     /** @private */
     _selectItemForValue(value) {
-      const valueIndex = this._indexOfValue(value, this.filteredItems);
+      const valueIndex = this.__getItemIndexByValue(this.filteredItems, value);
       const previouslySelectedItem = this.selectedItem;
 
       if (valueIndex >= 0) {
@@ -1029,42 +1199,48 @@ export const ComboBoxMixin = (subclass) =>
       }
     }
 
-    /** @protected */
-    _getItemElements() {
-      return Array.from(this.$.dropdown._scroller.querySelectorAll('vaadin-combo-box-item'));
-    }
-
     /** @private */
-    _getOverlayItems() {
-      return this.$.dropdown._items;
+    _getItemElements() {
+      return Array.from(this._scroller.querySelectorAll(`${this._tagNamePrefix}-item`));
     }
 
     /** @private */
-    _setOverlayItems(items) {
-      this.$.dropdown.set('_items', items);
+    _scrollIntoView(index) {
+      if (!this._scroller) {
+        return;
+      }
+      this._scroller.scrollIntoView(index);
     }
 
-    /** @private */
-    _indexOfValue(value, items) {
-      if (!items || !this._isValidValue(value)) {
+    /**
+     * Returns the first item that matches the provided value.
+     *
+     * @private
+     */
+    __getItemIndexByValue(items, value) {
+      if (!items || !isValidValue(value)) {
         return -1;
       }
 
-      return items.findIndex((item) => {
-        if (item instanceof ComboBoxPlaceholder) {
-          return false;
-        }
-
+      return findItemIndex(items, (item) => {
         return this._getItemValue(item) === value;
       });
     }
 
     /**
-     * Checks if the value is supported as an item value in this control.
+     * Returns the first item that matches the provided label.
+     * Labels are matched against each other case insensitively.
+     *
      * @private
      */
-    _isValidValue(value) {
-      return value !== undefined && value !== null;
+    __getItemIndexByLabel(items, label) {
+      if (!items || !label) {
+        return -1;
+      }
+
+      return findItemIndex(items, (item) => {
+        return this._getItemLabel(item).toString().toLowerCase() === label.toString().toLowerCase();
+      });
     }
 
     /** @private */
@@ -1095,7 +1271,7 @@ export const ComboBoxMixin = (subclass) =>
     /** @private */
     _onFocusout(event) {
       // Fixes the problem with `focusout` happening when clicking on the scroll bar on Edge
-      if (event.relatedTarget === this.$.dropdown.$.overlay) {
+      if (event.relatedTarget === this.$.overlay) {
         event.composedPath()[0].focus();
         return;
       }
@@ -1121,29 +1297,6 @@ export const ComboBoxMixin = (subclass) =>
       this._clear();
     }
 
-    /**
-     * Returns true if `value` is valid, and sets the `invalid` flag appropriately.
-     *
-     * @return {boolean} True if the value is valid and sets the `invalid` flag appropriately
-     */
-    validate() {
-      return !(this.invalid = !this.checkValidity());
-    }
-
-    /**
-     * Returns true if the current input value satisfies all constraints (if any).
-     * You can override this method for custom validations.
-     *
-     * @return {boolean}
-     */
-    checkValidity() {
-      if (super.checkValidity) {
-        return super.checkValidity();
-      }
-
-      return !this.required || !!this.value;
-    }
-
     /**
      * Fired when the value changes.
      *
@@ -1171,4 +1324,16 @@ export const ComboBoxMixin = (subclass) =>
      * To comply with https://developer.mozilla.org/en-US/docs/Web/Events/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
+     */
   };