igniteui-webcomponents
Version:
Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.
356 lines (355 loc) • 14.7 kB
TypeScript
import { type IComboResourceStrings } from 'igniteui-i18n-core';
import { type PropertyValues, type TemplateResult } from 'lit';
import { IgcBaseComboBoxComponent } from '../common/mixins/combo-box.js';
import type { AbstractConstructor } from '../common/mixins/constructor.js';
import type { Validator } from '../common/validators.js';
import type { ComboItemTemplate, ComboRenderFunction, ComboValue, FilteringOptions, GroupingDirection, IgcComboComponentEventMap, Item, Keys } from './types.js';
declare const IgcComboComponent_base: import("../common/mixins/constructor.js").Constructor<import("../common/mixins/forms/types.js").FormRequiredInterface & import("../common/mixins/forms/types.js").FormAssociatedElementInterface> & import("../common/mixins/constructor.js").Constructor<import("../common/mixins/event-emitter.js").EventEmitterInterface<IgcComboComponentEventMap>> & AbstractConstructor<IgcBaseComboBoxComponent>;
/**
* 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.
*
* @element igc-combo
*
* @slot prefix - Renders content before the input of the combo.
* @slot suffix - Renders content after the input of the combo.
* @slot header - Renders a container before the list of options of the combo.
* @slot footer - Renders a container after the list of options of the combo.
* @slot empty - Renders content when the combo dropdown list has no items/data.
* @slot helper-text - Renders content below the input of the combo.
* @slot toggle-icon - Renders content inside the suffix container of the combo.
* @slot clear-icon - Renders content inside the suffix container of the combo.
* @slot value-missing - Renders content when the required validation fails.
* @slot custom-error - Renders content when setCustomValidity(message) is set.
* @slot invalid - Renders content when the component is in invalid state (validity.valid = false).
*
* @fires igcChange - Emitted when the control's selection has changed.
* @fires igcOpening - Emitted just before the list of options is opened.
* @fires igcOpened - Emitted after the list of options is opened.
* @fires igcClosing - Emitter just before the list of options is closed.
* @fires igcClosed - Emitted after the list of options is closed.
*
* @csspart label - The encapsulated text label of the combo.
* @csspart input - The main input field of the combo.
* @csspart native-input - The native input of the main input field of the combo.
* @csspart prefix - The prefix wrapper of the combo.
* @csspart suffix - The suffix wrapper of the combo.
* @csspart toggle-icon - The toggle icon wrapper of the combo.
* @csspart clear-icon - The clear icon wrapper of the combo.
* @csspart case-icon - The case icon wrapper of the combo.
* @csspart helper-text - The helper text wrapper of the combo.
* @csspart search-input - The search input field of the combo.
* @csspart list-wrapper - The list of options wrapper of the combo.
* @csspart list - The list of options box of the combo.
* @csspart item - Represents each item in the list of options of the combo.
* @csspart group-header - Represents each header in the list of options of the combo.
* @csspart active - Appended to the item parts list when the item is active of the combo.
* @csspart selected - Appended to the item parts list when the item is selected of the combo.
* @csspart checkbox - Represents each checkbox of each list item of the combo.
* @csspart checkbox-indicator - Represents the checkbox indicator of each list item of the combo.
* @csspart checked - Appended to checkbox parts list when checkbox is checked in the combo.
* @csspart header - The container holding the header content of the combo.
* @csspart footer - The container holding the footer content of the combo.
* @csspart empty - The container holding the empty content of the combo.
*/
export default class IgcComboComponent<T extends object = any> extends IgcComboComponent_base {
static readonly tagName = "igc-combo";
static styles: import("lit").CSSResult[];
static register(): void;
protected get __validators(): Validator<IgcComboComponent<T>>[];
private readonly _slots;
protected readonly _rootClickController: import("../common/controllers/root-click.js").RootClickController;
protected readonly _i18nController: import("../common/i18n/i18n-controller.js").I18nController<IComboResourceStrings>;
protected readonly _formValue: import("../common/mixins/forms/form-value.js").FormValue<ComboValue<T>[]>;
/** The primary input of the combo component. */
private readonly _inputRef;
/** The search input of the combo component. */
private readonly _searchRef;
/** The combo virtualized dropdown list. */
private readonly _listRef;
private readonly _state;
private readonly _navigation;
private _data;
private _valueKey?;
private _displayKey?;
private _placeholderSearch?;
private _disableFiltering;
private _singleSelect;
private _selected;
private _filteringOptions;
private set _activeIndex(value);
private get _activeIndex();
private set _searchTerm(value);
private get _searchTerm();
private _activeDescendant?;
private _displayValue;
private get _mainAriaLabel();
/** The data source used to generate the list of options. */
set data(value: T[]);
get data(): T[];
/**
* The outlined attribute of the control.
* @attr outlined
* @default false
*/
outlined: boolean;
/**
* Enables single selection mode and moves item filtering to the main input.
* @attr single-select
* @default false
*/
set singleSelect(value: boolean);
get singleSelect(): boolean;
/**
* The autofocus attribute of the control.
* @attr autofocus
*/
autofocus: boolean;
/**
* Focuses the list of options when the menu opens.
* @attr autofocus-list
* @default false
*/
autofocusList: boolean;
/**
* Gets/Sets the locale used for getting language, affecting resource strings.
* @attr locale
*/
set locale(value: string);
get locale(): string;
/**
* The label attribute of the control.
* @attr label
*/
label?: string;
/**
* The placeholder attribute of the control.
* @attr placeholder
*/
placeholder?: string;
/**
* The placeholder attribute of the search input.
* @attr placeholder-search
*/
set placeholderSearch(value: string | undefined);
get placeholderSearch(): string;
/**
* The resource strings for localization.
*/
set resourceStrings(value: IComboResourceStrings);
get resourceStrings(): IComboResourceStrings;
/**
* The key in the data source used when selecting items.
* @attr value-key
*/
set valueKey(value: Keys<T> | undefined);
get valueKey(): Keys<T> | undefined;
/**
* The key in the data source used to display items in the list.
* @attr display-key
*/
set displayKey(value: Keys<T> | undefined);
get displayKey(): Keys<T> | undefined;
/**
* The key in the data source used to group items in the list.
* @attr group-key
*/
groupKey?: Keys<T> | string;
/**
* Sorts the items in each group by ascending or descending order.
* @attr group-sorting
* @default "asc"
* @type {"asc" | "desc" | "none"}
*/
groupSorting: GroupingDirection;
/**
* An object that configures the filtering of the combo.
* @attr filtering-options
*/
set filteringOptions(value: Partial<FilteringOptions<T>>);
get filteringOptions(): FilteringOptions<T>;
/**
* Enables the case sensitive search icon in the filtering input.
* @attr case-sensitive-icon
* @default false
*/
caseSensitiveIcon: boolean;
/**
* Disables the filtering of the list of options.
* @attr disable-filtering
* @default false
*/
set disableFiltering(value: boolean);
get disableFiltering(): boolean;
/**
* Hides the clear button.
* @attr disable-clear
* @default false
*/
disableClear: boolean;
/**
* The template used for the content of each combo item.
* @type {ComboItemTemplate<T>}
*/
itemTemplate: ComboItemTemplate<T>;
/**
* The template used for the content of each combo group header.
* @type {ComboItemTemplate<T>}
*/
groupHeaderTemplate: ComboItemTemplate<T>;
/**
* Sets the value (selected items). The passed value must be a valid JSON array.
* If the data source is an array of complex objects, the `valueKey` attribute must be set.
* Note that when `displayKey` is not explicitly set, it will fall back to the value of `valueKey`.
*
* @attr value
*
* @example
* ```tsx
* <igc-combo
* .data=${[
* {
* id: 'BG01',
* name: 'Sofia'
* },
* {
* id: 'BG02',
* name: 'Plovdiv'
* }
* ]}
* display-key='name'
* value-key='id'
* value='["BG01", "BG02"]'>
* </igc-combo>
* ```
*/
set value(items: ComboValue<T>[]);
/**
* Returns the current selection as a list of comma separated values,
* represented by the value key, when provided.
*/
get value(): ComboValue<T>[];
/**
* Returns the current selection as an array of objects as provided in the `data` source.
*/
get selection(): T[];
constructor();
protected willUpdate(props: PropertyValues<this>): void;
protected updated(props: PropertyValues<this>): void;
protected _restoreDefaultValue(): void;
protected _setDefaultValue(current: string | null): void;
protected _show(emitEvent?: boolean): Promise<boolean>;
protected _hide(emitEvent?: boolean): Promise<boolean>;
private _setSingleSelectionDisplayValue;
/**
* Resolves user-provided items (value keys or object references)
* to actual objects from the data source in a single pass.
*/
private _resolveItems;
/**
* Gets the value representation of a data record
* (its value-key property, or the record itself).
*/
private _resolveItemValue;
/**
* Maps data items to their value representations using the given key.
* When key is undefined, returns the items themselves.
*/
private _getValues;
private _emitSelectionChange;
private _selectItems;
private _deselectItems;
/**
* Syncs the internal `_selected` set from the current `_formValue`.
* This is a one-way sync: source of truth (_formValue) → view (_selected).
*/
private _syncSelectionFromValue;
/**
* Finds an item in the data array by its value (or value key).
* Returns undefined if the item is not found.
*/
private _findItemByValue;
protected _syncValueFromSelection(initial?: boolean): void;
private _toggleSelection;
private _selectByIndex;
private _clearSelection;
private _clearSingleSelection;
protected _handleMainInput({ detail, }: CustomEvent<string>): Promise<void>;
protected _handleFocusIn(): void;
protected _handleBlur(): void;
protected _handleSearchInput({ detail }: CustomEvent<string>): void;
private _handleClosing;
private _itemClickHandler;
private _handleClearIconClick;
private _handleCaseSensitivity;
/** Sets focus on the component. */
focus(options?: FocusOptions): void;
/** Removes focus from the component. */
blur(): void;
/**
* Selects option(s) in the list by either reference or valueKey.
* If not argument is provided all items will be selected.
* @param { Item<T> | Item<T>[] } items - One or more items to be selected. Multiple items should be passed as an array.
* When valueKey is specified, the corresponding value should be used in place of the item reference.
*
* @example
* ```typescript
* const combo<IgcComboComponent<T>> = document.querySelector('igc-combo');
*
* // Select one item at a time by reference when valueKey is not specified.
* combo.select(combo.data[0]);
*
* // Select multiple items at a time by reference when valueKey is not specified.
* combo.select([combo.data[0], combo.data[1]]);
*
* // Select one item at a time when valueKey is specified.
* combo.select('BG01');
*
* // Select multiple items at a time when valueKey is specified.
* combo.select(['BG01', 'BG02']);
* ```
*/
select(items?: Item<T> | Item<T>[]): void;
/**
* Deselects option(s) in the list by either reference or valueKey.
* If not argument is provided all items will be deselected.
* @param { Item<T> | Item<T>[] } items - One or more items to be deselected. Multiple items should be passed as an array.
* When valueKey is specified, the corresponding value should be used in place of the item reference.
*
* @example
* ```typescript
* const combo<IgcComboComponent<T>> = document.querySelector('igc-combo');
*
* // Deselect one item at a time by reference when valueKey is not specified.
* combo.deselect(combo.data[0]);
*
* // Deselect multiple items at a time by reference when valueKey is not specified.
* combo.deselect([combo.data[0], combo.data[1]]);
*
* // Deselect one item at a time when valueKey is specified.
* combo.deselect('BG01');
*
* // Deselect multiple items at a time when valueKey is specified.
* combo.deselect(['BG01', 'BG02']);
* ```
*/
deselect(items?: Item<T> | Item<T>[]): void;
protected _itemRenderer: ComboRenderFunction<T>;
private _renderToggleIcon;
private _renderClearIcon;
private _renderMainInput;
private _renderSearchInput;
private _renderEmptyTemplate;
private _renderList;
private _renderHelperText;
protected render(): TemplateResult<1>;
}
declare global {
interface HTMLElementTagNameMap {
'igc-combo': IgcComboComponent<object>;
}
}
export {};