docs(select): update select documentation (#1167)

oruga-ui · Jan 30, 2025 · e013598 · e013598
1 parent e0d17c6
commit e013598
Show file tree

Hide file tree

Showing 13 changed files with 273 additions and 89 deletions.
diff --git a/packages/docs/.vitepress/config.ts b/packages/docs/.vitepress/config.ts
@@ -66,7 +66,7 @@ export default defineConfig({
     appearance: false,
     themeConfig: {
         logo: "/logo.png",
-        outline: [2, 3],
+        outline: [2, 4],
         search: {
             provider: "local",
         },

diff --git a/packages/docs/.vitepress/theme/styles/vitepress.scss b/packages/docs/.vitepress/theme/styles/vitepress.scss
@@ -43,7 +43,7 @@ header .VPNavBar button {
 
 
 .main {
-    h1, h2, h3 {
+    h1, h2, h3, h4 {
         position: relative;
         margin: 0;
         line-height: 1.5em;
@@ -64,8 +64,12 @@ header .VPNavBar button {
     h3 {
         margin: 3rem 0 0;
         letter-spacing: -0.01em;
-        line-height: 1.5em;
-        font-size: 1.25em;
+        font-size: 1.3em;
+    }
+    h4 {
+        margin: 3rem 0 0;
+        letter-spacing: -0.01em;
+        font-size: 1.1em;
     }
 
     .header-anchor {
@@ -74,7 +78,7 @@ header .VPNavBar button {
         padding-right: 0.23em;
         font-weight: 500;
         opacity: 0;
-        transition: color .25s,opacity .25s;
+        transition: color .25s, opacity .25s;
     }
 
     h1:hover .header-anchor, h1 .header-anchor:focus,

diff --git a/packages/docs/components/Select.md b/packages/docs/components/Select.md
@@ -2,7 +2,7 @@
 
 <div class="vp-doc">
 
-> Select an item in a dropdown list. Use with Field to access all functionalities
+> Select an item in a list. Use with Field to access all functionalities.
 
 </div>
 
@@ -26,7 +26,7 @@
 
 ## Select component
 
-> Select an item in a dropdown list. Use with Field to access all functionalities
+> Select an item in a list. Use with Field to access all functionalities.
 
 ```html
 <o-select></o-select>

diff --git a/packages/oruga/src/components/notification/examples/index.vue b/packages/oruga/src/components/notification/examples/index.vue
@@ -33,8 +33,8 @@ import ProgrammaticallyCode from "./programmatically.vue?raw";
         <p>
             This component provides a programmatic interface that can be
             accessed by the
-            <a href="/documentation/composables.html"
-                ><code>useOruga()</code>
+            <a href="/documentation/composables.html">
+                <code>useOruga()</code>
             </a>
             composable.
         </p>

diff --git a/packages/oruga/src/components/select/Select.vue b/packages/oruga/src/components/select/Select.vue
@@ -25,7 +25,7 @@ import { injectField } from "../field/fieldInjection";
 import type { SelectProps } from "./props";
 
 /**
- * Select an item in a dropdown list. Use with Field to access all functionalities
+ * Select an item in a list. Use with Field to access all functionalities.
  * @displayName Select
  * @style _select.scss
  */

diff --git a/packages/oruga/src/components/select/examples/base.vue b/packages/oruga/src/components/select/examples/base.vue
@@ -1,57 +1,58 @@
-<script setup lang="ts">
-import type { OptionsProp } from "@oruga-ui/oruga-next";
-
-const options: OptionsProp<string> = [
-    { label: "Flint", value: "flint" },
-    { label: "Silver", value: "silver" },
-    { label: "Vane", value: "vane" },
-    { label: "Billy", value: "billy" },
-    { label: "Jack", value: "silver", attrs: { disabled: true } },
-];
-</script>
-
 <template>
     <section>
-        <o-field label="Simple">
+        <o-field label="Required">
             <o-select placeholder="Select a name" required>
                 <option value="flint">Flint</option>
                 <option value="silver">Silver</option>
+                <option value="vane">Vane</option>
+                <option value="Billy">billy</option>
+            </o-select>
+        </o-field>
+
+        <o-field label="Rounded">
+            <o-select placeholder="Select a character" rounded>
+                <option value="flint">Flint</option>
+                <option value="silver">Silver</option>
+                <option value="vane">Vane</option>
+                <option value="Billy">billy</option>
             </o-select>
         </o-field>
 
         <o-field
             label="Error"
             variant="danger"
             message="Something went wrong with this field">
-            <o-select placeholder="Select a character" :options="options" />
+            <o-select placeholder="Select a character">
+                <option value="flint">Flint</option>
+                <option value="silver">Silver</option>
+                <option value="vane">Vane</option>
+                <option value="Billy">billy</option>
+            </o-select>
         </o-field>
 
         <o-field label="Disabled">
-            <o-select
-                placeholder="Select a character"
-                disabled
-                :options="options" />
+            <o-select placeholder="Select a character" disabled>
+                <option value="flint">Flint</option>
+                <option value="silver">Silver</option>
+                <option value="vane">Vane</option>
+                <option value="Billy">billy</option>
+            </o-select>
         </o-field>
 
-        <o-field label="Disabled option">
+        <o-field label="Disabled options">
             <o-select placeholder="Select a character">
-                <option value="flint">Flint</option>
+                <option value="flint" disabled>Flint</option>
                 <option value="silver" disabled>Silver</option>
             </o-select>
         </o-field>
 
-        <o-field label="Rounded">
-            <o-select
-                placeholder="Select a character"
-                rounded
-                :options="options" />
-        </o-field>
-
         <o-field label="Expanded">
-            <o-select
-                placeholder="Select a character"
-                expanded
-                :options="options" />
+            <o-select placeholder="Select a character" expanded>
+                <option value="flint">Flint</option>
+                <option value="silver">Silver</option>
+                <option value="vane">Vane</option>
+                <option value="Billy" disabled>billy</option>
+            </o-select>
         </o-field>
     </section>
 </template>
diff --git a/packages/oruga/src/components/select/examples/grouped.vue b/packages/oruga/src/components/select/examples/grouped.vue
diff --git a/packages/oruga/src/components/select/examples/index.vue b/packages/oruga/src/components/select/examples/index.vue
@@ -2,8 +2,20 @@
 import Base from "./base.vue";
 import BaseCode from "./base.vue?raw";
 
-import Grouped from "./grouped.vue";
-import GroupedCode from "./grouped.vue?raw";
+import OptionsPrimitives from "./options-primitives.vue";
+import OptionsPrimitivesCode from "./options-primitives.vue?raw";
+
+import OptionsObject from "./options-object.vue";
+import OptionsObjectCode from "./options-object.vue?raw";
+
+import OptionsArray from "./options-array.vue";
+import OptionsArrayCode from "./options-array.vue?raw";
+
+import OptionsGrouped from "./options-grouped.vue";
+import OptionsGroupedCode from "./options-grouped.vue?raw";
+
+import OptionsNative from "./options-native.vue";
+import OptionsNativeCode from "./options-native.vue?raw";
 
 import Multiple from "./multiple.vue";
 import MultipleCode from "./multiple.vue?raw";
@@ -20,15 +32,121 @@ import WithIconsCode from "./with-icons.vue?raw";
 
 <template>
     <h3 id="base">Base</h3>
+    <div class="vp-doc">
+        <p>
+            The <b>select</b> input uses
+            <a
+                href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select">
+                HTML's native select input</a
+            >. Select inputs can be single value selections, or multi-value
+            selections by using the <code>multiple</code> attribute.
+        </p>
+    </div>
     <ExampleViewer :component="Base" :code="BaseCode" />
 
-    <h3 id="variants">Grouped</h3>
-    <ExampleViewer :component="Grouped" :code="GroupedCode" />
+    <h3 id="options">Options</h3>
+    <div class="vp-doc">
+        <p>There are 4 ways to provide options to a select input:</p>
+        <ul>
+            <li>An array of primitives</li>
+            <li>An object of value/label pairs</li>
+            <li>
+                An array of objects with label and value properties (the same as
+                the checkbox and radio inputs)
+            </li>
+            <li>
+                Using the native
+                <code>&lt;option&gt;</code>
+                tags directly inside the default slot.
+            </li>
+        </ul>
+    </div>
+
+    <h4 id="options-primitives">Array of primitives</h4>
+    <div class="vp-doc">
+        <p>
+            The simplest way to provide options is an array of primitives like
+            strings or numbers, where the primitive will be used for both
+            thestring casted <code>label</code> representation and the
+            <code>value</code> of the option.
+        </p>
+    </div>
+    <ExampleViewer
+        :component="OptionsPrimitives"
+        :code="OptionsPrimitivesCode" />
+
+    <h4 id="options-object">Value / Label object</h4>
+    <div class="vp-doc">
+        <p>
+            You may also provide the <code>options</code> prop where the keys
+            are values and the values of each property are labels.
+        </p>
+    </div>
+    <ExampleViewer :component="OptionsObject" :code="OptionsObjectCode" />
+
+    <h4 id="options-array">Array of objects</h4>
+    <div class="vp-doc">
+        <p>
+            The most flexible way to define options is to provide an array of
+            objects. The object is defined as: <br />
+            <code>{ value: any, label: string, attrs?: object }</code>
+            <br />
+            The
+            <code>value</code> attribute is the real value which will be used by
+            the <code>v-model</code> property and other events. The
+            <code>label</code> attribute is the visible representation of the
+            option. The <code>attrs</code> attribute is an object for additional
+            attributes, which will be applied to the option item tag.
+        </p>
+    </div>
+    <ExampleViewer :component="OptionsArray" :code="OptionsArrayCode" />
+
+    <h4 id="options-grouped">Option groups</h4>
+    <div class="vp-doc">
+        <p>
+            Using the array of objects syntax you can also create grouped
+            options (<code>&lt;optgroup&gt;</code> in HTML) by adding an
+            <code>options</code> property to the object option.
+        </p>
+    </div>
+    <ExampleViewer :component="OptionsGrouped" :code="OptionsGroupedCode" />
+
+    <h4 id="options-native">Default Slot</h4>
+    <div class="vp-doc">
+        <p>
+            Sometimes it may be desirable to manually output the contents of a
+            select list in order to create specialized structures. This can be
+            done by using the <code>default</code> slot to explicitly output
+            your options like the native HTML select element.
+        </p>
+    </div>
+    <ExampleViewer :component="OptionsNative" :code="OptionsNativeCode" />
 
-    <h3 id="variants">Multiple</h3>
+    <h3 id="multiple">Multiple</h3>
+    <div class="vp-doc">
+        <p>
+            The <b>select</b> input also supports a
+            <code>multiple</code> attribute that allows for multi-selection.
+            When used the <code>v-model</code> attribute will be an array of
+            values.
+        </p>
+        <div class="info custom-block">
+            <p class="custom-block-title">Accessibility Notes</p>
+            <p>
+                Select inputs with the <code>multiple</code> attribute can be
+                challenging for some users because they require holding-down the
+                control or command keys to perform multiple selections.
+                Depending on your audience, you may want to consider using a
+                <a href="/components/Checkbox.html#array">
+                    <b>checkbox input</b>
+                </a>
+                instead.
+            </p>
+        </div>
+    </div>
     <ExampleViewer :component="Multiple" :code="MultipleCode" />
 
-    <h3 id="variants">Sizes</h3>
+    <h3 id="sizes">Sizes</h3>
     <ExampleViewer :component="Sizes" :code="SizesCode" />
 
     <h3 id="variants">Variants</h3>

diff --git a/packages/oruga/src/components/select/examples/options-array.vue b/packages/oruga/src/components/select/examples/options-array.vue
@@ -0,0 +1,21 @@
+<template>
+    <section>
+        <o-field label="Select a character">
+            <o-select
+                placeholder="Select a character"
+                expanded
+                icon="user"
+                :options="[
+                    { label: 'Flint', value: 'flint' },
+                    { label: 'Silver', value: 'silver' },
+                    { label: 'Vane', value: 'vane' },
+                    { label: 'Billy', value: 'billy' },
+                    {
+                        label: 'Jack',
+                        value: 'jack',
+                        attrs: { disabled: true },
+                    },
+                ]" />
+        </o-field>
+    </section>
+</template>