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
0.3	Ivaylo Ganchev	Jan 09, 2019	Adding initial API
0.4	Ivaylo Ganchev	Jan 15, 2019	Adding Keyboard Navigation section
0.5	Ivaylo Ganchev	Jan 22, 2019	Update API section

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 iterate selection through all items that begin with a certain character by pressing that key
be able to type the first few characters of the option to select and confirm it 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
set place holder to show in the input when there is no selected value
specify a template with items for 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

End User Experience

left - closed state
center - default html select positioning of overlay
right - positioning the overlay below (like the combo)

3. Functionality

3.1. Keyboard Navigation

Dropdown list gets displayed when:
- input field is clicked
- dropdown button is clicked
- up/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/down arrow + ALT keys
- pressing ENTER key
- pressing SPACE key
- pressing ESC key
- clicking outside the dropdown list
- dropdown button is clicked again
When Dropdown list is opened, navigate through the items with Up/Down arrow keys.
When Dropdown list is opened, iteratively navigate through all items that begin with a certain character by pressing the corresponding key (speed of pressing should not matter).
When Dropdown list is opened, navigate to a certain item by rapidly typing in the first few characters.
An item from the dropdown list can be selected by:
- mouse click
- ENTER key when item is focused
- SPACE key when item is focused
- setting the value property in code

3.2. API

Properties

IgxSelectComponent

Name	Description	Type
value	Sets/Gets the IgxSelect value.	any
collapsed	Gets if the IgxSelect is collapsed.	boolean
overlaySettings	Sets optional overlay settings.	overlaySettings
disabled	Sets/Gets if the IgxSelect is disabled.	boolean

IgxSelectItemComponent

Name	Description	Type
value	The item value.	any
selected	Sets/Gets if the item is the currently selected one in the dropdown	boolean
disabled	Sets/Gets if the given item is disabled	boolean

Methods

IgxSelectComponent

Name	Description	Parameters
toggle	Toggles the IgxSelect.	overlaySettings?
open	Opens the IgxSelect.	overlaySettings?
close	Closes the IgxSelect.	none

Events

IgxSelectComponent

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

4. Test Scenarios

4.1. 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 value 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 the value property is not set or any item matches it.
In case there are several matching items with the same value the first one gets selected.
When an item is focused but not selected its value is not appended to the input.
When there is a selected item and the dropdown list is focused but not selected, its value is not appended to the input field.
When there is a selected item and the dropdown is opened the dropdown container overlays the input element so that the selected item is positioned exactly over the input element if there is enough space
When there is a selected item and the dropdown is opened the dropdown container is positioned above or bellow the input element if there is not enough space
When a prefix/es is/are applied to the input the text of the dropdown items aligns to the input text
The dropdown list can be closed without selecting anything
onOpening/onClosing event is fired on opening/closing the dropdown list and are cancelable
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 them
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 and all appropriate classes are applied
IgxSelect applies all appropriate classes on initialization
The entire component itself or the dropdown items can be disabled/enabled at runtime
The dropdown list persists selection through scrolling
Disabled items cannot be focused and/or selected. In case the value property matches a disabled item the match is disregarded and the input is empty.
The component can be used on a form and its input can be validated.
Accessibility for select should set the role of the select to combobox.
The component is decorated with the correct ARIA attributes.
The dropdown button of the component is decorated with button role and has aria-label attribute.
The items list container of the component is decorated with listbox role.
Each item in the dropdown list of IgxSelect is decorated with option role and has aria-selected or aria-disabled attribute if it is selected or disabled.
The control should not shift focus when the selected option is updated programmatically.
The select should not open if there are not any options inside.

4.2. 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 container to suggest values.
aria-owns attribute referring the element holding the listbox items.
aria-expanded attribute showing if items container is visible.

The dropdown button of IgxSelect is decorated with: