import { Badge } from 'terra-form-select/package.json?dev-site-package';

import AllowClearExample from './example/single/AllowClear?dev-site-example';
import ControlledExample from './example/single/Controlled?dev-site-example';
import SingleSelectExample from './example/single/SingleSelect?dev-site-example';
import DisabledExample from './example/single/Disabled?dev-site-example';
import InvalidExample from './example/single/Invalid?dev-site-example';
import IncompleteExample from './example/single/Incomplete?dev-site-example';
import MaxHeightExample from './example/single/MaxHeight?dev-site-example';
import OptGroupExample from './example/single/OptGroup?dev-site-example';

import SingleSelectPropsTable from 'terra-form-select/lib/SingleSelect?dev-site-props-table';
import OptionPropsTable from 'terra-form-select/lib/shared/_Option?dev-site-props-table';
import OptGroupPropsTable from 'terra-form-select/lib/shared/_OptGroup?dev-site-props-table';

<Badge />

# Terra Form Single Select

The Single Select component allows selecting a single option from a dropdown of selectable options.

Consumers are encouraged to use the `SingleSelectField` component over the `SingleSelect` component wherever possible, as the latter does not provide the labels necessary to support accessibility.

To create an accessible `SingleSelect` component:
1. Ensure that `SelectField` can receive keyboard focus.
2. Ensure that `SelectField` programmatically associates all related content (such as visible label, helper text & error messaging) to the field.
3. Ensure any visible `SelectLabel` matches any artificially applied programmatic label.
4. Error messaging should provide error suggestions when the system can programmatically understand what is wrong.

To close the combobox while using JAWS with VPC **ON** mode, user have to press escape key twice. The first escape key press loses the VPC focus and the second escape key press closes the single select as it has control focus.

## Getting Started

- Install with [npmjs](https://www.npmjs.com):
  - `npm install terra-form-select`

<!-- AUTO-GENERATED-CONTENT:START Peer Dependencies -->

## Peer Dependencies

This component requires the following peer dependencies be installed in your app for the component to properly function.

| Peer Dependency | Version |
|-|-|
| react | ^16.8.5 |
| react-dom | ^16.8.5 |
| react-intl | ^2.8.0 |

<!-- AUTO-GENERATED-CONTENT:END -->

## Implementation Notes:

The Form-Select component must be composed inside the [Base][1] component with a locale in order for it to load the correct translation strings.

[1]: /components/cerner-terra-core-docs/base/about

## Usage

```jsx
import { SingleSelect } from 'terra-form-select';
```

## Component Features

- [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-support)
- [Responsive Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#responsive-support)
- [Mobile Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#mobile-support)
- [Internationalization Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#internationalization-i18n)
- [Localization Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#internationalization-i18n)
- [LTR/RTL Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#ltr--rtl)

## Examples
<SingleSelectExample description="A Single Select allows selecting a single option." />
<DisabledExample />
<InvalidExample description="Applies theme-specific styling for invalid. Will also display error text when used with a Field." />
<IncompleteExample description="Applies theme-specific styling for incomplete. ***Note: Only use incomplete if given specific guidance, reserved for specific applications when no value has been provided. Not for general use.***" />
<OptGroupExample title="Ability to add Option Groups" description="An OptGroup provides a way to group options together within the listbox." />
<MaxHeightExample title="Ability to set a Maximum Height" description="An example of implementing a custom max height of the dropdown." />
<AllowClearExample title="Ability to Clear Selection" description="An example with an option to clear the selected item." />
<ControlledExample title="Create a Controlled Single Select" description="An example of implementing a controlled Single Select." />

## Single Select Props
<SingleSelectPropsTable />

## Option Props
<OptionPropsTable />

## OptGroup Props
<OptGroupPropsTable />