index.d.ts

// Type definitions for RefManager
// Project: react-ref-manager

import * as React from '@types/react';

/**
 * Contains the current focus status and context
 */
interface FocusObject {
    /**
     * The ref that was last focused or null when the ref cannot be found in the
     * RefManager instance.
     */
    ref: React.Component | null,
    /**
     * The ref pointing to the actual element in the DOM that was focused. For
     * standard React elements (<div>, <span>, <input> etc), this is the same as
     * ref. For custom React components that don't define a focus() method, this
     * is the ref to the backing elements in the DOM. Or null when the ref was
     * not found in the DOM.
     */
    DOMRef: React.Component | null,
    /**
     * The value of the id option passed when a ref was last focused.
     */
    id?: string | number,
    /**
     * The collectionId option passed when a ref was last focused.
     */
    collectionId: string | number,
    /**
     * The value of context at the time the ref was last focused. You can store
     * any information about when the ref was focused that you later want to
     * access, in here
     */
    context: any,
    /**
     * True if the focus attempt was successful. If false, see the ref and DOMRef
     * values to determine whether the failure was because the ref could not be
     * found in the RefManager instance, or in the DOM.
     */
    applied: boolean
}

/**
 * Contains the current scroll status
 */
interface ScrollObject {
    /**
     * ref The ref that was last scrolled to or null when the ref cannot be found
     * in the RefManager instance.
     */
    ref: React.Component | null,
    /**
     * The ref pointing to the actual element in the DOM that was scrolled to.
     * For standard React elements (<div>, <span>, <input> etc), this is the
     * same as ref. For custom React components that don't define a scrollIntoView()
     * method, this is the ref to the backing elements in the DOM. Or null when the
     * ref was not found in the DOM.
     */
    DOMRef: React.Component | null,
    /**
     * The value of the id option passed when a ref was last scrolled.
     */
    id?: string | number,
    /**
     * The collectionId option passed when a ref was last scrolled.
     */
    collectionId: string | number,
    /**
     * True if the scroll attempt was successful. If false, see the ref and DOMRef
     * values to determine whether the failure was because the ref could not be
     * found in the RefManager instance, or in the DOM.
     */
    applied: boolean
}

module RefManager {
    /**
     * Constants used to indicate directions that a ref collection can be iterated
     * over.
     */
    export enum FocusDirection {
        LEFT = 'LEFT',
        RIGHT = 'RIGHT',
        UP = 'UP',
        DOWN = 'DOWN'
    }

    /**
     * Class that contains functionality for storing, focusing and scrolling to refs
     * generated by React components
     */
    export default class RefManager {
        /**
         * Creates a new RefManager instance
         */
        constructor();

        /**
         * Returns whether a ref is mounted in the DOM and the element that is currently
         * focused
         */
        static refIsFocused(ref: React.Component): boolean;

        /**
         * Focuses a ref in the DOM if it is mounted. This method does NOT update any
         * RefManager instance's focus object.
         */
        static focus(ref: React.Component): React.Component | null;

        /**
         * Scrolls to a ref in the browser if it can be found in the DOM.
         */
        static scrollTo(ref: React.Component, options?: {} | boolean): React.Component | null;

        /**
         * Stores a ref for later use. This method should generally be called in
         * React's render method, using React Component's ref attribute.
         */
        set(collectionId: string | number, itemIdOrRef: string | number | React.Component, ref?: React.Component);

        /**
         * Retrieves a ref previously stored using set()
         */
        get(collectionId: string | number, itemId?: string | number): React.Component;

        /**
         * Sets the current focus object without actually focusing the ref in the DOM.
         * Useful if you need to focus a ref externally for whatever reason and need to
         * update a RefManager instance.
         *
         * This method still calls any change listeners that may have been added using
         * addFocusChangeListener()
         */
        setCurrentFocus(FocusObject): FocusObject;

        /**
         * Returns the current focus object. The focus object is updated every time one
         * of the focus* methods is used, or setCurrentFocus().
         *
         * The focus object is an empty object ({}) before any focus* methods are called.
         */
        getCurrentFocus(): FocusObject;

        /**
         * Returns whether the ref currently considered focused by the RefManager instance
         * is mounted in the DOM and the equal to document.activeElement.
         */
        isFocusedRefInDOM(): boolean;

        /**
         * Focuses a ref in the DOM and records it as currently focused in the RefManager
         * instance.
         */
        focus(ref: React.Component, options: { id?: string | number, collectionId: string | number, context?: any }): FocusObject;

        /**
         * Focuses a ref in the browser identified by an id and (optionally) a collectionId,
         * and updates the currently focused ref in the RefManager instance.
         */
        focusById(collectionId: string | number , itemIdOrOptions?: string | number | { context?: any }, options?: { context?: any }): FocusObject;

        /**
         * Focuses the next ref in a collection pointed to by the provided collectionId.
         */
        focusNextById(collectionId: string | number , options?: { direction?: FocusDirection, indexes?: Array<string | number>, collectionWidth?: number, yWrap?: boolean, xWrap?: boolean , context?: any }): FocusObject;

        /**
         * Focuses the next item in a collection of refs. If no item in a collection of refs
         * is currently focused, the first item is focused. If the last item in the
         * collection is already focused, the behaviour depends on the options.yWrap and
         * options.xWrap
         */
        focusNext(collectionId: { [key: string]: React.Component }, options?: { direction?: FocusDirection, indexes?: Array<string | number>, collectionWidth?: number, yWrap?: boolean, xWrap?: boolean, context?: any }): FocusObject;

        /**
         * Scrolls to a ref by an id and (optionally) collectionId that was used when
         * it was registered using set().
         *
         * When the ref is a custom React component that doesn't define a scrollIntoView method,
         * it's backing DOM element ref will be located, and that will be used to scroll to.
         */
        scrollToById(collectionId: string | number , itemIdOrOptions: any, options?: any): ScrollObject;

        /**
         * Scrolls to the ref that was last focused, if there is one.
         */
        scrollToFocused(options?: any): ScrollObject;

        /**
         * Adds a listener function to be called every time the current focus is changed
         * through the RefManager instance.
         *
         * The function is called with the previous focus object and the current
         * focus object as its first and second arguments.
         */
        addFocusChangeListener(listener: Function): Function

        /**
         * Removes a focus change listener that has been previously registered
         * with addFocusChangeListener().
         */
        removeFocusChangeListener(listener: Function)
    }
}