Skip to content

DropDown Specification

Jump to bottom
Simeon Simeonoff edited this page Sep 1, 2022 · 27 revisions

DropDown Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. ARIA support
  5. Assumptions and Limitations
  6. Test scenarios
  7. References
  8. 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 Notes
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

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.

Clone this wiki locally