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.0	Nikolay Alipiev	Nov 17, 2023	API Updates. Changes - PRs: 1, 2, 3, 4

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.
The simple combo should handle initial states gracefully without showing the clear icon unless a value is selected.

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.
Story 10: As an end-user, I want the value I typed to be automatically selected if it matches an available value when I press the Tab key, so I can quickly move to the next form field without extra actions.

3. Functionality

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 Specific Functional Behavior

Behavior in Required Forms: When the igx-simple-combo is part of a reactive form and marked as required, the clear icon will only appear once a value has been selected. Initial states will not show the icon, ensuring consistency with form validation.
Empty Objects as Values: If the value is set to an empty object ({}), the clear icon will be displayed. This indicates that an object (even if empty) is currently selected, aligning with the component’s design to provide a clear indication of the current state.
Tab Key Value Selection: The combo allows users to select a valid value by pressing the Tab key. If the typed value matches an existing item in the combo's data source, it is automatically selected when the user presses Tab. If no match exists, the combo will close without selecting any value. This streamlines user experience by allowing them to proceed without additional input actions like pressing Enter or clicking outside the input field.

3.5. Keyboard Navigation

Keys	Description
Enter	Select the focused value and close the dropdown
Enter	While the user is typing in the input select the first item in the list
Space	Select the focused value in the dropdown without closing it
Tab	If the typed value matches a combo item, it selects that item and closes the dropdown; otherwise, the dropdown closes without selecting a value

4. Public API

Properties

Name	Description	Type
`id`	combo id	`string`
`data`	combo data source	`any[]`
`value`	the value of the combo	any
`selection`	the selected items of the combo	any
`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`	defines the 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>`

Getters

Name	Description	Type
`displayValue`	the value of the combo text field	string
`value`	the value of the combo	any
`selection`	the selected items of the combo	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.
in non-required scenarios or when used as a standalone component (not part of a form), the component will display the clear icon if there is not initially selected value.