DropDown Specification - IgniteUI/igniteui-webcomponents GitHub Wiki

DropDown Specification

Overview
User Stories
Functionality
ARIA support
Assumptions and Limitations
Test scenarios
References
Dependencies

Owned by

Team Name: CodeX

Developer Name: Galina Edinakova

Designer Name:

Requires approval from

Peer Developer Name | Date:
Design Manager Name | Date:

Signed off by

Radoslav Mirchev| Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date
1	Galina Edinakova	13-Sep-2021
2	Galina Edinakova	9-Dec-2021
3	Galina Edinakova	13-Jan-2022

1. Overview

Objectives

The igc-dropdown component uses the igcToggle directive and displays a list of selectable dropdown items. The igc-dropdown should display a scrollable list of items which may be visually grouped. Clicking an item should select it and close the drop down. The igc-dropdown should appear above all other in-app UI elements.

2. User Stories

Developer Stories

As a developer, I want to

select an item
be notified, when selection has changed
be able to tie the dropdown to any kind of anchor.
open the dropdown within the viewport.
set the width of the dropdown.
set the height, and if it is exceeded a vertical scroll should appear.
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 group hierarchical data in groups without the need to flatten it?
to be able to set small, medium or large size to the dropdown and its items

As an end user, I want

to see a dropdown list of available choices
to have (or not have) a default selection
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 dropdown opening positions that are meaningful and dependent on my needs.
when the item content/text is too long to cut it and add ... to fit the available width (ellipsis).

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:

igcDropDown.select(value);
igcDropDown.select(index);

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

<igc-dropdown @igcChange="selectionChangeHandler"></igc-dropdown>

The igc-dropdown-group component can be used inside the igc-dropdown to group igc-dropdown-items. The example below illustrates how to display hierarchical data in drop down groups:

    // in example.ts
    export class MyExampleComponent {
        ...
        foods: any[] =  [{
            name: 'Vegetables',
            entries: [{
                    name: 'Cucumber',
                    refNo: `00000` 
                }, {
                    name: 'Lettuce',
                    refNo: `00001`
                },
                ...
            ]   
        }, {
            name: 'Fruits',
            entries: [{
                    name: 'Banana',
                    refNo: `10000` 
                }, {
                    name: 'Tomato',
                    refNo: `10001`
                },
                ...
            ]   
        }];
    }

    <!-- example.ts -->
   render() {
    return html`<igc-dropdown>
      ${foods.map((item) => {
        return html`
        <igc-dropdown-group>
          ${item.name}
           ${item.entries.map((food) => {
            return html`
            <igc-dropdown-item>${food.name}<igc-dropdown-item>`
        </igc-dropdown-group>`
      })}
    </igc-dropdown>`;
  }

3.3. Keyboard Navigation

The default way to select an item from the dropdown is by mouse click. Keyboard selection is done using the ENTER key. Pressing UP and DOWN or LEFT and RIGHT keys activates the previous/next item but is not changing the selection. Pressing ENTER key is closing the dropdown after changing the selection. Pressing the Esc key closes the dropdown without changing the selection.

Note: The dropdown itself has no tabIndex and is not focusable by default. This way we allow the dropdown's target to keep the focus if necessary.

3.4. API

Properties

IgcDropDownComponent

Name	Description	Type	Default value	Reflected
`open`	Sets dropdown's visibility.	Boolean	`false`	`false`
`placement`	Sets the position of the dropdown.	IgcPlacement	`bottom-start`	`false`
`positionStrategy`	The positioning strategy to use.	`'absolute' \| 'fixed'`	'absolute'	`false`
`scrollStrategy`	Determines the behavior of the dropdown while scrolling the container.	`scroll \| block \| close \| none`	`scroll`	`false`
`flip`	Whether to adjust dropdown's position based on the available space.	Boolean	`true`	`false`
`closeOnOutsideClick`	Whether the dropdown should close on clicking outside of it or its target.	Boolean	`true`	`false`
`closeOnSelect`	Whether the dropdown should close on selecting an item.	Boolean	`true`	`false`
`offset`	The amount of offset in horizontal and/or vertical direction.	{ x: number, y: number }		`false`
`sameWidth`	Whether to make the dropdown the same width as its target.	Boolean	`false`	`false`

IgcDropDownItemComponent

Name	Description	Type	Default value	Reflected
selected	Sets/Gets if the item is the currently selected one in the dropdown	Boolean	`false`	`true`
disabled	Sets/gets if the item is disabled	Boolean	`false`	`true`
value	The item's value. If not specified, defaults to the text content.	String	none	`true`

Note: igc-dropdown-item API selected setter will not trigger the igcSelect event.

Methods

IgcDropDownComponent

Name	Description	Parameters
toggle	Toggles the dropdown	none
show	Shows the dropdown	none
hide	Hides the dropdown	none
select	Selects an item by value	`new value \| index`
clearSelection	Clears current selection	none
navigateTo	Navigates to the item with specified value	`value \| index`

Events

IgcDropDownComponent

Name	Description	Cancelable	Parameters
igcChange	Emitted when item selection is changing, before the selection completes	false	{newValue}
igcOpening	Emitted before the dropdown is opened	true
igcOpened	Emitted after the dropdown is opened	false
igcClosing	Emitted before the dropdown is closed	true
igcClosed	Emitted after the dropdown is closed	false

Note: igc-dropdown select method will not trigger the igcSelect event.

IgcDropDownItemComponent

Name	Description	Cancelable	Parameters
igcSelect	Emitted when item selection is changing, before the selection completes	true	{ISelectionEventArgs}
?igcActivate	Emitted when item's active state is changing	true	{ISelectionEventArgs}

Slots

IgcDropDownComponent

Name	Description
`target`	Renders the target element
`(default)`	Renders the dropdown's content

IgcDropDownItemComponent

Name	Description
`(default)`	Renders the dropdown item's content
`prefix`	Renders the dropdown item's prefix
`suffix`	Renders the dropdown item's suffix

IgcDropDownHeaderComponent

Name	Description
`(default)`	Renders the dropdown header item's content

IgcDropDownGroupComponent

Name	Description
`(default)`	Renders the dropdown group's content
`label`	Renders the dropdown group's label

4. ARIA Support

The following components gets the corresponding aria attributes

selected item - aria-selected=true (https://www.w3.org/TR/wai-aria-1.1/#aria-selected)
dropdown list - role="listbox", aria-expanded
dropdown item - role="option"
dropdown group - role="group"
target - aria-activedescendant, aria-owns

5. Assumptions and Limitations

the only mode of selection will be single
keyboard navigation with arrow keys 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.

6. Test Scenarios

Automated

The dropdown shows all items properly
The dropdown is properly positioned according to the placement settings
The user should be able to select an item by pressing ENTER key and by click
The user can navigate through the items using Up & Down keys
The dropdown should support disabled items
The items can be disabled/enabled at runtime
The dropdown should support headers
The dropdown should notify when the selection has changed
The dropdown should persist selection through scrolling
The Escape key should close the dropdown and not change the selection
The dropdown should not change selection when setting it to non-existing item
Key navigation through disabled items should skip the disabled items
Disabled items cannot be activated
Disabled items cannot be selected
Currently active item is not changed when a disabled item is clicked
Drop down groups do render all items in them correctly
The dropdown is closed on clicking outside of it when closeOnOutsideClick=true and not closed when closeOnOutsideClick=false
The dropdown is closed on selecting an item when closeOnSelect=true and not closed when closeOnSelect=false
The dropdown's width is the same as its target's when sameWidth=true
The current selection is cleared on calling clearSelection() method
The igcClosing and igcClosed events are fired when the dropdown is closed by clicking outside of it.
The igcClosing and igcClosed events are fired when the dropdown is closed after selecting an item (via click or Enter key).

Manual

The dropdown 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 dropdown controls on the same page.
The dropdown content should not "flicker" when opening

7. References

https://material-components-web.appspot.com/select.html https://material.angular.io/components/select/overview https://material.angular.io/components/menu/overview https://material.io/guidelines/components/menus.html#menus-simple-menus

8. Dependencies

The igc-dropdown component depends on Popper and utilizes its positioning capabilities.

DropDown Specification - IgniteUI/igniteui-webcomponents GitHub Wiki

DropDown Specification

Contents

Owned by

Requires approval from

Signed off by

Revision History

1. Overview

Objectives

2. User Stories

Developer Stories

As a developer, I want to

As an end user, I want

3. Functionality

3.1. End User Experience

3.2. Developer Experience

3.3. Keyboard Navigation

3.4. API

Properties

Methods

Events

Slots

4. ARIA Support

5. Assumptions and Limitations

6. Test Scenarios

Automated

Manual

7. References

8. Dependencies