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
0.6	Ivaylo Ganchev	Feb 05, 2019	Update positioning and keyboard navigation
0.7	Ivaylo Ganchev	Feb 15, 2019	Cleanup and fixed screenshot reference
0.8	Stefan Ivanov	Oct 07, 2019	Adding header/footer template story
0.9	Ivaylo Ganchev	Oct 24, 2019	Adding select-item text @Input description-v8.2.6
1.0	Stefan Ivanov	June 1, 2020	Adding user story for ellipsis
1.1	Ivaylo Ganchev	Jun 19, 2020	Add label, hint, prefix, suffix info

1. Overview

Objectives

The igxSelect provides input with a dropdown list allowing the 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
when the item content/text is too long to cut it and add ... to fit the available width (ellipsis).

Developer Stories

As a developer, I want to:

get/set the value that is selected
get/set the select-item text to be displayed in the input field upon item selection.
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
add a header/footer template in the dropdown to precede/follow the list of values with content defined by me
be able to project content - set igxLabel, igxHint, igxPrefix OR igxSuffix directives.

End User Experience

Scenarios:

Enough space on top&bottom. Always display the selected item on top of the input. If there is scroll, scroll to the selected item as well. (Imgs 1.1, 1.2, 1.3)
Not enough space on top to display all the visible list items above the selected item: (Imgs 2.1, 2.2, 2.3)
- Display the items list starting on top of the input and list the items below.
- There is some partial space on top for one/several items + padding 5px. Display the items list in the visible port with default padding (5px). The container is scrolled with the remaining distance in order to Display the selected item on top of the input.(Img 2.2)
- Display the items list starting on top of the input and list the items below. Selected item is visible. (not enough space on top & no more scrolling )(Img 2.3)
Not enough space on bottom to display all the visible list items bellow the selected item: (Imgs 3.1, 3.2, 3.3)
- Display the items list starting on top of the input and list the items above.(Img 3.1)
- There is some partial space on bottom for one/several items + padding 5px. Display the items list in the visible port with default padding (5px). The container is scrolled with the remaining distance in order to Display the selected item on top of the input.(Img 3.2)
- Display the items list starting on top of the input and list the items above. Selected item is visible. (not enough space on bottom & no more scrolling ) (Img 3.3)
Less items and no scroll (Imgs 4.1, 4.2, 4.3)
- Not enough space on top or bottom – display all items in one direction starting on top of the input.(Imgs 4.1, 4.3)

3. Functionality

3.1. Keyboard Navigation

Dropdown list gets displayed when:
- input field is clicked
- dropdown button is clicked
- inputGroup area is clicked - incl. label, prefix and suffix. (excluding hint)
- 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 a selectable item (including already selected) of the dropdown list (excluding disabled, header, group header)
- dropdown button click
- inputGroup area is clicked - incl. label, prefix and suffix. (excluding hint)
- pressing up/down arrow + ALT keys
- pressing ENTER key
- pressing SPACE key
- pressing ESC key
- pressing TAB key
- pressing SHIFT + TAB keys
- clicking outside the dropdown list (input blur)
An item from the dropdown list can be selected by:
- mouse click
- ENTER key when item is focused
- SPACE key when item is focused
When expanded, the list items are navigable with up and down arrow keys and navigation is not wrapped.
HOME/END keys scroll up/down to the first/last list item and focus it when dropdown is expanded.
When the component is collapsed and focused, the user can navigate and select list items with up and down arrow keys. Navigation is not wrapped.
Character key/s iteratively navigate through all item values that start with the corresponding character/s. It is case insensitive and wraps selection.

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
type	Sets Input Group style type.	string / `line`, `box` or `border`
displayDensity	Sets Input Group displayDensity.	string / `compact`, `cosy` or`comfortable`
placeholder	Sets the Select placeholder.	string

IgxSelectItemComponent

Name	Description	Type
value	The item value.	any
text	Sets/Gets item's text to be displayed in the input when the item is selected.	string
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

Dropdown list is expanded 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
- using API open()/toggle() methods
When opened the dropdown list can be collapsed by:
- click on an item of the dropdown list
- pressing up/down arrow + ALT keys
- pressing ENTER key
- pressing SPACE key
- pressing ESC key
- pressing TAB key
- pressing SHIFT + TAB keys
- clicking outside the dropdown list
- dropdown button is clicked again
- using API close()/toggle() methods
The container is not displayed if the items property is not set.
Opening/closing events are emitted on input click.
Closing events are emitted on item click.
Opening/closing events are emitted on toggle button click.
Opening/closing events are triggered on key interaction.
Closing events are emitted on clicking outside the component (input blur).
When dropdown list is opened, items are navigable with Home, End and arrow keys.
When dropdown list is opened, items are navigable with Up/Down arrow keys until there are list items and selection is not wrapped.
When dropdown list is opened, navigation with Up/Down arrow starts from the selected item if any or first list item otherwise.
When dropdown list is opened, navigation with Up/Down arrow keys skips disabled items.
When Dropdown list is opened, pressing character key/s iteratively navigates through all item values that start with the corresponding character
Character key navigation when dropdown is opened is case insensitive
Character key navigation when dropdown is opened wraps selection
When Dropdown list is opened, pressing non-English character key/s iteratively navigates through all item values that start with the corresponding character
Character key navigation when dropdown is opened does not change focus on pressing non-matching characters
When Dropdown list is closed, interaction with Up/Down arrow keys navigates through items selecting the current one until there are list items and selection is not wrapped.
When dropdown list is closed, navigation with Up/Down arrow starts from the selected item if any or first list item otherwise.
When dropdown list is closed, navigation with Up/Down arrow keys skips and does not select disabled items.
In case there is an item with no value set, it will be possible to navigate with Up/Down arrow keys trough it when the select is in collapsed state(clearing input value).
When Dropdown list is closed, pressing character key/s iteratively selects through all item values that start with the corresponding character
Character key navigation when dropdown is closed is case insensitive
Character key navigation when dropdown is closed wraps selection
When Dropdown list is closed, pressing non-English character key/s iteratively navigates through and selects all item values that start with the corresponding character
Character key navigation when dropdown is closed does not change selection on pressing non-matching 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
- setting item's selected property
The igxSelect allows single-selection only
First item in the dropdown list is focused if there is not a selected item.
The input box is populated with the selected item value
The input box text is updated when the selected option text is changed
The input box is not populated with the text of an item that is focused but not selected
No text is appended to the input box when no item is selected and value is not set or does not match any item
By default, the select component will use the selected item element innerText to be displayed in the input field when selecting this item. If a select-item text property is set, it will take precedence over the item's element innerText.
Selection is cleared when setting the value property to non-existing item value
Disabled items are not selectable (both as user interaction AND trough API)
Group headers are not selectable
Selection is removed if selected option has been deleted
When value is set to the value of duplicated items, the first one gets selected
onSelection event is emitted on item selection by mouse click
onSelection event is emitted on item selection by ENTER/SPACE key
onSelection event is emitted on setting the value property
onSelection event is emitted on setting item's selected property
The component renders all aria attributes properly
All aria attributes of the dropdown items are set properly
Selected item is displayed over the input when there is enough space above and below the input.
The component scrolls to the selected item and displays it over the input when there is enough space above and below the input.
When there is some space above the input for one/several items to be displayed and first item is selected, the list displays starting from the input top left point so that the selected item is over the input.
When there is some space above the input for one/several items to be displayed and the selected item is in the middle of the list, the list displays above as many items as possible so that the selected item is over the input.
When there is some space above the input for the dropdown list to be displayed and one of the last items is selected, the dropdown is displayed over the input so that it starts from its top left point and the selected item is visible.
When there is some space below the input for one/several items to be displayed and last item is selected, the list displays starting from the input bottom left point so that the selected item is over the input.
When there is some space below the input for one/several items to be displayed and the selected item is in the middle of the list, the list displays above and below as many items as possible so that the selected item is over the input.
When there is some space below the input for the dropdown list to be displayed and first item in list is selected, the dropdown is displayed over the input so that it starts from its bottom left point and the selected item is visible.
Options text is indented to the input text even if there are one or more prefixes in the input
The items list default expansion arrow uses IgxSuffix and can be changed by the user.
If several IgxSuffixes are used, the expansion arrow is displayed always at the rightmost side.
Cover positioning scenarios listed in the End User Experience section above.
When the items container is opened, it is correctly re-positioned relative to the input, upon wrapper element/document X or Y axis scroll.
Disabled select - can not be interacted with as an user.
Disabled select - can select item via API.

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.
aria-labelledby- in case there is a label tag with igxLabel directive specified.
aria-activedescendant - specifies the currently active list item.