feat: add helperText slot and property API (#227)

* feat: add helperText API

- Add helperText API supporting string and slotted content
- Add demos
- Add unit and visual tests

Fix #219

demo/select-basic-demos.html

@@ -40,6 +40,37 @@ <h3>Basic usage</h3>
       </template>
     </vaadin-demo-snippet>
 
+    <h3>Helper text</h3>
+    <p>Use the <code>helper-text</code> attribute or add content to the <code>helper</code> slot to set helper content.</p>
+    <vaadin-demo-snippet id="helper-text">
+      <template preserve-content>
+        <vaadin-select label="Label" value="Value" helper-text="Helper text">
+          <template>
+            <vaadin-list-box>
+              <vaadin-item>Option one</vaadin-item>
+              <vaadin-item>Option two</vaadin-item>
+            </vaadin-list-box>
+          </template>
+        </vaadin-select>
+
+        <vaadin-select label="Label" value="Value">
+          <template>
+            <vaadin-list-box>
+              <vaadin-item>Option one</vaadin-item>
+              <vaadin-item>Option two</vaadin-item>
+            </vaadin-list-box>
+          </template>
+          <span slot="helper">Helper text</span>
+        </vaadin-select>
+
+        <style>
+          vaadin-select:first-of-type {
+            margin-right: 200px;
+          }
+        </style>
+      </template>
+    </vaadin-demo-snippet>
+
     <h3>Disabled and read-only</h3>
     <vaadin-demo-snippet id="select-list-box-disabled-readonly" when-defined="vaadin-select">
       <template preserve-content>

demo/select-theme-variants-demos.html

@@ -57,6 +57,33 @@ <h3>Small size</h3>
       </template>
     </vaadin-demo-snippet>
 
+    <h3>Helper text position</h3>
+    <vaadin-demo-snippet id="helper-text-positions">
+      <template preserve-content>
+        <h4>Below the field</h4>
+        <vaadin-select label="Name" value="Jose" helper-text="Helper text below">
+          <template>
+            <vaadin-list-box>
+              <vaadin-item>Jose</vaadin-item>
+              <vaadin-item>Manolo</vaadin-item>
+              <vaadin-item>Pedro</vaadin-item>
+            </vaadin-list-box>
+          </template>
+        </vaadin-select>
+        <h4>Above the field</h4>
+        <vaadin-select label="Name" value="Jose" helper-text="Helper text above"
+          theme="helper-above-field">
+        <template>
+          <vaadin-list-box>
+            <vaadin-item>Jose</vaadin-item>
+            <vaadin-item>Manolo</vaadin-item>
+            <vaadin-item>Pedro</vaadin-item>
+          </vaadin-list-box>
+        </template>
+        </vaadin-select>
+      </template>
+    </vaadin-demo-snippet>
+
   </template>
   <script>
     class SelectThemeVariantsDemos extends DemoReadyEventEmitter(SelectDemo(Polymer.Element)) {

src/vaadin-select.html

@@ -58,9 +58,11 @@
         invalid="[[invalid]]"
         error-message="[[errorMessage]]"
         readonly$="[[readonly]]"
+        helper-text="[[helperText]]"
         theme$="[[theme]]"
       >
       <slot name="prefix" slot="prefix"></slot>
+      <slot name="helper" slot="helper">[[helperText]]</slot>
       <div part="value"></div>
       <div part="toggle-button" slot="suffix" role="button" aria-haspopup="listbox" aria-label="Toggle"></div>
     </vaadin-select-text-field>
@@ -294,6 +296,14 @@
               type: String
             },
 
+            /**
+             * String used for the helper text.
+             */
+            helperText: {
+              type: String,
+              value: ''
+            },
+
             /**
              * When present, it specifies that the element is read-only.
              * @type {boolean}

test/select-test.html

@@ -137,6 +137,14 @@
     </template>
   </test-fixture>
 
+  <test-fixture id="select-with-slotted-helper">
+    <template>
+      <vaadin-select>
+        <div slot="helper">foo</div>
+      </vaadin-select>
+    </template>
+  </test-fixture>
+
   <script>
     function arrowUp(target) {
       MockInteractions.keyDownOn(target, 38, [], 'ArrowUp');
@@ -720,6 +728,20 @@
         }
       });
 
+      describe('helper-text', () => {
+        it('should display the helper text when slotted helper available', () => {
+          const select = fixture(`select-with-slotted-helper`);
+          const evt = new CustomEvent('slotchange');
+          select.shadowRoot.querySelector('[name="helper"]').dispatchEvent(evt);
+          expect(select._inputElement.querySelector('[slot="helper"]').assignedNodes()[0].textContent).to.eql('foo');
+        });
+
+        it('should display the helper text when provided', () => {
+          select.helperText = 'Foo';
+          expect(select._inputElement.helperText).to.equal(select.helperText);
+        });
+      });
+
       describe('validation', () => {
         it('should set invalid to true when is required but there is no value', () => {
           expect(select.invalid).to.be.false;

test/visual/select.html

@@ -29,7 +29,7 @@
     .capture-block {
       display: inline-block;
       width: 800px;
-      height: 350px;
+      height: 400px;
     }
   </style>
 
@@ -53,6 +53,16 @@
       </template>
     </vaadin-select>
 
+    <br />
+
+    <vaadin-select label="With helper" placeholder="Placeholder"
+      helper-text="Helper text as string">
+    </vaadin-select>
+
+    <vaadin-select label="With helper" placeholder="Placeholder">
+      <span slot="helper">Helper text as slot</span>
+    </vaadin-select>
+
     <br/>
 
     <vaadin-select label="Item as value" placeholder="Placeholder" value="Html&nbsp;as&nbsp;Content">