import type { FocusEventHandler, KeyboardEvent, KeyboardEventHandler, MutableRefObject } from "react";
/**
 * @remarks \@since 5.0.0
 */
export interface KeyboardFocusArg<E extends HTMLElement> {
    /**
     * The keyboard key/letter that was pressed. (`event.key`).
     */
    key: string;
    /**
     * The keyboard event.
     */
    event: KeyboardEvent<E>;
}
/**
 * @remarks \@since 5.0.0
 */
export declare type KeyboardFocusHandler<E extends HTMLElement> = (arg: KeyboardFocusArg<E>) => void;
/**
 * Optional event handlers that can be called for specific custom focus
 * behavior. If any of these functions call `event.stopPropagation()`, the
 * default focus behavior will not occur.
 *
 * @remarks \@since 5.0.0
 */
export interface KeyboardFocusCallbacks<E extends HTMLElement> {
    onFocus?: FocusEventHandler<E>;
    onKeyDown?: KeyboardEventHandler<E>;
    /**
     * This is called whenever a single letter has been pressed and
     * {@link KeyboardMovementBehavior.searchable} is `true`.
     */
    onSearch?: KeyboardFocusHandler<E>;
    /**
     * This is called whenever one of the
     * {@link KeyboardMovementBehavior.incrementKeys} are pressed.
     */
    onIncrement?: KeyboardFocusHandler<E>;
    /**
     * This is called whenever one of the
     * {@link KeyboardMovementBehavior.decrementKeys} are pressed.
     */
    onDecrement?: KeyboardFocusHandler<E>;
    /**
     * This is called whenever one of the
     * {@link KeyboardMovementBehavior.jumpToFirstKeys} are pressed.
     */
    onJumpToFirst?: KeyboardFocusHandler<E>;
    /**
     * This is called whenever one of the
     * {@link KeyboardMovementBehavior.jumpToLastKeys} are pressed.
     */
    onJumpToLast?: KeyboardFocusHandler<E>;
}
/**
 * @remarks \@since 5.0.0
 */
export interface KeyboardFocusHookOptions<E extends HTMLElement> extends KeyboardFocusCallbacks<E> {
    /**
     * A function that can be used to get the default focus index when the
     * container element first gains focus. If this returns `-1`, no child element
     * will be focused and the container will maintain focus instead.
     *
     * @param elements - The current list of elements that can be focused within
     * the container element
     * @param container - The container element that gained focus
     */
    getDefaultFocusIndex?(elements: readonly HTMLElement[], container: E): number;
    /**
     * An optional function to call when the custom focused element should change.
     * The default value is just to call `element.focus()`.
     *
     * @param element - The element that should gain custom focus
     * @param nextFocusIndex - The next focus index which can be used for
     * additional movement behavior.
     */
    onFocusChange?(element: HTMLElement, nextFocusIndex: number): void;
}
/** @remarks \@since 5.0.0 */
export interface KeyboardFocusHookReturnValue<E extends HTMLElement> {
    onFocus: FocusEventHandler<E>;
    onKeyDown: KeyboardEventHandler<E>;
    focusIndex: MutableRefObject<number>;
}
/**
 * @remarks \@since 5.0.0
 */
export declare function useKeyboardFocus<E extends HTMLElement>(options?: KeyboardFocusHookOptions<E>): KeyboardFocusHookReturnValue<E>;