feat: add select spec (microsoft#4194)

Co-authored-by: eljefe223 <jes@microsoft.com>
Co-authored-by: Chris Holt <chhol@microsoft.com>

packages/web-components/fast-components/src/listbox-option/README.md

@@ -1,2 +1,5 @@
 # fast-option
-An implementation of an [option](https://w3c.github.io/aria/#option).
+
+An implementation of an [HTML option element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option).
+
+For more information, view the [component specification](../../../fast-foundation/src/listbox-option/listbox-option.spec.md).

packages/web-components/fast-components/src/listbox-option/index.ts

@@ -6,8 +6,8 @@ import {
 import { OptionStyles as styles } from "./listbox-option.styles";
 
 /**
- * The FAST option Custom Element. Implements, {@link @microsoft/fast-foundation#Option}
- * {@link @microsoft/fast-foundation#OptionTemplate}
+ * The FAST option Custom Element. Implements {@link @microsoft/fast-foundation#ListboxOption}
+ * {@link @microsoft/fast-foundation#ListboxOptionTemplate}
  *
  *
  * @public

packages/web-components/fast-components/src/select/README.md

@@ -1,2 +1,5 @@
 # fast-select
-An implementation of a [combobox](https://w3c.github.io/aria-practices/#combobox).
+
+An implementation of an [HTML select element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+
+For more information, view the [component specification](../../../fast-foundation/src/select/select.spec.md).

packages/web-components/fast-foundation/src/listbox-option/README.md

@@ -0,0 +1,10 @@
+---
+id: listbox-option
+title: fast-option
+sidebar_label: option
+custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-foundation/src/listbox-option/README.md
+---
+
+An implementation of an [option](https://w3c.github.io/aria/#option). To avoid namespace collisions with the [Option() constructor](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement/Option), the component class is `ListboxOption`, and our implementation is named `fast-option`.
+
+The `<fast-option>` component will only provide internals related to form association when used within a form-associated component. See the [`fast-select` component](../select/README.md) for more details.

packages/web-components/fast-foundation/src/listbox-option/listbox-option.spec.md

@@ -0,0 +1,71 @@
+# Listbox Option
+
+## Overview
+
+The `<fast-option>` component is an option that is intended to be used with `<fast-listbox>` and `<fast-select>`.
+
+**Note**: To avoid namespace collisions with the [Option() constructor](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement/Option), the component class is `ListboxOption`, and our implementation is defined as `<fast-option>`. This makes the class distinct and keeps the component tag name familiar for authors.
+
+### API
+
+*Component Name*:
+
+- `fast-option`
+
+*Attributes*:
+
+- `disabled` - disables the control and prevents user interaction.
+- `selected` - Sets the selected state of the option.
+- `defaultSelected` - Reflects the initial state of the `selected` attribute.
+- `value` - The initial value of the option.
+
+*Slots*:
+
+- *(default)* - the content of the button
+- start - often times a glyph, icon, or button precedes the content
+- end - often times a glyph, icon, or button follows the content
+
+### Anatomy and Appearance
+
+**Structure**:
+
+```html
+  <template role="option">
+    <span part="start">
+      <slot name="start"></slot>
+    </span>
+    <span part="content">
+      <slot></slot>
+    </span>
+    <span part="end">
+      <slot name="end"></slot>
+    </span>
+  </template>
+```
+
+---
+
+## Implementation
+
+```html
+<fast-listbox>
+  <fast-option>Option</fast-option>
+</fast-listbox>
+
+<fast-select>
+  <fast-option value="option">Option</fast-option>
+</fast-select>
+```
+
+### States
+
+- `disabled` - when disabled, user interaction has no effect. Disabling the parent `<fast-listbox>` or `<fast-select>` will also prevent user interaction on the `<fast-option>`.
+- `selected` - The selected state is primarily controlled by user interactions on the parent `listbox` component. Changing the `selected` property directly will force the state to change.
+
+### Accessibility
+
+*Listbox Option* is RTL compliant and follows [aria specifications for the option role](https://w3c.github.io/aria/#option).
+
+### Test Plan
+
+While testing is still TBD for our web components, I would expect this to align with the testing strategy and not require any additional test support.

packages/web-components/fast-foundation/src/listbox/README.md

@@ -0,0 +1,40 @@
+---
+id: listbox
+title: fast-listbox
+sidebar_label: listbox
+custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-foundation/src/listbox/README.md
+---
+
+An implementation of a [listbox](https://w3c.github.io/aria-practices/#Listbox). While any DOM content is permissible as a child of the listbox, only [`fast-option`](../listbox-option/README.md) elements, `option` elements, and slotted items with `role="option"` will be treated as options and receive keyboard support.
+
+The `listbox` component has no internals related to form association. For a form-associated `listbox`, see the [`fast-select` component](../select/README.md).
+
+## Usage
+
+```html live
+<fast-design-system-provider use-defaults>
+    <label id="preferred-format">Preferred Format:</label><br />
+    <fast-listbox aria-labelledby="preferred-format" name="preferred-format">
+        <fast-option value="vinyl">Vinyl Record</fast-option>
+        <fast-option value="casette">Casette</fast-option>
+        <fast-option value="cd">Compact Disc</fast-option>
+        <fast-option value="digital">Digital</fast-option>
+    </fast-listbox>
+</fast-design-system-provider>
+```
+
+## Applying custom styles
+
+```ts
+import { customElement } from "@microsoft/fast-element";
+import { Listbox, ListboxTemplate as template } from "@microsoft/fast-foundation";
+
+import { ListboxStyles as styles } from "./listbox.styles";
+
+@customElement({
+    name: "fast-listbox",
+    styles,
+    template
+})
+export class FASTListbox extends Listbox {}
+```

packages/web-components/fast-foundation/src/listbox/listbox.spec.md

@@ -0,0 +1,84 @@
+# Listbox
+
+## Overview
+
+The `listbox` component is a component that provides a navigatable list of options for the user to select from.
+
+### Background
+
+This component is used as a building block for other components in this library that need a way for users to choose distinct options from a list. The goal for `listbox` is to handle implementation details related to the [`listbox`](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox) and [`combobox`](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox) aria roles.
+
+### Features
+
+- **Single and multiple selection mode**: Users can choose one or multiple options when the `multiple` attribute is present. *(Note: While our implementation currently only supports single selection mode, multiple selection mode is being tracked in [issue #4190](https://github.com/microsoft/fast/issues/4190).)*
+- **Keyboard navigation and type-ahead**: When the `listbox` is focused, keyboard navigation with the arrow keys will cycle through the available options. Type-ahead is also supported. See [Keyboard Interaction](https://www.w3.org/TR/wai-aria-practices-1.1/#listbox_kbd_interaction) for more details.
+- Users can choose one or multiple options when the `multiple` attribute is present.
+
+### Prior Art/Examples
+
+- [W3 Example](https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-scrollable.html)
+
+---
+
+## API
+
+*Component Name*:
+
+- `fast-listbox`
+
+*Attributes and Properties*:
+
+- `disabled` - Disables the control.
+- `options` - An array of all options in the `listbox`.
+- `role` - The role of the element, defaults to "listbox".
+- `selectedOptions` - A collection of the selected options in the `listbox`.
+- `selectedIndex` - The index of the first selected option, or `-1` if nothing is selected. Setting the `selectedIndex` property will update the `selected` state of the option at the new index. Out of range values will reset the `selectedIndex` to `-1`.
+
+*Slots*:
+
+- *default* - the list of options, either `<fast-option>` or elements with `role="option"`.
+
+### Anatomy and Appearance
+
+*Structure*:
+
+```html
+<template role="listbox">
+  <slot></slot>
+</template>
+```
+
+## Implementation
+
+*With `fast-option` elements*:
+
+```html
+<fast-listbox>
+    <fast-option>Option 1</fast-option>
+    <fast-option>Option 2</fast-option>
+    <fast-option>Option 3</fast-option>
+</fast-listbox>
+```
+
+*With compatible `option`-like elements*:
+
+```html
+<fast-listbox>
+    <option>Option 1</option>
+    <div role="option">Option 2</div>
+</fast-listbox>
+```
+
+**Note**: While `<fast-option>`, `<option>`, and elements with a `role="option"` will all function, `<fast-option>` has built-in accessibility support when used with a `<fast-listbox>`. See [Listbox Option](../listbox-option/listbox-option.spec.md) for more information.
+
+### States
+
+- `disabled` - when disabled, user interaction has no effect.
+
+### Accessibility
+
+*Listbox* is RTL compliant and supports the following aria best practices for listbox [W3C aria-practices](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox).
+
+### Test Plan
+
+While testing is still TBD for our web components, I would expect this to align with the testing strategy and not require any additional test support.

packages/web-components/fast-foundation/src/select/README.md

@@ -11,13 +11,12 @@ An implementation of an [HTML select element](https://developer.mozilla.org/en-U
 
 ```html live
 <fast-design-system-provider use-defaults>
-    <label for="shirt-size">Choose a T-Shirt size:</label>
-    <fast-select id="shirt-size">
-      <fast-option value="s">Small</fast-option>
-      <fast-option value="m">Medium</fast-option>
-      <fast-option value="l">Large</fast-option>
-      <fast-option value="xl">Extra Large</fast-option>
-    </fast-select>
+  <fast-select id="shirt-size">
+    <fast-option value="s">Small</fast-option>
+    <fast-option value="m">Medium</fast-option>
+    <fast-option value="l">Large</fast-option>
+    <fast-option value="xl">Extra Large</fast-option>
+  </fast-select>
 </fast-design-system-provider>
 ```
 
@@ -34,4 +33,4 @@ import { SelectStyles as styles } from "./select.styles";
     styles,
 })
 export class FASTSelect extends Select {}
-```
+```