@warp-ds/elements 2.9.1 → 2.10.0-next.1

package/dist/docs/select/examples.md

@@ -1 +1,117 @@
 ## Examples
+
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Placeholder
+
+A select doesn't have a `placeholder` as such, but an `<option>` with an empty value gives a similar result.
+
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="">Select an option</option>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Optional
+
+Add the `optional` prop to indicate that the select is not required. To make the select optional you must add an `<option>` with an empty value.
+
+<elements-example>
+
+```html
+<w-select label="Berries" optional>
+    <option value="">Select an option</option>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Help text
+
+Use `help-text` to give additional context when the label and options are not enough.
+
+<elements-example>
+
+```html
+<w-select label="Berries" help-text="We assume this is your jam">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### No visual label
+
+You must set either an `aria-label` or an [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby).
+
+<elements-example>
+
+```html
+<w-select aria-label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries" selected>Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+
+### Disabled
+
+Keep in mind that using disabled is an anti-pattern.
+
+There will always be users who don't understand why an element is disabled, or users who can't even see that
+it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
+
+<elements-example>
+    
+```html
+<w-select label="Berries" disabled>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Read only
+
+The `readonly` boolean attribute makes the selection immutable. Unlike disabled the select remains focusable. See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/readOnly) for more information.
+
+<elements-example>
+
+```html
+<w-select label="Berries" readonly>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>

package/dist/docs/select/select.md

@@ -4,14 +4,160 @@
 
 A dropdown component for selecting a single value.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-select--docs)
-
 ## Usage
 
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Validation
+
+Set the `invalid` attribute to display a textfield as invalid.
+
+`invalid` should be paired with `help-text` to provide feedback to the user about how to correct the error.
+
+<elements-example>
+
+```html
+<w-select label="Berries" invalid help-text="Select a red berry">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries" selected>Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
 ## Accessibility
 
+If a visible label isn't specified, an `aria-label` must be provided to the text field for accessibility. If the field is labeled by a separate element, an `aria-labelledby` property must be provided using the `id` of the labeling element instead.
+
 ## Examples
 
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Placeholder
+
+A select doesn't have a `placeholder` as such, but an `<option>` with an empty value gives a similar result.
+
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="">Select an option</option>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Optional
+
+Add the `optional` prop to indicate that the select is not required. To make the select optional you must add an `<option>` with an empty value.
+
+<elements-example>
+
+```html
+<w-select label="Berries" optional>
+    <option value="">Select an option</option>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Help text
+
+Use `help-text` to give additional context when the label and options are not enough.
+
+<elements-example>
+
+```html
+<w-select label="Berries" help-text="We assume this is your jam">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### No visual label
+
+You must set either an `aria-label` or an [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby).
+
+<elements-example>
+
+```html
+<w-select aria-label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries" selected>Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+
+### Disabled
+
+Keep in mind that using disabled is an anti-pattern.
+
+There will always be users who don't understand why an element is disabled, or users who can't even see that
+it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
+
+<elements-example>
+    
+```html
+<w-select label="Berries" disabled>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Read only
+
+The `readonly` boolean attribute makes the selection immutable. Unlike disabled the select remains focusable. See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/readOnly) for more information.
+
+<elements-example>
+
+```html
+<w-select label="Berries" readonly>
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
 ## `<w-select>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -20,19 +166,19 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| always | `boolean` | `false` | Whether to always show a hint.. **Deprecated**: Use `help-text` instead and only set it if you want to display the help text. |
-| auto-focus | `boolean` | `false` | Whether the element should receive focus on render.. **Deprecated**: Use the native `autofocus` attribute instead. |
+| always | `boolean` | `false` | Whether to always show a hint. **Deprecated**: Use `help-text` instead and only set it if you want to display the help text. |
+| auto-focus | `boolean` | `false` | Whether the element should receive focus on render. **Deprecated**: Use the native `autofocus` attribute instead. |
 | autofocus | `boolean` | `false` | Whether the element should receive focus on render |
 | disabled | `boolean` | `false` | Renders the field in a disabled state. |
-| help-text | `string` | `-` | The content displayed as the help text. Paired with `invalid` to show the text as a validation error. |
-| hint | `string` | `-` | The content displayed as the help text.. **Deprecated**: Use `help-text` instead. |
-| invalid | `boolean` | `false` | Renders the field in an invalid state. Paired with `help-text` to provide feedback about the error. |
-| label | `string` | `-` | The content to disply as the label |
-| name | `string` | `-` | - |
-| optional | `boolean` | `false` | Whether to show optional text |
-| read-only | `boolean` | `false` | Renders the field in a readonly state.. **Deprecated**: Use the native readonly attribute instead. |
+| help-text | `string` | `-` | The content displayed as the help text. |
+| hint | `string` | `-` | The content displayed as the help text. **Deprecated**: Use `help-text` instead. |
+| invalid | `boolean` | `false` | Renders the field in an invalid state. |
+| label | `string` | `-` | The content to display as the label. |
+| name | `string` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
+| optional | `boolean` | `false` | Whether to show the optional indicator after the label. |
+| read-only | `boolean` | `false` | Renders the field in a readonly state. **Deprecated**: Use the native readonly attribute instead. |
 | readonly | `boolean` | `false` | Renders the field in a readonly state. |
-| value | `string` | `-` | - |
+| value | `string` | `-` | Lets you set the current value. |
 
 ### Property Details
 
@@ -70,7 +216,9 @@ Renders the field in a disabled state.
 
 #### help-text
 
-The content displayed as the help text. Paired with `invalid` to show the text as a validation error.
+The content displayed as the help text.
+
+Paired with `invalid` to show the text as a validation error.
 
 - Type: `string`
 - Default: `-`
@@ -86,28 +234,30 @@ The content displayed as the help text.
 
 #### invalid
 
-Renders the field in an invalid state. Paired with `help-text` to provide feedback about the error.
+Renders the field in an invalid state.
+
+Paired with `help-text` to provide feedback about the error.
 
 - Type: `boolean`
 - Default: `false`
 
 #### label
 
-The content to disply as the label
+The content to display as the label.
 
 - Type: `string`
 - Default: `-`
 
 #### name
 
-
+The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form.
 
 - Type: `string`
 - Default: `-`
 
 #### optional
 
-Whether to show optional text
+Whether to show the optional indicator after the label.
 
 - Type: `boolean`
 - Default: `false`
@@ -130,7 +280,7 @@ Renders the field in a readonly state.
 
 #### value
 
-
+Lets you set the current value.
 
 - Type: `string`
 - Default: `-`

package/dist/docs/select/usage.md

@@ -1 +1,31 @@
 ## Usage
+
+<elements-example>
+
+```html
+<w-select label="Berries">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries">Cloudberries</option>
+</w-select>
+```
+
+</elements-example>
+
+### Validation
+
+Set the `invalid` attribute to display a textfield as invalid.
+
+`invalid` should be paired with `help-text` to provide feedback to the user about how to correct the error.
+
+<elements-example>
+
+```html
+<w-select label="Berries" invalid help-text="Select a red berry">
+    <option value="raspberries">Raspberries</option>
+    <option value="strawberries">Strawberries</option>
+    <option value="cloudberries" selected>Cloudberries</option>
+</w-select>
+```
+
+</elements-example>