diff --git a/packages/react-select/Spec.md b/packages/react-select/Spec.md new file mode 100644 index 0000000000000..29cf862cbd2b0 --- /dev/null +++ b/packages/react-select/Spec.md @@ -0,0 +1,243 @@ +# @fluentui/react-select Spec + +## Background + +The Select component allows users to select one value from a predefined set of values. It does so by providing a styled wrapper around the HTML `` +- Native-feeling cross platform UX (particularly on mobile) is a primary concern +- Performance, accessibility, and bundle size are primary concerns + +Combobox is recommended if any of the following are needed: + +- Filtering or freeform text input +- Virtualization +- Control over styling the dropdown and options +- Multiple selection + +## Prior Art + +The [Open UI research on Select](https://open-ui.org/components/select.research) combines both the ideas of the proposed Fluent Combobox and Select. There is also an [Open UI draft describing the select element](https://open-ui.org/components/select). + +### Comparison of v8 and v0 + +`@fluentui/react` has three different controls that are different flavors of select/combobox: + +- [Combobox](https://developer.microsoft.com/en-us/fluentui#/controls/web/combobox): an editable combobox with a textfield and dropdown listbox +- [Dropdown](https://developer.microsoft.com/en-us/fluentui#/controls/web/dropdown): a non-editable combobox with dropdown listbox +- [Pickers](https://developer.microsoft.com/en-us/fluentui#/controls/web/pickers): an editable combobox with greater customization, particularly in displaying selected items + +`@fluentui/react-northstar` has one combobox control: + +- [Dropdown](https://fluentsite.z22.web.core.windows.net/0.51.2/components/dropdown/definition): either an editable or non-editable combobox with a tag-like approach to selected items + +### Functional variations across v8 and v0 components + +The main functional variants in existing components are as follows: + +- Editable vs. non-editable: editable comboboxes have a textbox and allow the user to type, which optionally filters the listbox +- Within editable comboboxes: freeform text input and filtering on input are optional +- Within editable comboboxes: When a typed value does not match an option, it can be cleared or preserved on blur +- Single vs. multiselect +- Within multiselect: selected options may be presented as text within the combobox value, pills, or a custom render. + +### Dropdown options variations across v8 and v0 Components + +- Options may have an icon, image, text + description, or entirely custom render +- Options may be grouped with a group header and divider +- There may be a "load more results" action +- Within multiselect: There may be a "Select all" option + +## Sample Code + +Default/standard Select: + +```tsx + + +``` + +Select with grouped options: + +```tsx + + +``` + +Inline Select with appearance and size set: + +```tsx + + +``` + +Disabled Select with second option selected: + +```tsx + + +``` + +## Variants + +### Layout + +- Block (default) +- Inline + +### Size + +- Small +- Medium (default) +- Large + +### Appearance + +- Filled darker +- Filled lighter +- Outline (default) +- Transparent + +### Unsupported Select variants + +#### Multiple Selection + +The Select component does not support multi-select, and does not support the native `multiselect` attribute. Multiple selection is instead provided through the Combobox component. This is because the native `` over using the native element directly. + +#### Size attribute + +For similar reasons to `multiple`, the native `size` attribute is not supported out of the box. It also has very limited styling support, and therefore also has little benefit over the native ``. + +## API + +From [Select.types.tsx](https://github.com/microsoft/fluentui/blob/master/packages/react-select/src/components/Select/Select.types.ts) + +### Slots + +In this component, `select` is the primary slot. Since `select` is primary, `root` is a separate explicit slot to customize the wrapper. + +```ts +export type SelectSlots = { + /** Root of the component, renders as a ``. */ + root: IntrinsicShorthandProps<'span'>; + /** The actual `` element. The only children that are supported in practice are the `` and `