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

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 an array of possible values for the autocomplete behavior.

Example:

<input type="text" [igxAutocomplete]="completions" />

Acceptance criteria

1. Pass an array of data which will act as the source for autocompletion.
2. Keyboard navigation both inside the drop down panel and the text input while keeping the focus inside the text input.
3. Selection; with mouse/touch and keyboard.
4. A condition function for filtering the passed items for the user. A sane default should be provided off the shelf and the user should be able to provide a custom one.
   • [Open for consideration] - the default condition will be case-insensitive startsWith

User Stories

Developer

As a developer, I want to be able to:

1. provide my own template for the items in the suggestion panel.
2. provide my own function which will act as a filter for the items displayed in the suggestion panel.
3. control and modify where and how is the panel rendered.
4. listen to and react when a end-user selects an item from the panel.

End-User

• TBD

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

• Drop down navigation

  • Navigate through items with Arrow Up/Down
  • Auto highlight first match when igxAutocompleteHighlightMatch is true

• Item selection

  • Update model on item selection

• Templating

• Custom filtering

• 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.
• igxAutocompleteCondition: a user provided function with the signature (value: any, term: any) -> boolean which will act as a filtering condition for the suggestion panel.
• igxAutocompleteSettings: OverlaySettings to be applied when rendering the suggestion panel.
• igxAutocompleteItemTemplate: A TemplateRef which when passed in will allow the users custom templating.
• igxAutocompleteDisabled: Enable/disable the directive. Does not affect the host component/element.
• igxAutocompleteHighlightMatch: Highlight first match in the drop down

6. Assumptions and Limitations

• igxAutocompleteSettings will be limited to positioning strategy settings

7. References

igxAutocomplete issue

Angular Material Autocomplete

ARIA 1.1 Combobox role and ARIA 1.1 Combobox with Listbox Popup Examples