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

Reusable React components for building experiences for Office 365.

/// <reference types="react" />
import * as React from 'react';
import { IComboBoxOption, IComboBoxProps } from './ComboBox.types';
import { BaseComponent } from '../../Utilities';
export interface IComboBoxState {
    isOpen?: boolean;
    selectedIndex: number;
    focused?: boolean;
    suggestedDisplayValue?: string;
    currentOptions: IComboBoxOption[];
    currentPendingValueValidIndex: number;
    currentPendingValueValidIndexOnHover: number;
    currentPendingValue: string;
}
export declare class ComboBox extends BaseComponent<IComboBoxProps, IComboBoxState> {
    static defaultProps: IComboBoxProps;
    refs: {
        [key: string]: React.ReactInstance;
        root: HTMLElement;
    };
    private _comboBox;
    private _comboBoxWrapper;
    private _comboBoxMenu;
    private _selectedElement;
    private _id;
    private readonly _readOnlyPendingAutoCompleteTimeout;
    private _lastReadOnlyAutoCompleteChangeTimeoutId;
    private _currentPromise;
    private _currentVisibleValue;
    private _classNames;
    private _isScrollIdle;
    private readonly _scrollIdleDelay;
    private _scrollIdleTimeoutId;
    private _focusInputAfterClose;
    constructor(props: IComboBoxProps);
    componentDidMount(): void;
    componentWillReceiveProps(newProps: IComboBoxProps): void;
    componentDidUpdate(prevProps: IComboBoxProps, prevState: IComboBoxState): void;
    componentWillUnmount(): void;
    render(): JSX.Element;
    /**
     * Set focus on the input
     */
    focus(shouldOpenOnFocus?: boolean): 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(updatedValue);
    /**
     * 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);
    /**
     * 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, 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(event);
    /**
     * Submit a pending value if there is one
     */
    private _submitPendingValue();
    private _onRenderContainer(props);
    private _onRenderList(props);
    private _onRenderItem(item);
    private _onRenderLowerContent();
    private _renderSeparator(item);
    private _renderHeader(item);
    private _renderOption(item);
    /**
     * 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 _onRenderOption(item);
    /**
     * 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 selectedKey - the known selected key to find
     * @returns { number } - the index of the selected option, -1 if not found
     */
    private _getSelectedIndex(options, selectedKey);
    /**
     * 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);
    /**
     * 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(ev);
    /**
     * Handle keyup on the input
     * @param ev - the keyboard event that was fired
     */
    private _onInputKeyUp(ev);
    private _onOptionMouseEnter(index);
    private _onOptionMouseMove(index);
    private _onOptionMouseLeave;
    /**
     * 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();
    /**
   * 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();
}