IgxSelect Specification

Revision History

Version	User	Date	Notes
0.1	Milko Venkov	Dec 12, 2018	Initial Draft
0.2	Milko Venkov	Jan 07, 2019	Placeholder and form scenarios added

1. Overview

Objectives

The igxSelect provides an input with dropdown list allowing selection of a single item.

2. User and Developer Stories

User Stories

As an end user, I want to:

have an input that allows me to select a single item from a dropdown list
be able to easily and quickly navigate through the list of items
be able to select and confirm one option from the dropdown list by using my keyboard
be able to close the dropdown list without selecting anything
see the currently selected item when opening the dropdown list

Developer Stories

As a developer, I want to:

get/set the value that is selected
clear the selected value
set place holder to show in the input when there is no selected value
bind the control to an array of primitive values (string, number, etc.)
bind the control to an array of objects and:
- be able to specify which property should be used for the text shown in list items
- be able to specify which property should be used for the value of the list items
bind the control to a remote set of data
specify a template for the way data should be visualized inside the dropdown list
be notified, when the value of the input has changed
be notified, when the dropdown list of the input is shown
be notified, when the dropdown list of the input is hidden
put igxSelect on a form and validate the input

3. API

API

Properties

IgxDropDownComponent

Name	Description	Type
selectedItem	Gets the selected item	IgxDropDownItemComponent
items	Gets all non-header items	IgxDropDownItemComponent[]
headers	Gets all header items	IgxDropDownItemComponent[]
allowItemsFocus	Allows items to take focus	boolean
width	Sets/gets the tab width of the control	string
height	Sets/gets the tab height of the control	string
id	Sets/gets the dropdown's id	string
element	Get dropdown html element	HtmlElement
collapsed	Gets if the dropdown is collapsed	bool

IgxDropDownItemComponent

Name	Description	Type
isSelected	Sets/Gets if the item is the currently selected one in the dropdown	boolean
disabled	Sets/gets if the given item is disabled	boolean
isFocused	Sets/gets if the given item is focused	boolean
isHeader	Sets/gets if the given item is header	boolean
index	Gets item index	number
elementHeight	Gets item element height	number
element	Get item html element	ElementRef

Note: igx-dropdown-item API isSelected setter will not trigger the onSelection event

Methods

IgxDropDownComponent

Name	Description	Parameters
toggle	Toggles the dropdown	overlaySettings?
open	Opens the dropdown	overlaySettings?
close	Closes the dropdown	none
setSelectedItem	Select an item by index	new selected item index

Events

IgxDropDownComponent

Name	Description	Cancelable	Parameters
onSelection	Emitted when item selection is changing, before the selection completes	false	{ISelectionEventArgs}
onOpening	Emitted before the dropdown is opened	false
onOpened	Emitted after the dropdown is opened	false
onClosing	Emitted before the dropdown is closed	false
onClosed	Emitted after the dropdown is closed	false

Note: igx-dropdown API setSelectedItem method will trigger the onSelection event

4. Test Scenarios

Automation

Input text box is read-only
Dropdown list gets displayed when
- input filed is pressed
- dropdown button is pressed
- down arrow + ALT keys are pressed
- ENTER key is pressed when select is active
- SPACE key is pressed when select is active
When opened the dropdown list can be closed by
- click on an item of the dropdown list
- pressing up arrow + ALT keys
- pressing ENTER key
- pressing SPACE key
- pressing ESC key
- clicking outside the dropdown list
When dropdown list is closed and input is active
- pressing up/down arrow keys selects previous/next selectable item
- pressing home/end keys selects first/last selectable item
- typing in the input should select first item matching the typed input
An item from the dropdown list can be selected by
- mouse click
- ENTER key when item is focused
- setting the selectedItem property in code
igSelect allows single-selection only, there is always one or no dropdown item selected.
The input text box is populated with the selected item value.
The input text box is empty when none of the items is selected and placeholder is not set.
The input text box is populated with placeholder value when none of the items is selected and placeholder is set.
When an item from the dropdown list is focused but not selected, its value is not appended to the input field.
While opening the dropdown list, if there is selected item, the text of the selected item should be placed exactly above the input
While opening the dropdown list, if there is selected item and there is not enough screen space to place selected item over the input's text, dropdown list should be displayed above or bellow the input
The dropdown list can be closed without selecting anything
onOpening/onClosing event is fired on opening/closing the dropdown list
onOpened/onClosed event is fired after the dropdown list has been opened/closed
Pressing Home key scrolls up to the first non-disabled item of the dropdown list
Pressing End key scrolls down to the last non-disabled item of the dropdown list
Key navigation through disabled items should skip the disabled items
Vertical scrollbar is visible only when the items does not fit inside the dropdown list container
Dropdown list appearance can be customized by applying templates
When using key navigation to move up and down the items list the current item is focused and movement starts from the last selected item if any or from the first item in the list if no list item is selected
onSelectionChange event is triggered when an item is being selected
Selected item is highlighted in the dropdown list
IgxSelect can be bound to an array of primitive data, array of objects or remote service
IgxSelect applies all appropriate classes on initialization
The items can be disabled/enabled at runtime
The dropdown list should persist selection through scrolling
Disabled items cannot be focused
Disabled items cannot be selected
Add igxSelect on a form and validate its input

Manual

The IgxSelect's list shows/hides in a timely manner with a big number of items
Focus is changed in a timely manner when navigating via keyboard
The user may have more than one IgxSelect controls on the same page.
The IgxSelect's list content should not "flicker" when opening

5. ARIA Support

In 2014 the W3C finalized their WAI-ARIA specification which defined how to design Web content and Web applications to be more accessible to users with disabilities. The IgxSelect has been designed so that it follows these guidelines.

The IgxSelect is decorated with

combobox role
aria-haspopup="listbox" attribute to indicate that IgxSelect can popup a listbox to suggest values
aria-owns attribute referring the element holding listbox items
aria-expanded attribute showing if listbox is visible

The dropdown button of IgxSelect is decorated with: