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.
323 lines (322 loc) • 13.8 kB
TypeScript
import { LitElement, type TemplateResult } from 'lit';
import type { Constructor } from '../common/mixins/constructor.js';
import { type FormValue } from '../common/mixins/forms/form-value.js';
import IgcInputComponent from '../input/input.js';
import { DataController } from './controllers/data.js';
import { NavigationController } from './controllers/navigation.js';
import { SelectionController } from './controllers/selection.js';
import type { ComboItemTemplate, ComboRenderFunction, ComboValue, FilteringOptions, GroupingDirection, IgcComboComponentEventMap, Item, Keys } from './types.js';
declare const IgcComboComponent_base: Constructor<import("../common/mixins/forms/types.js").FormRequiredInterface & import("../common/mixins/forms/types.js").FormAssociatedElementInterface> & Constructor<import("../common/mixins/event-emitter.js").EventEmitterInterface<IgcComboComponentEventMap>> & Constructor<LitElement>;
/**
* 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 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(): import("../common/validators.js").Validator<IgcComboComponent<any>>[];
protected _formValue: FormValue<ComboValue<T>[]>;
private _data;
private _valueKey?;
private _displayKey?;
private _groupKey?;
private _disableFiltering;
private _singleSelect;
private _groupSorting;
private _filteringOptions;
private _activeDescendant;
private _displayValue;
protected _state: DataController<T>;
protected _selection: SelectionController<T>;
protected _navigation: NavigationController<T>;
protected inputSuffix: Array<HTMLElement>;
protected inputPrefix: Array<HTMLElement>;
protected _searchInput: IgcInputComponent;
private _input;
private _list;
/** 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
*/
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
*/
autofocusList: boolean;
/**
* 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
*/
placeholderSearch: string;
/**
* Sets the open state of the component.
* @attr open
*/
open: boolean;
/**
* 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
*/
set groupKey(value: Keys<T> | undefined);
get groupKey(): Keys<T> | undefined;
/**
* Sorts the items in each group by ascending or descending order.
* @attr group-sorting
* @default asc
* @type {"asc" | "desc" | "none"}
*/
set groupSorting(value: GroupingDirection);
get groupSorting(): GroupingDirection;
/**
* An object that configures the filtering of the combo.
* @attr filtering-options
* @type {FilteringOptions<T>}
* @param filterKey - The key in the data source used when filtering the list of options.
* @param caseSensitive - Determines whether the filtering operation should be case sensitive.
* @param matchDiacritics -If true, the filter distinguishes between accented letters and their base letters.
*/
set filteringOptions(value: Partial<FilteringOptions<T>>);
get filteringOptions(): FilteringOptions<T>;
/**
* Enables the case sensitive search icon in the filtering input.
* @attr case-sensitive-icon
*/
caseSensitiveIcon: boolean;
/**
* Disables the filtering of the list of options.
* @attr disable-filtering
* @default false
*/
set disableFiltering(value: boolean);
get disableFiltering(): 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>[];
protected _updateSelection(): void;
protected toggleDirectiveChange(): void;
private _rootClickController;
constructor();
protected firstUpdated(): Promise<void>;
protected _restoreDefaultValue(): void;
protected _setDefaultValue(current: string | null): void;
protected _setFormValue(): void;
protected resetSearchTerm(): void;
protected updateValue(initial?: boolean): void;
/** Sets focus on the component. */
focus(options?: FocusOptions): void;
/** Removes focus from the component. */
blur(): void;
/**
* Returns the current selection as an array of objects as provided in the `data` source.
*/
get selection(): T[];
/**
* Selects option(s) in the list by either reference or valueKey.
* If not argument is provided all items will be selected.
* @param { Item<T> | Items<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> | Items<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 handleMainInput({ detail }: CustomEvent<string>): Promise<void>;
private _handleBlur;
protected handleSearchInput({ detail }: CustomEvent<string>): void;
protected handleOpening(): boolean;
protected handleClosing(): boolean;
protected _show(emitEvent?: boolean): Promise<boolean>;
/** Shows the list of options. */
show(): Promise<boolean>;
protected _hide(emitEvent?: boolean): Promise<boolean>;
/** Hides the list of options. */
hide(): Promise<boolean>;
protected _toggle(emit?: boolean): Promise<boolean>;
/** Toggles the list of options. */
toggle(): Promise<boolean>;
private _getActiveDescendantId;
protected itemRenderer: ComboRenderFunction<T>;
protected listKeydownHandler(event: KeyboardEvent): void;
protected itemClickHandler(event: PointerEvent): void;
protected toggleSelect(index: number): void;
protected selectByIndex(index: number): void;
protected clearSingleSelection(): void;
protected handleClearIconClick(e: PointerEvent): void;
protected handleMainInputKeydown(e: KeyboardEvent): void;
protected handleSearchInputKeydown(e: KeyboardEvent): void;
protected toggleCaseSensitivity(): void;
private _stopPropagation;
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 {};