From 7454cc12a1b799cde3fc3d5fd48a82fbd2c6b970 Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Fri, 4 Jun 2021 08:19:28 -0400
Subject: [PATCH] restore select docs

---
 docs/components/select.md | 174 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 174 insertions(+)

diff --git a/docs/components/select.md b/docs/components/select.md
index 356aa60e..5101dd26 100644
--- a/docs/components/select.md
+++ b/docs/components/select.md
@@ -15,3 +15,177 @@ Selects allow you to choose one or more items from a dropdown menu.
   <sl-menu-item value="option-6">Option 6</sl-menu-item>
 </sl-select>
 ```
+
+?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+
+## Examples
+
+### Placeholders
+
+Use the `placeholder` attribute to add a placeholder.
+
+```html preview
+<sl-select placeholder="Select one">
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Clearable
+
+Use the `clearable` attribute to make the control clearable.
+
+```html preview
+<sl-select placeholder="Clearable" clearable>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Pill
+
+Use the `pill` prop to give selects rounded edges.
+
+```html preview
+<sl-select pill>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Disabled
+
+Use the `disabled` prop to disable a select.
+
+```html preview
+<sl-select placeholder="Disabled" disabled>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Multiple
+
+To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. When using this option, `value` will be an array instead of a string.
+
+```html preview
+<sl-select placeholder="Select a few" multiple clearable>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-menu-divider></sl-menu-divider>
+  <sl-menu-item value="option-4">Option 4</sl-menu-item>
+  <sl-menu-item value="option-5">Option 5</sl-menu-item>
+  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+</sl-select>
+```
+
+### Grouping Options
+
+Options can be grouped visually using menu labels and menu dividers.
+
+```html preview
+<sl-select placeholder="Select one">
+  <sl-menu-label>Group 1</sl-menu-label>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-menu-divider></sl-menu-divider>
+  <sl-menu-label>Group 2</sl-menu-label>
+  <sl-menu-item value="option-4">Option 4</sl-menu-item>
+  <sl-menu-item value="option-5">Option 5</sl-menu-item>
+  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+</sl-select>
+```
+
+### Sizes
+
+Use the `size` attribute to change a select's size.
+
+```html preview
+<sl-select placeholder="Small" size="small" multiple>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+
+<br>
+
+<sl-select placeholder="Medium" size="medium" multiple>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+
+<br>
+
+<sl-select placeholder="Large" size="large" multiple>
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Selecting Options Programmatically
+
+The `value` prop is bound to the current selection. As the selection changes, so will the value. To programmatically manage the selection, update the `value` property.
+
+```html preview
+<div class="selecting-example">
+  <sl-select placeholder="">
+    <sl-menu-item value="option-1">Option 1</sl-menu-item>
+    <sl-menu-item value="option-2">Option 2</sl-menu-item>
+    <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  </sl-select>
+
+  <br>
+
+  <sl-button data-option="option-1">Set 1</sl-button>
+  <sl-button data-option="option-2">Set 2</sl-button>
+  <sl-button data-option="option-3">Set 3</sl-button>
+</div>
+
+<script>
+  const container = document.querySelector('.selecting-example');
+  const select = container.querySelector('sl-select');
+
+  [...container.querySelectorAll('sl-button')].map(button => {
+    button.addEventListener('click', () => {
+      select.value = button.dataset.option; 
+    });
+  });
+</script>
+```
+
+### Labels
+
+Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html preview
+<sl-select label="Select one">
+  <sl-menu-item value="option-1">Option 1</sl-menu-item>
+  <sl-menu-item value="option-2">Option 2</sl-menu-item>
+  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+</sl-select>
+```
+
+### Help Text
+
+Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+
+```html preview
+<sl-select 
+  label="Experience" 
+  help-text="Please tell us your skill level."
+>
+  <sl-menu-item value="option-1">Novice</sl-menu-item>
+  <sl-menu-item value="option-2">Intermediate</sl-menu-item>
+  <sl-menu-item value="option-3">Advanced</sl-menu-item>
+</sl-select>
+```
+
+[component-metadata:sl-select]