feat(b-form-select): add group/tree support and dedicated option and …

…option-group components (closes #3222) (#4267) * feat(b-form-select): add group/tree support and dedicated option and option-group components * Improve option property handling * Update package.json * Nested `<optgroup>`'s is invalid HTML... * remove duplicate import * Update index.js * Update mixin-options.js * Update form-datalist.spec.js * Create form-select-option.spec.js * Update form-options.js * Create form-select-option-group.spec.js * Update form-select.spec.js * Improve warnings * Update form-select.spec.js * Update form-select.spec.js * Update README.md * Update README.md * Update package.json * Update _slug.js * Update componentdoc.vue * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md
bootstrap-vue · Nov 18, 2019 · f1ed017 · f1ed017
1 parent f3f5279
commit f1ed017
Show file tree

Hide file tree

Showing 27 changed files with 875 additions and 115 deletions.
diff --git a/docs/components/componentdoc.vue b/docs/components/componentdoc.vue
@@ -5,6 +5,7 @@
         <anchored-heading :id="`comp-ref-${componentName}`" level="3">
           <code class="notranslate bigger" translate="no">{{ tag }}</code>
         </anchored-heading>
+        <b-badge v-if="version" variant="success">v{{ version }}+</b-badge>
         <b-badge
           v-if="componentFunctional"
           variant="secondary"
@@ -340,6 +341,10 @@ export default {
     aliases: {
       type: Array,
       default: () => []
+    },
+    version: {
+      type: String,
+      default: null
     }
   },
   computed: {

diff --git a/docs/pages/docs/components/_slug.js b/docs/pages/docs/components/_slug.js
@@ -33,9 +33,9 @@ export default {
       h(AnchoredHeading, { props: { id: 'component-reference' } }, 'Component reference'),
       // Component reference information
       ...this.meta.components.map(
-        ({ component, events, rootEventListeners, slots, aliases, props: propsMeta }) =>
+        ({ component, events, rootEventListeners, slots, aliases, props: propsMeta, version }) =>
           h(Componentdoc, {
-            props: { component, events, rootEventListeners, slots, aliases, propsMeta }
+            props: { component, events, rootEventListeners, slots, aliases, propsMeta, version }
           })
       ),
       // Component importing information

diff --git a/src/components/form-checkbox/README.md b/src/components/form-checkbox/README.md
@@ -89,8 +89,124 @@ named slot `first`.
 
 ## Checkbox group options array
 
-Please see the [`<b-form-select>` `options` prop](/docs/components/form-select#options-property)
-docs for details on the formats and helper props associated with `options`.
+`options` can be an array of strings or objects. Available fields:
+
+- **`value`** The selected value which will be set on `v-model`
+- **`disabled`** Disables item for selection
+- **`text`** Display text, or **`html`** Display basic inline html
+
+`value` can be a string, number, or simple object. Avoid using complex types in values.
+
+If both `html` and `text` are provided, `html` will take precedence. Only basic/native HTML is
+supported in the `html` field (components will not work). Note that not all browsers will render
+inline html (i.e. `<i>`, `<strong>`, etc) inside `<option>` elements of a `<select>`.
+
+<p class="alert alert-danger">
+  <strong>Be cautious</strong> of placing user supplied content in the <code>html</code> field,
+  as it may make you vulnerable to
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/Cross-site_scripting">
+  <abbr title="Cross Site Scripting Attacks">XSS attacks</abbr></a>, if you do not first
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/HTML_sanitization">sanitize</a> the
+  user supplied string.
+</p>
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = ['A', 'B', 'C', { text: 'D', value: { d: 1 }, disabled: true }, 'E', 'F']
+```
+
+If an array entry is a string, it will be used for both the generated `value` and `text` fields.
+
+You can mix using strings and [objects](#options-as-an-array-of-objects) in the array.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'A', value: 'A', disabled: false },
+  { text: 'B', value: 'B', disabled: false },
+  { text: 'C', value: 'C', disabled: false },
+  { text: 'D', value: { d: 1 }, disabled: true },
+  { text: 'E', value: 'E', disabled: false },
+  { text: 'F', value: 'F', disabled: false }
+]
+```
+
+### Options as an array of objects
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first' },
+  { text: 'Item 2', value: 'second' },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4' },
+  { text: 'Item 5', value: { foo: 'bar', baz: true } }
+]
+```
+
+If `value` is missing, then `text` will be used as both the `value` and `text` fields. If you use
+the `html` property, you **must** supply a `value` property.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first', disabled: false },
+  { text: 'Item 2', value: 'second', disabled: false },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4', value: 'Item 4', disabled: false },
+  { text: 'Item 5', value: 'E', disabled: false }
+]
+```
+
+### Changing the option field names
+
+If you want to customize the field property names (for example using `name` field for display
+`text`) you can easily change them by setting the `text-field`, `html-field`, `value-field`, and
+`disabled-field` props to a string that contains the property name you would like to use:
+
+```html
+<template>
+  <div>
+    <b-form-checkbox-group
+      v-model="selected"
+      :options="options"
+      class="mb-3"
+      value-field="item"
+      text-field="name"
+      disabled-field="notEnabled"
+    ></b-form-checkbox-group>
+    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: [],
+        options: [
+          { item: 'A', name: 'Option A' },
+          { item: 'B', name: 'Option B' },
+          { item: 'D', name: 'Option C', notEnabled: true },
+          { item: { d: 1 }, name: 'Option D' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-checkbox-group-options-fields.vue -->
+```
 
 ## Inline and stacked checkboxes
 

diff --git a/src/components/form-file/form-file.js b/src/components/form-file/form-file.js
@@ -12,6 +12,9 @@ import normalizeSlotMixin from '../../mixins/normalize-slot'
 
 const NAME = 'BFormFile'
 
+const VALUE_EMPTY_DEPRECATED_MSG =
+  'Setting "value"/"v-model" to an empty string for reset is deprecated. Set to "null" instead.'
+
 // @vue/component
 export const BFormFile = /*#__PURE__*/ Vue.extend({
   name: NAME,
@@ -32,9 +35,7 @@ export const BFormFile = /*#__PURE__*/ Vue.extend({
       validator: val => {
         /* istanbul ignore next */
         if (val === '') {
-          warn(
-            `${NAME} - setting value/v-model to an empty string for reset is deprecated. Set to 'null' instead`
-          )
+          warn(VALUE_EMPTY_DEPRECATED_MSG, NAME)
           return true
         }
         return (

diff --git a/src/components/form-radio/README.md b/src/components/form-radio/README.md
@@ -130,8 +130,124 @@ To have them appear _above_ the inputs generated by `options`, place them in the
 
 ## Radio group options array
 
-Please see the [`<b-form-select>` `options` prop](/docs/components/form-select#options-property)
-docs for details on the formats and helper props associated with `options`.
+`options` can be an array of strings or objects. Available fields:
+
+- **`value`** The selected value which will be set on `v-model`
+- **`disabled`** Disables item for selection
+- **`text`** Display text, or **`html`** Display basic inline html
+
+`value` can be a string, number, or simple object. Avoid using complex types in values.
+
+If both `html` and `text` are provided, `html` will take precedence. Only basic/native HTML is
+supported in the `html` field (components will not work). Note that not all browsers will render
+inline html (i.e. `<i>`, `<strong>`, etc) inside `<option>` elements of a `<select>`.
+
+<p class="alert alert-danger">
+  <strong>Be cautious</strong> of placing user supplied content in the <code>html</code> field,
+  as it may make you vulnerable to
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/Cross-site_scripting">
+  <abbr title="Cross Site Scripting Attacks">XSS attacks</abbr></a>, if you do not first
+  <a class="alert-link" href="https://en.wikipedia.org/wiki/HTML_sanitization">sanitize</a> the
+  user supplied string.
+</p>
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = ['A', 'B', 'C', { text: 'D', value: { d: 1 }, disabled: true }, 'E', 'F']
+```
+
+If an array entry is a string, it will be used for both the generated `value` and `text` fields.
+
+You can mix using strings and [objects](#options-as-an-array-of-objects) in the array.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'A', value: 'A', disabled: false },
+  { text: 'B', value: 'B', disabled: false },
+  { text: 'C', value: 'C', disabled: false },
+  { text: 'D', value: { d: 1 }, disabled: true },
+  { text: 'E', value: 'E', disabled: false },
+  { text: 'F', value: 'F', disabled: false }
+]
+```
+
+### Options as an array of objects
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first' },
+  { text: 'Item 2', value: 'second' },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4' },
+  { text: 'Item 5', value: { foo: 'bar', baz: true } }
+]
+```
+
+If `value` is missing, then `text` will be used as both the `value` and `text` fields. If you use
+the `html` property, you **must** supply a `value` property.
+
+Internally, BootstrapVue will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+const options = [
+  { text: 'Item 1', value: 'first', disabled: false },
+  { text: 'Item 2', value: 'second', disabled: false },
+  { html: '<b>Item</b> 3', value: 'third', disabled: true },
+  { text: 'Item 4', value: 'Item 4', disabled: false },
+  { text: 'Item 5', value: 'E', disabled: false }
+]
+```
+
+### Changing the option field names
+
+If you want to customize the field property names (for example using `name` field for display
+`text`) you can easily change them by setting the `text-field`, `html-field`, `value-field`, and
+`disabled-field` props to a string that contains the property name you would like to use:
+
+```html
+<template>
+  <div>
+    <b-form-radio-group
+      v-model="selected"
+      :options="options"
+      class="mb-3"
+      value-field="item"
+      text-field="name"
+      disabled-field="notEnabled"
+    ></b-form-radio-group>
+    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        selected: 'A',
+        options: [
+          { item: 'A', name: 'Option A' },
+          { item: 'B', name: 'Option B' },
+          { item: 'D', name: 'Option C', notEnabled: true },
+          { item: { d: 1 }, name: 'Option D' }
+        ]
+      }
+    }
+  }
+</script>
+
+<!-- b-form-radio-group-options-fields.vue -->
+```
 
 ## Radio value and v-model