Skip to content

DropDown Specification

Danail Marinov edited this page Jun 11, 2019 · 62 revisions

DropDown Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. ARIA support
  5. Assumptions and Limitations
  6. Test scenarios
  7. References

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
0.4 Alexander Marinov May 9, 2018 Update API and test scenarios
0.5 Milko Venkov May 10, 2018 Updating the API
0.6 Milko Venkov May 15, 2018 Updating the API
0.7 Milko Venkov July 5, 2018 Updating specification
0.8 Milko Venkov July 24, 2018 Add isSelected setter to igxDropDownItem
1.1 Viktor Slavov Jan 25, 2019 Add IgxDropDownGroup section, user stories
1.2 Milko Venkov Feb 15, 2019 Assumptions and Limitations update - modal
1.3 Danail Marinov Jun 10, 2019 Display Density variations

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 have a selection made by default
  • not to have a selected item by default
  • 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 depending 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 the width of the dropdown.
  • set the height, and if it is exceeded a vertical scroll should appear.
  • 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.
  • be able to group hierarchical data in groups without the need to flatten it
  • to be able to set Comfortable, Cosy or Compact Display Density

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:

igxDropDown.setSelectedItem(2);

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

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

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

    // in example.component.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`
                },
                ...
            ]   
        }];
    }
    <!-- in example.component.html -->
    <igx-drop-down>
        <igx-drop-down-item-group *ngFor="let foodGroup of foods" [label]="foodGroup.name">
            <igx-drop-down-item *ngFor="let food of foodGroup.entries" [value]='food.refNo'>
                {{ food.name }}
            </igx-drop-down-item>
        </igx-drop-down-item-group>
    </igx-drop-down>

3.3. Keyboard Navigation

The default way to select an item from the dropdown is by mouse click. To enable keyboard navigation IgxDropDownItemNavigationDirective should be added. If keyboard navigation is enabled, 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

DropDown can be configured for Comfortable, Cosy and Compact Display Density with the following settings: Dropdown

Comfortable Display Density is recommended for mobile.

Cosy and Compact Display Density are recommended for desktop.

Тext does not wrap.

4.5. 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 Note: if an igx-drop-down-item is inside of a disabled igx-drop-down-item-group, the disabled get will always return true

IgxDropDownGroupComponent

Name Description Type
disabled Sets/gets if the given item group is disabled. When true, disables all drop down items inside of the group boolean
label The label of the group. Blank by default string

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

5. ARIA Support

We provide the aria-selected property which lets the screen readers know if an item is selected or not.

The following components gets the corresponding aria attributes

6. 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.
  • By default Dropdown will not close on click outside and will be shown as modal and centered on the screen. To show dropdown as not modal and with close on outside click the developer may add IgxToggleAction directive to the caller of the dropdown, or provide OverlaySettings with modal set to false and closeOnOutsideClick set to true to the open/toggle method.
  • We will provide default values for min/max-width with CSS and will allow the users to override those using the width property.
  • The igx-drop-down-item-group tag should be used only to group igx-drop-down-items. All other content will be disregarded by the IgxDropDownGroupComponent

7. Test Scenarios

Automated

  • The user should be able to select an item by SPACE/ENTER keys and by click
  • The selection can be changed indefinitely
  • The user can navigate through the items using Up/Down/Home/End 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 should not change the selection
  • The dropdown should not change selection when setting it to non-existing item
  • Home key should focus the first enabled and non-header item
  • End key should focus the last enabled and non-header item
  • Key navigation through disabled items should skip the disabled items
  • Width and height can be changed at run-time
  • Disabled items cannot be focused
  • Disabled items cannot be selected
  • Items do not loose focus when a disabled item is clicked
  • Drop down groups do render all items in them correctly
  • All drop down items in a disabled drop down group are also disabled

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

8. References

igxDropDown Issue 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

Clone this wiki locally
You can’t perform that action at this time.