office-ui-fabric-react/lib-amd/components/ComboBox/ComboBox.d.ts

Reusable React components for building experiences for Office 365.

/// <reference types="react" />
import { BaseComponent } from '../../Utilities';
import { IComboBoxOption, IComboBoxProps } from './ComboBox.types';
export interface IComboBoxState {
    isOpen?: boolean;
    selectedIndices?: number[];
    focused?: boolean;
    suggestedDisplayValue?: string;
    currentOptions: IComboBoxOption[];
    currentPendingValueValidIndex: number;
    currentPendingValueValidIndexOnHover: number;
    currentPendingValue?: string;
}
export declare class ComboBox extends BaseComponent<IComboBoxProps, IComboBoxState> {
    static defaultProps: IComboBoxProps;
    private _root;
    private _autofill;
    private _comboBoxWrapper;
    private _comboBoxMenu;
    private _selectedElement;
    private _id;
    private _lastReadOnlyAutoCompleteChangeTimeoutId;
    private _currentPromise;
    private _currentVisibleValue;
    private _classNames;
    private _isScrollIdle;
    private _hasPendingValue;
    private _scrollIdleTimeoutId;
    private _processingTouch;
    private _lastTouchTimeoutId;
    private _processingExpandCollapseKeyOnly;
    private _focusInputAfterClose;
    private _gotMouseMove;
    constructor(props: IComboBoxProps);
    componentDidMount(): void;
    componentWillReceiveProps(newProps: IComboBoxProps): void;
    componentDidUpdate(prevProps: IComboBoxProps, prevState: IComboBoxState): void;
    componentWillUnmount(): void;
    render(): JSX.Element;
    /**
     * @inheritdoc
     */
    focus: (shouldOpenOnFocus?: boolean | undefined, useFocusAsync?: boolean | undefined) => void;
    /**
     * Close menu callout if it is open
     */
    dismissMenu: () => void;
    /**
     * componentWillReceiveProps handler for the auto fill component
     * Checks/updates the iput value to set, if needed
     * @param { IAutofillProps } defaultVisibleValue - the defaultVisibleValue that got passed
     *  in to the auto fill's componentWillReceiveProps
     * @returns { string } - the updated value to set, if needed
     */
    private _onUpdateValueInAutofillWillReceiveProps;
    /**
     * componentDidUpdate handler for the auto fill component
     *
     * @param { string } defaultVisibleValue - the current defaultVisibleValue in the auto fill's componentDidUpdate
     * @param { string } suggestedDisplayValue - the current suggestedDisplayValue in the auto fill's componentDidUpdate
     * @returns { boolean } - should the full value of the input be selected?
     * True if the defaultVisibleValue equals the suggestedDisplayValue, false otherwise
     */
    private _onShouldSelectFullInputValueInAutofillComponentDidUpdate;
    /**
     * Get the correct value to pass to the input
     * to show to the user based off of the current props and state
     * @returns { string } the value to pass to the input
     */
    private _getVisibleValue;
    /**
     * Is the index within the bounds of the array?
     * @param options - options to check if the index is valid for
     * @param index - the index to check
     * @returns { boolean } - true if the index is valid for the given options, false otherwise
     */
    private _indexWithinBounds(options, index);
    /**
     * Handler for typing changes on the input
     * @param updatedValue - the newly changed value
     */
    private _onInputChange;
    /**
     * Process the new input's new value when the comboBox
     * allows freeform entry
     * @param updatedValue - the input's newly changed value
     */
    private _processInputChangeWithFreeform(updatedValue);
    /**
     * Process the new input's new value when the comboBox
     * does not allow freeform entry
     * @param updatedValue - the input's newly changed value
     */
    private _processInputChangeWithoutFreeform(updatedValue);
    private _getFirstSelectedIndex();
    /**
     * Walk along the options starting at the index, stepping by the delta (positive or negative)
     * looking for the next valid selectable index (e.g. skipping headings and dividers)
     * @param index - the index to get the next selectable index from
     * @param delta - optional delta to step by when finding the next index, defaults to 0
     * @returns { number } - the next valid selectable index. If the new index is outside of the bounds,
     * it will snap to the edge of the options array. If delta == 0 and the given index is not selectable
     */
    private _getNextSelectableIndex(index, searchDirection);
    /**
     * Set the selected index. Note, this is
     * the "real" selected index, not the pending selected index
     * @param index - the index to set (or the index to set from if a search direction is provided)
     * @param searchDirection - the direction to search along the options from the given index
     */
    private _setSelectedIndex(index, submitPendingValueEvent, searchDirection?);
    /**
     * Focus (and select) the content of the input
     * and set the focused state
     */
    private _select;
    /**
     * Callback issued when the options should be resolved, if they have been updated or
     * if they need to be passed in the first time. This only does work if an onResolveOptions
     * callback was passed in
     */
    private _onResolveOptions;
    /**
     * OnBlur handler. Set the focused state to false
     * and submit any pending value
     */
    private _onBlur;
    /**
     * Submit a pending value if there is one
     */
    private _submitPendingValue(submitPendingValueEvent);
    private _onRenderContainer;
    private _onLayerMounted;
    private _onRenderList;
    private _onRenderItem;
    private _onRenderLowerContent;
    private _renderSeparator(item);
    private _renderHeader(item);
    private _renderOption;
    /**
     * If we are coming from a mouseOut:
     * there is no visible selected option.
     *
     * Else if We are hovering over an item:
     * that gets the selected look.
     *
     * Else:
     * Use the current valid pending index if it exists OR
     * we do not have a valid index and we currently have a pending input value,
     * otherwise use the selected index
     * */
    private _isOptionSelected(index);
    /**
     * Gets the pending selected index taking into account hover, valueValidIndex, and selectedIndex
     * @param includeCurrentPendingValue - Should we include the currentPendingValue when
     * finding the index
     */
    private _getPendingSelectedIndex(includeCurrentPendingValue);
    /**
     * Scroll handler for the callout to make sure the mouse events
     * for updating focus are not interacting during scroll
     */
    private _onScroll;
    /**
     * Scroll the selected element into view
     */
    private _scrollIntoView();
    private _onRenderOptionContent;
    /**
     * Click handler for the menu items
     * to select the item and also close the menu
     * @param index - the index of the item that was clicked
     */
    private _onItemClick(index);
    /**
     * Handles dismissing (cancelling) the menu
     */
    private _onDismiss;
    /**
     * Get the index of the option that is marked as selected
     * @param options - the comboBox options
     * @param selectedKeys - the known selected key to find
     * @returns { number } - the index of the selected option, -1 if not found
     */
    private _getSelectedIndices(options, selectedKeys);
    /**
     * Reset the selected index by clearing the
     * input (of any pending text), clearing the pending state,
     * and setting the suggested display value to the last
     * selected state text
     */
    private _resetSelectedIndex();
    /**
     * Clears the pending info state
     */
    private _clearPendingInfo();
    /**
     * Set the pending info
     * @param currentPendingValue - new pending value to set
     * @param currentPendingValueValidIndex - new pending value index to set
     * @param suggestedDisplayValue - new suggest display value to set
     */
    private _setPendingInfo(currentPendingValue?, currentPendingValueValidIndex?, suggestedDisplayValue?);
    /**
     * Set the pending info from the given index
     * @param index - the index to set the pending info from
     */
    private _setPendingInfoFromIndex(index);
    /**
     * Sets the pending info for the comboBox
     * @param index - the index to search from
     * @param searchDirection - the direction to search
     */
    private _setPendingInfoFromIndexAndDirection(index, searchDirection);
    private _notifyPendingValueChanged(prevState);
    /**
     * Sets the isOpen state and updates focusInputAfterClose
     */
    private _setOpenStateAndFocusOnClose(isOpen, focusInputAfterClose);
    /**
     * Handle keydown on the input
     * @param ev - The keyboard event that was fired
     */
    private _onInputKeyDown;
    private _isExpandCollapseKey(ev);
    /**
     * Handle keyup on the input
     * @param ev - the keyboard event that was fired
     */
    private _onInputKeyUp;
    private _onOptionMouseEnter(index);
    private _onOptionMouseMove(index);
    private _onOptionMouseLeave;
    private _shouldIgnoreMouseEvent();
    /**
     * Handle dismissing the menu and
     * eating the required key event when disabled
     * @param ev - the keyboard event that was fired
     */
    private _handleInputWhenDisabled(ev);
    /**
     * Click handler for the button of the comboBox
     * and the input when not allowing freeform. This
     * toggles the expand/collapse state of the comboBox (if enbled)
     */
    private _onComboBoxClick;
    /**
     * Click handler for the autofill.
     */
    private _onAutofillClick;
    private _onTouchStart;
    private _onPointerDown;
    private _handleTouchAndPointerEvent();
    /**
     * Get the styles for the current option.
     * @param item Item props for the current option
     */
    private _getCaretButtonStyles();
    /**
     * Get the styles for the current option.
     * @param item Item props for the current option
     */
    private _getCurrentOptionStyles(item);
    /**
     * Get the aria-activedescendant value for the comboxbox.
     * @returns the id of the current focused combo item, otherwise the id of the currently selected element, null otherwise
     */
    private _getAriaActiveDescentValue();
    /**
     * Get the aria autocomplete value for the Combobox
     * @returns 'inline' if auto-complete automatically dynamic, 'both' if we have a list of possible values to pick from and can
     * dynamically populate input, and 'none' if auto-complete is not enabled as we can't give user inputs.
     */
    private _getAriaAutoCompleteValue();
    private _isPendingOption(item);
    /**
     * Given default selected key(s) and selected key(s), return the selected keys(s).
     * When default selected key(s) are available, they take precedence and return them instead of selected key(s).
     *
     * @returns No matter what specific types the input parameters are, always return an array of
     *  either strings or numbers instead of premitive type.  This normlization makes caller's logic easier.
     */
    private _getSelectedKeys(defaultSelectedKey, selectedKey);
    private _getPreviewText(item);
    private _normalizeToString(value?);
    private _removeZeroWidthSpaces(value);
}