@spectrum-web-components/picker 1.3.0-beta.6 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
-## Description
+## Overview
 
-An `<sp-picker>` is an alternative to HTML's `<select>` element. Use `<sp-menu-item>` elements to outline the options that will be made available to the user when interacting with the `<sp-picker>` element.
+An `<sp-picker>` is an alternative to HTML's `<select>` element. Use [`<sp-menu-item>`](../menu-item) elements to outline the options that will be made available to the user when interacting with the `<sp-picker>` element.
 
 ### Usage
 
@@ -30,154 +30,68 @@ When looking to leverage the `Picker` base class as a type and/or for extension
 import { Picker } from '@spectrum-web-components/picker';
 ```
 
-## Sizes
+### Anatomy
 
-<sp-tabs selected="m" auto label="Size Attribute Options">
-<sp-tab value="s">Small</sp-tab>
-<sp-tab-panel value="s">
+#### Labels
 
-```html demo
-<sp-field-group>
-    <div>
-        <sp-field-label for="picker-s" size="s">Selection type:</sp-field-label>
-        <sp-picker id="picker-s" size="s" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-    <div>
-        <sp-field-label for="picker-s-quiet" size="s">
-            Selection type:
-        </sp-field-label>
-        <sp-picker id="picker-s-quiet" quiet size="s" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-</sp-field-group>
-```
+To render accessibly, an `<sp-picker>` element should be paired with an `<sp-field-label>` element that has the `for` attribute referencing the `id` of the `<sp-picker>` element.
 
-</sp-tab-panel>
-<sp-tab value="m">Medium</sp-tab>
-<sp-tab-panel value="m">
+For an accessible label that renders within the bounds of the picker itself, but still fulfills the accessibility contract, use the `label` attribute or a `<span slot="label">` as a child element of `<sp-picker>`.
+
+<sp-tabs selected="sp-field-label" auto label="Label options">
+<sp-tab value="sp-field-label">Uses &lt;sp-field-label&gt;</sp-tab>
+<sp-tab-panel value="sp-field-label">
 
 ```html demo
-<sp-field-group>
-    <div>
-        <sp-field-label for="picker-m" size="m">Selection type:</sp-field-label>
-        <sp-picker id="picker-m" size="m" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-    <div>
-        <sp-field-label for="picker-m-quiet" size="m">
-            Selection type:
-        </sp-field-label>
-        <sp-picker id="picker-m-quiet" quiet size="m" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-</sp-field-group>
+<sp-field-label for="uses-sp-field-label">Selection type:</sp-field-label>
+<sp-picker id="uses-sp-field-label">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
 ```
 
 </sp-tab-panel>
-<sp-tab value="l">Large</sp-tab>
-<sp-tab-panel value="l">
+<sp-tab value="label-attribute">Uses label attribute</sp-tab>
+<sp-tab-panel value="label-attribute">
 
 ```html demo
-<sp-field-group>
-    <div>
-        <sp-field-label for="picker-l" size="l">Selection type:</sp-field-label>
-        <sp-picker id="picker-l" size="l" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-    <div>
-        <sp-field-label for="picker-l-quiet" size="l">
-            Selection type:
-        </sp-field-label>
-        <sp-picker id="picker-l-quiet" quiet size="l" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-</sp-field-group>
+<sp-picker label="Selection type" id="uses-label-attribute">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
 ```
 
 </sp-tab-panel>
-<sp-tab value="xl">Extra Large</sp-tab>
-<sp-tab-panel value="xl">
+<sp-tab value="label-slot">Uses label slot</sp-tab>
+<sp-tab-panel value="label-slot">
 
 ```html demo
-<sp-field-group>
-    <div>
-        <sp-field-label for="picker-xl" size="xl">
-            Selection type:
-        </sp-field-label>
-        <sp-picker id="picker-xl" size="xl" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-    <div>
-        <sp-field-label for="picker-xl-quiet" size="xl">
-            Selection type:
-        </sp-field-label>
-        <sp-picker id="picker-xl-quiet" quiet size="xl" label="Selection type">
-            <sp-menu-item>Deselect</sp-menu-item>
-            <sp-menu-item>Select inverse</sp-menu-item>
-            <sp-menu-item>Feather...</sp-menu-item>
-            <sp-menu-item>Select and mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save selection</sp-menu-item>
-            <sp-menu-item disabled>Make work path</sp-menu-item>
-        </sp-picker>
-    </div>
-</sp-field-group>
+<sp-picker id="uses-label-slot">
+    <span slot="label">Selection type:</span>
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
 ```
 
 </sp-tab-panel>
 </sp-tabs>
 
-## Icons
+#### Icons
 
 `<sp-menu-item>`s in an `<sp-picker>` that are provided content addressed to their `icon` slot will be passed to the `<sp-picker>` element when that item is chosen.
 
@@ -199,7 +113,7 @@ import { Picker } from '@spectrum-web-components/picker';
 </sp-picker>
 ```
 
-When you choose to leverage `<sp-menu-item>` elements without text content, you will need to be sure to leverage the `value` attribute so that the `<sp-picker>` element can differentiate between the available options. Further, it is important that you apply accessible labeling to the `[slot="icon"]` content as follows:
+When using `<sp-menu-item>` elements without text content, be sure to use the `value` attribute so that the `<sp-picker>` element can differentiate between the available options. Furthermore, it is important to apply accessible labeling to the `[slot="icon"]` content as follows:
 
 ```html
 <sp-field-label for="picker-icons-only">Choose an action...</sp-field-label>
@@ -223,67 +137,78 @@ When you choose to leverage `<sp-menu-item>` elements without text content, you
 </sp-picker>
 ```
 
-### Advanced icon management
+##### Advanced icon management
 
-The `icons` attribute allows you to manage whether to `only` display the icon in the `<sp-picker>` element or to display `none` of the icons in the `<sp-picker>`.
+The `icons` attribute manages how the selected item will appear. Set `icons="only"` to display only the selected item's icon in the `<sp-picker>` element, or `icons="none"` to display the selected item text without the icon `<sp-picker>`.
 
-When using `icons="only"` and your `<sp-menu-item>` elements still have text content, that content will be applied to `<sp-picker>` element in a non-visible way.
+When using `icons="only"` on `<sp-menu-item>` elements that have text content, that text will be applied to `<sp-picker>` element in a non-visible way.
 
-```html
+<sp-tabs selected="only" auto label="Icons Attribute Options">
+<sp-tab value="only">Only</sp-tab>
+<sp-tab-panel value="only">
+
+```html demo
 <sp-field-label for="picker-icons-value">Choose an action...</sp-field-label>
 <sp-picker
     label="What would you like to do?"
-    value="item-2"
+    value="save"
     id="picker-icons-value"
     icons="only"
 >
-    <sp-menu-item>
+    <sp-menu-item value="save">
         <sp-icon-save-floppy slot="icon"></sp-icon-save-floppy>
         Save
     </sp-menu-item>
-    <sp-menu-item>
+    <sp-menu-item value="finish">
         <sp-icon-stopwatch slot="icon"></sp-icon-stopwatch>
         Finish
     </sp-menu-item>
-    <sp-menu-item>
+    <sp-menu-item value="review">
         <sp-icon-user-activity slot="icon"></sp-icon-user-activity>
         Review
     </sp-menu-item>
 </sp-picker>
 ```
 
-When using `icons="none"`, the icons will only be available in the overlaid menu.
+</sp-tab-panel>
+<sp-tab value="none">None</sp-tab>
+<sp-tab-panel value="none">
 
-```html
+```html demo
 <sp-field-label for="picker-icons-none">Choose an action...</sp-field-label>
 <sp-picker
     label="What would you like to do?"
-    value="item-2"
+    value="save"
     id="picker-icons-none"
     icons="none"
 >
-    <sp-menu-item>
+    <sp-menu-item value="save">
         <sp-icon-save-floppy slot="icon"></sp-icon-save-floppy>
         Save
     </sp-menu-item>
-    <sp-menu-item>
+    <sp-menu-item value="finish">
         <sp-icon-stopwatch slot="icon"></sp-icon-stopwatch>
         Finish
     </sp-menu-item>
-    <sp-menu-item>
+    <sp-menu-item value="review">
         <sp-icon-user-activity slot="icon"></sp-icon-user-activity>
         Review
     </sp-menu-item>
 </sp-picker>
 ```
 
-## Value
+</sp-tab-panel>
+</sp-tabs>
+
+#### Value
 
-When the `value` of an `<sp-picker>` matches the `value` attribute or the trimmed `textContent` (or `itemText`) of a descendent `<sp-menu-item>` element, it will make that element as `selected`.
+When the `value` of an `<sp-picker>` matches either the `value` attribute or the trimmed `textContent` (or `itemText`) of a descendent `<sp-menu-item>`, it will mark that element as `selected`.
 
-### Matching `value`
+<sp-tabs selected="matching-value" auto label="Selected">
+<sp-tab value="matching-value">Matching value</sp-tab>
+<sp-tab-panel value="matching-value">
 
-```html
+```html demo
 <sp-field-label for="picker-value">Selection type:</sp-field-label>
 <sp-picker
     label="Select a Country with a very long label, too long in fact"
@@ -300,9 +225,11 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
-### Matching `itemText`
+</sp-tab-panel>
+<sp-tab value="matching-item-text">Matching itemText</sp-tab>
+<sp-tab-panel value="matching-item-text">
 
-```html
+```html demo
 <sp-field-label for="picker-item-text">Selection type:</sp-field-label>
 <sp-picker
     label="Select a Country with a very long label, too long in fact"
@@ -319,17 +246,20 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
-## States
+</sp-tab-panel>
+</sp-tabs>
 
-### Invalid
+### Options
 
-```html
-<sp-field-label for="picker-invalid">Standard:</sp-field-label>
-<sp-picker
-    label="Select a Country with a very long label, too long in fact"
-    invalid
-    id="picker-invalid"
->
+#### Sizes
+
+<sp-tabs selected="m" auto label="Size attribute options">
+<sp-tab value="s">Small</sp-tab>
+<sp-tab-panel value="s">
+
+```html demo
+<sp-field-label for="picker-s" size="s">Selection type:</sp-field-label>
+<sp-picker id="picker-s" size="s" label="Selection type">
     <sp-menu-item>Deselect</sp-menu-item>
     <sp-menu-item>Select inverse</sp-menu-item>
     <sp-menu-item>Feather...</sp-menu-item>
@@ -340,13 +270,65 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 <br />
 <br />
-<sp-field-label for="picker-invalid-quiet">Quiet:</sp-field-label>
-<sp-picker
-    label="Select a Country with a very long label, too long in fact"
-    invalid
-    quiet
-    id="picker-invalid-quiet"
->
+<sp-field-label for="picker-s-quiet" size="s">Selection type:</sp-field-label>
+<sp-picker id="picker-s-quiet" quiet size="s" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
+</sp-tab-panel>
+<sp-tab value="m">Medium</sp-tab>
+<sp-tab-panel value="m">
+
+```html demo
+<sp-field-label for="picker-m" size="m">Selection type:</sp-field-label>
+<sp-picker id="picker-m" size="m" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+<br />
+<br />
+<sp-field-label for="picker-m-quiet" size="m">Selection type:</sp-field-label>
+<sp-picker id="picker-m-quiet" quiet size="m" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
+</sp-tab-panel>
+<sp-tab value="l">Large</sp-tab>
+<sp-tab-panel value="l">
+
+```html demo
+<sp-picker id="picker-l" size="l" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+<br />
+<br />
+<sp-field-label for="picker-l-quiet" size="l">Selection type:</sp-field-label>
+<sp-picker id="picker-l-quiet" quiet size="l" label="Selection type">
     <sp-menu-item>Deselect</sp-menu-item>
     <sp-menu-item>Select inverse</sp-menu-item>
     <sp-menu-item>Feather...</sp-menu-item>
@@ -357,7 +339,43 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
-### Side Label
+</sp-tab-panel>
+<sp-tab value="xl">Extra Large</sp-tab>
+<sp-tab-panel value="xl">
+
+```html demo
+<sp-field-label for="picker-xl" size="xl">Selection type:</sp-field-label>
+<sp-picker id="picker-xl" size="xl" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+<br />
+<br />
+<sp-field-label for="picker-xl-quiet" size="xl">Selection type:</sp-field-label>
+<sp-picker id="picker-xl-quiet" quiet size="xl" label="Selection type">
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Side Label
+
+<sp-tabs selected="standard-side-label" auto label="Side-aligned option">
+<sp-tab value="standard-side-label">Side label, standard</sp-tab>
+<sp-tab-panel value="standard-side-label">
 
 ```html
 <sp-field-label side-aligned="start" for="picker-sideLabel">
@@ -375,8 +393,13 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
     <sp-menu-item>Save selection</sp-menu-item>
     <sp-menu-item disabled>Make work path</sp-menu-item>
 </sp-picker>
-<br />
-<br />
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet-side-label">Side label, quiet</sp-tab>
+<sp-tab-panel value="quiet-side-label">
+
+```html demo
 <sp-field-label side-aligned="start" for="picker-sideLabel-quiet">
     Quiet:
 </sp-field-label>
@@ -395,9 +418,66 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
-### Disabled
+</sp-tab-panel>
+</sp-tabs>
+
+### States
 
-```html
+#### Invalid
+
+<sp-tabs selected="standard-invalid" auto label="Invalid states">
+<sp-tab value="standard-invalid">Invalid, standard</sp-tab>
+<sp-tab-panel value="standard-invalid">
+
+```html demo
+<sp-field-label for="picker-invalid">Standard:</sp-field-label>
+<sp-picker
+    label="Select a Country with a very long label, too long in fact"
+    invalid
+    id="picker-invalid"
+>
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet-invalid">Invalid, quiet</sp-tab>
+<sp-tab-panel value="quiet-invalid">
+
+```html demo
+<sp-field-label for="picker-invalid-quiet">Quiet:</sp-field-label>
+<sp-picker
+    label="Select a Country with a very long label, too long in fact"
+    invalid
+    quiet
+    id="picker-invalid-quiet"
+>
+    <sp-menu-item>Deselect</sp-menu-item>
+    <sp-menu-item>Select inverse</sp-menu-item>
+    <sp-menu-item>Feather...</sp-menu-item>
+    <sp-menu-item>Select and mask...</sp-menu-item>
+    <sp-menu-divider></sp-menu-divider>
+    <sp-menu-item>Save selection</sp-menu-item>
+    <sp-menu-item disabled>Make work path</sp-menu-item>
+</sp-picker>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Disabled
+
+<sp-tabs selected="standard-disabled" auto label="Disabled states">
+<sp-tab value="standard-disabled">Disabled, standard</sp-tab>
+<sp-tab-panel value="standard-disabled">
+
+```html demo
 <sp-field-label for="picker-disabled">Standard:</sp-field-label>
 <sp-picker
     label="Select a Country with a very long label, too long in fact"
@@ -412,8 +492,13 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
     <sp-menu-item>Save selection</sp-menu-item>
     <sp-menu-item disabled>Make work path</sp-menu-item>
 </sp-picker>
-<br />
-<br />
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet-disabled">Disabled, quiet</sp-tab>
+<sp-tab-panel value="quiet-disabled">
+
+```html demo
 <sp-field-label for="picker-disabled-quiet">Quiet:</sp-field-label>
 <sp-picker
     label="Select a Country with a very long label, too long in fact"
@@ -431,20 +516,37 @@ When the `value` of an `<sp-picker>` matches the `value` attribute or the trimme
 </sp-picker>
 ```
 
-### Pending
+</sp-tab-panel>
+</sp-tabs>
 
-When in pending state, `<sp-picker>` elements will not respond to click events and will be delivered with a `<sp-progress-circle>` to visually outline that it is pending. It will not toggle open or display its `<sp-menu-item>` descendants until the attribute is removed.
+#### Pending
 
-```html
+While in pending state, `<sp-picker>` elements will not respond to click events and will be delivered with `<sp-progress-circle>` to visually denote that it is pending. It will not toggle open or display its `<sp-menu-item>` descendants until the attribute is removed. Use the `pending-label` attribute to customize the pending text for assoistive technology, which is set to `Pending` by default.
+
+<sp-tabs selected="standard-pending" auto label="Pending states">
+<sp-tab value="standard-pending">Pending, standard</sp-tab>
+<sp-tab-panel value="standard-pending">
+
+```html demo
 <sp-field-label for="picker-loading">Standard:</sp-field-label>
-<sp-picker id="picker-loading" label="Loading blending modes..." pending>
+<sp-picker
+    id="picker-loading"
+    label="Loading blending modes..."
+    pending
+    pending-label="loading options"
+>
     <sp-menu-item>Pass through</sp-menu-item>
     <sp-menu-item>Normal</sp-menu-item>
     <sp-menu-item>Multiply</sp-menu-item>
     <sp-menu-item>Screen</sp-menu-item>
 </sp-picker>
-<br />
-<br />
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet-pending">Pending, quiet</sp-tab>
+<sp-tab-panel value="quiet-pending">
+
+```html demo
 <sp-field-label for="picker-loading-quiet">Quiet:</sp-field-label>
 <sp-picker
     id="picker-loading-quiet"
@@ -459,7 +561,12 @@ When in pending state, `<sp-picker>` elements will not respond to click events a
 </sp-picker>
 ```
 
-## Force Popover on Mobile Devices
+</sp-tab-panel>
+</sp-tabs>
+
+## Behaviors
+
+#### Force Popover on Mobile Devices
 
 On mobile, the menu can be exposed in either a `sp-popover` or `sp-tray`. By default, `sp-picker` will render an `sp-tray`. If you would like to render `sp-popover` on mobile, add the attribute `forcePopover` to the `sp-picker`.
 
@@ -488,6 +595,71 @@ To see this functionality in action, load this page from your mobile device or u
 </sp-picker>
 ```
 
-## Accessibility
+</sp-tab-panel>
+</sp-tabs>
+
+### Accessibility
+
+#### Include a visible label
+
+Every picker should have a label. A picker without a label is ambiguous and not accessible.
+
+#### Use help text to show context
+
+A picker’s description in the help text can communicate what to select or how to select an option. This includes information such as:
+
+-   An overall description of the picker options
+-   Hints for what kind of information to choose
+-   More context for why a user needs to make a selection
+
+The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with a picker. Don’t add help text to maintain layout continuity with other inputs that require help text if it isn’t actually relevant or meaningful to a user.
+
+The help text area also displays an error message. When a picker already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the picker.
+
+Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to complete the interaction. Error text tells a user how to fix the error by re-stating the selection requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other (e.g., minimum requirements).
+
+Use [`<sp-help-text>`](../help-text/) to add help text and error text:
+
+<sp-tabs selected="help-text-demo" auto label="Using help text">
+<sp-tab value="help-text-demo">Help text</sp-tab>
+<sp-tab-panel value="help-text-demo">
 
-To render accessibly, an `<sp-picker>` element should be paired with an `<sp-field-label>` element that has a `for` attribute referencing the `id` of the `<sp-picker>` element. For an accessible label that renders within the bounds of the picker itself, but still fulfills the accessibility contract, use the `label` attribute or a `<span slot="label">` as a child element of `<sp-picker>`.
+```html demo
+<sp-field-label for="text">Preferred contact method:</sp-field-label>
+<sp-picker id="text" label="Select contact method" aria-describedby="help-text">
+    <sp-menu-item>Phone</sp-menu-item>
+    <sp-menu-item>Text</sp-menu-item>
+    <sp-menu-item>Email</sp-menu-item>
+</sp-picker>
+<sp-help-text id="help-text">
+    Choose the best way to contact you in case there's an issue with your
+    account.
+</sp-help-text>
+```
+
+</sp-tab-panel>
+<sp-tab value="error-text-demo">Error text</sp-tab>
+<sp-tab-panel value="error-text-demo">
+
+```html demo
+<sp-field-label for="error-text" required invalid>
+    Preferred contact method:
+</sp-field-label>
+<sp-picker
+    id="error-text"
+    invalid
+    label="Select contact method"
+    required
+    aria-describedby="error-help-text"
+>
+    <sp-menu-item>Phone</sp-menu-item>
+    <sp-menu-item>Text</sp-menu-item>
+    <sp-menu-item>Email</sp-menu-item>
+</sp-picker>
+<sp-help-text id="error-help-text" variant="negative">
+    Select a contact method.
+</sp-help-text>
+```
+
+</sp-tab-panel>
+</sp-tabs>