vaadin-combo-box.html

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

<!--
`<vaadin-combo-box>` is a combo box element combining a dropdown list with an
input field for filtering the list of items. If you want to replace the default
input field with a custom implementation, you should use the
[`<vaadin-combo-box-light>`](#vaadin-combo-box-light) element.

Items in the dropdown list must be provided as a list of `String` values.
Defining the items is done using the `items` property, which can be assigned
with data-binding, using an attribute or directly with the JavaScript property.

```html
<vaadin-combo-box
    label="Fruit"
    items="[[data]]">
</vaadin-combo-box>
```

```js
combobox.items = ['apple', 'orange', 'banana'];
```

When the selected `value` is changed, a `value-changed` event is triggered.

This element is also extended with the `IronFormElementBehavior` to
enable usage within an `iron-form`.

### Item Template

`<vaadin-combo-box>` supports using custom item template provided in the light
DOM:

```html
<vaadin-combo-box items='[{"label": "Hydrogen", "value": "H"}]'>
  <template>
    [[index]]: [[item.label]] <b>[[item.value]</b>
  </template>
</vaadin-combo-box>
```

The following properties are available for item template bindings:

Property name | Type | Description
--------------|------|------------
`index`| Number | Index of the item in the `items` array
`item` | String or Object | The item reference
`selected` | Boolean | True when item is selected
`focused` | Boolean | True when item is focused

See the [Item Template Live Demos](demo/item-template.html) for more examples.

### Styling
There are custom properties and mixins you can use to style the component:

Custom property | Description | Default
----------------|-------------|-------------
`--vaadin-combo-box-overlay-max-height` | Property that determines the max height of overlay | `65vh`

@element vaadin-combo-box
@demo demo/index.html
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-input/iron-input.html">
<link rel="import" href="../iron-validatable-behavior/iron-validatable-behavior.html">
<link rel="import" href="../iron-a11y-announcer/iron-a11y-announcer.html">
<link rel="import" href="../paper-input/paper-input-container.html">
<link rel="import" href="../paper-input/paper-input-error.html">
<link rel="import" href="../paper-icon-button/paper-icon-button.html">
<link rel="import" href="vaadin-combo-box-behavior.html">
<link rel="import" href="vaadin-combo-box-overlay.html">
<link rel="import" href="vaadin-combo-box-shared-styles.html">
<link rel="import" href="vaadin-combo-box-icons.html">

<dom-module id="vaadin-combo-box">
  <template>
    <style include="vaadin-combo-box-shared-styles">
      :host {
        display: block;
      }

      :host > #overlay {
        display: none;
      }

      paper-input-container {
        position: relative;
        padding: 0;
      }

      paper-icon-button.toggle-button,
      :host ::content paper-icon-button.toggle-button {
        position: absolute;
        top: 10px;
        right: 8px;
        margin: 0;
        padding: 0;
        width: 6px;
        height: 4px;
        line-height: 0;
        color: #676767;
        cursor: pointer;
      }

      paper-input-container paper-icon-button:hover,
      paper-input-container ::content paper-icon-button:hover,
      :host([opened]) paper-input-container paper-icon-button,
      :host([opened]) paper-input-container ::content paper-icon-button {
        color: rgba(0, 0, 0, .54);
      }

      :host([opened]) paper-input-container ::content paper-icon-button:hover,
      :host([opened]) paper-input-container paper-icon-button:hover {
        color: rgba(0, 0, 0, .86);
      }

      :host([opened]) paper-input-container {
        /* Keep the paper-input-container above the dropdown. */
        z-index: 20;
      }

      #input::-ms-clear {
        display: none;
      }

      #input {
        box-sizing: border-box;
        color: #444444;
        font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
        font-size: 12px;
        padding-left: 8px;
        padding-right: 8px;
      }

      #input::-webkit-input-placeholder { /* Chrome/Opera/Safari */
        color:  #444444;
        font-size: 10px;
      }
      #input::-moz-placeholder { /* Firefox 19+ */
        color:  #444444;
        font-size: 10px;
      }
      #input:-ms-input-placeholder { /* IE 10+ */
        color:  #444444;
        font-size: 10px;
      }
      #input:-moz-placeholder { /* Firefox 18- */
        color:  #444444;
        font-size: 10px;
      }

      :host([opened][has-value]) #input {
        margin-right: -32px;
      }

      paper-input-container {
        --paper-input-container-underline: {
          display: none;
        };
      }
      paper-input-container {
        --paper-input-container-underline-focus: {
          display: none
        };
      }

    </style>

    <paper-input-container
          id="inputContainer"
          disabled$="[[disabled]]"
          no-label-float="[[noLabelFloat]]"
          always-float-label="[[_computeAlwaysFloatLabel(alwaysFloatLabel,placeholder)]]"
          auto-validate$="[[autoValidate]]"
          invalid="[[invalid]]">
      <label on-down="_preventDefault" id="label" hidden$="[[!label]]" aria-hidden="true" on-tap="_openAsync">[[label]]</label>

      <content select="[prefix]"></content>

      <input
          is="iron-input"
          id="input"
          type="text"
          role="combobox"
          autocomplete="off"
          autocapitalize="none"
          bind-value="{{_inputElementValue}}"
          aria-label$="[[label]]"
          aria-expanded$="[[_getAriaExpanded(opened)]]"
          aria-autocomplete="list"
          disabled$="[[disabled]]"
          invalid="{{invalid}}"
          prevent-invalid-input="[[preventInvalidInput]]"
          allowed-pattern="[[allowedPattern]]"
          pattern$="[[pattern]]"
          required$="[[required]]"
          autofocus$="[[autofocus]]"
          inputmode$="[[inputmode]]"
          name$="[[name]]"
          placeholder$="[[placeholder]]"
          readonly$="[[readonly]]"
          size$="[[size]]"
          on-input="_inputValueChanged"
          on-blur="_onBlur"
          on-change="_stopPropagation"
          key-event-target>

      <content select="[suffix]"></content>

      <content select=".toggle-button">
        <paper-icon-button
            noink
            id="toggleIcon"
            tabindex="-1"
            src="images/down-arrow.svg"
            aria-label="Toggle"
            aria-expanded$="[[_getAriaExpanded(opened)]]"
            class="toggle-button rotate-on-open">
        </paper-icon-button>
      </content>

      <template is="dom-if" if="[[errorMessage]]">
        <paper-input-error>[[errorMessage]]</paper-input-error>
      </template>
    </paper-input-container>

    <vaadin-combo-box-overlay
        id="overlay"
        opened$=[[opened]]
        position-target="[[_getPositionTarget()]]"
        _focused-index="[[_focusedIndex]]"
        _item-label-path="[[itemLabelPath]]"
        on-down="_onOverlayDown"
        loading="[[loading]]"
        on-mousedown="_preventDefault"
        vertical-offset="-2">
    </vaadin-combo-box-overlay>
  </template>
</dom-module>

<script>
  Polymer({
    is: 'vaadin-combo-box',

    behaviors: [
      Polymer.IronValidatableBehavior,
      vaadin.elements.combobox.ComboBoxBehavior
    ],

    properties: {
      /**
       * The label for this element.
       */
      label: {
        type: String,
        reflectToAttribute: true
      },

      /**
       * Set to true to disable the floating label.
       */
      noLabelFloat: {
        type: Boolean,
        value: false
      },

      /**
       * Set to true to always float the label.
       */
      alwaysFloatLabel: {
        type: Boolean,
        value: false
      },

      /**
       * Set to true to auto-validate the input value.
       */
      autoValidate: {
        type: Boolean,
        value: false
      },

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

      /**
       * Set to true to prevent the user from entering invalid input.
       */
      preventInvalidInput: {
        type: Boolean
      },

      /**
       * Set this to specify the pattern allowed by `preventInvalidInput`.
       */
      allowedPattern: {
        type: String
      },

      /**
       * A pattern to validate the `input` with.
       */
      pattern: {
        type: String
      },

      /**
       * Set to true to mark the input as required.
       */
      required: {
        type: Boolean,
        value: false
      },

      /**
       * The error message to display when the input is invalid.
       */
      errorMessage: {
        type: String
      },

      autofocus: {
        type: Boolean
      },

      inputmode: {
        type: String
      },

      name: {
        type: String
      },

      /**
       * A placeholder string in addition to the label. If this is set, the label will always float.
       */
      placeholder: {
        type: String,
        // need to set a default so _computeAlwaysFloatLabel is run
        value: ''
      },

      readonly: {
        type: Boolean,
        value: false
      },

      size: {
        type: Number
      }

    },

    attached: function() {
      this._setInputElement(this.$.input);

      // Use the default toggle/clear or one replaced in light DOM.
      this._toggleElement = Polymer.dom(this).querySelector('.toggle-button') || this.$.toggleIcon;
      this._preventInputBlur();
    },

    detached: function() {
      this._restoreInputBlur();
    },

    _computeAlwaysFloatLabel: function(alwaysFloatLabel, placeholder) {
      return placeholder || alwaysFloatLabel;
    },

    _getPositionTarget: function() {
      return this.$.inputContainer;
    },

    _getAriaExpanded: function(value) {
      return value.toString();
    }
  });

</script>