Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(select): update select documentation #1167

Merged
merged 3 commits into from
Jan 30, 2025
Merged

docs(select): update select documentation #1167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b5a6036
docs(select): update select documentation
mlmoravek Jan 28, 2025
85b67dd
docs(select): update select documentation
mlmoravek Jan 28, 2025
99ac7e6
docs(select): update select documentation
mlmoravek Jan 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/docs/.vitepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ export default defineConfig({
appearance: false,
themeConfig: {
logo: "/logo.png",
outline: [2, 3],
outline: [2, 4],
search: {
provider: "local",
},
Expand Down
12 changes: 8 additions & 4 deletions packages/docs/.vitepress/theme/styles/vitepress.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ header .VPNavBar button {


.main {
h1, h2, h3 {
h1, h2, h3, h4 {
position: relative;
margin: 0;
line-height: 1.5em;
Expand All @@ -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 {
Expand All @@ -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,
Expand Down
4 changes: 2 additions & 2 deletions packages/docs/components/Select.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>
Expand Down
4 changes: 2 additions & 2 deletions packages/oruga/src/components/notification/examples/index.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion packages/oruga/src/components/select/Select.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down
63 changes: 32 additions & 31 deletions packages/oruga/src/components/select/examples/base.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
42 changes: 0 additions & 42 deletions packages/oruga/src/components/select/examples/grouped.vue
View file
Open in desktop

This file was deleted.

130 changes: 124 additions & 6 deletions packages/oruga/src/components/select/examples/index.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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>
Expand Down
21 changes: 21 additions & 0 deletions packages/oruga/src/components/select/examples/options-array.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Loading