carbon-components-angular
Version:
Next generation components
361 lines (357 loc) • 12 kB
TypeScript
/**
*
* carbon-angular v0.0.0 | combobox.component.d.ts
*
* Copyright 2014, 2025 IBM
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { OnChanges, ElementRef, EventEmitter, AfterViewInit, AfterContentInit, TemplateRef, OnDestroy } from "@angular/core";
import { AbstractDropdownView, DropdownService } from "carbon-components-angular/dropdown";
import { ListItem } from "carbon-components-angular/dropdown";
import { I18n, Overridable } from "carbon-components-angular/i18n";
import { Observable } from "rxjs";
import * as i0 from "@angular/core";
/**
* Get started with importing the module:
*
* ```typescript
* import { ComboBoxModule } from 'carbon-components-angular';
* ```
*
* ComboBoxes are similar to dropdowns, except a combobox provides an input field for users to search items and (optionally) add their own.
* Multi-select comboboxes also provide "pills" of selected items.
*
* [See demo](../../?path=/story/components-combobox--basic)
*/
export declare class ComboBox implements OnChanges, AfterViewInit, AfterContentInit, OnDestroy {
protected elementRef: ElementRef;
protected dropdownService: DropdownService;
protected i18n: I18n;
/**
* Text to show when nothing is selected.
*/
set placeholder(value: string | Observable<string>);
get placeholder(): string | Observable<string>;
/**
* Value to display for accessibility purposes on the combobox control menu when closed
*/
set openMenuAria(value: string | Observable<string>);
get openMenuAria(): string | Observable<string>;
/**
* Value to display for accessibility purposes on the combobox control menu when opened
*/
set closeMenuAria(value: string | Observable<string>);
get closeMenuAria(): string | Observable<string>;
/**
* Value to display on the clear selections icon, when multi is selected
*/
set clearSelectionsTitle(value: string | Observable<string>);
get clearSelectionsTitle(): string | Observable<string>;
/**
* Value to display for accessibility purposes to clear selections, when multi is selected
*/
set clearSelectionsAria(value: string | Observable<string>);
get clearSelectionsAria(): string | Observable<string>;
/**
* Value to display on the clear the selected item icon, when single is selected
*/
set clearSelectionTitle(value: string | Observable<string>);
get clearSelectionTitle(): string | Observable<string>;
/**
* Value to display for accessibility purposes on the clear the selected item icon, when single is selected
*/
set clearSelectionAria(value: string | Observable<string>);
get clearSelectionAria(): string | Observable<string>;
static comboBoxCount: number;
id: string;
labelId: string;
/**
* List of items to fill the content with.
*
* **Example:**
* ```javascript
* items = [
* {
* content: "Abacus",
* selected: false
* },
* {
* content: "Byte",
* selected: false,
* },
* {
* content: "Computer",
* selected: false
* },
* {
* content: "Digital",
* selected: false
* }
* ];
* ```
*
*/
items: Array<ListItem>;
/**
* Combo box type (supporting single or multi selection of items).
*/
type: "single" | "multi";
/**
* Combo box render size.
*/
size: "sm" | "md" | "lg";
/**
* Specifies the property to be used as the return value to `ngModel`
*/
itemValueKey: string;
/**
* Label for the combobox.
*/
label: string | TemplateRef<any>;
/**
* Hide label while keeping it accessible for screen readers
*/
hideLabel: boolean;
/**
* Sets the optional helper text.
*/
helperText: string | TemplateRef<any>;
/**
* set to `true` to place the dropdown view inline with the component
*/
appendInline: boolean;
/**
* Set to `true` to show the invalid state.
*/
invalid: boolean;
/**
* Value displayed if combobox is in an invalid state.
*/
invalidText: string | TemplateRef<any>;
/**
* Set to `true` to show a warning (contents set by warnText)
*/
warn: boolean;
/**
* Sets the warning text
*/
warnText: string | TemplateRef<any>;
/**
* Max length value to limit input characters
*/
maxLength: number;
/**
* @deprecated since v5 - Use `cdsLayer` directive instead
*/
theme: "light" | "dark";
/**
* Specify feedback (mode) of the selection.
* `top`: selected item jumps to top
* `fixed`: selected item stays at its position
* `top-after-reopen`: selected item jump to top after reopen dropdown
*/
selectionFeedback: "top" | "fixed" | "top-after-reopen";
/**
* Specify aria-autocomplete attribute of text input.
* "list", is the expected value for a combobox that invokes a drop-down list
*/
autocomplete: string;
/**
* Overrides the automatic dropUp.
*/
dropUp: boolean;
/**
* Set to `true` to disable combobox.
*/
disabled: boolean;
/**
* Set to `true` for readonly state.
*/
readonly: boolean;
/**
* Experimental: enable fluid state
*/
fluid: boolean;
/**
* Emits a ListItem
*
* Example:
* ```javascript
* {
* content: "one",
* selected: true
* }
* ```
*/
selected: EventEmitter<ListItem | ListItem[]>;
/**
* Intended to be used to add items to the list.
*
* Emits an event that includes the current item list, the suggested index for the new item, and a simple ListItem
*
* Example:
* ```javascript
* {
* items: [{content: "one", selected: true}, {content: "two", selected: true}],
* index: 1,
* value: {
* content: "some user string",
* selected: false
* }
* }
* ```
*
*
* Example:
* ```javascript
* {
* after: 1,
* value: "some user string"
* }
* ```
*/
submit: EventEmitter<{
items: ListItem[];
index: number;
value: {
content: string;
selected: boolean;
};
}>;
/** Emits an empty event when the menu is closed */
close: EventEmitter<void>;
/** Emits the search string from the input */
search: EventEmitter<string>;
/** Emits an event when the clear button is clicked. */
clear: EventEmitter<Event>;
/** ContentChild reference to the instantiated dropdown list */
view: AbstractDropdownView;
dropdownMenu: any;
input: ElementRef;
listbox: ElementRef;
hostClass: boolean;
open: boolean;
showClearButton: boolean;
/** Selected items for multi-select combo-boxes. */
pills: any[];
/** used to update the displayValue */
selectedValue: string;
outsideClick: any;
keyboardNav: any;
/**
* controls whether the `drop-up` class is applied
*/
_dropUp: boolean;
protected noop: any;
protected onTouchedCallback: () => void;
protected propagateChangeCallback: (_: any) => void;
protected _placeholder: Overridable;
protected _closeMenuAria: Overridable;
protected _openMenuAria: Overridable;
protected _clearSelectionsTitle: Overridable;
protected _clearSelectionsAria: Overridable;
protected _clearSelectionTitle: Overridable;
protected _clearSelectionAria: Overridable;
protected _isFocused: boolean;
/**
* Creates an instance of ComboBox.
*/
constructor(elementRef: ElementRef, dropdownService: DropdownService, i18n: I18n);
/**
* Lifecycle hook.
* Updates pills if necessary.
*
*/
ngOnChanges(changes: any): void;
/**
* Sets initial state that depends on child components
* Subscribes to select events and handles focus/filtering/initial list updates
*/
ngAfterContentInit(): void;
/**
* Binds event handlers against the rendered view
*/
ngAfterViewInit(): void;
/**
* Removing the `Dropdown` from the body if it is appended to the body.
*/
ngOnDestroy(): void;
/**
* Handles `Escape/Tab` key closing the dropdown, and arrow up/down focus to/from the dropdown list.
*/
hostkeys(ev: KeyboardEvent): void;
_noop(): void;
writeValue(value: any): void;
onBlur(): void;
registerOnChange(fn: any): void;
registerOnTouched(fn: any): void;
/**
* `ControlValueAccessor` method to programmatically disable the combobox.
*
* ex: `this.formGroup.get("myCoolCombobox").disable();`
*/
setDisabledState(isDisabled: boolean): void;
/**
* Called by `n-pill-input` when the selected pills have changed.
*/
updatePills(): void;
clearSelected(event: any): void;
/**
* Closes the dropdown and emits the close event.
*/
closeDropdown(): void;
/**
* Opens the dropdown.
*/
openDropdown(): void;
/**
* Toggles the dropdown.
*/
toggleDropdown(): void;
/**
* Sets the list group filter, and manages single select item selection.
*/
onSearch(searchString: any, shouldEmitSearch?: boolean): void;
/**
* Intended to be used to add items to the list.
*/
onSubmit(event: KeyboardEvent): void;
clearInput(event: any): void;
isTemplate(value: any): boolean;
/**
* Handles keyboard events so users are controlling the `Dropdown` instead of unintentionally controlling outside elements.
*/
_keyboardNav(event: KeyboardEvent): void;
/**
* Creates the `Dropdown` list as an element that is appended to the DOM body.
*/
_appendToBody(): void;
/**
* Creates the `Dropdown` list appending it to the dropdown parent object instead of the body.
*/
_appendToDropdown(): void;
/**
* Detects whether or not the `Dropdown` list is visible within all scrollable parents.
* This can be overridden by passing in a value to the `dropUp` input.
*/
_shouldDropUp(): boolean;
/**
* Handles clicks outside of the `Dropdown` list.
*/
_outsideClick(event: any): void;
handleFocus(event: FocusEvent): void;
protected updateSelected(): void;
protected checkForReorder(): void;
static ɵfac: i0.ɵɵFactoryDeclaration<ComboBox, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<ComboBox, "cds-combo-box, ibm-combo-box", never, { "placeholder": "placeholder"; "openMenuAria": "openMenuAria"; "closeMenuAria": "closeMenuAria"; "clearSelectionsTitle": "clearSelectionsTitle"; "clearSelectionsAria": "clearSelectionsAria"; "clearSelectionTitle": "clearSelectionTitle"; "clearSelectionAria": "clearSelectionAria"; "id": "id"; "labelId": "labelId"; "items": "items"; "type": "type"; "size": "size"; "itemValueKey": "itemValueKey"; "label": "label"; "hideLabel": "hideLabel"; "helperText": "helperText"; "appendInline": "appendInline"; "invalid": "invalid"; "invalidText": "invalidText"; "warn": "warn"; "warnText": "warnText"; "maxLength": "maxLength"; "theme": "theme"; "selectionFeedback": "selectionFeedback"; "autocomplete": "autocomplete"; "dropUp": "dropUp"; "disabled": "disabled"; "readonly": "readonly"; "fluid": "fluid"; }, { "selected": "selected"; "submit": "submit"; "close": "close"; "search": "search"; "clear": "clear"; }, ["view"], ["*"], false>;
}