# exmg-searchbar

A customizable search bar element.

> This search bar uses mwc-textfield for the input element.
> More information about styling and the input element itself can be found on the link below:
> https://github.com/material-components/material-components-web-components/tree/master/packages/textfield

## Usage

Import this element to your project with `npm i @exmg/exmg-searchbar`.

Then add the snippet below into your code.

```html
<exmg-searchbar></exmg-searchbar>
```

### Default Filtering

ExmgSearchBar has it's own filtering methods in it which you can also override.
To achieve default filtering, take the example of html code below:

```html
<exmg-searchbar .data="${dataArray}" .filterKeys="${filterKeys}" suggestion-label-key="url"> </exmg-searchbar>
```

When you pass the data array into `data` property along with `filterKeys`, exmg-search bar automatically filters
data and shows suggestions.

`filterKeys` property has to contain specific key names from the type of each item in `data`.

For example; if you have `[{username:"exmachina",name: "Ex Machina"},{username:"livery",name:"Livery"}]` as the data array,
you can pass `['username']` to filter out `username` values of data. Or pass `['username', 'name']` to filter out values of both keys.

To determine which value of items passed into `data` should be shown as the label of each suggestion, use `suggestion-label-key` just like `filterKeys` but the only difference is, it accepts a single key as a simple string, not an array.

### Custom Suggestions and Filtering

By extending `ExmgSearchBar`, you can override any of 
three functions of your selection.
These functions are:

- `filter(data: any[], filterKeys: string[], query: string): ExmgSearchSuggestion[]: TemplateResult`
- `renderSuggestions(suggestions: ExmgSearchSuggestion[])`
- `renderSuggestionsLoading(): TemplateResult`

`filter` expects array of `ExmgSearchSuggestion` objects. By implementing your own filtering method, 
you might not need `suggestion-label-key` since you can place any string value into `text` property of `ExmgSearchSuggestion`.

Please check `ExmgSearchBar` class in order to see how these three functions are working. After that you can extend
`ExmgSearchBar` class and override those functions to create your fancy filtering methods or suggestions.

### Showing Suggestions Manually

If you are handling filtering logic manually on the parent, you can follow this way to
show suggestions manually.
To show suggestons, pass the suggestion data to `suggestions` property of `exmg-searchbar`.
It accepts array of `ExmgSearchSuggestion` type of elements into suggestions.

> Follow this document for available properties, events, methods and styling.

## Styling

| Variable                                             | Default             | Description                                      |
| ---------------------------------------------------- | ------------------- | ------------------------------------------------ |
| --exmg-searchbar-error-color                         | #b00020             | Error color of search bar                        |
| --exmg-searchbar-hint-color                          | rgba(0, 0, 0, 0.6)  | Hint text color of search bar                    |
| --exmg-searchbar-primary-color                       | #0071dc             | Primary theme color of search bar                |
| --exmg-searchbar-text-color                          | rgba(0, 0, 0, 0.87) | Text color of search bar                         |
| --exmg-searchbar-suggestions-spinner-color           | #0071dc             | Suggestions loading indicator color              |
| --exmg-searchbar-suggestions-spinner-width           | 3px                 | Suggestions loading indicator spinner width      |
| --exmg-searchbar-suggestions-max-visible-suggestions | 5                   | Max visible suggestions before showing scrollbar |
| --exmg-searchbar-suggestions-min-height              | 40px                | Suggestion item row height                       |
| --exmg-searchbar-suggestions-text-color              | rgba(0, 0, 0, 0.6)  | Suggestion item text color                       |
| --exmg-searchbar-suggestions-background-color        | #ffffff             | Suggestions list background color                |
| --exmg-searchbar-suggestions-z-index                 | 1                   | z-index of suggestions list                      |
| --exmg-searchbar-width                               | 100%                | Width of search bar                              |

## Properties

| Name                    | Type                   | Default     | Description                                                                                                                                     |
| ----------------------- | ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| filterKeys              | string[]               | `undefined` | Set of which keys of `data` should be checked to filter data by default.                                                                        |
| data                    | any[]                  | `undefined` | The data in search bar to filter.                                                                                                               |
| keepFocus               | boolean                | `false`     | If true, keeps focus on search bar after `query-submit` is fired                                                                                |
| keepSuggestionsOnSelect | boolean                | `false`     | Option to whether keep suggestions visible or not on suggestion selection                                                                       |
| submitKeys              | string[]               | `['ENTER']` | Determines which keys should trigger submitting search query                                                                                    |
| notifyOnQueryChange     | boolean                | `true`      | If true, dispatches `query-change` event with the current query on every change of search input.                                                |
| searchQuery             | string                 | `''`        | Current query of search bar                                                                                                                     |
| suggestionLabelKey      | string                 | `undefined` | Defines which property of each data item should be placed into suggestions' labels.                                                             |
| submitOnKeyPress        | boolean                | `true`      | If true, dispatches `query-submit` event with the current query upon receiving key press event with specific keys passed to `keys` string array |
| suggestions             | ExmgSearchSuggestion[] | `[]`        | List of suggestions to be passed into and displayed                                                                                             |
| suggestionsLoading      | boolean                | `false`     | If true and there are no suggestions passed to element, a loading indicator should be shownbar                                                  |

## Events

#### @query-change

Fired on query change.

Payload: `{value: string}`

#### @query-submit

Fired on query submit.

Payload: `{value: string}`

#### @suggestion-select

Fired on suggestion selection.

This event is also fired when 
there is only one suggestion
and user submits query.

Payload: `{value: any, index: number}`

## Methods

#### clearSuggestions()

Clears suggestions.

#### hideSuggestionsLoading()

Hides the loading indicator.

#### search()

Fires `query-submit` event with passed query into search bar.

#### setQuery(query: string)

Sets query.

#### setSuggestions(suggestions: ExmgSearchSuggestion[])

Sets `suggestions`.

#### showSuggestionsLoading()

Shows the loading indicator if there are no suggestions available.