@ux-aspects/ux-aspects/components/tag-input/tag-input.component.d.ts

Open source user interface framework for building modern, responsive, mobile big data applications

import { BooleanInput } from '@angular/cdk/coercion';
import { AfterContentInit, ElementRef, EventEmitter, OnChanges, OnDestroy, QueryList, SimpleChanges, TemplateRef } from '@angular/core';
import { ControlValueAccessor, ValidationErrors, Validator } from '@angular/forms';
import { TypeaheadComponent } from '../typeahead/index';
import { TypeaheadOptionEvent } from '../typeahead/typeahead-event';
import { TagInputEvent } from './tag-input-event';
import * as i0 from "@angular/core";
export declare class TagInputComponent<T = any> implements AfterContentInit, OnChanges, ControlValueAccessor, Validator, OnDestroy {
    private readonly _changeDetector;
    private readonly _element;
    private readonly _typeaheadKeyService;
    private readonly _document;
    /** Specify a unique Id for the component */
    id: string;
    /**
     * The list of tags appearing in the tag input. This can be an array of strings or custom objects.
     * See the `displayProperty` property for details of using a custom object.
     */
    get tags(): T | ReadonlyArray<T>;
    set tags(value: T | ReadonlyArray<T>);
    /** The editable text appearing in the tag input. */
    input: string;
    /**
     * Determines the display value of the `options`, if they are custom objects.
     * This may be a function or a string. If a function is provided, it receives
     * the option object as an argument, and should return the appropriate display value.
     * If the name of a property is provided as a string, that property is used as the display value.
     */
    display: TagInputDisplayFunction<T> | string;
    /** Controls whether pasting text into the text input area automatically converts that text into one or more tags. */
    addOnPaste: boolean;
    /** The aria-label to apply to the child `input` element. */
    ariaLabel: string;
    /** ID of the element which serves as a label for the input element. */
    ariaLabelledby: string;
    /** Controls the disabled state of the tag input. */
    disabled: boolean;
    /** Specified if this is a required input. */
    required: boolean;
    /**
     * If set to `true`, the tag input will prevent addition and removal of tags to enforce the minTags and maxTags settings.
     * Otherwise, a validation error will be raised.
     */
    enforceTagLimits: boolean;
    /**
     * If `true`, input entered into the text input area can be converted into a tag by pressing enter.
     * Otherwise, tags can only be added from the typeahead list or other external means.
     * (Note that the `maxTags` and `tagPattern` will prevent invalid inputs regardless of this setting.)
     */
    freeInput: boolean;
    /** If `true` the input field will be readonly and selection can only occur by using the dropdown. */
    readonlyInput: boolean;
    /**
     * The maximum number of tags permitted in the tag input. If the number of tags is equal to `maxTags` and
     * `enforceTagLimits` is `true`, addition of tags will be prevented until a tag is removed
     */
    maxTags: number;
    /**
     * The minimum number of tags permitted in the tag input. If the number of tags is equal to `minTags` and `enforceTagLimits` is
     * `true`, removal of tags will be prevented until a new tag is added.
     */
    minTags: number;
    /** The placeholder text which appears in the text input area when it is empty. */
    placeholder: string;
    /** Controls whether the typeahead appears when the text input area is clicked. This has no effect if the ux-typeahead component is not configured. */
    showTypeaheadOnClick: boolean;
    /**
     * A string containing the characters which delimit tags.
     * Typing one of the characters in `tagDelimiters` will cause the preceding text to be added as a tag,
     * and the text input area will be cleared. Pasting a string containing one or more of characters in
     * `tagDelimiters` will cause the string to be split into multiple tags.
     * Note that the delimiter character will not be part of the tag text.
     */
    tagDelimiters: string;
    /** The validation expression for tags added via the input text area. Strings which do not match this expression will not be added as tags. */
    tagPattern: RegExp;
    /**
     * A template which will be rendered as the content of each tag. The following context properties are available in the template:
     * - `tag: any` - the string or custom object representing the tag.
     * - `index: number` - the zero-based index of the tag as it appears in the tag input.
     * - `api: TagApi` - provides the functions getTagDisplay, removeTagAt and canRemoveTagAt.
     */
    tagTemplate: TemplateRef<TagTemplateContext<T>>;
    /**
     * A function which returns either a string, string[], or Set<string>, compatible with the NgClass directive. The function receives the following parameters:
     * - `tag: any` - the string or custom object representing the tag.
     * - `index: number` - the zero-based index of the tag as it appears in the tag input.
     * - `selected: boolean` - true if the tag is currently selected.
     */
    tagClass: TagClassFunction<T>;
    /**
     * An object which contains details of validation errors. The following properties will be present if there is a related validation error:
     * - `tagRangeError` - present if the number of tags is outside the range specified by minTags and maxTags.
     * - `inputPattern` - present if an input has been submitted which does not match the tagPattern.
     */
    validationErrors: any;
    /** Defines the autocomplete property on the input field which can be used to prevent the browser from displaying autocomplete suggestions. */
    autocomplete: string;
    /**
     * A custom function which is called to create a new tag object.
     * This can be used to populate other properties in the tag object.
     * If `createTag` is not provided, then an object is created with the `displayProperty` set to the input.
     * If `displayProperty` is also not set, then the tag is created as a simple string.
     */
    createTagHandler: (value: string) => any;
    /** Define a custom icon to be used instead of the chevron */
    icon: TemplateRef<void>;
    /** Determine if we should show the clear all button */
    clearButton: boolean;
    /** Determine an aria label for the clear button */
    clearButtonAriaLabel: string;
    /** Determine if the dropdown panel should close on external click.*/
    set autoCloseDropdown(value: boolean);
    get autoCloseDropdown(): boolean;
    /** Emits when tags is changed. */
    tagsChange: EventEmitter<readonly T[]>;
    /** Emits when input is changed. */
    inputChange: EventEmitter<string>;
    /** Raised when a tag is about to be added. The `tag` property of the event contains the tag to be added. Call `preventDefault()` on the event to prevent addition. */
    tagAdding: EventEmitter<TagInputEvent>;
    /** Raised when a tag has been added. The tag property of the event contains the tag. */
    tagAdded: EventEmitter<TagInputEvent>;
    /** Raised when a tag has failed validation according to the `tagPattern`. The tag property of the event contains the string which failed validation. */
    tagInvalidated: EventEmitter<TagInputEvent>;
    /** Raised when a tag is about to be removed. The `tag` property of the event contains the tag to be removed. Call `preventDefault()` on the event to prevent removal. */
    tagRemoving: EventEmitter<TagInputEvent>;
    /** Raised when a tag has been removed. The tag property of the event contains the tag. */
    tagRemoved: EventEmitter<TagInputEvent>;
    /** Raised when a tag has been clicked. The `tag` property of the event contains the clicked tag. Call `preventDefault()` on the event to prevent the default behaviour of selecting the tag. */
    tagClick: EventEmitter<TagInputEvent>;
    inputFocus: EventEmitter<FocusEvent>;
    inputBlur: EventEmitter<FocusEvent>;
    typeaheadQuery: QueryList<TypeaheadComponent>;
    tagInput: ElementRef<HTMLInputElement>;
    selectedIndex: number;
    tagApi: TagApi<T>;
    valid: boolean;
    inputValid: boolean;
    typeahead: TypeaheadComponent;
    highlightedElement: HTMLElement;
    get _showClearButton(): boolean;
    _tags: ReadonlyArray<T>;
    private _onChangeHandler;
    private _onTouchedHandler;
    private _subscription;
    private readonly _onDestroy;
    private _autoCloseDropdown;
    static ngAcceptInputType_autoCloseDropdown: BooleanInput;
    ngAfterContentInit(): void;
    ngOnChanges(changes: SimpleChanges): void;
    ngOnDestroy(): void;
    writeValue(value: T[]): void;
    registerOnChange(fn: () => void): void;
    registerOnTouched(fn: () => void): void;
    setDisabledState(isDisabled: boolean): void;
    /**
     * Set focus on the input field.
     */
    focus(): void;
    /**
     * Validate the value of the control (tags property).
     */
    validate(): ValidationErrors | null;
    keyHandler(event: KeyboardEvent): void;
    focusOutHandler(): void;
    onClick(): void;
    tagClickHandler(event: MouseEvent, tag: T, index: number): void;
    inputClickHandler(): void;
    inputFocusHandler(): void;
    inputPasteHandler(event: ClipboardEvent): void;
    typeaheadOptionSelectedHandler(event: TypeaheadOptionEvent): void;
    /**
     * Commit the current input value and clear the input field if successful.
     */
    commitInput(): void;
    /**
     * Commit the given tag object and clear the input if successful.
     */
    commitTypeahead(tag: T): void;
    /**
     * Commit the given string value as one or more tags, if validation passes. Returns true if the tag(s) were created.
     */
    commit(input: string): boolean;
    /**
     * If no tag is selected, select the rightmost tag. If a tag is selected, remove it.
     */
    backspace(): void;
    /**
     * Move the highlighted option forwards or backwards in the list. Wraps at the limits.
     * @param delta Value to be added to the selected index, i.e. -1 to move backwards, +1 to move forwards.
     */
    moveSelection(delta: number): void;
    /**
     * Returns a value to display for the given tag. Uses display function/property name if set, otherwise assumes that the tag is a simple string.
     */
    getTagDisplay(tag: any): string;
    /**
     * Returns true if the given index is selected (tag index or input field).
     */
    isSelected(index: number): boolean;
    /**
     * Select the tag at the given index. Does nothing if disabled is true.
     */
    selectTagAt(tagIndex: number): void;
    /**
     * Select the input field, giving it focus. Does nothing if disabled is true.
     */
    selectInput(): void;
    /**
     * Remove the tag at the given index. Does nothing if disabled is true or the minTags property prevents removal.
     */
    removeTagAt(tagIndex: number): void;
    /**
     * Returns true if the tag at the given index can be removed.
     */
    canRemoveTagAt(): boolean;
    /**
     * Returns true if the input field should be available.
     */
    isInputVisible(): boolean;
    /**
     * Returns true if any part of the control has focus.
     */
    hasFocus(): boolean;
    toggle(): void;
    clear(): void;
    setInputValue(text: string): void;
    setTagsValue(tags: ReadonlyArray<T>): void;
    private connectTypeahead;
    /**
     * Validate the given tagValue with the tagPattern, if set. Update validationErrors on validation failure.
     */
    private validateTag;
    /**
     * Create a tag object for the given tagValue. If createTagHandler is specified, use it; otherwise if displayProperty is specified, create an object with the tagValue as the single named property; otherwise return the tagValue itself.
     */
    private createTag;
    /**
     * Add a tag object, calling the tagAdding and tagAdded events. Returns true if the tag was added to the tags array.
     */
    private addTag;
    /**
     * Returns true if the given tagIndex is a valid tag index.
     */
    private isValidTagIndex;
    /**
     * Returns true if the given index is a valid selection index (tags or input field).
     */
    private isValidSelectIndex;
    /**
     * Returns the character corresponding to the given key event, mainly for IE compatibility.
     */
    private getKeyChar;
    /**
     * Returns an array of strings corresponding to the input string split by the tagDelimiters characters.
     */
    private splitTagInput;
    static ɵfac: i0.ɵɵFactoryDeclaration<TagInputComponent<any>, never>;
    static ɵcmp: i0.ɵɵComponentDeclaration<TagInputComponent<any>, "ux-tag-input", ["ux-tag-input"], { "id": { "alias": "id"; "required": false; }; "tags": { "alias": "tags"; "required": false; }; "input": { "alias": "input"; "required": false; }; "display": { "alias": "display"; "required": false; }; "addOnPaste": { "alias": "addOnPaste"; "required": false; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "required": { "alias": "required"; "required": false; }; "enforceTagLimits": { "alias": "enforceTagLimits"; "required": false; }; "freeInput": { "alias": "freeInput"; "required": false; }; "readonlyInput": { "alias": "readonlyInput"; "required": false; }; "maxTags": { "alias": "maxTags"; "required": false; }; "minTags": { "alias": "minTags"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "showTypeaheadOnClick": { "alias": "showTypeaheadOnClick"; "required": false; }; "tagDelimiters": { "alias": "tagDelimiters"; "required": false; }; "tagPattern": { "alias": "tagPattern"; "required": false; }; "tagTemplate": { "alias": "tagTemplate"; "required": false; }; "tagClass": { "alias": "tagClass"; "required": false; }; "validationErrors": { "alias": "validationErrors"; "required": false; }; "autocomplete": { "alias": "autocomplete"; "required": false; }; "createTagHandler": { "alias": "createTag"; "required": false; }; "icon": { "alias": "icon"; "required": false; }; "clearButton": { "alias": "clearButton"; "required": false; }; "clearButtonAriaLabel": { "alias": "clearButtonAriaLabel"; "required": false; }; "autoCloseDropdown": { "alias": "autoCloseDropdown"; "required": false; }; }, { "tagsChange": "tagsChange"; "inputChange": "inputChange"; "tagAdding": "tagAdding"; "tagAdded": "tagAdded"; "tagInvalidated": "tagInvalidated"; "tagRemoving": "tagRemoving"; "tagRemoved": "tagRemoved"; "tagClick": "tagClick"; "inputFocus": "inputFocus"; "inputBlur": "inputBlur"; }, ["typeaheadQuery"], ["*"], false, never>;
}
/**
 * The API available to tag templates.
 */
export interface TagApi<T = any> {
    /**
     * Returns the display value of the given tag, according to the displayProperty property.
     */
    getTagDisplay: (tag: T) => string;
    /**
     * Removes the tag at the given index, if possible.
     */
    removeTagAt: (index: number) => void;
    /**
     *    Returns true if the tag at the given index can be removed.
     */
    canRemoveTagAt: (index: number) => boolean;
}
/**
 * The function used to return custom class information, for use in `ngClass`.
 */
export type TagClassFunction<T = any> = (tag: T, index: number, selected: boolean) => string | string[] | Set<string>;
export type TagInputDisplayFunction<T> = (option: T) => string;
export interface TagTemplateContext<T = string | any> {
    tag: T;
    index: number;
    api: TagApi;
}