igxAutocomplete Specification

Revision history

Version	Author	Date	Notes
0.1	Radoslav Karaivanov	2019-01-08	Initial Draft
0.2	Nikolay Alipiev	2019-01-17	Test scenarios and `igxAutocompleteHighlightMatch`
0.3	Nikolay Alipiev	2019-01-17	Assumptions and Limitations & References sections
0.4	Nikolay Alipiev	2019-01-24	Update entire specification with new requirements

Overview

The igxAutocomplete directive provides a way to enhance a text input by showing a panel of suggested options provided by the developer.

The simplest use-case for an end-user should be attaching the directive to an input element and providing to a template for the panel.

Example:

<input type="text" [igxAutocomplete]="townsPanel" />
<igx-drop-down #townsPanel>
    <igx-drop-down-item *ngFor="let town of towns | startsWith:townSelected" [value]="town">
        {{town}}
    </igx-drop-down-item>
</igx-drop-down>

Acceptance criteria

Pass an template for the panel that will act as an autocompletion drop down.
Keyboard navigation both inside the drop down panel and the text input while keeping the focus inside the text input.
Selection; with mouse/touch and keyboard.
Compatibility support

User Stories

Developer

As a developer, I want to be able to:

provide my own template for the items in the suggestion panel.
control and modify where and how is the panel rendered.
listen to and react when a end-user selects an item from the panel.
Enable and disable dynamically the autocomplete panel

End-User

Open autocomplete panel when start typing in the input.
Auto selection of the first item, so that it is easily selected with Enter key.
Keyboard navigation both inside the drop down panel and the text input while keeping the focus inside the text input.
Selection; with mouse/touch and keyboard.
Default width of the autocomplete panel should map input or its parent group container.
Closing the panel using ECS, TAB or loosing focus of the input.
Compatibility support
Disable browser default autofill

Functionality

TBD

Test Scenarios

Drop down opening
- Do not open when input is focused
- Do not open when igxAutocompleteDisabled is true
- Open when start typing in the input
- Do not open browsers' autofill drop down
Drop down closing
- Blur
- ESC
- Select item with click or ENTER
- When disabled is set to true dynamically
Drop down navigation
- Navigate through items with Arrow Up/Down
- Auto highlight first match when panel is opened
Item selection
- Update model on item selection with Enter key or mouse click
Panel settings
- Use different positioning of the autocomplete
Input properties and Output events
ARIA
Textarea
Integration with other components

WAI-ARIA Considerations

Please follow the guidelines for a combo with a listbox popup defined here.

API

Output events

Open for consideration

onItemSelected: a cancelable event which is emitted when a selection is made through mouse/touch/keyboard interaction.

Input properties

Open for consideration

igxAutocomplete: an array of objects acting as a "data source" for the suggestion panel.
igxAutocompleteSettings: OverlaySettings to be applied when rendering the suggestion panel.
igxAutocompleteDisabled: Enable/disable the directive. Does not affect the host component/element.