@vaadin/multi-select-combo-box 25.3.2 → 25.4.0-alpha2

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

@@ -15,6 +15,8 @@ import { TooltipController } from '@vaadin/component-base/src/tooltip-controller
 import { InputControlMixin } from '@vaadin/field-base/src/input-control-mixin.js';
 import { InputController } from '@vaadin/field-base/src/input-controller.js';
 import { LabelledInputController } from '@vaadin/field-base/src/labelled-input-controller.js';
+import { MultiSelectComboBoxHighlightMixin } from './vaadin-multi-select-combo-box-highlight-mixin.js';
+import { MultiSelectComboBoxSelectAllMixin } from './vaadin-multi-select-combo-box-select-all-mixin.js';
 
 const DEFAULT_I18N = {
   cleared: 'Selection cleared',
@@ -22,11 +24,21 @@ const DEFAULT_I18N = {
   selected: 'added to selection',
   deselected: 'removed from selection',
   total: '{count} items selected',
+  selectAll: 'Select All',
+  deselectAll: 'Deselect All',
+  selectFiltered: 'Select Filtered',
+  deselectFiltered: 'Deselect Filtered',
 };
 
 export const MultiSelectComboBoxMixin = (superClass) =>
   class MultiSelectComboBoxMixinClass extends I18nMixin(
-    ComboBoxFocusIndexMixin(ComboBoxDataProviderMixin(ComboBoxItemsMixin(InputControlMixin(ResizeMixin(superClass))))),
+    MultiSelectComboBoxSelectAllMixin(
+      MultiSelectComboBoxHighlightMixin(
+        ComboBoxFocusIndexMixin(
+          ComboBoxDataProviderMixin(ComboBoxItemsMixin(InputControlMixin(ResizeMixin(superClass)))),
+        ),
+      ),
+    ),
   ) {
     static get properties() {
       return {
@@ -177,13 +189,6 @@ export const MultiSelectComboBoxMixin = (superClass) =>
           sync: true,
         },
 
-        /** @private */
-        _focusedChipIndex: {
-          type: Number,
-          value: -1,
-          observer: '_focusedChipIndexChanged',
-        },
-
         /** @private */
         _lastFilter: {
           type: String,
@@ -218,9 +223,11 @@ export const MultiSelectComboBoxMixin = (superClass) =>
 
     /**
      * The object used to localize this component. To change the default
-     * localization, replace this with an object that provides all properties, or
+     * localization, set this to an object that provides all properties, or
      * just the individual properties you want to change.
      *
+     * When not set, defaults to `undefined`.
+     *
      * The object has the following JSON structure and default values:
      * ```js
      * {
@@ -235,9 +242,19 @@ export const MultiSelectComboBoxMixin = (superClass) =>
      *   // Screen reader announcement of the selected items count.
      *   // {count} is replaced with the actual count of items.
      *   total: '{count} items selected',
+     *   // Text of the select all button when no filter is set.
+     *   selectAll: 'Select All',
+     *   // Text of the select all button when no filter is set
+     *   // and all items are selected.
+     *   deselectAll: 'Deselect All',
+     *   // Text of the select all button when a filter is set.
+     *   selectFiltered: 'Select Filtered',
+     *   // Text of the select all button when a filter is set
+     *   // and all items matching the filter are selected.
+     *   deselectFiltered: 'Deselect Filtered',
      * }
      * ```
-     * @type {!MultiSelectComboBoxI18n}
+     * @type {MultiSelectComboBoxI18n | undefined}
      */
     get i18n() {
       return super.i18n;
@@ -354,6 +371,10 @@ export const MultiSelectComboBoxMixin = (superClass) =>
         this.__updateChips();
       }
 
+      if (props.has('_highlightState')) {
+        this.__updateChipHighlight(props.get('_highlightState'));
+      }
+
       if (props.has('readonly')) {
         this._setDropdownItems(this.filteredItems);
 
@@ -387,8 +408,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
      */
     clear() {
       this.__updateSelection([]);
-
-      announce(this.__effectiveI18n.cleared);
+      this.__announceSelection();
     }
 
     /** @private */
@@ -483,7 +503,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
       // Do not commit focused item on not blur / outside click
       if (this._ignoreCommitValue) {
         this._inputElementValue = '';
-        this._focusedIndex = -1;
+        this._clearItemHighlight();
         this._ignoreCommitValue = false;
       } else {
         this.__commitUserInput();
@@ -497,8 +517,8 @@ export const MultiSelectComboBoxMixin = (superClass) =>
 
     /** @private */
     __commitUserInput() {
-      if (this._focusedIndex > -1) {
-        const focusedItem = this._dropdownItems[this._focusedIndex];
+      if (this._hasHighlightedItem) {
+        const focusedItem = this._highlightedItem;
         // Do not unselect an already selected item when it was focused by
         // filtering, in which case the input value still equals the filter.
         if (
@@ -559,7 +579,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
       // Do not validate when focusout is caused by document
       // losing focus, which happens on browser tab switch.
       if (blurred && document.hasFocus()) {
-        this._focusedChipIndex = -1;
+        this._clearChipHighlight();
         this._requestValidation();
       }
 
@@ -647,13 +667,13 @@ export const MultiSelectComboBoxMixin = (superClass) =>
      * @override
      */
     _hasValidInputValue() {
-      const hasInvalidOption = this._focusedIndex < 0 && this._inputElementValue !== '';
+      const hasInvalidOption = !this._hasHighlightedItem && this._inputElementValue !== '';
       return this.allowCustomValue || !hasInvalidOption;
     }
 
     /**
-     * Override method inherited from the combo-box
-     * to not request data provider when read-only.
+     * Override method from `ComboBoxDataProviderMixin` to not request
+     * data provider when read-only.
      *
      * @protected
      * @override
@@ -783,6 +803,16 @@ export const MultiSelectComboBoxMixin = (superClass) =>
       this.dispatchEvent(new CustomEvent('change', { bubbles: true }));
     }
 
+    /**
+     * Announces the number of selected items to screen readers.
+     * @private
+     */
+    __announceSelection() {
+      const { cleared, total } = this.__effectiveI18n;
+      const count = this.selectedItems.length;
+      announce(count === 0 ? cleared : total.replace('{count}', count));
+    }
+
     /** @private */
     __updateTopGroup(selectedItemsOnTop, selectedItems, opened) {
       if (!selectedItemsOnTop) {
@@ -1101,11 +1131,13 @@ export const MultiSelectComboBoxMixin = (superClass) =>
 
         if (this.readonly) {
           this.close();
+        } else if (this._isSelectAllHighlighted) {
+          this._toggleSelectAll();
         } else if (this._hasValidInputValue()) {
           // Keep selected item focused after committing on Enter.
-          const focusedItem = this._dropdownItems[this._focusedIndex];
+          const focusedItem = this._highlightedItem;
           this._commitValue();
-          this._focusedIndex = this._dropdownItems.indexOf(focusedItem);
+          this._highlightItem(focusedItem);
         }
 
         return;
@@ -1115,8 +1147,8 @@ export const MultiSelectComboBoxMixin = (superClass) =>
     }
 
     /**
-     * Override method inherited from the combo-box
-     * to not update focused item when readonly.
+     * Override method from `ComboBoxBaseMixin` to not update focused
+     * item when readonly.
      * @protected
      * @override
      */
@@ -1129,8 +1161,8 @@ export const MultiSelectComboBoxMixin = (superClass) =>
     }
 
     /**
-     * Override method inherited from the combo-box
-     * to not update focused item when readonly.
+     * Override method from `ComboBoxBaseMixin` to not update focused
+     * item when readonly.
      * @protected
      * @override
      */
@@ -1151,120 +1183,80 @@ export const MultiSelectComboBoxMixin = (superClass) =>
     _onKeyDown(event) {
       super._onKeyDown(event);
 
-      const chips = this._chips;
-
-      if (!this.readonly && chips.length > 0) {
+      if (!this.readonly && this._chips.length > 0) {
         switch (event.key) {
           case 'Backspace':
-            this._onBackSpace(chips);
+            this._onBackSpace();
             break;
           case 'ArrowLeft':
-            this._onArrowLeft(chips, event);
-            break;
           case 'ArrowRight':
-            this._onArrowRight(chips, event);
+            this._onChipArrow(event);
             break;
           default:
-            this._focusedChipIndex = -1;
+            this._clearChipHighlight();
             break;
         }
       }
     }
 
     /** @private */
-    _onArrowLeft(chips, event) {
+    _onChipArrow(event) {
       if (this.inputElement.selectionStart !== 0) {
         return;
       }
 
-      const idx = this._focusedChipIndex;
-      if (idx !== -1) {
+      if (this._hasHighlightedChip) {
         event.preventDefault();
       }
-      let newIdx;
-
-      if (!this.__isRTL) {
-        if (idx === -1) {
-          // Focus last chip
-          newIdx = chips.length - 1;
-        } else if (idx > 0) {
-          // Focus prev chip
-          newIdx = idx - 1;
-        }
-      } else if (idx === chips.length - 1) {
-        // Blur last chip
-        newIdx = -1;
-      } else if (idx > -1) {
-        // Focus next chip
-        newIdx = idx + 1;
-      }
 
-      if (newIdx !== undefined) {
-        this._focusedChipIndex = newIdx;
-      }
-    }
+      const hadHighlightedItem = this._hasHighlightedItem;
 
-    /** @private */
-    _onArrowRight(chips, event) {
-      if (this.inputElement.selectionStart !== 0) {
-        return;
+      const isPrevKey = this.__isRTL ? event.key === 'ArrowRight' : event.key === 'ArrowLeft';
+      if (isPrevKey) {
+        this._highlightPrevChip();
+      } else {
+        this._highlightNextChip();
       }
 
-      const idx = this._focusedChipIndex;
-      if (idx !== -1) {
+      // The label of the highlighted item was prefilled into the input, so
+      // restore the filter once the highlight moved from the item to a chip.
+      // Place the caret at the start of the input, so that the next arrow
+      // key press continues to navigate the chips instead of moving the caret.
+      if (hadHighlightedItem && this._hasHighlightedChip) {
         event.preventDefault();
-      }
-      let newIdx;
-
-      if (this.__isRTL) {
-        if (idx === -1) {
-          // Focus last chip
-          newIdx = chips.length - 1;
-        } else if (idx > 0) {
-          // Focus prev chip
-          newIdx = idx - 1;
-        }
-      } else if (idx === chips.length - 1) {
-        // Blur last chip
-        newIdx = -1;
-      } else if (idx > -1) {
-        // Focus next chip
-        newIdx = idx + 1;
-      }
-
-      if (newIdx !== undefined) {
-        this._focusedChipIndex = newIdx;
+        this._inputElementValue = this.filter;
+        this._setSelectionRange(0, 0);
       }
     }
 
     /** @private */
-    _onBackSpace(chips) {
+    _onBackSpace() {
       if (this.inputElement.selectionStart !== 0) {
         return;
       }
 
-      const idx = this._focusedChipIndex;
-      if (idx === -1) {
-        this._focusedChipIndex = chips.length - 1;
+      const chip = this._highlightedChip;
+      if (chip) {
+        this.__removeItem(chip.item);
+        this._clearChipHighlight();
       } else {
-        this.__removeItem(chips[idx].item);
-        this._focusedChipIndex = -1;
+        this._highlightLastChip();
       }
     }
 
     /** @private */
-    _focusedChipIndexChanged(focusedIndex, oldFocusedIndex) {
-      if (focusedIndex > -1 || oldFocusedIndex > -1) {
-        const chips = this._chips;
-        chips.forEach((chip, index) => {
-          chip.toggleAttribute('focused', index === focusedIndex);
-        });
+    __updateChipHighlight(oldState) {
+      const chips = this._chips;
+
+      if (oldState?.type === 'chip') {
+        chips[oldState.index]?.removeAttribute('focused');
+      }
 
-        // Announce focused chip
-        if (focusedIndex > -1) {
-          const item = chips[focusedIndex].item;
-          const itemLabel = this._getItemLabel(item);
-          announce(`${itemLabel} ${this.__effectiveI18n.focused}`);
+      if (this._hasHighlightedChip) {
+        const chip = chips[this._highlightState.index];
+        if (chip) {
+          chip.setAttribute('focused', '');
+          announce(`${this._getItemLabel(chip.item)} ${this.__effectiveI18n.focused}`);
         }
       }
     }

package/src/vaadin-multi-select-combo-box-select-all-button.js

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { html, LitElement } from 'lit';
+import { defineCustomElement } from '@vaadin/component-base/src/define.js';
+import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
+import { multiSelectComboBoxSelectAllButtonStyles } from './styles/vaadin-multi-select-combo-box-select-all-button-base-styles.js';
+
+/**
+ * An element used by `<vaadin-multi-select-combo-box>` to select or deselect
+ * all items shown in the dropdown. The element is not focusable itself, the
+ * keyboard highlight is reflected with the `focused` attribute while the DOM
+ * focus stays in the input.
+ *
+ * ### Styling
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute   | Description
+ * ------------|-------------
+ * `focused`   | Set when the button is highlighted with the keyboard
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @customElement vaadin-multi-select-combo-box-select-all-button
+ * @extends HTMLElement
+ * @private
+ */
+class MultiSelectComboBoxSelectAllButton extends PolylitMixin(LumoInjectionMixin(LitElement)) {
+  static get is() {
+    return 'vaadin-multi-select-combo-box-select-all-button';
+  }
+
+  static get styles() {
+    return multiSelectComboBoxSelectAllButtonStyles;
+  }
+
+  static get properties() {
+    return {
+      /**
+       * The text shown in the button.
+       */
+      label: {
+        type: String,
+        sync: true,
+      },
+
+      /**
+       * True when the button is highlighted with the keyboard.
+       */
+      focused: {
+        type: Boolean,
+        value: false,
+        reflectToAttribute: true,
+        sync: true,
+      },
+    };
+  }
+
+  /** @protected */
+  render() {
+    return html`${this.label}`;
+  }
+
+  /** @protected */
+  firstUpdated() {
+    super.firstUpdated();
+
+    this.setAttribute('role', 'button');
+  }
+}
+
+defineCustomElement(MultiSelectComboBoxSelectAllButton);

package/src/vaadin-multi-select-combo-box-select-all-mixin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 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';
+
+/**
+ * A mixin that manages the select all button of `<vaadin-multi-select-combo-box>`.
+ */
+export declare function MultiSelectComboBoxSelectAllMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<MultiSelectComboBoxSelectAllMixinClass> & T;
+
+export declare class MultiSelectComboBoxSelectAllMixinClass {
+  /**
+   * Set to true to show a button above the dropdown items for selecting
+   * or deselecting all items matching the current filter at once. Items
+   * that do not match the filter keep their selection state.
+   *
+   * The button is only supported with the `items` API. It is not shown
+   * when using `dataProvider`.
+   * @attr {boolean} select-all-button-visible
+   */
+  selectAllButtonVisible: boolean;
+}

package/src/vaadin-multi-select-combo-box-select-all-mixin.js

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 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/src/vaadin-combo-box-placeholder.js';
+import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
+
+/**
+ * A mixin that manages the select all button of `<vaadin-multi-select-combo-box>`.
+ */
+export const MultiSelectComboBoxSelectAllMixin = (superClass) =>
+  class MultiSelectComboBoxSelectAllMixinClass extends superClass {
+    static get properties() {
+      return {
+        /**
+         * Set to true to show a button above the dropdown items for selecting
+         * or deselecting all items matching the current filter at once. Items
+         * that do not match the filter keep their selection state.
+         *
+         * The button is only supported with the `items` API. It is not shown
+         * when using `dataProvider`.
+         * @attr {boolean} select-all-button-visible
+         */
+        selectAllButtonVisible: {
+          type: Boolean,
+          value: false,
+          sync: true,
+        },
+
+        /**
+         * Shows the select all button with `dataProvider`, and is called instead of
+         * the local toggle while `_allSelected` is set. The function must update
+         * `selectedItems` and may return a promise. The component announces the
+         * result after it resolves, without firing `change`.
+         * Internal API for the Flow component.
+         * @private
+         */
+        _toggleSelectAllHandler: {
+          type: Function,
+          attribute: false,
+          sync: true,
+        },
+
+        /**
+         * Whether all items matching the filter are selected, set by the server
+         * with a data provider. When not set, the component computes it locally.
+         * @private
+         */
+        _allSelected: {
+          type: Boolean,
+          attribute: false,
+          sync: true,
+        },
+      };
+    }
+
+    #button;
+
+    constructor() {
+      super();
+
+      const button = document.createElement('vaadin-multi-select-combo-box-select-all-button');
+      button.setAttribute('slot', 'select-all');
+      button.id = `select-all-${this.localName}-${generateUniqueId()}`;
+      button.addEventListener('click', () => this._toggleSelectAll());
+      this.#button = button;
+    }
+
+    /** @protected */
+    get _hasSelectAllButton() {
+      return (
+        this.selectAllButtonVisible &&
+        !this.readonly &&
+        (!this.dataProvider || this.#hasActiveHandler) &&
+        this.#hasLoadedFilteredItems()
+      );
+    }
+
+    /** @protected */
+    willUpdate(props) {
+      super.willUpdate(props);
+
+      if (props.has('filter') || !this.opened || !this._hasSelectAllButton) {
+        this._clearSelectAllHighlight();
+      }
+    }
+
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('_highlightState')) {
+        this.#button.focused = this._isSelectAllHighlighted;
+
+        if (props.get('_highlightState')?.type === 'item' && this._isSelectAllHighlighted) {
+          // When highlighting the button, revert input value to the filter
+          this._revertInputValue();
+        }
+      }
+
+      // Properties that affect whether the button is shown, or the label
+      // of the button
+      const buttonProps = [
+        'selectAllButtonVisible',
+        '_toggleSelectAllHandler',
+        '_allSelected',
+        'readonly',
+        'dataProvider',
+        'filteredItems',
+        'selectedItems',
+        'itemIdPath',
+        'filter',
+        '__effectiveI18n',
+      ];
+
+      if (buttonProps.some((prop) => props.has(prop))) {
+        this.#updateButton();
+      }
+    }
+
+    /**
+     * Override method from `ComboBoxBaseMixin` to reference the select all
+     * button from the input while the button is highlighted.
+     * @protected
+     * @override
+     */
+    _updateActiveDescendant() {
+      if (this._isSelectAllHighlighted) {
+        this.inputElement?.setAttribute('aria-activedescendant', this.#button.id);
+      } else {
+        super._updateActiveDescendant();
+      }
+    }
+
+    /**
+     * Selects all items matching the current filter, or deselects
+     * them when all of them are already selected. Delegates to
+     * `_toggleSelectAllHandler` while `_allSelected` is set.
+     * @protected
+     */
+    _toggleSelectAll() {
+      if (this.#hasServerState) {
+        this.#toggleSelectAllWithHandler();
+      } else {
+        this.#toggleSelectAllLocally();
+      }
+    }
+
+    get #hasActiveHandler() {
+      return !!this.dataProvider && !!this._toggleSelectAllHandler;
+    }
+
+    get #hasServerState() {
+      return this.#hasActiveHandler && this._allSelected != null;
+    }
+
+    #updateButton() {
+      this.toggleAttribute('has-select-all', this._hasSelectAllButton);
+
+      if (!this._hasSelectAllButton) {
+        this.#button.remove();
+        return;
+      }
+
+      const button = this.#button;
+      button.label = this.#getButtonLabel();
+
+      if (button.parentNode !== this) {
+        this.appendChild(button);
+      }
+    }
+
+    #getButtonLabel() {
+      const { selectAll, deselectAll, selectFiltered, deselectFiltered } = this.__effectiveI18n;
+      const allSelected = this.#hasServerState ? this._allSelected : this.#areAllFilteredItemsSelected();
+
+      if (this.filter) {
+        return allSelected ? deselectFiltered : selectFiltered;
+      }
+
+      return allSelected ? deselectAll : selectAll;
+    }
+
+    async #toggleSelectAllWithHandler() {
+      // The handler owns the selection and is expected to update
+      // `selectedItems` itself. Intentionally do not fire `change` and do
+      // not request validation here, only announce the result.
+      try {
+        await this._toggleSelectAllHandler();
+      } catch (error) {
+        console.error(error);
+        return;
+      }
+
+      this.__announceSelection();
+    }
+
+    #toggleSelectAllLocally() {
+      const filteredItems = this.#getFilteredItems();
+      let selectedItems;
+
+      if (this.#areAllFilteredItemsSelected()) {
+        selectedItems = this.selectedItems.filter((item) => !this.#includesItem(filteredItems, item));
+      } else {
+        const missingItems = filteredItems.filter((item) => !this.#includesItem(this.selectedItems, item));
+        selectedItems = [...this.selectedItems, ...missingItems];
+      }
+
+      this.__updateSelection(selectedItems);
+      this.__announceSelection();
+    }
+
+    #areAllFilteredItemsSelected() {
+      const items = this.#getFilteredItems();
+      return items.length > 0 && items.every((item) => this.#includesItem(this.selectedItems, item));
+    }
+
+    #hasLoadedFilteredItems() {
+      // Hide the button while no page is loaded, for example after `clearCache()`
+      return (this.filteredItems || []).some((item) => !(item instanceof ComboBoxPlaceholder));
+    }
+
+    #getFilteredItems() {
+      return this.filteredItems || [];
+    }
+
+    #includesItem(items, item) {
+      return items.some((other) => this._isSameItem(item, other));
+    }
+  };