@eccenca/gui-elements/dist/types/components/AutocompleteField/AutoCompleteField.d.ts

GUI elements based on other libraries, usable in React application, written in Typescript.

import React from "react";
import { HTMLInputProps as BlueprintHTMLInputProps, InputGroupProps as BlueprintInputGroupProps } from "@blueprintjs/core";
import { ContextOverlayProps } from "../../index";
import { SuggestFieldItemRendererModifierProps } from "./interfaces";
type SearchFunction<T> = (value: string) => T[];
type AsyncSearchFunction<T> = (value: string) => Promise<T[]>;
/**
 * Parameters for the auto-complete field parameterized by T and U.
 * @param T is the input data structure/type of the items that can be selected.
 * @param UPDATE_VALUE The value type that will be pushed into the onChange callback.
 */
export interface SuggestFieldProps<T, UPDATE_VALUE> {
    /**
     * Additional class names.
     */
    className?: string;
    /**
     * Fired when text is typed into the input field. Returns a list of items of type T.
     */
    onSearch: SearchFunction<T> | AsyncSearchFunction<T>;
    /**
     * Fired when value selected from input
     * @param value The value that has been converted with itemValueSelector.
     * @param e     The event
     */
    onChange?(value: UPDATE_VALUE, e?: React.SyntheticEvent<HTMLElement>): any;
    /**
     * The initial value for the auto-complete input field
     */
    initialValue?: T;
    /**
     * Returns the UI representation of the selectable items.
     * If the return value is a string, a default render component will be displayed with search highlighting.
     *
     * @param item  The item that should be displayed as an option in the select list.
     * @param query The current search query
     * @param modifiers Modifiers for rendered elements, e.g. active, disabled.
     * @param handleClick The function that needs to be called when the rendered item gets clicked. Else a selection
     *                    via mouse is not possible. This only needs to be used when returning a JSX.Element.
     */
    itemRenderer(item: T, query: string, modifiers: SuggestFieldItemRendererModifierProps, handleClick: () => any): string | JSX.Element;
    /** Renders the string that should be displayed in the input field after the item has been selected.
     */
    itemValueRenderer(item: T): string;
    /**
     * Selects the part from the auto-completion item that is called with the onChange callback.
     * @param item The selected item that should be converted to the value that onChange is called with.
     */
    itemValueSelector(item: T): UPDATE_VALUE;
    /** The string representation of the actual value, i.e. without meta data etc. This will be used to compare if values are equal. */
    itemValueString(item: T): string;
    /** The text that should be displayed when no search result has been found and no custom entry can be created. */
    noResultText: string;
    /**
     * Props to spread to the underlying input field. This is BlueprintJs specific. To control this input, use
     * `query` and `onQueryChange` instead of `inputProps.value` and
     * `inputProps.onChange`.
     */
    inputProps?: BlueprintInputGroupProps & BlueprintHTMLInputProps;
    /**
     * Optional props of the internally used `<ContextOverlay/>` element..
     */
    contextOverlayProps?: Partial<Omit<ContextOverlayProps, "content" | "children">>;
    /** Defines if a value can be reset, i.e. a reset icon is shown and the value is set to a specific value.
     *  When undefined, a value cannot be reset.
     */
    reset?: {
        /** Returns true if the currently set value can be reset, i.e. set to the resetValue. The reset icon is only
         *  shown if true is returned. */
        resettableValue(value: T): boolean;
        /** The value onChange is called with when a reset action is triggered. */
        resetValue: UPDATE_VALUE;
        /** The reset button text that is shown on hovering over the reset icon. */
        resetButtonText: string;
    };
    /** If enabled the auto completion component will auto focus. */
    autoFocus?: boolean;
    /** Contains methods for new item creation. If undefined no new, custom items can be created. */
    createNewItem?: {
        /** Creates a new item from the query. */
        itemFromQuery: (query: string) => T;
        /** Renders how the option to newly create an item should look like in the selection list. */
        itemRenderer: (query: string, modifiers: SuggestFieldItemRendererModifierProps, handleClick: React.MouseEventHandler<HTMLElement>) => JSX.Element | undefined;
        /** If the new item option will always be shown as the first entry in the suggestion list, else it will be the last entry.
         * @default false
         */
        showNewItemOptionFirst?: boolean;
    };
    /** Dropdown is only rendered when the query has a value (input field is not empty). */
    onlyDropdownWithQuery?: boolean;
    /** If true the input field will be disabled. */
    disabled?: boolean;
    /** The value to which the search query should be reset after the popover closes.
     *  By default the query is reset to the result of itemValueRenderer(selectedValue).
     *
     * @param selectedValue The currently selected value.
     */
    resetQueryToValue?(selectedValue: T): string;
    /** If an error occurs during the auto-completion request, the error details will be prefixed with this string. */
    requestErrorPrefix?: string;
    /** Creates a backdrop when the popover is shown that captures outside clicks in order to close the popover.
     * This is needed if other components on the same page are swallowing events, e.g. the react-flow canvas.
     * hasBackDrop should then be set to true in these cases otherwise the popover won't close when clicking those other components.
     **/
    hasBackDrop?: boolean;
    /**
     * Use the full available width of the parent container.
     */
    fill?: boolean;
    /** Utility that fetches more options when clicked*/
    loadMoreResults?: () => Promise<T[] | undefined>;
}
/**
 * A component with the appearance of an input field that allows to select and optionally create new items.
 * It shows suggestions for the entered text from which the user can select any option.
 *
 * It has the following fixed behavior:
 *
 * - When not focused, a different representation of the item value can be shown, e.g. the label of the value.
 * - When changing an existing item the input text is set to the original value in order to be able to edit the original value.
 * - When for a specific input text, the only item returned is the currently set item itself, all items are shown below it, to make
 *   clear that there are still other items to choose from.
 * - The suggestions are fetched with a short delay, so not too many unnecessary requests are fired.
 * - Items where itemRenderer returns a string have a default representation, i.e. highlighting of search words, active flag etc.
 */
export declare function SuggestField<T, UPDATE_VALUE>(props: SuggestFieldProps<T, UPDATE_VALUE>): React.JSX.Element;
export declare namespace SuggestField {
    var defaultProps: {
        autoFocus: boolean;
        disabled: boolean;
        onlyDropdownWithQuery: boolean;
        fill: boolean;
        requestErrorPrefix: string;
        hasBackDrop: boolean;
    };
}
export default SuggestField;