vaadin-combo-box-mixin.html

<!--
@license
Copyright (c) 2017 Vaadin Ltd.
This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
-->

<link rel="import" href="../../polymer/polymer-element.html">
<link rel="import" href="../../polymer/lib/utils/templatize.html">
<link rel="import" href="../../iron-a11y-announcer/iron-a11y-announcer.html">

<script>
  window.Vaadin = window.Vaadin || {};

  /**
   * @polymerMixin
   * @memberof Vaadin
   */
  Vaadin.ComboBoxMixin = subclass => class VaadinComboBoxMixinElement extends subclass {

    static get properties() {
      return {
        /**
         * True if the dropdown is open, false otherwise.
         */
        opened: {
          type: Boolean,
          notify: true,
          value: false,
          reflectToAttribute: true,
          observer: '_openedChanged'
        },

        /**
         * Set to true to disable this element.
         */
        disabled: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        /**
         * When present, it specifies that the element field is read-only.
         */
        readonly: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        /**
         * A full set of items to filter the visible options from.
         * The items can be of either `String` or `Object` type.
         */
        items: {
          type: Array
        },

        /**
         * If `true`, the user can input a value that is not present in the items list.
         * `value` property will be set to the input value in this case.
         * Also, when `value` is set programmatically, the input value will be set
         * to reflect that value.
         */
        allowCustomValue: {
          type: Boolean,
          value: false
        },

        /**
         * 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: {
          type: Array
        },

        /**
         * The `String` value for the selected item of the combo box. Provides
         * the value for `iron-form`.
         *
         * When there’s no item selected, the value is an empty string.
         *
         * Use `selectedItem` property to get the raw selected item from
         * the `items` array.
         */
        value: {
          type: String,
          observer: '_valueChanged',
          notify: true,
          value: ''
        },

        /**
         * Used to detect user value changes and fire `change` events.
         */
        _lastCommittedValue: String,

        /*
         * When set to `true`, "loading" attribute is added to host and the overlay element.
         */
        loading: {
          type: Boolean,
          value: false,
          reflectToAttribute: true
        },

        _focusedIndex: {
          type: Number,
          value: -1
        },

        /**
         * Filtering string the user has typed into the input field.
         */
        filter: {
          type: String,
          value: '',
          notify: true
        },

        /**
         * The selected item from the `items` array.
         */
        selectedItem: {
          type: Object,
          notify: true
        },

        /**
         * Path for label of the item. If `items` is an array of objects, the
         * `itemLabelPath` is used to fetch the displayed string label for each
         * item.
         *
         * The item label is also used for matching items when processing user
         * input, i.e., for filtering and selecting items.
         *
         * When using item templates, the property is still needed because it is used
         * for filtering, and for displaying the selected item value in the input box.
         */
        itemLabelPath: {
          type: String,
          value: 'label'
        },

        /**
         * Path for the value of the item. If `items` is an array of objects, the
         * `itemValuePath:` is used to fetch the string value for the selected
         * item.
         *
         * The item value is used in the `value` property of the combo box,
         * to provide the form value.
         */
        itemValuePath: {
          type: String,
          value: 'value'
        },

        /**
         * The name of this element.
         */
        name: {
          type: String
        },

        /**
         * Set to true if the value is invalid.
         */
        invalid: {
          type: Boolean,
          reflectToAttribute: true,
          notify: true,
          value: false
        },

        _toggleElement: Object,
        _clearElement: Object,

        _inputElementValue: String,

        _closeOnBlurIsPrevented: Boolean,

        _previousDocumentPointerEvents: String
      };
    }

    static get observers() {
      return [
        '_filterChanged(filter, itemValuePath, itemLabelPath)',
        '_itemsChanged(items.*, itemValuePath, itemLabelPath)',
        '_filteredItemsChanged(filteredItems.*, itemValuePath, itemLabelPath)',
        '_loadingChanged(loading)',
        '_selectedItemChanged(selectedItem)',
        '_toggleElementChanged(_toggleElement)'
      ];
    }

    ready() {
      super.ready();

      this.addEventListener('focusout', e => {
        if (!this._closeOnBlurIsPrevented) {
          this.close();
        }
      });

      this._lastCommittedValue = this.value;
      Polymer.IronA11yAnnouncer.requestAvailability();

      // 2.0 does not support 'overlay.selection-changed' syntax in listeners
      this.$.overlay.addEventListener('selection-changed', this._overlaySelectedItemChanged.bind(this));

      this.addEventListener('vaadin-combo-box-dropdown-closed', this._onClosed.bind(this));
      this.addEventListener('vaadin-combo-box-dropdown-opened', this._onOpened.bind(this));
      this.addEventListener('keydown', this._onKeyDown.bind(this));
      this.addEventListener('click', this._onClick.bind(this));

      this.$.overlay.addEventListener('vaadin-overlay-touch-action', this._onOverlayTouchAction.bind(this));

      this.addEventListener('touchend', e => {
        if (!this._clearElement || e.composedPath()[0] !== this._clearElement) {
          return;
        }

        e.preventDefault();
        this._clear();
      });
    }

    /**
     * Opens the dropdown list.
     */
    open() {
      // Prevent _open() being called when input is disabled or read-only
      if (!this.disabled && !this.readonly) {
        this.opened = true;
      }
    }

    /**
     * Closes the dropdown list.
     */
    close() {
      this.opened = false;
    }

    _openedChanged(value, old) {
      // Prevent _close() being called when opened is set to its default value (false).
      if (old === undefined) {
        return;
      }

      if (this.opened) {
        this._openedWithFocusRing = this.hasAttribute('focus-ring') || (this.focusElement && this.focusElement.hasAttribute('focus-ring'));
        // For touch devices, we don't want to popup virtual keyboard on touch devices unless input
        // is explicitly focused by the user.
        if (!this.$.overlay.touchDevice) {
          // Check to see if there is a focused property and if it's already true.
          if (!this.focused) {
            this.focus();
          }
        }
      } else {
        if (this._openedWithFocusRing && this.hasAttribute('focused')) {
          this.focusElement.setAttribute('focus-ring', '');
        }
        this._onClosed();
      }
    }

    _onOverlayTouchAction(event) {
      // On touch devices, blur the input on touch start inside the overlay, in order to hide
      // the virtual keyboard. But don't close the overlay on this blur.
      this._closeOnBlurIsPrevented = true;
      this.inputElement.blur();
      this._closeOnBlurIsPrevented = false;
    }

    _onClick(e) {
      this._closeOnBlurIsPrevented = true;

      const path = e.composedPath();
      if (path.indexOf(this._clearElement) !== -1) {
        this._clear();
        this.focus();
      } else if (path.indexOf(this.inputElement) !== -1) {
        if (path.indexOf(this._toggleElement) > -1 && this.opened) {
          this.close();
        } else {
          this.open();
        }
      }

      this._closeOnBlurIsPrevented = false;
    }

    /**
     * Keyboard navigation
     */

    _onKeyDown(e) {
      if (this._isEventKey(e, 'down')) {
        this._closeOnBlurIsPrevented = true;
        this._onArrowDown();
        this._closeOnBlurIsPrevented = false;

        // prevent caret from moving
        e.preventDefault();
      } else if (this._isEventKey(e, 'up')) {
        this._closeOnBlurIsPrevented = true;
        this._onArrowUp();
        this._closeOnBlurIsPrevented = false;

        // prevent caret from moving
        e.preventDefault();
      } else if (this._isEventKey(e, 'enter')) {
        this._onEnter(e);
      } else if (this._isEventKey(e, 'esc')) {
        this._onEscape(e);
      }
    }

    _isEventKey(e, k) {
      return Polymer.IronA11yKeysBehavior.keyboardEventMatchesKeys(e, k);
    }

    _getItemLabel(item) {
      return this.$.overlay.getItemLabel(item);
    }

    _getItemValue(item) {
      let value = item ? this.get(this.itemValuePath, item) : undefined;
      if (value === undefined) {
        value = item ? item.toString() : '';
      }
      return value;
    }

    _onArrowDown() {
      if (this.opened) {
        if (this.$.overlay._items) {
          this._focusedIndex = Math.min(this.$.overlay._items.length - 1, this._focusedIndex + 1);
          this._prefillFocusedItemLabel();
        }
      } else {
        this.open();
      }
    }

    _onArrowUp() {
      if (this.opened) {
        if (this._focusedIndex > -1) {
          this._focusedIndex = Math.max(0, this._focusedIndex - 1);
        } else {
          if (this.$.overlay._items) {
            this._focusedIndex = this.$.overlay._items.length - 1;
          }
        }

        this._prefillFocusedItemLabel();
      } else {
        this.open();
      }
    }

    _prefillFocusedItemLabel() {
      if (this._focusedIndex > -1) {
        // Reset the input value asyncronously to prevent partial value changes
        // announce. Makes OSX VoiceOver to announce the complete value instead.
        this._inputElementValue = '';
        // 1ms delay needed for OSX VoiceOver to realise input value was reset
        setTimeout(() => {
          this._inputElementValue = this._getItemLabel(this.$.overlay._focusedItem);
          this._markAllSelectionRange();
        }, 1);
      }
    }

    _setSelectionRange(start, end) {
      // vaadin-text-field does not implement setSelectionRange, hence we need the native input
      const input = this._nativeInput || this.inputElement;

      // Setting selection range focuses and/or moves the caret in some browsers,
      // and there's no need to modify the selection range if the input isn't focused anyway.
      // This affects Safari. When the overlay is open, and then hiting tab, browser should focus
      // the next focusable element instead of the combo-box itself.
      // Checking the focused property here is enough instead of checking the activeElement.
      if (this.hasAttribute('focused') && input && input.setSelectionRange) {
        try {
          input.setSelectionRange(start, end);
        } catch (ignore) {
          // IE11 randomly fails when running tests in Sauce.
        }
      }
    }

    _markAllSelectionRange() {
      if (this._inputElementValue !== undefined) {
        this._setSelectionRange(0, this._inputElementValue.length);
      }
    }

    _clearSelectionRange() {
      if (this._inputElementValue !== undefined) {
        const pos = this._inputElementValue ? this._inputElementValue.length : 0;
        this._setSelectionRange(pos, pos);
      }
    }

    _onEnter(e) {
      // should close on enter when custom values are allowed, input field is cleared, or when an existing
      // item is focused with keyboard.
      if (this.opened && (this.allowCustomValue || this._inputElementValue === '' || this._focusedIndex > -1)) {
        this.close();

        // Do not submit the surrounding form.
        e.preventDefault();
      }
    }

    _onEscape(e) {
      if (this.opened) {
        this._stopPropagation(e);

        if (this._focusedIndex > -1) {
          this._focusedIndex = -1;
          this._revertInputValue();
        } else {
          this.cancel();
        }
      }
    }

    _toggleElementChanged(toggleElement) {
      if (toggleElement) {
        // Don't blur the input on toggle mousedown
        toggleElement.addEventListener('mousedown', e => e.preventDefault());
      }
    }

    /**
     * Clears the current value.
     */
    _clear() {
      this.selectedItem = null;

      if (this.allowCustomValue) {
        this.value = '';
      }

      if (!this.opened) {
        this._detectAndDispatchChange();
      }
    }

    /**
     * Reverts back to original value.
     */
    cancel() {
      this._revertInputValueToValue();
      // In the next _detectAndDispatchChange() call, the change detection should not pass
      this._lastCommittedValue = this.value;
      this.close();
    }

    _onOpened() {
      // Pre P2 iron-list used a debouncer to render. Now that we synchronously render items,
      // we need to flush the DOM to make sure it doesn't get flushed in the middle of _render call
      // because that will cause problems to say the least.
      Polymer.flush && Polymer.flush();

      // With iron-list v1.3.9, calling `notifyResize()` no longer renders
      // the items synchronously. It is required to have the items rendered
      // before we update the overlay and the list positions and sizes.
      this.$.overlay.ensureItemsRendered();
      this.$.overlay._selector.toggleScrollListener(true);

      // Ensure metrics are up-to-date
      this.$.overlay.updateViewportBoundaries();
      Polymer.Async.microTask.run(() => this.$.overlay.adjustScrollPosition());
      setTimeout(() => this.$.overlay.$.dropdown.notifyResize(), 1);


      // _detectAndDispatchChange() should not consider value changes done before opening
      this._lastCommittedValue = this.value;
    }

    _onClosed() {

      // Happens when the overlay is closed by clicking outside
      if (this.opened) {
        this.close();
      }

      if (this.$.overlay._items && this._focusedIndex > -1) {
        const focusedItem = this.$.overlay._items[this._focusedIndex];
        if (this.selectedItem !== focusedItem) {
          this.selectedItem = focusedItem;
        }
        // make sure input field is updated in case value doesn't change (i.e. FOO -> foo)
        this._inputElementValue = this._getItemLabel(this.selectedItem);
      } else if (this._inputElementValue === '' || this._inputElementValue === undefined) {
        this.selectedItem = null;

        if (this.allowCustomValue) {
          this.value = '';
        }
      } else {
        if (this.allowCustomValue) {
          const e = new CustomEvent('custom-value-set', {detail: this._inputElementValue, composed: true, cancelable: true, bubbles: true});
          this.dispatchEvent(e);
          if (!e.defaultPrevented) {
            const customValue = this._inputElementValue;
            this.selectedItem = null;
            this.value = customValue;
          }
        } else {
          this._inputElementValue = this._getItemLabel(this.selectedItem);
        }
      }

      this._detectAndDispatchChange();

      this._clearSelectionRange();

      this.filter = '';
    }

    /**
     *  Filtering and items handling
     */
    _inputValueChanged(e) {
      // Handle only input events from our inputElement.
      if (e.composedPath().indexOf(this.inputElement) !== -1) {
        this._inputElementValue = this.inputElement.value;
        this._filterFromInput();
      }
    }

    _filterFromInput(e) {
      if (!this.opened) {
        this.open();
      }

      if (this.filter === this._inputElementValue) {
        // 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);
      } else {
        this.filter = this._inputElementValue;
      }
    }

    _filterChanged(filter, itemValuePath, itemLabelPath) {
      if (filter === undefined || itemValuePath === undefined || itemLabelPath === undefined) {
        return;
      }
      if (this.items) {
        this.filteredItems = this._filterItems(this.items, filter);
      } else {
        // With certain use cases (e. g., external filtering), `items` are
        // undefined. Filtering is unnecessary per se, but the filteredItems
        // observer should still be invoked to update focused item.
        this._filteredItemsChanged({path: 'filteredItems', value: this.filteredItems}, itemValuePath, itemLabelPath);
      }
    }

    _loadingChanged(loading) {
      if (loading) {
        this._focusedIndex = -1;
      }
    }

    _revertInputValue() {
      if (this.filter !== '') {
        this._inputElementValue = this.filter;
      } else {
        this._revertInputValueToValue();
      }
      this._clearSelectionRange();
    }

    _revertInputValueToValue() {
      if (this.allowCustomValue && !this.selectedItem) {
        this._inputElementValue = this.value;
      } else {
        this._inputElementValue = this._getItemLabel(this.selectedItem);
      }
    }

    _updateHasValue(hasValue) {
      if (hasValue) {
        this.setAttribute('has-value', '');
      } else {
        this.removeAttribute('has-value');
      }
    }

    _selectedItemChanged(selectedItem) {
      if (selectedItem === null || selectedItem === undefined) {
        if (this.filteredItems) {
          if (!this.allowCustomValue) {
            this.value = '';
          }

          this._updateHasValue(this.value !== '');
          this._inputElementValue = this.value;
        }
      } else {
        const value = this._getItemValue(selectedItem);
        if (this.value !== value) {
          this.value = value;
        }

        this._updateHasValue(true);
        this._inputElementValue = this._getItemLabel(selectedItem);

        // Could not be defined in 1.x because ready is called after all prop-setters
        if (this.inputElement) {
          this.inputElement.value = this._inputElementValue;
        }
      }

      this.$.overlay._selectedItem = selectedItem;
      if (this.filteredItems && this.$.overlay._items) {
        this._focusedIndex = this.filteredItems.indexOf(selectedItem);
      }
    }

    _valueChanged(value, oldVal) {
      if (value === '' && oldVal === undefined) { // initializing, no need to do anything (#554)
        return;
      }

      if (this._isValidValue(value)) {
        let item;
        if (this._getItemValue(this.selectedItem) !== value) {
          const valueIndex = this._indexOfValue(value, this.filteredItems);
          this.selectedItem = valueIndex >= 0 ? this.filteredItems[valueIndex] : null;
        } else {
          item = this.selectedItem;
        }

        if (!item && this.allowCustomValue) {
          this._inputElementValue = value;
        }

        this._updateHasValue(this.value !== '');
      } else {
        this.selectedItem = null;
      }
      // In the next _detectAndDispatchChange() call, the change detection should pass
      this._lastCommittedValue = undefined;
    }

    _detectAndDispatchChange() {
      if (this.value !== this._lastCommittedValue) {
        this.dispatchEvent(new CustomEvent('change', {bubbles: true}));
        this._lastCommittedValue = this.value;
      }
    }

    _itemsChanged(e, itemValuePath, itemLabelPath) {
      if (e.value === undefined || itemValuePath === undefined || itemLabelPath === undefined) {
        return;
      }
      if (e.path === 'items' || e.path === 'items.splices') {
        this.filteredItems = this.items ? this.items.slice(0) : this.items;

        const valueIndex = this._indexOfValue(this.value, this.items);
        this._focusedIndex = valueIndex;

        const item = valueIndex > -1 && this.items[valueIndex];
        if (item) {
          this.selectedItem = item;
        }
      }
    }

    _filteredItemsChanged(e, itemValuePath, itemLabelPath) {
      if (e.value === undefined || itemValuePath === undefined || itemLabelPath === undefined) {
        return;
      }
      if (e.path === 'filteredItems' || e.path === 'filteredItems.splices') {
        this._setOverlayItems(this.filteredItems);

        this._focusedIndex = this.opened ?
          this.$.overlay.indexOfLabel(this.filter) :
          this._indexOfValue(this.value, this.filteredItems);

        // async needed to reposition correctly after filtering
        // (especially when aligned on top of input)
        setTimeout(() => {
          this.$.overlay.$.dropdown.notifyResize();
          this.$.overlay.updateViewportBoundaries();
          this.$.overlay.ensureItemsRendered();
          this.$.overlay._selector.notifyResize();
          Polymer.flush && Polymer.flush();
        }, 1);
      }
    }

    _filterItems(arr, filter) {
      if (!arr) {
        return arr;
      }

      return arr.filter(item => {
        filter = filter ? filter.toString().toLowerCase() : '';
        // Check if item contains input value.
        return this._getItemLabel(item).toString().toLowerCase().indexOf(filter) > -1;
      });
    }

    _setOverlayItems(items) {
      this.$.overlay.set('_items', items);

      this.$.overlay.$.dropdown.notifyResize();
    }

    _indexOfValue(value, items) {
      if (items && this._isValidValue(value)) {
        for (let i = 0; i < items.length; i++) {
          if (this._getItemValue(items[i]) === value) {
            return i;
          }
        }
      }

      return -1;
    }

    /**
     * Checks if the value is supported as an item value in this control.
     *
     * @return {boolean}
     */
    _isValidValue(value) {
      return value !== undefined && value !== null;
    }

    _overlaySelectedItemChanged(e) {
      if (this.selectedItem !== e.detail.item) {
        this.selectedItem = e.detail.item;
      }

      if (this.opened) {
        this.close();
      }

      // stop this private event from leaking outside.
      e.stopPropagation();
    }


    /**
     * 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 the `checkValidity` method for custom validations.
     */
    checkValidity() {
      if (this.inputElement.validate) {
        return this.inputElement.validate();
      }
    }

    get _instanceProps() {
      return {
        item: true,
        index: true,
        selected: true,
        focused: true
      };
    }

    _ensureTemplatized() {
      if (!this._TemplateClass) {
        const tpl = this.querySelector('template');
        if (tpl) {
          this._TemplateClass = Polymer.Templatize.templatize(tpl, this, {
            instanceProps: this._instanceProps,
            forwardHostProp: function(prop, value) {
              const items = this.$.overlay._selector.querySelectorAll('vaadin-combo-box-item');
              Array.prototype.forEach.call(items, item => {
                if (item._itemTemplateInstance) {
                  item._itemTemplateInstance.set(prop, value);
                  item._itemTemplateInstance.notifyPath(prop, value, true);
                }
              });
            }
          });
        }
      }
    }

    _preventInputBlur() {
      if (this._toggleElement) {
        this._toggleElement.addEventListener('click', this._preventDefault);
      }
      if (this._clearElement) {
        this._clearElement.addEventListener('click', this._preventDefault);
      }
    }

    _restoreInputBlur() {
      if (this._toggleElement) {
        this._toggleElement.removeEventListener('click', this._preventDefault);
      }
      if (this._clearElement) {
        this._clearElement.removeEventListener('click', this._preventDefault);
      }
    }

    _preventDefault(e) {
      e.preventDefault();
    }

    _stopPropagation(e) {
      e.stopPropagation();
    }

    /**
     * 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 value changes.
     * To comply with https://developer.mozilla.org/en-US/docs/Web/Events/change
     * @event change
     */
  };
</script>