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

import SearchFieldPropsTable from 'terra-search-field/lib/SearchField?dev-site-props-table';
import SearchFieldBasic from './Examples.2/SearchFieldBasic?dev-site-example';

<Badge />

# Terra Search Field

## Table of Contents
* [Overview](/components/cerner-terra-core-docs/search-field/about#overview)
* [Examples](/components/cerner-terra-core-docs/search-field/about#examples)
* [Accessibility](/components/cerner-terra-core-docs/search-field/about#accessibility)
* [Implementation](/components/cerner-terra-core-docs/search-field/about#implementation)
* [Testing](/components/cerner-terra-core-docs/search-field/about#testing)
* [Properties](/components/cerner-terra-core-docs/search-field/about#properties)
* [Terra Standards](/components/cerner-terra-core-docs/search-field/about#terra-standards)

## Overview

A search component with a field that automatically performs a search callback after user input. This component has an input field with a clear button to clear entered text and a search button. 

<SearchFieldBasic title='Basic Search Field' />

### Features
Supports:
* Management of label visibility above the search field.
* Placeholder text
* Minimum length of search text required before performing autosearch.
* Search delay
* Default search text
* Disabling of the search field.
* Disabling the Auto Formatting.
* Numeric filtering when search text is entered. 
* Programatically setting the search text to a certain value.  
* Management of invalid search text states.
* [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)

Refer to the [examples](/components/cerner-terra-core-docs/search-field/about#examples) section for detailed demonstration of the features supported by the Search Field.

**Note**: The examples display the search text on top/below the search field, that is done to demonstrate the state updates in the callback functions therefore they might not be in compliance with certain Accessibility rules.

## Examples
|Link to Example| Description|
|-|-|
|[BasicSearchField](/components/cerner-terra-core-docs/search-field/examples/search-field-basic)|An example of basic search field.|
|[SearchFieldWithDefaultLabel](/components/cerner-terra-core-docs/search-field/examples/search-field-with-default-label)|An example demonstrating search field with default label using the 'isLabelVisible' prop.|
|[SearchFieldWithCustomLabel](/components/cerner-terra-core-docs/search-field/examples/search-field-with-custom-label)|An example demonstrating search field with a custom label using the 'groupName' and 'isLabelVisible' props.|
|[SearchFieldWithNoLabel](/components/cerner-terra-core-docs/search-field/examples/search-field-with-no-label)|An example demonstrating search field with no label using the 'groupName' and 'isLabelVisible' props.|
|[SearchFieldPlaceholder](/components/cerner-terra-core-docs/search-field/examples/search-field-placeholder)|An example demonstrating search field with a placeholder using the 'placeholder' prop.|
|[SearchFieldMinimumLength](/components/cerner-terra-core-docs/search-field/examples/search-field-minimum-length)|An example demonstrating search field with a minimum search text length set using the 'minimumSearchTextLength' prop.|
|[SearchFieldDelayed](/components/cerner-terra-core-docs/search-field/examples/search-field-delayed)|An example demonstrating search field with a search delay using 'searchDelay' prop.|
|[SearchFieldDefaultValue](/components/cerner-terra-core-docs/search-field/examples/search-field-default-value)|An example demonstrating search field with a default search text value using the 'defaultValue' prop.|
|[SearchFieldDisabled](/components/cerner-terra-core-docs/search-field/examples/search-field-disabled)|An example demonstrating disabled search field using 'isDisabled' prop.|
|[SearchFieldDisabledAutoFormatAttrs](/components/cerner-terra-core-docs/search-field/examples/search-field-disable-auto-format-attrs)|An example demonstrating search field with disabled autoformat attributes using 'inputAttributes' prop.|
|[SearchFieldBlock](/components/cerner-terra-core-docs/search-field/examples/search-field-block)|An example demonstrating search field with block style using the 'isBlock' prop.|
|[SearchFieldDisableAutoSearch](/components/cerner-terra-core-docs/search-field/examples/search-field-disable-auto-search)|An example demonstrating search field with autosearch disabled using the 'disableAutoSearch' prop.|
|[SearchFieldFilterNumeric](/components/cerner-terra-core-docs/search-field/examples/search-field-filter-numeric)|An example demonstrating search field with numeric filtering using the 'onChange' callback prop.|
|[SearchFieldFocus](/components/cerner-terra-core-docs/search-field/examples/search-field-focus)|An example demonstrating search field with focus using the 'inputRefCallback' callback ref prop.|
|[SearchFieldProgrammaticSet](/components/cerner-terra-core-docs/search-field/examples/search-field-programmatic-set)|An example demonstrating search field with search text set programmatically using the 'inputRefCallback' callback ref prop.|
|[SearchFieldInvalid](/components/cerner-terra-core-docs/search-field/examples/search-field-invalid)|An example demonstrating search field with invalid text using the 'onInvalidSearch' prop.|

## Accessibility
### Keyboard Interactions

List of keyboard interactions supported by Search Field

|Key interactions|Description|
|---|---|
|Tab           | Moves focus into the search field. If already on the search text box with text entered, tab moves focus to the clear text button. If already on clear text button, tab moves followed by focus to the search button.|
|Shift + Tab    | Moves focus to the previous focusable element in the tab sequence.|
|Space| When on clear button, clears the current search text. When on search button, triggers the search callback.|
|Enter| When on clear button, clears the current search text. When on search button, triggers the search callback.|

### Assistive Technology Support
#### WAI ARIA Roles and States
* [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)
  * aria-label default value is set to 'search' for the basic search field.
  * When '[_groupName_](/components/cerner-terra-core-docs/search-field/about#search-field-props)' prop is passed in, the prop value will be used as a custom aria-label.
  * A custom aria-label value can also be passed in through '[inputAttributes](/components/cerner-terra-core-docs/search-field/about#search-field-props)' prop.
  * Consumers should provide a group name whenever possible. "Patient Search", "Global Search", "Location Search", "Find Person", etc to provide proper context to screen reader users.
  * Consumers should also make the label visible whenever possible. Hidden label for this component is a special allowance, but is not ideal.

#### Placeholder text

* Placeholder text is italicized text that lives within the input field but disappears when the user starts typing inside the form field.
* Placeholder text should not be relied on in order to prevent errors from occurring later, instead use masked entry, helper text, or a combination of both.
* Placeholder text is only appropriate when the information it conveys is not vital to the completion of the form, as such, placeholder text is reserved for specific components to provide additional details as to the type of input field:
  * Dropdown
  * Search


## Implementation

### Installation
- Install with [npmjs](https://www.npmjs.com):
  - `npm install terra-search-field`

### 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 |

### Implementation Notes:

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

[1]: https://engineering.cerner.com/terra-core/components/terra-base/base/base

### Usage

```jsx
import SearchField from 'terra-search-field';
```

## Testing

The Search Field has the following data attributes available for browser tests:

- The data attribute, `data-terra-search-field-button` can be used to select the search and clear button
  - use `data-terra-search-field-button="Search"` to select the search button
  - use `data-terra-search-field-button="Clear"` to select the clear button

```js
describe('SearchField', () => {
  it('searches the text in search field', () => {
    browser.click('#Search_Field_Id > [data-terra-search-field-button="Search"]');
    Terra.validates.element('open', { selector: '#root' });
  });

  it('clears the text in search field', () => {
    browser.click('#Search_Field_Id [data-terra-search-field-button="Clear"]');
    Terra.validates.element('closed', { selector: '#root' });
  });
});
```

## Properties

### Search Field Props
<SearchFieldPropsTable />

## Terra Standards
* [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-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)
* [LTR/RTL Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#ltr--rtl)