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

import AllowClearExample from './example/search/AllowClear?dev-site-example';
import ControlledExample from './example/search/Controlled?dev-site-example';
import SearchExample from './example/search/Search?dev-site-example';
import DisabledExample from './example/search/Disabled?dev-site-example';
import IsTouchAccessibleExample from './example/search/IsTouchAccessible?dev-site-example';
import InvalidExample from './example/search/Invalid?dev-site-example';
import IncompleteExample from './example/search/Incomplete?dev-site-example';
import MaxHeightExample from './example/search/MaxHeight?dev-site-example';
import OptGroupExample from './example/search/OptGroup?dev-site-example';

import SearchSelectPropsTable from 'terra-form-select/lib/SearchSelect?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 Search Select

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

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

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

## 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 { SearchSelect } 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
<SearchExample description="A Search Select allows selecting a single option." />
<IsTouchAccessibleExample description="Ensure accessibility on touch devices. Will render the dropdown menu in normal DOM flow with position absolute. By default, the menu renders in a portal, which is inaccessible on touch devices." />
<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 Search." />
<AllowClearExample title="Ability to Clear Selection" description="An example with an option to clear the selected item." />
<ControlledExample title="Create a Controlled Search Select" description="An example of implementing a controlled Search Select." />

## Search Select Props
<SearchSelectPropsTable />

## Option Props
<OptionPropsTable />

## OptGroup Props
<OptGroupPropsTable />