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
0.4	Nikolay Alipiev	2019-02-08	Features
0.5	Nikolay Alipiev	2019-02-12	Home/End - default browser HTML input behavior
0.6	Nikolay Alipiev	2019-02-20	Update ARIA section

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

Keyboard navigation

The following keyboards can be used when navigating through the drop down items:

Arrow Down, Arrow Up, Alt + Arrow Down, Alt + Arrow Up will open drop down, if closed.
Typing in the input will open drop down, if closed.
Arrow Down - will move to next drop down item, if drop down opened.
Arrow Up - will move to previous drop down item, if drop down opened.
Enter will confirm the already selected item and will close the drop down.
Esc will close the drop down.

Note: When autocomplete is opened an then the first item in the list is automatically selected. The same is valid when list is filtered.

Note: The behavior of the other keyboard combinations will be the default HTML input behavior

Selection and model binding

When value is selected in the drop down, then input element value is automatically updated. In order to achieve that define the value property of the drop down item and bind it. Then on selection, the autocomplete will update the bound input value:

<igx-input-group class="group">
    <input igxInput name="towns" type="text" [(ngModel)]="townSelected" required
        [igxAutocomplete]='townsPanel'/>
    <label igxLabel for="towns">Towns</label>
</igx-input-group>
<igx-drop-down #townsPanel>
    <igx-drop-down-item *ngFor="let town of towns" [value]="town">
        {{town}}
    </igx-drop-down-item>
</igx-drop-down>

@Component({
    selector: 'app-autocomplete-sample',
    styleUrls: ['autocomplete.sample.css'],
    templateUrl: `autocomplete.sample.html`
})
export class AutocompleteSampleComponent {
    townSelected;
    constructor() {
        this.towns = [ 'Sofia', 'Plovdiv', 'Varna', 'Burgas'];
    }
}

Enable/Disable autocomplete drop down

The following sample defines igxAutocompleteDisabled, which allows to dynamically enable and disable the autocomplete drop down:

<igx-input-group class="group">
    <input igxInput name="towns" type="text"
        [igxAutocomplete]='townsPanel'
        [igxAutocompleteDisabled]="disabled"/>
    <label igxLabel for="towns">Towns</label>
</igx-input-group>
<igx-drop-down #townsPanel>
    <igx-drop-down-item *ngFor="let town of towns">
        {{town}}
    </igx-drop-down-item>
</igx-drop-down>
<igx-switch name="toggle" [(ngModel)]="!disabled"></igx-switch>

@Component({
    selector: 'app-autocomplete-sample',
    styleUrls: ['autocomplete.sample.css'],
    templateUrl: `autocomplete.sample.html`
})
export class AutocompleteSampleComponent {
    disabled;
    constructor() {
        this.towns = [ 'Sofia', 'Plovdiv', 'Varna', 'Burgas'];
    }
}

Note: When autocomplete is dynamically disabled, then it will be automatically closed.

Drop Down settings

The igx-autocomplete drop down positioning, scrolling strategy and outlet can be configured using, the igxAutocompleteSettings option. It allows values from type AutocompleteOverlaySettings.

The following example displays that the positioning of the drop down can be set to be always above the input, where the directive is applied. It also disables opening and closing animations. For that purpose the ConnectedPositioningStrategy is used:

<igx-input-group #inputGroup>
    <input igxInput name="towns" type="text"
        [igxAutocomplete]='townsPanel'
        [igxAutocompleteSettings]='settings'/>
    <label igxLabel for="towns">Towns</label>
</igx-input-group>
<igx-drop-down #townsPanel>
    <igx-drop-down-item *ngFor="let town of towns">
        {{town}}
    </igx-drop-down-item>
</igx-drop-down>

@Component({
    selector: 'app-autocomplete-sample',
    styleUrls: ['autocomplete.sample.css'],
    templateUrl: `autocomplete.sample.html`
})
export class AutocompleteSampleComponent {
    constructor() {
        this.towns = [ 'Sofia', 'Plovdiv', 'Varna', 'Burgas'];
    }
    @ViewChild('inputGroup', { read: IgxInputGroupComponent }) inputGroup: IgxInputGroupComponent;
    this.settings = {
        positionStrategy: new ConnectedPositioningStrategy({
            closeAnimation: null,
            openAnimation: null,
            verticalDirection: VerticalAlignment.Top
        })
    };
}

Note: The default positioning strategy is AutoPositionStrategy and drop down is opened according to the available space.

Compatibility support

Applying the igxAutocomplete directive will decorate the element with the following aria attributes:

role="combobox" - role of the element, where the directive is applied.
aria-autocomplete="list" - indicates that input completion suggestions are provided in the form of list
aria-haspopup="listbox" attribute to indicate that igxAutocomplete can pop-up a container to suggest values.
aria-expanded="true"/"false" - value depending on the collapsed state of the drop-down.
aria-owns="dropDownID" - id of the drop-down used for displaying suggestions.
aria-activedescendant="listItemId" - value is set to the id of the current active list element.

The drop-down component, used as provider for suggestions, will expose the following aria attributes:

role="listbox" - applied on the igx-drop-down component container
role="group" - applied on the igx-drop-down-item-group component container
role="option" - applied on the igx-drop-down-item component container
aria-disabled="true"/"false" applied on igx-drop-down-item, igx-drop-down-item-group component containers when they are disabled.

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 close() method
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 DO NOT scroll up/down to the first/last item if any, but instead move the caret to the start/end of the input.
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 Open using the arrow keys (Arrow Down, Arrow Up, Alt + Arrow Down, Alt + Arrow Up)
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 handle autocomplete being attached to number inputs.
It should be able to re-type the same value when it is reset while open.

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. AutoPositionStrategy is default strategy
igxAutocompleteDisabled: Enable/disable the directive. Does not affect the host component/element.