@vaadin/multi-select-combo-box 24.6.0-alpha9 → 24.6.0-rc1

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

@@ -7,23 +7,20 @@ import './vaadin-multi-select-combo-box-item.js';
 import './vaadin-multi-select-combo-box-overlay.js';
 import './vaadin-multi-select-combo-box-scroller.js';
 import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
-import { ComboBoxDataProviderMixin } from '@vaadin/combo-box/src/vaadin-combo-box-data-provider-mixin.js';
-import { ComboBoxMixin } from '@vaadin/combo-box/src/vaadin-combo-box-mixin.js';
-import { ComboBoxPlaceholder } from '@vaadin/combo-box/src/vaadin-combo-box-placeholder.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { MultiSelectComboBoxInternalMixin } from './vaadin-multi-select-combo-box-internal-mixin.js';
 
 /**
  * An element used internally by `<vaadin-multi-select-combo-box>`. Not intended to be used separately.
  *
  * @customElement
  * @extends HTMLElement
- * @mixes ComboBoxDataProviderMixin
- * @mixes ComboBoxMixin
+ * @mixes MultiSelectComboBoxInternalMixin
  * @mixes ThemableMixin
  * @private
  */
-class MultiSelectComboBoxInternal extends ComboBoxDataProviderMixin(ComboBoxMixin(ThemableMixin(PolymerElement))) {
+class MultiSelectComboBoxInternal extends MultiSelectComboBoxInternalMixin(ThemableMixin(PolymerElement)) {
   static get is() {
     return 'vaadin-multi-select-combo-box-internal';
   }
@@ -49,399 +46,6 @@ class MultiSelectComboBoxInternal extends ComboBoxDataProviderMixin(ComboBoxMixi
       ></vaadin-multi-select-combo-box-overlay>
     `;
   }
-
-  static get properties() {
-    return {
-      /**
-       * A subset of items, filtered based on the user input.
-       */
-      filteredItems: {
-        type: Array,
-        notify: true,
-      },
-
-      /**
-       * When true, filter string isn't cleared after selecting an item.
-       */
-      keepFilter: {
-        type: Boolean,
-        value: false,
-      },
-
-      /**
-       * When set to `true`, "loading" attribute is set
-       * on the host and the overlay element.
-       * @type {boolean}
-       */
-      loading: {
-        type: Boolean,
-        notify: true,
-      },
-
-      /**
-       * Total number of items.
-       * @type {number | undefined}
-       */
-      size: {
-        type: Number,
-        notify: true,
-      },
-
-      /**
-       * Selected items to render in the dropdown
-       * when the component is read-only.
-       */
-      selectedItems: {
-        type: Array,
-        value: () => [],
-      },
-
-      /**
-       * Set to true to group selected items at the top of the overlay.
-       * @attr {boolean} selected-items-on-top
-       */
-      selectedItemsOnTop: {
-        type: Boolean,
-        value: false,
-      },
-
-      /**
-       * Last input value entered by the user before value is updated.
-       * Used to store `filter` property value before clearing it.
-       */
-      lastFilter: {
-        type: String,
-        notify: true,
-      },
-
-      /**
-       * A subset of items to be shown at the top of the overlay.
-       */
-      topGroup: {
-        type: Array,
-        observer: '_topGroupChanged',
-      },
-
-      _target: {
-        type: Object,
-      },
-    };
-  }
-
-  static get observers() {
-    return ['_readonlyChanged(readonly)'];
-  }
-
-  /**
-   * Reference to the clear button element.
-   * @protected
-   * @return {!HTMLElement}
-   */
-  get clearElement() {
-    return this.querySelector('[part="clear-button"]');
-  }
-
-  /**
-   * Tag name prefix used by scroller and items.
-   * @protected
-   * @return {string}
-   */
-  get _tagNamePrefix() {
-    return 'vaadin-multi-select-combo-box';
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to allow opening dropdown when readonly.
-   * @override
-   */
-  open() {
-    if (!this.disabled && !(this.readonly && this.selectedItems.length === 0)) {
-      this.opened = true;
-    }
-  }
-
-  /** @protected */
-  ready() {
-    super.ready();
-
-    this._target = this;
-    this._toggleElement = this.querySelector('.toggle-button');
-  }
-
-  /** @private */
-  _readonlyChanged() {
-    this._setDropdownItems(this.filteredItems);
-  }
-
-  /**
-   * Override combo-box method to group selected
-   * items at the top of the overlay.
-   *
-   * @protected
-   * @override
-   */
-  _setDropdownItems(items) {
-    if (this.readonly) {
-      super._setDropdownItems(this.selectedItems);
-      return;
-    }
-
-    if (this.filter || !this.selectedItemsOnTop) {
-      super._setDropdownItems(items);
-      return;
-    }
-
-    if (items && items.length && this.topGroup && this.topGroup.length) {
-      // Filter out items included to the top group.
-      const filteredItems = items.filter(
-        (item) => this._comboBox._findIndex(item, this.topGroup, this.itemIdPath) === -1,
-      );
-
-      super._setDropdownItems(this.topGroup.concat(filteredItems));
-      return;
-    }
-
-    super._setDropdownItems(items);
-  }
-
-  /** @private */
-  _topGroupChanged(topGroup) {
-    if (topGroup) {
-      this._setDropdownItems(this.filteredItems);
-    }
-  }
-
-  /**
-   * Override combo-box method to set correct owner for using by item renderers.
-   * This needs to be done before the scroller gets added to the DOM to ensure
-   * Lit directive works in case when combo-box is opened using attribute.
-   *
-   * @protected
-   * @override
-   */
-  _initScroller() {
-    const comboBox = this.getRootNode().host;
-
-    this._comboBox = comboBox;
-
-    super._initScroller(comboBox);
-  }
-
-  /**
-   * Override Enter handler to keep overlay open
-   * when item is selected or unselected.
-   * @param {!Event} event
-   * @protected
-   * @override
-   */
-  _onEnter(event) {
-    if (this.opened) {
-      // Do not submit the surrounding form.
-      event.preventDefault();
-      // Do not trigger global listeners.
-      event.stopPropagation();
-
-      if (this.readonly) {
-        this.close();
-      } else if (this._hasValidInputValue()) {
-        // Keep selected item focused after committing on Enter.
-        const focusedItem = this._dropdownItems[this._focusedIndex];
-        this._commitValue();
-        this._focusedIndex = this._dropdownItems.indexOf(focusedItem);
-      }
-
-      return;
-    }
-
-    super._onEnter(event);
-  }
-
-  /**
-   * Override Escape handler to not clear
-   * selected items when readonly.
-   * @param {!Event} event
-   * @protected
-   * @override
-   */
-  _onEscape(event) {
-    if (this.readonly) {
-      event.stopPropagation();
-      if (this.opened) {
-        this.close();
-      }
-      return;
-    }
-
-    super._onEscape(event);
-  }
-
-  /**
-   * Override from combo-box to ignore requests to clear the filter if the
-   * keepFilter option is enabled. Exceptions are when the dropdown is closed,
-   * so the filter is still cleared on cancel and focus out.
-   * @protected
-   * @override
-   */
-  _clearFilter() {
-    if (!this.keepFilter || !this.opened) {
-      super._clearFilter();
-    }
-  }
-
-  /**
-   * Override method from combo-box to always clear the filter when reverting
-   * the input value, regardless of the keepFilter option.
-   * @override
-   * @protected
-   */
-  _revertInputValueToValue() {
-    super._revertInputValueToValue();
-    this.filter = '';
-  }
-
-  /**
-   * @protected
-   * @override
-   */
-  _commitValue() {
-    // Store filter value for checking if user input is matching
-    // an item which is already selected, to not un-select it.
-    this.lastFilter = this.filter;
-
-    super._commitValue();
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to not update focused item when readonly.
-   * @protected
-   * @override
-   */
-  _onArrowDown() {
-    if (!this.readonly) {
-      super._onArrowDown();
-    } else if (!this.opened) {
-      this.open();
-    }
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to not update focused item when readonly.
-   * @protected
-   * @override
-   */
-  _onArrowUp() {
-    if (!this.readonly) {
-      super._onArrowUp();
-    } else if (!this.opened) {
-      this.open();
-    }
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to close dropdown on blur when readonly.
-   * @param {boolean} focused
-   * @protected
-   * @override
-   */
-  _setFocused(focused) {
-    // Disable combo-box logic that updates selectedItem
-    // based on the overlay focused index on input blur
-    if (!focused) {
-      this._ignoreCommitValue = true;
-    }
-
-    super._setFocused(focused);
-
-    if (!focused && this.readonly && !this._closeOnBlurIsPrevented) {
-      this.close();
-    }
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to not commit an already selected item again
-   * on blur, which would result in un-selecting.
-   * @protected
-   * @override
-   */
-  _detectAndDispatchChange() {
-    if (this._ignoreCommitValue) {
-      this._ignoreCommitValue = false;
-
-      // Reset internal combo-box state
-      this.selectedItem = null;
-      this._inputElementValue = '';
-      return;
-    }
-
-    super._detectAndDispatchChange();
-  }
-
-  /**
-   * @param {CustomEvent} event
-   * @protected
-   * @override
-   */
-  _overlaySelectedItemChanged(event) {
-    event.stopPropagation();
-
-    // Do not un-select on click when readonly
-    if (this.readonly) {
-      return;
-    }
-
-    if (event.detail.item instanceof ComboBoxPlaceholder) {
-      return;
-    }
-
-    if (this.opened) {
-      // Store filter value for checking if user input is matching
-      // an item which is already selected, to not un-select it.
-      this.lastFilter = this.filter;
-
-      this.dispatchEvent(
-        new CustomEvent('combo-box-item-selected', {
-          detail: {
-            item: event.detail.item,
-          },
-        }),
-      );
-    }
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to not request data provider when read-only.
-   *
-   * @protected
-   * @override
-   */
-  _shouldFetchData() {
-    if (this.readonly) {
-      return false;
-    }
-
-    return super._shouldFetchData();
-  }
-
-  /**
-   * Override method inherited from the combo-box
-   * to not clear the data provider cache when read-only.
-   *
-   * @protected
-   * @override
-   */
-  clearCache() {
-    if (this.readonly) {
-      return;
-    }
-
-    super.clearCache();
-  }
 }
 
 defineCustomElement(MultiSelectComboBoxInternal);

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

@@ -0,0 +1,253 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2024 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';
+import type { DelegateFocusMixinClass } from '@vaadin/a11y-base/src/delegate-focus-mixin.js';
+import type { DisabledMixinClass } from '@vaadin/a11y-base/src/disabled-mixin.js';
+import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
+import type { KeyboardMixinClass } from '@vaadin/a11y-base/src/keyboard-mixin.js';
+import type { ComboBoxDataProvider, ComboBoxItemModel } from '@vaadin/combo-box/src/vaadin-combo-box.js';
+import type { ControllerMixinClass } from '@vaadin/component-base/src/controller-mixin.js';
+import type { DelegateStateMixinClass } from '@vaadin/component-base/src/delegate-state-mixin.js';
+import type { ResizeMixinClass } from '@vaadin/component-base/src/resize-mixin.js';
+import type { SlotStylesMixinClass } from '@vaadin/component-base/src/slot-styles-mixin.js';
+import type { ClearButtonMixinClass } from '@vaadin/field-base/src/clear-button-mixin.js';
+import type { FieldMixinClass } from '@vaadin/field-base/src/field-mixin.js';
+import type { InputConstraintsMixinClass } from '@vaadin/field-base/src/input-constraints-mixin.js';
+import type { InputControlMixinClass } from '@vaadin/field-base/src/input-control-mixin.js';
+import type { InputMixinClass } from '@vaadin/field-base/src/input-mixin.js';
+import type { LabelMixinClass } from '@vaadin/field-base/src/label-mixin.js';
+import type { ValidateMixinClass } from '@vaadin/field-base/src/validate-mixin.js';
+import type { MultiSelectComboBox } from './vaadin-multi-select-combo-box.js';
+
+export type MultiSelectComboBoxRenderer<TItem> = (
+  root: HTMLElement,
+  comboBox: MultiSelectComboBox<TItem>,
+  model: ComboBoxItemModel<TItem>,
+) => void;
+
+export interface MultiSelectComboBoxI18n {
+  cleared: string;
+  focused: string;
+  selected: string;
+  deselected: string;
+  total: string;
+}
+
+export declare function MultiSelectComboBoxMixin<TItem, T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<ClearButtonMixinClass> &
+  Constructor<ControllerMixinClass> &
+  Constructor<DelegateFocusMixinClass> &
+  Constructor<DelegateStateMixinClass> &
+  Constructor<DisabledMixinClass> &
+  Constructor<FieldMixinClass> &
+  Constructor<FocusMixinClass> &
+  Constructor<InputConstraintsMixinClass> &
+  Constructor<InputControlMixinClass> &
+  Constructor<InputMixinClass> &
+  Constructor<KeyboardMixinClass> &
+  Constructor<LabelMixinClass> &
+  Constructor<MultiSelectComboBoxMixinClass<TItem>> &
+  Constructor<ResizeMixinClass> &
+  Constructor<SlotStylesMixinClass> &
+  Constructor<ValidateMixinClass> &
+  T;
+
+export declare class MultiSelectComboBoxMixinClass<TItem> {
+  /**
+   * Set to true to auto expand horizontally, causing input field to
+   * grow until max width is reached.
+   * @attr {boolean} auto-expand-horizontally
+   */
+  autoExpandHorizontally: boolean;
+
+  /**
+   * Set to true to not collapse selected items chips into the overflow
+   * chip and instead always expand vertically, causing input field to
+   * wrap into multiple lines when width is limited.
+   * @attr {boolean} auto-expand-vertically
+   */
+  autoExpandVertically: boolean;
+
+  /**
+   * When true, the user can input a value that is not present in the items list.
+   * @attr {boolean} allow-custom-value
+   */
+  allowCustomValue: boolean;
+
+  /**
+   * Set true to prevent the overlay from opening automatically.
+   * @attr {boolean} auto-open-disabled
+   */
+  autoOpenDisabled: boolean;
+
+  /**
+   * Function that provides items lazily. Receives two arguments:
+   *
+   * - `params` - Object with the following properties:
+   *   - `params.page` Requested page index
+   *   - `params.pageSize` Current page size
+   *   - `params.filter` Currently applied filter
+   *
+   * - `callback(items, size)` - Callback function with arguments:
+   *   - `items` Current page of items
+   *   - `size` Total number of items.
+   */
+  dataProvider: ComboBoxDataProvider<TItem> | null | undefined;
+
+  /**
+   * A subset of items, filtered based on the user input. Filtered items
+   * can be assigned directly to omit the internal filtering functionality.
+   * The items can be of either `String` or `Object` type.
+   */
+  filteredItems: TItem[] | undefined;
+
+  /**
+   * Filtering string the user has typed into the input field.
+   */
+  filter: string;
+
+  /**
+   * A full set of items to filter the visible options from.
+   * The items can be of either `String` or `Object` type.
+   */
+  items: TItem[] | undefined;
+
+  /**
+   * A function used to generate CSS class names for dropdown
+   * items and selected chips based on the item. The return
+   * value should be the generated class name as a string, or
+   * multiple class names separated by whitespace characters.
+   */
+  itemClassNameGenerator: (item: TItem) => string;
+
+  /**
+   * The item property used for a visual representation of the item.
+   * @attr {string} item-label-path
+   */
+  itemLabelPath: string;
+
+  /**
+   * Path for the id of the item, used to detect whether the item is selected.
+   * @attr {string} item-id-path
+   */
+  itemIdPath: string;
+
+  /**
+   * Path for the value of the item. If `items` is an array of objects,
+   * this property is used as a string value for the selected item.
+   * @attr {string} item-value-path
+   */
+  itemValuePath: string;
+
+  /**
+   * The object used to localize this component.
+   * To change the default localization, replace the entire
+   * _i18n_ object or just the property you want to modify.
+   *
+   * The object has the following JSON structure and default values:
+   * ```
+   * {
+   *   // Screen reader announcement on clear button click.
+   *   cleared: 'Selection cleared',
+   *   // Screen reader announcement when a chip is focused.
+   *   focused: ' focused. Press Backspace to remove',
+   *   // Screen reader announcement when item is selected.
+   *   selected: 'added to selection',
+   *   // Screen reader announcement when item is deselected.
+   *   deselected: 'removed from selection',
+   *   // Screen reader announcement of the selected items count.
+   *   // {count} is replaced with the actual count of items.
+   *   total: '{count} items selected',
+   * }
+   * ```
+   */
+  i18n: MultiSelectComboBoxI18n;
+
+  /**
+   * When true, filter string isn't cleared after selecting an item.
+   * @attr {boolean} keep-filter
+   */
+  keepFilter: boolean;
+
+  /**
+   * True when loading items from the data provider, false otherwise.
+   */
+  loading: boolean;
+
+  /**
+   * A space-delimited list of CSS class names to set on the overlay element.
+   *
+   * @attr {string} overlay-class
+   */
+  overlayClass: string;
+
+  /**
+   * True if the dropdown is open, false otherwise.
+   */
+  opened: boolean;
+
+  /**
+   * Number of items fetched at a time from the data provider.
+   * @attr {number} page-size
+   */
+  pageSize: number;
+
+  /**
+   * A hint to the user of what can be entered in the control.
+   * The placeholder will be only displayed in the case when
+   * there is no item selected.
+   */
+  placeholder: string;
+
+  /**
+   * Custom function for rendering the content of every item.
+   * Receives three arguments:
+   *
+   * - `root` The `<vaadin-multi-select-combo-box-item>` internal container DOM element.
+   * - `comboBox` The reference to the `<vaadin-multi-select-combo-box>` element.
+   * - `model` The object with the properties related with the rendered
+   *   item, contains:
+   *   - `model.index` The index of the rendered item.
+   *   - `model.item` The item.
+   */
+  renderer: MultiSelectComboBoxRenderer<TItem> | null | undefined;
+
+  /**
+   * The list of selected items.
+   * Note: modifying the selected items creates a new array each time.
+   */
+  selectedItems: TItem[];
+
+  /**
+   * Set to true to group selected items at the top of the overlay.
+   * @attr {boolean} selected-items-on-top
+   */
+  selectedItemsOnTop: boolean;
+
+  /**
+   * Total number of items.
+   */
+  size: number | undefined;
+
+  /**
+   * Clears the cached pages and reloads data from data provider when needed.
+   */
+  clearCache(): void;
+
+  /**
+   * Clears the selected items.
+   */
+  clear(): void;
+
+  /**
+   * 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;
+}