@sap-ux/ui-components/dist/components/UIComboBox/UIComboBox.d.ts

SAP UI Components Library

import React from 'react';
import type { IComboBoxProps, IComboBoxOption } from '@fluentui/react';
import './UIComboBox.scss';
import './Callout.scss';
import type { UIMessagesExtendedProps } from '../../helper/ValidationMessage/index.js';
export { type IComboBoxOption as UIComboBoxOption, type ISelectableOption as UISelectableOption, type IComboBox as UIComboBoxRef, type IOnRenderComboBoxLabelProps as UIOnRenderComboBoxLabelProps, SelectableOptionMenuItemType as UISelectableOptionMenuItemType } from '@fluentui/react';
export declare enum UIComboBoxLoaderType {
    /**
     * Loader within dropdown list
     */
    List = "List",
    /**
     * Loader within input
     */
    Input = "Input"
}
export interface UIComboBoxExternalSearchProps {
    /**
     * Label displayed in the dropdown when there are no available options.
     */
    noDataLabel?: string;
    /**
     * Callback triggered immediately when the user types in the input field.
     * Useful to clear data and show loader indicator.
     */
    onInputChange?: (query: string) => void;
    /**
     * Callback triggered after the user stops typing for the specified debounce duration.
     * This is where the external search should be performed.
     */
    onExternalSearch: (query: string) => void;
    /**
     * Delay in milliseconds between the last user input and triggering the external search.
     *
     * @default 500
     */
    debounceTime?: number;
}
export interface UIComboBoxProps extends IComboBoxProps, UIMessagesExtendedProps {
    wrapperRef?: React.RefObject<HTMLDivElement>;
    highlight?: boolean;
    useComboBoxAsMenuMinWidth?: boolean;
    openMenuOnClick?: boolean;
    /**
     *
     */
    onRefresh?(): void;
    /**
     *
     */
    onHandleChange?(value: string | number): void;
    tooltipRefreshButton?: string;
    /**
     * Show loading indicator(s).
     * Supported places:
     * 1. List - loader within dropdown list
     * 2. Input - loader within input
     */
    isLoading?: boolean | UIComboBoxLoaderType[];
    isForceEnabled?: boolean;
    readOnly?: boolean;
    calloutCollisionTransformation?: boolean;
    /**
     * Determines whether the `key` property should be considered during search.
     * By default, only the `text` property of an option is considered.
     *
     * @default false
     */
    searchByKeyEnabled?: boolean;
    /**
     * Custom filter function to apply custom filtering logic on top of the default search.
     * Receives the current search term and an option, returning `true` if the option should be shown,
     * `false` to hide it, or `undefined` to apply the default search filtering behavior.
     */
    customSearchFilter?: (searchTerm: string, option: IComboBoxOption) => boolean | undefined;
    /**
     * Properties to support external (backend) search behavior in the ComboBox.
     */
    externalSearchProps?: UIComboBoxExternalSearchProps;
}
export interface UIComboBoxState {
    minWidth?: number;
    isListHidden?: boolean;
}
/**
 * UIComboBox component.
 *
 * @exports
 * @class {UIComboBox}
 * @extends {React.Component<UIComboBoxProps, UIComboBoxState>}
 */
export declare class UIComboBox extends React.Component<UIComboBoxProps, UIComboBoxState> {
    static defaultProps: {
        openMenuOnClick: boolean;
    };
    private readonly comboBox;
    private readonly comboboxDomRef;
    private readonly menuDomRef;
    private readonly selectedElement;
    private query;
    private readonly ignoreOpenKeys;
    private isListHidden;
    private readonly calloutCollisionTransform;
    private readonly onExternalSearchDebounce;
    private hiddenOptions;
    /**
     * Initializes component properties.
     *
     * @param {UIComboBoxProps} props
     */
    constructor(props: UIComboBoxProps);
    /**
     * Method checks if the options or loading state have changed and a query exists, it updates the hidden options.
     *
     * @param nextProps - The incoming props to compare with current props.
     * @returns Always returns true to allow the component to re-render.
     */
    shouldComponentUpdate(nextProps: UIComboBoxProps): boolean;
    /**
     * Checks if the loading state has changed between the previous and new loader values.
     *
     * @param prevLoader The previous loading state.
     * @param newLoader The new loading state.
     * @returns True if the loading state has changed.
     */
    private isLoaderChanged;
    /**
     * Updates hidden options.
     *
     * @param opts Current combobox options
     * @param isLoading Current combobox loading state
     */
    private updateHiddenOptions;
    /**
     * Determines whether an option should be hidden based on the current search query.
     * Applies a custom filter if `customSearchFilter` is provided, otherwise uses the default
     * search logic to match the `text` property (and `key` if `searchByKeyEnabled` is enabled).
     *
     * @param option - The option to evaluate for visibility.
     * @param query - The current search query string.
     * @returns `true` if the option should be hidden, `false` if it should be visible.
     */
    private isOptionVisibleByQuery;
    /**
     * Method prevents cursor from jumping to the end of input.
     *
     * @param {React.FormEvent<IComboBox>} event Combobox event object
     */
    private setCaretPosition;
    /**
     * Method filters options and hides unmatched options.
     *
     * @param {React.FormEvent<IComboBox>} event Combobox event object
     */
    private onInput;
    /**
     * Method opens menu when user clicks on Combobox (input or button).
     *
     * @param event
     */
    private onClick;
    /**
     * Method handles keydown event and does following.
     * 1. Fix for bug(in fluentui sources) regarding keyboard navigation when last item is not visible.
     * 2. Opens list when user enters any key.
     *
     * @param {React.FormEvent<HTMLInputElement>} event Keydown event
     */
    private onKeyDown;
    /**
     * Method resets search query.
     */
    private reserQuery;
    /**
     * Method called on combobox option resolvation.
     * We should not allow to add any custom option.
     *
     * @returns {IComboBoxOption[]} Array of combobox items.
     */
    private readonly onResolveOptions;
    /**
     * Default renderer for combobox item when highlight mode is enabled.
     * We should pass highlight query within props and avoid rendering if it is hidden.
     *
     * @param {IComboBoxOption} props Combobox item props.
     * @param {Function} defaultRender Combobox item default renderer.
     * @returns {JSX.Element | null} Element to render.
     */
    private readonly _onRenderItem;
    /**
     * Method called on combobox item render.
     * We should pass query to it and avoid rendering if it is hidden.
     *
     * @param {IComboBoxOption} props Combobox item props.
     * @param {Function} defaultRender Combobox item default renderer.
     * @returns {JSX.Element | null} Element to render.
     */
    private readonly onRenderItem;
    /**
     * Method to get current selected index.
     *
     * @returns {number | undefined} Selected item index.
     */
    private readonly getCurrentSelectedIndex;
    /**
     * Return a value for the placeholder.
     *
     * @returns {string}
     */
    private readonly getPlaceholder;
    /**
     * Default renderer for combobox item's option/label when highlight mode is enabled.
     * We should use different componenet which support highlighting - 'ComboboxSearchOption'.
     *
     * @param {IComboBoxOption} props Combobox item props.
     * @param {Function} defaultRender Combobox item default renderer.
     * @returns {JSX.Element | null} Element to render.
     */
    private readonly _onRenderOption;
    /**
     * Method called on combobox item's option/label render.
     * We should use different componenet which support highlighting - 'ComboboxSearchOption'.
     *
     * @param {IComboBoxOption} props Combobox item props.
     * @param {Function} defaultRender Combobox item default renderer.
     * @returns {JSX.Element | null} Element to render.
     */
    private readonly onRenderOption;
    /**
     * Method which determines what is next visible item - it is used to fix bug in fluentui sources..
     *
     * @param {number} index Current index.
     * @param {boolean} forward Dirrection to look up.
     * @returns {ComboboxItemInfo | null} Combobox item object.
     */
    private getNextVisibleItem;
    /**
     * Method is used as fix for bug(in fluentui sources) regarding keyboard navigation when last item is not visible.
     *
     * @param {boolean} forward Dirrection to look up.
     * @returns {boolean} Returs true if method changed navigation.
     */
    private _setCyclingNavigation;
    /**
     * Method for property 'useComboBoxAsMenuMinWidth' - method resolves current dropdown width and updates state with latest value.
     * 'minWidth' from state is used to set callout size in render.
     */
    private calculateMenuMinWidth;
    /**
     * Method called only when property 'highlight' is true.
     * Method called after each value live change - we need recheck if there is any visible item after search is done.
     * 1. If there no any visible item - we hide menu callout.
     * 2. If there is any visible item - we show menu callout.
     *
     * @param option Selected option.
     * @param index Selected option's index.
     * @param value Text value entered in input.
     */
    private onPendingValueChanged;
    /**
     * Public method to close menu callout if it is open.
     */
    dismissMenu(): void;
    /**
     * Public method to set the focus on the combo box.
     */
    setFocus(): void;
    /**
     * Method called only when property 'onRefresh' has been defined.
     * It is called when click on the refresh buttonIcon.
     */
    private handleRefreshButton;
    handleChange: IComboBoxProps['onChange'];
    /**
     * Custom render function for the combo box dropdown list.
     *
     * This method handles following cases:
     * 1. If a loading state is active (as determined by `isLoaderApplied`), it renders a loading indicator.
     * 2. If no options are available and a `noDataLabel` is provided via `externalSearchProps`, it shows a "no data" message.
     *
     * @param props The rendering props for the selectable, droppable list.
     * @param defaultRender The default rendering function provided by the ComboBox component.
     * @returns A JSX element representing the rendered list.
     */
    private readonly onRenderList;
    /**
     * Handle multiselect change by avoiding 'blur' event.
     * Problem is that blur event uses suggested value and toggles selection for it.
     *
     * @param {React.FormEvent<IComboBox>} event on change
     * @param {IComboBoxOption} option changed option
     * @param {number} index option index
     * @param {string} value changed value
     */
    private onMultiSelectChange;
    /**
     * Method is used to fix bug in fluent ui.
     * Bug is for multiselect combobox - when keyboard navigation is used, then scrollbar position is not updated to make selected option visible in viewport.
     */
    private onScrollToItem;
    /**
     * Method returns class names string depending on props and component state.
     *
     * @param {InputValidationMessageInfo} messageInfo Error/warning message if applied
     * @returns {string} Class names of root combobox element.
     */
    private getClassNames;
    /**
     * Method returns properties for Autofill component(combobox's inner compnent for text input).
     * Method handles 'highlight' and 'readOnly' properties.
     *
     * @returns {IAutofillProps} Properties for Autofill component.
     */
    private getAutofillProps;
    /**
     * Method returns if loader should be displayed for passed type.
     *
     * @param type Loader's place
     * @param isLoading Current combobox loading state
     * @returns True if loader should be displayed for passed type.
     */
    private isLoaderApplied;
    /**
     * Method renders dropdown expand icon.
     * Overwritten renderer to replace expand icon with loader when combobox has laoding property set.
     *
     * @param props Button properties
     * @param defaultRender Default icon renderer
     * @returns React element to render.
     */
    private onRenderIcon;
    /**
     * Called when the user types in to the input of the combo box.
     *
     * @param text The current input value typed by the user.
     */
    private onInputValueChange;
    /**
     * Collects and stores the keys of all hidden combo box options.
     *
     * @param options The list of combo box options to scan for hidden entries.
     */
    private collectHiddenOptionKeys;
    /**
     * @returns {JSX.Element}
     */
    render(): JSX.Element;
}
//# sourceMappingURL=UIComboBox.d.ts.map