docs(BFormSelect): Refactor (bootstrap-vue-next#2460)

* docs(BFormSelect): Refactor examples

* docs: Normalize options docs between checkbox, radio and select

* docs: Factor out options property documentation

* docs: remnove unused code fragments

apps/docs/src/data/components/formSelect.data.ts

@@ -113,7 +113,6 @@ export default {
       component: 'BFormSelectOption',
       styleSpec: {kind: StyleKind.Tag, value: 'option'},
       sourcePath: '/BFormSelect/BFormSelectOption.vue',
-      emits: [],
       props: {
         '': {
           value: {
@@ -154,7 +153,6 @@ export default {
           ),
         } satisfies Record<keyof BvnComponentProps['BFormSelectOptionGroup'], PropertyReference>,
       },
-      emits: [],
       slots: [
         {
           name: 'first',

apps/docs/src/docs/components/_options.md

@@ -0,0 +1,46 @@
+# Options
+
+## Options Property
+
+`options` can be an array of strings or objects, or a key-value object. Available fields:
+
+- **`value`** The selected value which will be set on `v-model`
+- **`disabled`** Disables item for selection
+- **`text`** Display text
+
+`value` can be a string, number, or simple object. Avoid using complex types in values.
+
+::: info NOTE
+The BootstrapVue field `html` on the `options` object has been deprecated. See our
+[Migration Guide](/docs/migration-guide/#v-html) for details.
+:::
+
+### Options as an array
+
+<<< FRAGMENT ./demo/OptionsArray.ts#snippet{ts}
+
+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, BootstrapVueNext will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<<< FRAGMENT ./demo/OptionsObjectArray.ts#snippet{ts}
+
+### Options as an array of objects
+
+<<< FRAGMENT ./demo/OptionsObjectArrayRaw.ts#snippet{ts}
+
+If `value` is missing, then `text` will be used as both the `value` and `text` fields.
+
+Internally, BootstrapVueNext will convert the above array to the following array (the
+[array of objects](#options-as-an-array-of-objects)) format:
+
+<<< FRAGMENT ./demo/OptionsObjectArrayNormalized.ts#snippet{ts}
+
+### 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`, `value-field`, and
+`disabled-field` props to a string that contains the property name you would like to use:

apps/docs/src/docs/components/demo/RadioObjectArrayRaw.ts → apps/docs/src/docs/components/demo/OptionsGroups.ts

@@ -3,8 +3,10 @@
 const options = [
   {text: 'Item 1', value: 'first'},
   {text: 'Item 2', value: 'second'},
-  {text: 'Item 3', value: 'third', disabled: true},
-  {text: 'Item 4'},
+  {
+    label: 'Grouped options',
+    options: [{text: 'Item< 3', value: 'third', disabled: true}, {text: 'Item 4'}],
+  },
   {text: 'Item 5', value: {foo: 'bar', baz: true}},
 ]
 // #endregion snippet

apps/docs/src/docs/components/demo/SelectCustomFields.vue

@@ -0,0 +1,27 @@
+<template>
+  <BFormSelect
+    v-model="selected"
+    :options="exFieldNamesOptions"
+    class="mb-3"
+    value-field="item"
+    text-field="name"
+    disabled-field="notEnabled"
+  />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const exFieldNamesOptions = [
+  {item: 'A', name: 'Option A'},
+  {item: 'B', name: 'Option B'},
+  {item: 'D', name: 'Option C', notEnabled: true},
+  {item: {d: 1}, name: 'Option D'},
+]
+
+const selected = ref('A')
+</script>

apps/docs/src/docs/components/demo/SelectMultiValue.vue

@@ -0,0 +1,23 @@
+<template>
+  <BFormSelect v-model="selected" :options="exMultiOptions" multiple :select-size="4" />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const exMultiOptions = [
+  {value: 'a', text: 'This is First option'},
+  {value: 'b', text: 'Default Selected Option'},
+  {value: 'c', text: 'This is another option'},
+  {value: 'd', text: 'This one is disabled', disabled: true},
+  {value: 'e', text: 'This is option e'},
+  {value: 'f', text: 'This is option f'},
+  {value: 'g', text: 'This is option g'},
+]
+
+const selected = ref(['b'])
+</script>

apps/docs/src/docs/components/demo/SelectOptionsGroup.vue

@@ -0,0 +1,26 @@
+<template>
+  <BFormSelect v-model="selected" :options="ex1GroupOptions" />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const ex1GroupOptions = [
+  {value: null, text: 'Please select an option'},
+  {value: 'a', text: 'This is First option'},
+  {value: 'b', text: 'Selected Option', disabled: true},
+  {
+    label: 'Grouped options',
+    options: [
+      {value: {C: '3PO'}, text: 'Option with object value'},
+      {value: {R: '2D2'}, text: 'Another option with object value'},
+    ],
+  },
+]
+
+const selected = ref()
+</script>

apps/docs/src/docs/components/demo/SelectOptionsManual.vue

@@ -0,0 +1,21 @@
+<template>
+  <BFormSelect v-model="selected">
+    <BFormSelectOption :value="null">Please select an option</BFormSelectOption>
+    <BFormSelectOption value="a">Option A</BFormSelectOption>
+    <BFormSelectOption value="b" disabled>Option B (disabled)</BFormSelectOption>
+    <BFormSelectOptionGroup label="Grouped options">
+      <BFormSelectOption :value="{C: '3PO'}">Option with object value</BFormSelectOption>
+      <BFormSelectOption :value="{R: '2D2'}">Another option with object value</BFormSelectOption>
+    </BFormSelectOptionGroup>
+  </BFormSelect>
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const selected = ref(null)
+</script>

apps/docs/src/docs/components/demo/SelectOptionsMixed.vue

@@ -0,0 +1,27 @@
+<template>
+  <BFormSelect v-model="selected" :options="exFirstSlotOptions" class="mb-3">
+    <!-- This slot appears above the options from 'options' prop -->
+    <template #first>
+      <BFormSelectOption :value="null" disabled>-- Please select an option --</BFormSelectOption>
+    </template>
+
+    <!-- These options will appear after the ones from 'options' prop -->
+    <BFormSelectOption value="C">Option C</BFormSelectOption>
+    <BFormSelectOption value="D">Option D</BFormSelectOption>
+  </BFormSelect>
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const exFirstSlotOptions = [
+  {value: 'A', text: 'Option A (from options prop)'},
+  {value: 'B', text: 'Option B (from options prop)'},
+]
+
+const selected = ref(null)
+</script>

apps/docs/src/docs/components/demo/SelectOverview.vue

@@ -0,0 +1,24 @@
+```vue
+<template>
+  <BFormSelect v-model="selected" :options="ex1Options" />
+
+  <BFormSelect v-model="selected" :options="ex1Options" size="sm" class="mt-3" />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const ex1Options = [
+  {value: null, text: 'Please select an option'},
+  {value: 'a', text: 'This is First option'},
+  {value: 'b', text: 'Selected Option'},
+  {value: {C: '3PO'}, text: 'This is an option with object value'},
+  {value: 'd', text: 'This one is disabled', disabled: true},
+]
+
+const selected = ref(null)
+</script>

apps/docs/src/docs/components/demo/SelectSingleValue.vue

@@ -0,0 +1,21 @@
+<template>
+  <BFormSelect v-model="selected" :options="ex1Options" />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const ex1Options = [
+  {value: null, text: 'Please select an option'},
+  {value: 'a', text: 'This is First option'},
+  {value: 'b', text: 'Selected Option'},
+  {value: {C: '3PO'}, text: 'This is an option with object value'},
+  {value: 'd', text: 'This one is disabled', disabled: true},
+]
+
+const selected = ref()
+</script>

apps/docs/src/docs/components/demo/SelectSizing.vue

@@ -0,0 +1,21 @@
+<template>
+  <BFormSelect v-model="selected" :options="ex1Options" :select-size="4" />
+
+  <div class="mt-3">
+    Selected: <strong>{{ selected }}</strong>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {ref} from 'vue'
+
+const ex1Options = [
+  {value: null, text: 'Please select an option'},
+  {value: 'a', text: 'This is First option'},
+  {value: 'b', text: 'Selected Option'},
+  {value: {C: '3PO'}, text: 'This is an option with object value'},
+  {value: 'd', text: 'This one is disabled', disabled: true},
+]
+
+const selected = ref()
+</script>

apps/docs/src/docs/components/form-checkbox.md

@@ -20,48 +20,9 @@ For cross browser consistency, `BFormCheckboxGroup` and `BFormCheckbox` use Boot
 
 <<< DEMO ./demo/CheckboxExample2.vue
 
-## Checkbox group options array
+## Options property
 
-`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
-
-`value` can be a string, number, or simple object. Avoid using complex types in values.
-
-<<< FRAGMENT ./demo/CheckboxArray.ts#snippet{ts}
-
-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, BootstrapVueNext will convert the above array to the following array (the
-[array of objects](#options-as-an-array-of-objects)) format:
-
-<<< FRAGMENT ./demo/CheckboxObjectArray.ts#snippet{ts}
-
-::: info NOTE
-The BootstrapVue field `html` on the `options` object has been deprecated. See our
-[Migration Guide](/docs/migration-guide/#v-html) for details.
-:::
-
-### Options as an array of objects
-
-<<< FRAGMENT ./demo/CheckboxObjectArrayRaw.ts#snippet{ts}
-
-If `value` is missing, then `text` will be used as both the `value` and `text` fields.
-
-Internally, BootstrapVueNext will convert the above array to the following array (the
-[array of objects](#options-as-an-array-of-objects)) format:
-
-<<< FRAGMENT ./demo/CheckboxObjectArrayNormalized.ts#snippet{ts}
-
-### 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`, `value-field`, and
-`disabled-field` props to a string that contains the property name you would like to use:
+<!--@include: ./_options.md{5,}-->
 
 <<< DEMO ./demo/CheckboxCustomFields.vue