Simple Combo

Simple Combo Specification

Owned by

PwnJS

Boris Penkov

Stefan Ivanov

Requires approval from

Nikolay Alipiev | Date:
Simeon Simeonov | Date:

Signed off by

Konstantin Dinev | Date:
Damyam Petev | Date:

Revision History

Version	User	Date	Notes
0.1	Boris Penkov, Stefan Ivanov	Oct 28, 2021	Initial Draft
0.2	Plamena Miteva	July 08, 2022	Updating the API

1. Overview

Objectives

The igx-simple-combo is a modification of the igx-combo component that allows single selection and has the appropriate UI and behavior for that. It inherits all the igx-combo API.

Check igxCombo spec for behavior and API that will be reused by the igx-simple-combo. This document will only point to the differences in the behavior, UI, and API between the igx-simple-combo and the igx-combo.

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

The simple combo should allow the user to fill a form field by selecting a single value for it.
The simple combo should allow typing in the input to filter the dropdown list.
The simple combo should allow users to add custom values and select them.
The simple combo should support keyboard navigation.
The simple combo should support templating for its input and dropdown items.
The simple combo should support the three display densities.
The simple combo should be themeable.
The simple combo should work with form validation rules.

2. User Stories

Developer stories:

Story 1: As a developer, I want the combo to filter the list of values according to what the user types in the input out of the box.
Story 2: As a developer, I want to combine combos in a cascading scenario, so that I am able to fill the next one values with relevant content to the selection made in the current one e.g. cities only in that particular US state.
Story 3: As a developer, I want the combo to style along with the other components so that I can easily change the theme of my whole application.

End-user stories:

Story 1: As an end-user, I want to type in the input, so that I can search for the value I want to select (i.e. no disabled input and no second input for search in the dropdown)
Story 2: As an end-user, I want to clear the value typed in the input so that I can revert the list of values in the dropdown to show all possible values.
Story 3: As an end-user, I want to clear my selection by erasing characters in the input, so that the combo is in an empty/unselected state.
Story 4: As an end-user, I want to open the dropdown by clicking the dropdown icon, so that I can select a value.
Story 5: As an end-user, I want to open the dropdown by starting to type when the input is focused so that I can select a value.
Story 6: As an end-user, I want to use the keyboard to navigate and select values, so that I can save time when filling forms.
Story 7: As an end-user, I want to click a value, so that I can select it and close the dropdown to continue with the rest of the form.
Story 8: As an end-user, I expect that if I click the selected value, it will stay selected and the dropdown will close allowing me to continue with the rest of the form.
Story 9: As an end-user, I want the dropdown menu to open whenever I interact with the value in the editor, be it by typing, deleting characters or clearing the whole value using the clear icon.

3. Functionality

Design Handoff- https://www.figma.com/file/kJxlQPb78W2C4S2g0gDjbs/Combo-Design-Handoff?node-id=55%3A5564&t=yuCAZ9GzeuDDtmdS-1

The simple combo should look and feel exactly as the igx-combo so that when used together in a form they behave identically. The simple combo uses the value in its input field as the user types to search across all bound values and return matching ones, unless such are not existing when it is possible to add the value in the input as a selectable value in the list of items (when the property allows for this). The dropdown shows just a list of items that is scrollable when items exceed dropdown height and selection is singular i.e. if A is selected and I choose to select B, that also deselects A (there are no checkboxes in the list item template by default).

3.1. End-User Experience

** End-to-end user experience that represents the topic overview sample

3.2. Developer Experience

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description
Enter	Selects the focused value and closes the dropdown
Enter	While the user is typing in the input selects the first item in the list
Space	Selects the focused value in the dropdown without closing it

4. Public API

Properties

Name	Description	Type
`id`	combo id	`string`
`data`	combo data source	`any`
`value`	combo value	`string`
`allowCustomValue`	enables/disables combo custom value	`boolean`
`valueKey`	combo value data source property	`string`
`displayKey`	combo display data source property	`string`
`groupKey`	combo item group	`string`
`virtualizationState`	defined he current state of the virtualized data. It contains `startIndex` and `chunkSize`	`IForOfState`
`totalItemCount`	total count of the virtual data items, when using remote service	`number`
`width`	defines combo width	`string`
`height`	defines combo height	`string`
`itemsMaxHeight`	defines dropdown maximum height	`number`
`itemsWidth`	defines dropdown width	`string`
`itemHeight`	defines dropdown item height	`number`
`placeholder`	defines the "empty value" text	`string`
`collapsed`	gets dropdown state	`boolean`
`disabled`	defines whether the control is active or not	`boolean`
`ariaLabelledBy`	defines label ID related to combo	`boolean`
`valid`	gets if control is valid, when used in a form	`boolean`
`overlaySettings`	controls how the dropdown is displayed	`OverlaySettings`
`selected`	Get current selection state	`Array<any>`

Methods

Name	Description	Return type	Parameters
`open`	Opens dropdown	`void`	`None`
`close`	Closes dropdown	`void`	`None`
`toggle`	Toggles dropdown	`void`	`None`
`select`	Select a defined item	`void`	newItem: `any`
`deselect`	Deselect a defined item	`void`	item: `any`

Events

Name	Description	Cancelable	Parameters
`selectionChanging`	Emitted when item selection is changing, before the selection completes	true	{ oldSelection: `any`, newSelection: `any`, displayText: `string`, owner: `IgxSimpleComboComponent` }
`searchInputUpdate`	Emitted when an the search input's input event is triggered	true	`IComboSearchInputEventArgs`
`addition`	Emitted when an item is being added to the data collection	false	{ oldCollection: `Array<any>`, addedItem: `<any>`, newCollection: `Array<any>`, owner: `IgxSimpleComboComponent` }
`onDataPreLoad`	Emitted when new chunk of data is loaded from the virtualization	false	`IForOfState`
`opening`	Emitted before the dropdown is opened	true	`IBaseCancelableBrowserEventArgs`
`opened`	Emitted after the dropdown is opened	false	`IBaseEventArgs`
`closing`	Emitted before the dropdown is closed	true	`IBaseCancelableBrowserEventArgs`
`closed`	Emitted after the dropdown is closed	false	`IBaseEventArgs`

5. Test Scenarios

6. ARIA Support

The following components gets the corresponding ARIA attributes:

The aria-labelledby attribute is applied to both combo input and dropdown and can be set by the ariaLabelledBy property, the combo label or placeholder.

The dropdown item container has aria-activedescendant attribute to identify the currently active element of the item list and the items inside it have role role="option" or role="group" in case they are header items.

7. Assumptions and Limitations

When the combo is bound to a remote service and there is a predefined selection, be aware of the following:

the input of the combo will remain blank until the requested data is not loaded.

When the combo is used in template/reactive forms, be aware of the following:

if the simple combobox is bound via ngModel or formControl and the required validator is applied, null, undefined, '' values cannot be selected.