Skip to content

Simple Combo

Nikolay Alipiev edited this page Nov 17, 2023 · 26 revisions

Simple Combo Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Public API
  5. Test Scenarios
  6. ARIA support
  7. Assumptions and Limitations
  8. References

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

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.

Dropdown

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

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

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.

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 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

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

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.

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.

Specify all referenced external sources

Clone this wiki locally