feat(forms): new b-form-datalist helper component (#2899)

tmorehouse · web-flow · commit e9a8e8547b12 · 2019-03-22T16:20:05.000-03:00
diff --git a/src/components/form-input/README.md b/src/components/form-input/README.md
@@ -448,6 +448,10 @@ chosen, or new values to be entered.
 <!-- b-form-input-datalist.vue -->
 ```
 
+BootstrapVue provides the form helper component
+[`<b-form-datalist>`](/docs/components/form/#datalist-helper) for quickly creating a `<datalist>`
+from an array of options.
+
 **Notes:**
 
 - Datalists work in conjunction with the browser's built in auto-complete, displaying datalist
diff --git a/src/components/form/README.md b/src/components/form/README.md
@@ -177,6 +177,7 @@ See also:
 - `<b-form-text>` Help text blocks for inputs
 - `<b-form-invalid-feedback>` Invalid feedback text blocks for input `invalid` states
 - `<b-form-valid-feedback>` Valid feedback text blocks for input `valid` states
+- `<b-form-datalist>` Create `<datalist>` for use with `<b-form-input>` or plain `<input>`
 
 See also: [`<b-form-group>`](/docs/components/form-group) Form input wrapper to generate form-groups
 that support labels, help text and feedback
@@ -262,6 +263,41 @@ or the `force-show` prop to display the feedback.
 <!-- form-feedback-example.vue -->
 ```
 
+### Datalist helper
+
+For broswers that support
+[`<datalist>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) elements,
+the `<b-form-datalist>` helper component will allow you to quickly create a `<datalist>` and
+child `<option>` elements via an array passed to the `options` prop.
+
+```html
+<template>
+  <label for="input-with-list">Input with datalist</label>
+  <b-form-input list="input-list" id="input-with-list"></b-form-input>
+  <b-form-datalist id="input-list" :options="options"></b-form-datalist>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      options: ['Apple', 'Banana', 'Grape', 'Kiwi', 'Orange']
+    }
+  }
+}
+</script>
+
+<!-- form-datalist-example.vue -->
+```
+
+`<b-form-datalist>` is also available via the shorter alias of `<b-datalist>`.
+
+See also:
+
+- [`<b-form-input> datalist`](/docs/components/form-input#datalist-support) for datalist usage.
+- [`<b-form-select> options`](/docs/components/form-select#options-property) for more information on
+  the `options` array format.
+
 ## Validation
 
 Disable browser native HTML5 validation by setting the `novalidate` prop to true on `<b-form>`.
diff --git a/src/components/form/form-datalist.js b/src/components/form/form-datalist.js
@@ -0,0 +1,25 @@
+import formOptionsMixin from '../../mixins/form-options'
+import { htmlOrText } from '../../utils/html'
+
+// @vue/component
+export default {
+  name: 'BFormDatalist',
+  mixins: [formOptionsMixin],
+  props: {
+    id: {
+      type: String,
+      default: null,
+      required: true
+    }
+  },
+  render(h) {
+    const options = this.formOptions.map((option, index) => {
+      return h('option', {
+        key: `option_${index}_opt`,
+        attrs: { disabled: option.disabled },
+        domProps: { ...htmlOrText(option.html, option.text), value: option.value }
+      })
+    })
+    return h('datalist', { attrs: { id: this.id } }, [options, this.$slots.default])
+  }
+}
diff --git a/src/components/form/form-datalist.spec.js b/src/components/form/form-datalist.spec.js
@@ -0,0 +1,57 @@
+import Datalist from './form-datalist'
+import { mount } from '@vue/test-utils'
+
+describe('form-datalist', () => {
+  it('has root element datalist', async () => {
+    const wrapper = mount(Datalist, {
+      propsData: {
+        id: 'testlist'
+      }
+    })
+    expect(wrapper.is('datalist')).toBe(true)
+
+    wrapper.destroy()
+  })
+
+  it('has user supplied ID', async () => {
+    const wrapper = mount(Datalist, {
+      propsData: {
+        id: 'testlist'
+      }
+    })
+    expect(wrapper.attributes('id')).toBe('testlist')
+
+    wrapper.destroy()
+  })
+
+  it('has no oprion elements by default', async () => {
+    const wrapper = mount(Datalist, {
+      propsData: {
+        id: 'testlist'
+      }
+    })
+    expect(wrapper.findAll('option').length).toBe(0)
+
+    wrapper.destroy()
+  })
+
+  it('has options when options set', async () => {
+    const wrapper = mount(Datalist, {
+      propsData: {
+        id: 'testlist',
+        options: ['one', 'two']
+      }
+    })
+    const $options = wrapper.findAll('option')
+
+    expect($options.length).toBe(2)
+
+    expect($options.at(0).text()).toBe('one')
+    expect($options.at(1).text()).toBe('two')
+
+    expect($options.at(0).attributes('value')).toBe('one')
+    expect($options.at(1).attributes('value')).toBe('two')
+
+    wrapper.destroy()
+  })
+})
diff --git a/src/components/form/index.js b/src/components/form/index.js
@@ -1,4 +1,5 @@
 import BForm from './form'
+import BFormDatalist from './form-datalist'
 import BFormRow from './form-row'
 import BFormText from './form-text'
 import BFormInvalidFeedback from './form-invalid-feedback'
@@ -7,6 +8,8 @@ import { registerComponents } from '../../utils/plugins'
 
 const components = {
   BForm,
+  BFormDatalist,
+  BDatalist: BFormDatalist,
   BFormRow,
   BFormText,
   BFormInvalidFeedback,
diff --git a/src/components/form/package.json b/src/components/form/package.json
@@ -23,7 +23,11 @@
       "BFormText",
       "BFormInvalidFeedback",
       "BFormValidFeedback",
-      "BFormRow"
+      "BFormRow",
+      {
+        "component": "BFormDatalist",
+        "aliases": ["BDatalist"]
+      }
     ]
   }
 }

Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,11 @@`
`23`	`23`	`"BFormText",`
`24`	`24`	`"BFormInvalidFeedback",`
`25`	`25`	`"BFormValidFeedback",`
`26`		`- "BFormRow"`
	`26`	`+ "BFormRow",`
	`27`	`+ {`
	`28`	`+ "component": "BFormDatalist",`
	`29`	`+ "aliases": ["BDatalist"]`
	`30`	`+ }`
`27`	`31`	`]`
`28`	`32`	`}`
`29`	`33`	`}`