carbon-components-angular
Version:
Next generation components
316 lines (312 loc) • 11 kB
TypeScript
/**
*
* carbon-angular v0.0.0 | dropdown.component.d.ts
*
* Copyright 2014, 2024 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 { EventEmitter, ElementRef, OnInit, AfterContentInit, OnDestroy, TemplateRef, AfterViewInit } from "@angular/core";
import { ControlValueAccessor } from "@angular/forms";
import { Observable, Subscription } from "rxjs";
import { AbstractDropdownView } from "./abstract-dropdown-view.class";
import { I18n } from "carbon-components-angular/i18n";
import { ListItem } from "./list-item.interface";
import { DropdownService } from "./dropdown.service";
import { ElementService } from "carbon-components-angular/utils";
import * as i0 from "@angular/core";
/**
* Drop-down lists enable users to select one or more items from a list.
*
* #### Opening behavior/List DOM placement
* By default the dropdown will try to figure out the best placement for the dropdown list.
*
* If it's not contained within any scrolling elements, it will open inline, if it _is_
* contained within a scrolling container it will try to open in the body, or an `cds-placeholder`.
*
* To control this behavior you can use the `appendInline` input:
* - `[appendInline]="null"` is the default (auto detection)
* - `[appendInline]="false"` will always append to the body/`cds-placeholder`
* - `[appendInline]="true"` will always append inline (next to the dropdown button)
*
* Get started with importing the module:
*
* ```typescript
* import { DropdownModule } from 'carbon-components-angular';
* ```
*
* [See demo](../../?path=/story/components-dropdown--basic)
*/
export declare class Dropdown implements OnInit, AfterContentInit, AfterViewInit, OnDestroy, ControlValueAccessor {
protected elementRef: ElementRef;
protected i18n: I18n;
protected dropdownService: DropdownService;
protected elementService: ElementService;
static dropdownCount: number;
id: string;
/**
* Label for the dropdown.
*/
label: string | TemplateRef<any>;
/**
* Hide label while keeping it accessible for screen readers
*/
hideLabel: boolean;
/**
* Sets the optional helper text.
*/
helperText: string | TemplateRef<any>;
/**
* Value displayed if no item is selected.
*/
placeholder: string;
/**
* The selected value from the `Dropdown`. Can be a string or template.
*/
displayValue: string | TemplateRef<any>;
/**
* Sets the optional clear button tooltip text.
*/
clearText: string;
/**
* Size to render the dropdown field.
*/
size: "sm" | "md" | "lg";
/**
* Defines whether or not the `Dropdown` supports selecting multiple items as opposed to single
* item selection.
*/
type: "single" | "multi";
/**
* @deprecated since v5 - Use `cdsLayer` directive instead
* `light` or `dark` dropdown theme
*/
theme: "light" | "dark";
/**
* Set to `true` to disable the dropdown.
*/
disabled: boolean;
/**
* Set to `true` for a loading dropdown.
*/
skeleton: boolean;
/**
* Set to `true` for an inline dropdown.
*/
inline: boolean;
/**
* Set to `true` for a dropdown without arrow key activation.
*/
disableArrowKeys: boolean;
/**
* Set to `true` for invalid state.
*/
invalid: boolean;
/**
* Value displayed if dropdown is in invalid state.
*/
invalidText: string | TemplateRef<any>;
/**
* Set to `true` to show a warning (contents set by warningText)
*/
warn: boolean;
/**
* Sets the warning text
*/
warnText: string | TemplateRef<any>;
/**
* set to `true` to place the dropdown view inline with the component
*/
appendInline: boolean;
/**
* Query string for the element that contains the `Dropdown`.
* Used to trigger closing the dropdown if it scrolls outside of the viewport of the `scrollableContainer`.
*/
scrollableContainer: string;
/**
* Specifies the property to be used as the return value to `ngModel`
*/
itemValueKey: string;
/**
* Specify feedback (mode) of the selection.
* `top`: selected item jumps to top
* `fixed`: selected item stays at it's position
* `top-after-reopen`: selected item jump to top after reopen dropdown
*/
selectionFeedback: "top" | "fixed" | "top-after-reopen";
/**
* Accessible label for the button that opens the dropdown list.
* Defaults to the `DROPDOWN.OPEN` value from the i18n service.
*/
menuButtonLabel: any;
/**
* Provides the label for the "# selected" text.
* Defaults to the `DROPDOWN.SELECTED` value from the i18n service.
*/
selectedLabel: any;
/**
* Overrides the automatic dropUp.
*/
dropUp: boolean;
/**
* Emits selection events.
*/
selected: EventEmitter<Object>;
/**
* Emits event notifying to other classes that the `Dropdown` has been closed (collapsed).
*/
onClose: EventEmitter<any>;
/**
* Emits event notifying to other classes that the `Dropdown` has been closed (collapsed).
*/
close: EventEmitter<any>;
/**
* Maintains a reference to the `AbstractDropdownView` object within the content DOM.
*/
view: AbstractDropdownView;
/**
* Maintains a reference to the view DOM element of the `Dropdown` button.
*/
dropdownButton: any;
/**
* ViewChid of the dropdown view.
*/
dropdownMenu: any;
hostClass: boolean;
/**
* Set to `true` if the dropdown is closed (not expanded).
*/
menuIsClosed: boolean;
/**
* controls whether the `drop-up` class is applied
*/
_dropUp: boolean;
noop: any;
outsideClick: any;
outsideKey: any;
keyboardNav: any;
protected visibilitySubscription: Subscription;
protected onTouchedCallback: () => void;
private _writtenValue;
protected get writtenValue(): any[];
protected set writtenValue(val: any[]);
/**
* Creates an instance of Dropdown.
*/
constructor(elementRef: ElementRef, i18n: I18n, dropdownService: DropdownService, elementService: ElementService);
/**
* Updates the `type` property in the `@ContentChild`.
* The `type` property specifies whether the `Dropdown` allows single selection or multi selection.
*/
ngOnInit(): void;
/**
* Initializes classes and subscribes to events for single or multi selection.
*/
ngAfterContentInit(): void;
ngAfterViewInit(): void;
/**
* Removing the `Dropdown` from the body if it is appended to the body.
*/
ngOnDestroy(): void;
/**
* Propagates the injected `value`.
*/
writeValue(value: any): void;
onBlur(): void;
registerOnChange(fn: any): void;
/**
* Registering the function injected to control the touch use of the `Dropdown`.
*/
registerOnTouched(fn: any): void;
/**
* function passed in by `registerOnChange`
*/
propagateChange: (_: any) => void;
/**
* `ControlValueAccessor` method to programmatically disable the dropdown.
*
* ex: `this.formGroup.get("myDropdown").disable();`
*
* @param isDisabled `true` to disable the input
*/
setDisabledState(isDisabled: boolean): void;
/**
* Adds keyboard functionality for navigation, selection and closing of the `Dropdown`.
*/
onKeyDown(event: KeyboardEvent): void;
closedDropdownNavigation(event: any): void;
/**
* Returns the display value if there is a selection and displayValue is set,
* if there is just a selection the ListItem content property will be returned,
* otherwise the placeholder will be returned.
*/
getDisplayStringValue(): Observable<string>;
isRenderString(): boolean;
getRenderTemplateContext(): {
items: ListItem[];
item?: undefined;
} | {
item: ListItem;
items?: undefined;
} | {
items?: undefined;
item?: undefined;
};
getSelectedCount(): number;
clearSelected(): void;
/**
* Returns `true` if there is a value selected.
*/
valueSelected(): boolean;
_noop(): void;
/**
* Handles clicks outside of the `Dropdown`.
*/
_outsideClick(event: any): void;
_outsideKey(event: any): void;
/**
* Handles keyboard events so users are controlling the `Dropdown` instead of unintentionally controlling outside elements.
*/
_keyboardNav(event: KeyboardEvent): void;
/**
* Creates the `Dropdown` list appending it to the dropdown parent object instead of the body.
*/
_appendToDropdown(): void;
/**
* Creates the `Dropdown` list as an element that is appended to the DOM body.
*/
_appendToBody(): 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;
/**
* Expands the dropdown menu in the view.
*/
openMenu(): void;
/**
* Collapsing the dropdown menu and removing unnecessary `EventListeners`.
*/
closeMenu(): void;
/**
* Controls toggling menu states between open/expanded and closed/collapsed.
*/
toggleMenu(): void;
isTemplate(value: any): boolean;
/**
* Controls when it's needed to apply the selection feedback
*/
protected checkForReorder(): void;
static ɵfac: i0.ɵɵFactoryDeclaration<Dropdown, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<Dropdown, "cds-dropdown, ibm-dropdown", never, { "id": "id"; "label": "label"; "hideLabel": "hideLabel"; "helperText": "helperText"; "placeholder": "placeholder"; "displayValue": "displayValue"; "clearText": "clearText"; "size": "size"; "type": "type"; "theme": "theme"; "disabled": "disabled"; "skeleton": "skeleton"; "inline": "inline"; "disableArrowKeys": "disableArrowKeys"; "invalid": "invalid"; "invalidText": "invalidText"; "warn": "warn"; "warnText": "warnText"; "appendInline": "appendInline"; "scrollableContainer": "scrollableContainer"; "itemValueKey": "itemValueKey"; "selectionFeedback": "selectionFeedback"; "menuButtonLabel": "menuButtonLabel"; "selectedLabel": "selectedLabel"; "dropUp": "dropUp"; }, { "selected": "selected"; "onClose": "onClose"; "close": "close"; }, ["view"], ["*"], false>;
}