Select Specification

Overview
User Stories
Functionality
Test Scenarios
Accessibility
Assumptions and Limitations
References

Owned by

Web Development

Developer Name

Simeon Simeonoff

Designer Name

Vasil Tashkov

Requires approval from

Silvia Ivanova | Date:
Vasil Tashkov | Date: 18.07.2022

Signed off by

Radoslav Mirchev | Date: 28-Jul-2022
Damyan Petev | Date:
Svilen Dimchevski | Date: 18.07.2022

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

Select Specification - IgniteUI/igniteui-webcomponents GitHub Wiki

Select Specification

Contents

Owned by

Requires approval from

Signed off by

Revision History

1. Overview

Objectives

2. User Stories

3. Functionality

3. Keyboard Navigation

Keyboard navigation when the list of options is not visible:

Keyboard navigation when the list of options is visible:

Properties

Methods

Events

Slots

4. Test Scenarios

5. Accessibility

6. Assumptions and Limitations

7. References

⚠️ GitHub.com Fallback ⚠️

Select Specification - IgniteUI/igniteui-webcomponents GitHub Wiki

Select Specification

Contents

Owned by

Requires approval from

Signed off by

Revision History

Objectives

Keyboard navigation when the list of options is not visible:

Keyboard navigation when the list of options is visible:

Properties

Methods

Events

Slots

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️