DropDown Specification

Revision History

Version	User	Date	Notes
0.1	Alexander Marinov	April 20, 2018	Initial Draft
0.2	Milko Venkov	April 25, 2018	Add changes to API
0.3	Alexander Marinov	May 3, 2018	Add changes to API

1. Overview

Objectives

The igx-dropdown should display a list of items and should support selection of a single item.

The igx-dropdown should display a scrollable list of items which may be visually grouped. Clicking or tapping an item should select the item and should close the drop down.

The igx-dropdown should appear above all other in-app UI elements.

2. User Stories

As an end user, I want

to see a dropdown list of available choices
to select a choice using a mouse click
to select a choice using the SPACE and ENTER keys
to see the dropdown above all other elements on the page
to scroll the list of choices if they are too many
to be able to scroll navigate through the items using Up/Down arrow keys and Home/End keys.
to see the choices grouped if applicable
to close the dropdown by selecting an item or by pressing the ESC key
the dropdown to preserve selection
to have visual clue if a choice from the list is not selectable
to have visual clue if a choice from the list is selected, focused or hovered.
to change the selected values indefinitely, so that I can change my choice.
to have or not animations on dropdown open, so that I have a meaningful interactions.
to have dropdown opening positions that are meaningful and dependent on my needs.
to have separators in the dropdown list, so that I have the items organized depening on my needs.

Developer Stories

As a developer, I want to

select an item
be notified, when selection has changed
be able to implement the dropdown to any kind of anchor.
open the dropdown within the viewport.
set max(min) width of the dropdown.
set max height, and if it is exeeded a vertical scroll should appear.
have vertical scroll if the dropwdown reaches a viewport edge.
be able to select from different animations or disable all animation for the dropdown opening/closing, so that the interaction is meaningful.
default opening positions (Top start, Top end, Bottom start, Bottom end, attempt to vertically align the currently selected anchor with the list item.)
be able to customize the opening position by anchor margins (Top, Bottom, Left, Right) in pixels.
add a separator in the dropdown items so that I can organize them better.

3. Functionality

3.1. End User Experience

Users are able to select an item from a predefined list of items which is displayed in the application UI.

3.2. Developer Experience

Developers are able to select items programatically like:

<igx-dropdown #dropdown [selectedItem]=2></igx-dropdown>

Developers can also subscribe to an event emitted before the item selection is completed:

<igx-dropdown #dropdown (onSelection)="itemSelection(args)"></igx-dropdown>

3.3. Keyboard Navigation

The default way to select an item from the dropdown is by mouse click. However, selection is also possible using the ENTER and SPACE keys. Pressing UP and DOWN keys is changing the focus to the previous/next item but is not changing the selection. Pressing ENTER or SPACE key is closing the dropdown after the selection is changed.

Pressing the Esc key is closing the dropdown and is not changing the selection.

Pressing the Home key is scrolling the list and set the focus to the first item which is not disabled or header.

Pressing the End key is scrolling the list and set the focus to the last item which is not disabled or header.

3.4. User Interface

Desktop:

Min Width = 2x64 Max WIdth 7x64 H of an item = 32px of an item

Тext does not wrap, if the max width is reached elipsis is applied.

3.6. API

Properties

IgxDropDownComponent

Name	Description	Type
selectedItem	Sets/Gets the selected item	number
items	Sets/Gets all the items	QueryList of IgxDropDownItemComponent
allowItemsFocus	Allows items to take focus	boolean
width	Sets the tab width of the control	string
height	Sets the tab height of the control	string
tabIndex	Sets the tab index of the control	number
zIndex	Sets the `z-index` for the control	number
ariaLabelledby	Specifies the `aria-labelledby` attribute	string

IgxDropDownItemComponent

Name	Description	Type
isSelected	Defines if the given item is selected	boolean
isDisabled	Disables the given item	boolean
isFocused	Defines if the given item is focused	boolean
isHeader	Defines if the item is a group header	boolean
tabIndex	Sets the tab index of the dropdown item	number

Methods

IgxDropDownComponent

Name	Description	Parameters
toggleDropDown	Toggles the drop down.	none
setSelectedItem	Selects a dropdown item	new selected item index

Events

IgxDropDownComponent

Name	Description	Cancelable	Parameters
onSelection	Emitted when item selection is changing, before the selection completes.	true	{ oldSelection: string, newSelection: string, event?: Event }
onOpen	Emitted when the dropdown opens	false
onClose	Emitted when the dropdown closes	false

Note: igx-dropdown API selectedItem setter will trigger the onSelection event

4. ARIA Support

We provide the ariaLabelledby property which the developer may use to provide essential information about the dropdown. If left empty, we should provide a default value.

The following components gets the corresponding aria attributes

dropdown - aria-labelledby (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute)
dropdown item - aria-label="Select item ${value}
selected item - aria-selected=true (https://www.w3.org/TR/wai-aria-1.1/#aria-selected)

5. Assumptions and Limitations

the only mode of selection will be single

multiple selection is out of scope for the dropdown component and will be provided by another component.

moving the focus up and down via the keyboard will not change selection.
Pressing the Esc key will close the dropdown, but will not update the selection.
Dropdown will not handle page up and page down key actions.
Dropdown will not close on click outside the dropdown. This should be handled by the developer by adding IgxToggleAction directive to the caller of dropdown and setting its target to point to the dropdown's IgxToggle.