Skip to content

Select Specification

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

Select Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

Web Development

Developer Name

Simeon Simeonoff

Designer Name

Vasil Tashkov

Requires approval from

Signed off by

Revision History

Version Users Date Notes
1 Names of Developers and Designers Date

1. Overview

The <igc-select> component represents a control that provides a menu of options.

Objectives

The <igc-select> component provides an input with a dropdown list allowing the selection of one or more items.

2. User Stories

Developer stories:

  • Story 01: I want to be able to insert a component that allows, upon clicking, the showing of a list of options, so that the users of my app can select item(s) from that list.
  • Story 02: I want to be able to easily list all items in a way that separates their underlying value from the displayed option, so that I can separate my model from my view.
  • Story 03: I want to be able to initialize the selected value from the list of options, so that I can pre-fill the input with default data.
  • Story 04: I want to be able to label the input, so that I can communicate what the expected input value should be.
  • Story 05: I want to be able to provide a description or additional text as a secondary label, so that I can communicate what the expected input value should be in greater detail.
  • Story 06: I want to be able to provide a placeholder text, so that I can showcase a sample input value or provide a call-to-action message.
  • Story 07: I want to be able to show icons at the beginning/end of the component, so that I can communicate the meaning of the input data clearer.
  • Story 08: I want to be able to customize the size of the component, so that I can better manage the layout of my app.
  • Story 09: I want to be able to see the list of items at all times, regardless of where I place the component in the layout of my app.???
  • Story 10: I want to be able to customize visual style of the component, so that it can fit the design language of my app.
  • Story 11: I want to be able to disable the component, so that I can control the flow of information based on design requirements/constraints.
  • Story 12: I want to pad the list of items with a header and/or footer, so that I can provide additional information/functionality in the provided area(s).
  • Story 13: I want to bundle the list options into labeled groups, so that I can control the properties of all items in the group at the same time.
  • Story 14: I want to be able to mark the component as required, so that I can enforce the collection of data from the users of my app.
  • Story 15: I want to be able to control the validity of the component, so that I can have better control of whether the selected data is valid or not.
  • Story 16: I want to be able to disable individual options from the list of items, so that I can have better control over which options are selectable and which are not.
  • Story 17: I want to be able to use the component in the context of the <igc-form> component, so that I can collect its data alongside other inputs.

End-User Stories:

  • Story 01: I want to be able to select an item from a list of options, so that I can fill in an input from a list of pre-defined values.
  • Story 02: I want to be able to identify the selected item from the list of options, so that I can know which item is the currently selected one.
  • Story 03: I want to be able to navigate and select the list of options using my keyboard and mouse, so that I can use the best input method for me.

3. Functionality

Design handoff - https://www.figma.com/file/ZGvwW5t9020ZMVC1pLWtg5/Select-All-Themes?node-id=0%3A1

<igc-select 
    name="foods"
    label="Favorite Food"
    placeholder="Please choose an option"
    size="small"
    value="apple"
    outlined
    required>
    <header slot="header"></header>
    <igc-icon slot="suffix">clear</igc-icon>
    <igc-select-group>
        <h3 slot="label">Fruits</h3>
        <igc-select-item value="apple">Apple</igc-select-item>
        <igc-select-item value="banana" selected>Banana</igc-select-item>
        <igc-select-item value="mango" disabled>Mango</igc-select-item>
        <igc-select-item value="orange">Orange</igc-select-item>
    </igc-select-group>
    <igc-select-group>
        <h3 slot="label">Veggies</h3>
        <igc-select-item value="cucumber">Cucumber</igc-select-item>
        <igc-select-item value="tomato">Tomato</igc-select-item>
    </igc-select-group>
    <footer slot="footer"></footer>
    <span slot="helper-text">An apple a day keeps the doctor away.</span>
</igc-select>

The above example shows an optional usage of the <igc-select> component. It is given a name so that it can be registered and used inside an <igc-form>. The label attribute labels the input portion of the <igc-select> control. The placeholder attribute provides a text to be used if no value is selected. The helper-text slot provides for additional text to be placed along the bottom edge of the control. The size of the component can be controlled via the size attribute, as per usual it can vary between small, medium, and large. If the outlined attribute is present the component will be styled differently only in its material version. The value attribute should be used to select an item from the list of items. The <igc-select> control also supports most of the <igc-input> attribute, such as required, disabled, autofocus, etc.

The <igc-select> component can be padded using a header and/or footer. The header and footer slots can be used for that.

The <igc-select> provides all placement options present in the <igc-drop-down> component via the same placement attribute.

The <igc-select> component can be prefixed and/or suffixed by slotting in content via its prefix and suffix properties.

The <igc-select-item> component allows the users to declaratively specify a list of options to be used by the <igc-select> control. Each item provides a value attribute that represents the data it carries upon selection. Additional content can be placed between the opening and closing brackets of the <igc-select-item> component. This content will only be used as value in case the value attribute is not present on the <igc-select-item> component; Some or all items can be disabled via the disabled attribute.

Multiple <igc-select-item>s can be placed between the opening and close brackets of an <igc-select-group> component. This component allows the users to visually group items together. The <igc-select-group> can be labelled via its label slot.

3. Keyboard Navigation

To trigger any keyboard navigation event, the <igc-select> must be in focus. To trigger open the list of options the Enter, Spacebar or Alt + Up/Down keys are pressed. Using the Up and Right arrow keys will select the next item in the list until the end of the list of options is reached, in which case the keyboard navigation will do nothing upon pressing the aforementioned keys. The Down and Left keys will select the previous item in the list of options until the beginning of the list is reached, in which case the keyboard navigation will do nothing upon pressing the aforementioned keys.

If the list of options has been triggered either via mouse click or by pressing the Enter or Spacebar keys, pressing Up or Left and Down or Right arrow keys activates the previous/next item, but it will not change the selection. Pressing the Enter key will close the dropdown and will change the currently selected option.

Pressing the Home key selects the first item in the list of options. Conversely, the End key selects the last item in the list of options.

Pressing the Esc key closes the list of options without changing the selection.

Keyboard navigation when the list of options is not visible:

Keys Description
Enter Opens the list of options.
Spacebar Opens the list of options.
Alt + Up/Down Toggles the list of options.
Down Selects the next item from the list of options.
Right Selects the next item from the list of options.
Up Selects the previous item from the list of options.
Left Selects the previous item from the list of options.
Home Selects the first item from the list of options.
End Selects the last item from the list of options.

Keyboard navigation when the list of options is visible:

Keys Description
Enter Selects the active item and closes the lit of options.
Alt + Up/Down Toggles the list of options.
Down Activates the next item from the list of options.
Right Activates the next item from the list of options.
Up Activates the previous item from the list of options.
Left Activates the previous item from the list of options.
Esc Closes the list of options.

Additional functionality: Typing while the component is in focus will query the list of items and select the one that most closely matches the current user input, unless the select menu is open in which case the matching item is activated.

3.2. API

Properties

The following properties are available on the <igc-select> component:

Name Description Type Default value Reflected
open Opens the list of items by default. Boolean false false
name Sets the name of the component. string - false
value Sets the value of the component. Marks the item matching the value as selected. string - false
disabled Sets the disabled state of the component. Boolean false true
required Sets the required state of the component. Boolean false true
invalid Sets the validity of the component. Boolean false true
autofocus Automatically focuses the component on page load. Boolean false false
label Sets the label of the component. string - false
placeholder Sets the placeholder of the component. string - false
outlined Sets material-themed inputs to outlined style mode. Boolean false true
size Sets the size of the component. small | medium | large medium true

The following properties are available on the <igc-select-item> component:

Name Description Type Default value Reflected
value Sets the value of the item. string - false
selected Sets the item as selected. Boolean false false
disabled Sets the item as disabled. Boolean false true

The following properties are available on the <igc-select-group> component:

Name Description Type Default value Reflected
disabled Disables all items within the group. Boolean false true

Methods

Name Description Return type Parameters
focus Focuses the component. - options: FocusOptions
blur Blurs the component. void -
toggle Toggles the list of options. void -
show Shows the list of options. void -
hide Hides the list of options. void -
select Selects an item by value. IgcSelectItem value | index
clearSelection Clears current selection. void -
navigateTo Navigates to the item with specified value. IgcSelectItem value | index
reportValidity Checks for validity marks the component as invalid if no value and required. boolean -

Events

The following events are emitted for the <igc-select> component:

Name Description Cancelable Parameters
igcFocus Emitted when the component gains focus. false
igcBlur Emitted when the component loses focus. false
igcChange Emitted when item selection is changing, before the selection completes false {newValue}
igcOpening Emitted before the list of options is opening true
igcOpened Emitted after the list of options is opened false
igcClosing Emitted before the dropdown is closing true
igcClosed Emitted after the list of options is closed false

Slots

The <igc-select> component provides the following slots:

Name Description
(default) Renders the list of options.
header Renders the header element.
footer Renders the footer element.
prefix Renders the prefix element.
suffix Renders the suffix element.
helper-text Renders the helper-text element.
toggle-icon Renders the toggle-icon element.

The <igc-select-item> component provides the following slots:

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

The <igc-select-group> component provides the following slots:

Name Description
(default) Renders the group's content.
label(could be a prop?) Renders the group's label.

4. Test Scenarios

  • The <igc-select> renders
  • The <igc-select> renders and <igc-input>
  • The <igc-select> renders all `(s) properly
  • The <igc-select> renders all `(s) properly
  • The <igc-select> list of options are properly positioned
  • The <igc-select> list of options takes the width of the input
  • The <igc-select> should open the list of options on ENTER or by click
  • The <igc-select> should accept a name property
  • The <igc-select> should accept a value property
  • The <igc-select> should accept a label property
  • The <igc-select> should accept a placeholder property
  • The <igc-select> should accept an invalid property
  • The <igc-select> should accept a size property
  • The <igc-select> should accept an autofocus property
  • The <igc-select> should be able to be marked as disabled
  • The <igc-select> should be able to be marked as required
  • The <igc-select> should be able to be marked as outlined
  • The <igc-select> should support a helper-text slot
  • The <igc-select> should support a header slot
  • The <igc-select> should support a footer slot
  • The <igc-select> should support a toggle-icon slot that replaces the default toggle icon
  • The <igc-select> should support accept any number of elements rendered in the prefix slot
  • The <igc-select> should support accept any number of elements rendered in the suffix slot
  • The <igc-select> should notify when the selection has changed
  • The <igc-select> should persist selection through scrolling
  • The <igc-select-group> groups renders all items in them correctly
  • The <igc-select-group> should be able to be marked as disabled
  • The <igc-select-item> should be able to be marked as disabled
  • The <igc-select-item> should accept a value property
  • The igcClosing and igcClosed events are fired when the <igc-select> is closed by clicking outside of it.
  • The igcClosing and igcClosed events are fired when the <igc-select> is closed after selecting an item (via click or Enter key).
  • The igcChange event is fired when the selected item changes
  • The igcFocus event is fired when the <igc-select> gains focus
  • The igcBlur event is fired when the <igc-select> loses focus
  • The navigateTo() method should navigate to the item either by index or value
  • The select() method should select the item either by index or value
  • The reportValidity() method should report query the current validity status
  • The setCustomValidity() method should allow users to set the validity message shown
  • The show() method show the list of options
  • The hide() method hide the list of options
  • The toggle() method open the list of options if not shown and vice-versa
  • The user should be able to select an item by pressing Enter, Spacebar key, and by clicking
  • The user can navigate through the items using Up & Down and Left & Right arrow keys
  • The items can be disabled/enabled at runtime
  • The Escape key should close the list of options and not change the selection
  • The list of options 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
  • The list of options is closed on selecting an item
  • The current selection is cleared on calling clearSelection() method

5. Accessibility

ARIA Support

  • <igc-select> - role combobox.
    • aria-describedby - helper-text???
    • aria-haspopup - true
    • aria-expanded - controlled via the value of the open property
    • aria-owns - to be linked to the encapsulated dropdown
    • aria-disabled - set to the disabled attribute of the component
  • <igc-select-item selected> item - aria-selected="true" (https://www.w3.org/TR/wai-aria-1.1/#aria-selected) - provided by the <igc-dropdown-item> item
  • <igc-select-item> - role="option" - provided by the <igc-dropdown-item> item
  • <igc-select-group> - role="group" - provided by the <igc-dropdown-item> item
  • encapsulated <igc-dropdown> - role="listbox"

The component should provide full RTL support by default.

6. Assumptions and Limitations

Assumptions Limitation Notes

7. References

Specify all referenced external sources

Clone this wiki locally