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

Web Development Team

Developer Name

1. Simeon Simeonoff
2. Silvia Ivanova

Designer Name

1. Vasil Tashkov

• Silvia Ivanova | Date:
• Svilen Dimchevski | Date:

• Radoslav Mirchev | Date: 05-Dec-2022
• Radoslav Karaivanov | Date: 06-Dec-2022

The Combo component is similar to the Select component in that it provides a list of options from which the user can make a selection. In contrast to the Select component, the Combo component displays all options in a virtualized list of items, meaning the combo box can simultaneously show thousands of options, where one or more options can be selected. Additionally, users can create custom item templates, allowing for robust data visualization. The Combo component features case-sensitive filtering, grouping, complex data binding, dynamic addition of values and more.

End-to-end user experience prototype

Elaborate more on the multi-facetted use cases

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(s) 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 of 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 18: 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.
• Story 19: I want to be able to select multiple items from the list of options, so that I can aggregate information as a list of values.
• Story 20: I want to be able to mark the component as read-only, so that users can be informed about a default selection.
• Story 21: I want to be able to provide a collection of values as a data object, so that I don't have to declaratively describe thousands of options in markup.
• Story 22: I want to be able to specify which property in an object should be used as the text value, so that I can separate the actual value from what is displayed to the end user.
• Story 23: I want to be able to specify which property in an object should be used as the data value, so that I can separate the actual value from what is displayed to the end user.
• Story 24: I want to be able to specify which property in an object should be used as the filter value, so that I can filter by value different from what is displayed to the end user.
• Story 25: I want to be able to control how filtering behaves with text containing diacritics/accented symbols and how the component should match them.
• Story 26: I want to be able to select falsy values(0, false, '', null, NaN).
• Story 27: I want to be able to specify a template for individual items, so that I can better customize the end-user experience.
• Story 28: I want to be able to quickly clear the selection made by the end user, so that I can provide a way to start the selection-process anew.
• Story 29: I want to be able to change the UI elements regarding clearing/toggling of the selection, so that I can better customize the end-user experience.
• Story 30: I want to be able to modify the collection of values at runtime, so that I don't have to reinitialize the component every time the data changes.
• Story 31: I want to be able to filter the data of the dropdown at runtime, so that I can provide better end-user experience.
• Story 32: I want to be notified when the value of the input has changed, so that I can react to it in the business logic of my app.
• Story 33: I want to be notified when the dropdown of the input is shown/hidden, so that I can react to it in the business logic of my app.
• Story 34: I want to be notified when the user fires keyboard events inside the input's dropdown, so that I can react to it in the business logic of my app.
• Story 35: I want to show the list of data in a performant way, so that I can present a large set of data for selection to the end-user.
• Story 36: I want to evaluate the validity state of the component, so that I can notify the end-user when a field is required.

A future release will implement the following Developer Story:

• Story 37*: I want to be able to provide a remote collection of values as a data object, so that I don't have to declaratively describe thousands of options in markup.

End-user stories:

• Story 01: I want to be able to select one or more items 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 items from the list of options, so that I can know which items are 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.
• Story 04: I want to be able to filter list of options by a keyword, so that I can limit the number of choices presented to me.
• Story 05: I want to be able to have a clear distinction between selected and unselected items, so that I can make better decisions about my selection.
• Story 06: I want to be able to have a clear distinction between selected and unselected items, so that I can make better decisions about my selection.
• Story 07: I want to be able to easily clear my selection, so that I can quickly restart the selection process.
• Story 08: I want my browser to quickly load the list of options, so that I can quickly start selecting items.
• Story 09: I want to be able to change the search case sensitivity, so that I can better identify the items I'm looking for.
• Story 10: I want to be able to see the text I'm typing when the combo is on focus, so that I am certain of the option I am searching for.
• Story 11: I want to be able to see the list of options upon clearing my selection, so that I can skim over the available options.

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience

• Design Handoff
• Prototype

** Integration scenarios or functionality with other features/components prototype > ** End-to-end user experienceprototype > ** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off

3.2. Developer Experience

The following example illustrates how the Combo component can be used in a Lit application.

import { html, render } from 'lit';
const cities = [
  {
    name: 'London',
    id: 'UK01',
    region: 'EMEA',
  },
  {
    name: 'Sofia',
    id: 'BG01',
    region: 'EMEA',
  },
];

const combo = document.querySelector('igc-combo');

// Get the item and the visual index(filter-bound);
const itemTemplate = (item) => {
  return html`
    <div>
      <span>${item.name} (${item.id})</span>
    </div>
  `;
};

// Get the item and the visual index(filter-bound);
const groupHeaderTemplate = (item) => {
  return html`
    <div>
      <span>${item.region}</span>
    </div>
  `;
};

combo.itemTemplate = itemTemplate;
combo.groupHeaderTemplate = groupHeaderTemplate;

const app = html`
  <igc-combo
    .data=${cities}
    label="Cities"
    display-key="name"
    value-key="id"
    value='["BG01", "BG02"]'
    group-key="region"
    group-sorting="desc"
    autofocus
    autofocus-list
    placeholder="Pick a city"
    placeholder-search="Search for a city"
    case-sensitive-icon
    disable-filtering
    outlined
    required
  ></igc-combo>
`;

render(app);

3.3. Keyboard Navigation

• To trigger any keyboard navigation event, the <igc-combo> must be in focus. The list of options can be opened by pressing on any character key, the Down key, or the Alt + Down keys, as well as with a mouse click. Using the Down arrow key will focus(activate) 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 key. The Up arrow key will focus(activate) the previous item in the list of options until the beginning of the list is reached. If the user continues pressing on the up key when in the beginning of the list of options, the dropdown closes and the focus returns to the combo input.
• While the dropdown menu is open, pressing the Home key focuses(activates) the first item in the list of options. Conversely, the End key focuses(activates) the last item in the list of options. While an item is active, pressing the Space keys will select/deselect the active item. The Enter key behaves similarly, but will also close the dropdown menu upon selection/deselection.
• Pressing the Esc key closes the list of options without changing the selection.
• When adding custom values is allowed, a new item can be added while the Add Item button is on focus by pressing the Enter key.

Additional functionality: Typing while the component is in focus will filter the list of items for those that most closely match the current user input.

3.4. Grouping

• When a group key is set, the igc-combo will group its items based on that key.
• Items which cannot be resolved based on the passed group key (that is T[groupKey] returning null or undefined) will be aggregated into a group named "Other".
• When grouping is enabled, developers may control the sorting directions of the groups through the groupSorting property. Defaults to 'asc' (ascending).
• The sorting is locale aware.

Scheduled for implementation:

Scheduled for implementation:

Scheduled for implementation:

The <igc-combo> component provides the following CSS parts:

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

Scheduled for implementation:

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

The <igc-combo-header> component provides the following slots:

ARIA Support

• <igc-combo> - role combobox.
  • aria-owns - encapsulated container holding all items.
  • aria-haspopup
  • aria-describedby - helper-text.
  • aria-disabled - set to the disabled attribute of the component.
• <igc-combo-item>(implicit)
  • role - option.
  • aria-selected - depends on its selection status.
• <igc-select-group>(implicit)
  • role - group
• encapsulated container holding all items - role="listbox"

RTL Support The component should provide full RTL support by default.

Specify all referenced external sources