# Pragma Filter Component

This document describes the required features for the pragma-filter component.

## Component

Name: pragma-filter

A input that will filter a specified data source. Data source binding must be set as component attribute

## UI

Component will contain the following elements:
1. text input with default place-holder of "Search"
1. pragma-icon-button with search svg
1. pragma-icon-button with cancel svg

## Accessibility

Below all on custom element:
1. 'aria-label' = Filter [Visualisation Title]
1. 'role' = search

## Keyboard and Focus Behaviour

1. ENTER will trigger data source filter with filter string.
1. Trigger filter on loss of focus? Would prevent the need for a search button.

## Mouse/Touch Behaviour

1. Trigger filter on search icon button click.
1. Clear filter string on cancel icon button click.

## Usage

The component is used in the HTML markup. The following is a example of how it is used.

```html
<pragma-filter datasource.bind="myDataSource" placeholder="Search"></pragma-filter>
```

## Features

#### Cache data

The original data records are cached in the group-worker on first load. This is necessary to reduce the complexity of the
filter operation which would need differing implementations to deal with flat list and perspective data. In addition,
once the filter cleared, the original data can be retrieved from the cache without the need for a remote fetch.

#### Fuzzy search

The fuzzy search operation is done in the group-worker to ensure the potentially long running operation is non-blocking
by keeping it off the main thread.

Operation will be executed by calling the filter function on the visualisation's data source object, with the filter
string passed as a parameter.

Each property of each record item will be evaluated to determine if it contains the filter string. The filtered data
will then be passed back to the visualisation data source for processing. Perspective data will be created from the
filtered data items and the visualisation will render the filtered data.

#### Managing state of input field

During filter operation, busy indicator for target visualisation will be shown and the filter string input will be made
read-only. This is done to prevent unintended filter requests while the operation is in progress. A stateChangedCallback
will be triggered on the return on filtered results. State of the loading indicator will change and the visualisation
function will be called.

#### Clear filter string

Clearing the filter string is done by clicking the clear button. This will trigger a filter with no filter string, the
group-worker will in turn return the initial cached data items. Perspective data will be recreated and the visualisation
will render the initial data.

#### V2 Features

1. Filtering of hierarchical data - 2 modes, filter entire hierarchy and filter specified level
1. Use pragma-action-icon to show animation when busy

#### Possible Enhancements

1. Relevance - percentage on filtered results
1. Drop-down listing the visualisation model property names, filter string will be updated to that selected property name
 is prefixed to filter string, i.e Code: [filter value].
1. Auto-complete listing visualisation property names
1. Selected visualisation model property names will be displayed as "tags" above the input field;
1. Can specify *AND* and *OR* operators, i.e SiteCode: A11 AND UnitCode: mm