igxAutocomplete Specification

Revision history
Overview
Acceptance criteria
User Stories
- Developer
- End-User
Functionality
Test Scenarios
WAI-ARIA Considerations
API - Output events - Input properties
Assumptions and Limitations
References

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 can easily be confirmed 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

Dropdown menu popup gets displayed when
- typing a matching value in the input
- in code calling the public open() method
When opened the dropdown can be closed by
- pressing ESC key
- selecting an item with click or ENTER key
- calling the directive's onTab() method
- calling the directive's close() method
- disabling the directive dynamically
Dropdown list is not displayed on input clicking or focusing
ENTER key does not open the dropdown list when the input is empty or filled with a matching item value
SPACE key does not open the dropdown list
The autocomplete directive does not use the browsers' autofill feature
When disabled, typing a matching value in the input does not open the dropdown list
Dropdown list is populated with matching values if any, otherwise remains empty
When typing in the input, the dropdown list refreshes on every key stroke and displays the matching items only
The previously selected item value is not preserved and attached to the input
The first suggestion in the dropdown list is highlighted
onItemSelected event is triggered on item selection
Dropdown items are navigable using Arrow Up/Down keys
When dropdown list is opened, Home/End keys scroll up/down to the first/last item if any
The width of the dropdown list is equal to the input's width
The component/s that use 'igxAutocomlete' directive is positioned accordingly to the overlay settings if any
The directive can be used on HTML input or textarea element
The directive can be used with Angular Reactive forms
The dropdown list should not open using the arrow keys
When opened the dropdown can be closed by clicking outside the control
It should not throw when attempting to close the panel of a destroyed autocomplete
The dropdown list should hide when the options list is empty.
The control value should be updated when autofilling.
After an option is selected, you may continue typing inside the input.
It should clear the input if value is reset programmatically.
ARIA should set role of input to combobox.
ARIA should set role of autocomplete panel to listbox.
It should throw if the user attempts to open the panel too early.
It should handle autocomplete being attached to number inputs.
It should update the width while the panel is open.
It should update the panel width if the window is resized.
It should be able to re-type the same value when it is reset while open.

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.