chore: adds option docs in new format

Vonage · Oct 31, 2024 · a4a0848 · a4a0848
1 parent c5dd033
commit a4a0848
Show file tree

Hide file tree

Showing 5 changed files with 165 additions and 95 deletions.
diff --git a/apps/docs/content/_data/components.json b/apps/docs/content/_data/components.json
@@ -215,8 +215,13 @@
 	},
 	{
 		"title": "Option",
-		"page": "legacy",
-		"markdown": "./libs/components/src/lib/option/README.md"
+		"description": "Use to display an option list inside the Select, Searchable Select or Combobox components",
+		"variations": "./libs/components/src/lib/option/VARIATIONS.md",
+		"guidelines": "./libs/components/src/lib/option/GUIDELINES.md",
+		"hideGuidelines": "true",
+		"hideAccessibility": "true",
+		"code": "./libs/components/src/lib/option/README.md",
+		"accessibility": "./libs/components/src/lib/option/ACCESSIBILITY.md"
 	},
 	{
 		"title": "Searchable Select",

diff --git a/libs/components/src/lib/option/ACCESSIBILITY.md b/libs/components/src/lib/option/ACCESSIBILITY.md
diff --git a/libs/components/src/lib/option/GUIDELINES.md b/libs/components/src/lib/option/GUIDELINES.md
diff --git a/libs/components/src/lib/option/README.md b/libs/components/src/lib/option/README.md
@@ -1,124 +1,116 @@
-# Option
+## Usage
 
-The option component is generally used inside select or combobox.
+<vwc-tabs>
+<vwc-tab label="Web component"></vwc-tab>
+<vwc-tab-panel>
 
 ```js
-<script type="module">import '@vonage/vivid/option';</script>
+import '@vonage/vivid/option';
 ```
 
-## Members
+or, if you need to use a unique prefix:
 
-### Text
-
-Use the `text` attribute to set the option's text.
-
-- Type: `string`
-- Default: `undefined`
+```js
+import { registerOption } from '@vonage/vivid';
 
-```html preview
-<style>
-	div[role='listbox'] {
-		width: 150px;
-	}
-</style>
-<div role="listbox">
-	<vwc-option text="Option"></vwc-option>
-</div>
+registerOption('your-prefix');
 ```
 
-### Label
-
-Add the `label` attribute to add a label to the option to replace the text shown in `vwc-select` when selected.
-`label` will return the `label` attribute's value. If not set, it will revert to the `text`.
-Note that you cannot set `label` programmatically like this: `option.label = 'new label'`. You can only set it via the attribute.
-
-### Icon
-
-Add the `icon` attribute to add an icon to the option.
-Check out the [vivid icons gallery](/icons/icons-gallery/) to see what icons are available.
-
-- Type: `string`
-- Default: `''`
-
 ```html preview
-<style>
-	div[role='listbox'] {
-		width: 150px;
-	}
-</style>
-<div role="listbox">
-	<vwc-option text="Option" icon="chat-line"></vwc-option>
-</div>
-```
-
-### Selected
-
-Add the `selected` attribute to select the option.
+<script type="module">
+	import { registerOption } from '@vonage/vivid';
+	registerOption('your-prefix');
+</script>
 
-- Type: `boolean`
-- Default: `false`
-
-```html preview
-<style>
-	div[role='listbox'] {
-		width: 150px;
-	}
-</style>
-<div role="listbox">
-	<vwc-option text="Option" selected></vwc-option>
+<div class="container">
+	<your-prefix-option text="Option text"></your-prefix-option>
 </div>
-```
-
-### Disabled
-
-Add the `disabled` attribute to disable the option.
 
-- Type: `boolean`
-- Default: `false`
-
-```html preview
 <style>
-	div[role='listbox'] {
-		width: 150px;
+	.container {
+		width: 250px;
 	}
 </style>
-<div role="listbox">
-	<vwc-option text="Option" disabled></vwc-option>
-</div>
 ```
 
-### Value
-
-Use the `value` attribute to set the option's value.
+</vwc-tab-panel>
+<vwc-tab label="Vue"></vwc-tab>
+<vwc-tab-panel>
+
+```html
+<script setup lang="ts">
+	import { VOption } from '@vonage/vivid-vue';
+</script>
+<template>
+	<VOption text="Option text" />
+</template>
+```
 
-- Type: `string`
-- Default: `undefined`
+</vwc-tab-panel>
+</vwc-tabs>
+
+## Label
+
+The `label` attribute can be used xsto display different text in the parent element when selected.
+
+In the example below, the international dialing code (`label`) is displayed when selected, but the country name (`text`) is used in the option list.
+
+```html preview 270px
+<vwc-select
+	label="Country code"
+	icon="flag-united-states"
+	class="country-code"
+	id="country-code"
+>
+	<vwc-option
+		label="+1"
+		value="1"
+		text="United States"
+		icon="flag-united-states"
+	></vwc-option>
+	<vwc-option
+		label="+44"
+		value="44"
+		text="United Kingdom"
+		icon="flag-united-kingdom"
+	></vwc-option>
+	<vwc-option
+		label="+49"
+		value="49"
+		text="Germany"
+		icon="flag-germany"
+	></vwc-option>
+	<vwc-option
+		label="+355"
+		value="355"
+		text="Albania"
+		icon="flag-albania"
+	></vwc-option>
+</vwc-select>
+
+<script>
+	const select = document.getElementById('country-code');
+	select?.addEventListener('change', (e) => {
+		select.icon = select.selectedOptions[0].icon;
+	});
+</script>
 
-```html preview
 <style>
-	div[role='listbox'] {
-		width: 150px;
+	.country-code {
+		inline-size: 120px;
 	}
 </style>
-<div role="listbox">
-	<vwc-option text="Option" value="my-value"></vwc-option>
-</div>
 ```
 
 ## Slots
 
-### Icon
+### Icon Slot
 
 Set the `icon` slot to show an icon before the option's text.
 If set, the `icon` attribute is ignored.
 
 ```html preview
-<style>
-	div[role='listbox'] {
-		width: 150px;
-	}
-</style>
-<div role="listbox">
+<div class="container">
 	<vwc-option text="Option" value="my-value">
 		<vwc-icon
 			slot="icon"
@@ -127,16 +119,22 @@ If set, the `icon` attribute is ignored.
 		></vwc-icon>
 	</vwc-option>
 </div>
+
+<style>
+	.container {
+		width: 250px;
+	}
+</style>
 ```
 
-### Tag Icon
+### Tag Icon Slot
 
-If the option is represented as a tag in a [`searchable-select`](/components/searchable-select/) component, you can use `tag-icon` slot to show an icon in the tag.
+If the option is represented as a tag in a [Searchable Select](/components/searchable-select/) component, you can use `tag-icon` slot to show an icon in the tag.
 
-```html preview 230px
+```html preview 180px
 <vwc-searchable-select multiple>
 	<vwc-option value="afghanistan" text="Afghanistan" selected>
 		<vwc-icon slot="tag-icon" name="flag-afghanistan"></vwc-icon>
 	</vwc-option>
 </vwc-searchable-select>
-```
+```
diff --git a/libs/components/src/lib/option/VARIATIONS.md b/libs/components/src/lib/option/VARIATIONS.md
@@ -0,0 +1,67 @@
+## Text
+
+The `text` attribute set the text to be displayed in the option list item and in the parent element when selected.
+
+The [label attribute](/components/option/code/#label) can be used xsto display different text in the parent element when selected.
+
+```html preview
+<div class="container">
+	<vwc-option text="Option text" value="option1"></vwc-option>
+</div>
+
+<style>
+	.container {
+		width: 250px;
+	}
+</style>
+```
+
+## Selected
+
+The `selected` attribute indicates that the option is selected.
+
+```html preview
+<div class="container">
+	<vwc-option selected text="Option text" value="option1"></vwc-option>
+</div>
+
+<style>
+	.container {
+		width: 250px;
+	}
+</style>
+```
+
+## Icons
+
+The `icon` attribute displays an icon from the [icon library](/icons/icons-gallery/), which is displayed at the start of the option, before the text.
+
+Custom icons can be provided using the [icon slot](/components/option/code/#icon-slot).
+
+```html preview
+<div class="container">
+	<vwc-option icon="chat-line" text="Option text" value="option1"></vwc-option>
+</div>
+
+<style>
+	.container {
+		width: 250px;
+	}
+</style>
+```
+
+## Disabled
+
+The `disabled` attribute indicates that the option is disabled and can not be selected.
+
+```html preview
+<div class="container">
+	<vwc-option disabled text="Option text" value="option1"></vwc-option>
+</div>
+
+<style>
+	.container {
+		width: 250px;
+	}
+</style>
+```