import { type HookErrorHandler } from '../utils/errors.js';
/** A scalar key value accepted by {@link useKeyPress}. @public */
export type KeyType = string | number;
/** A key predicate may return a truthy key to expose to the handler. @public */
export type KeyPredicate = (event: KeyboardEvent) => KeyType | boolean | undefined;
/** A key, key-code, list of independent alternatives, or custom predicate. @public */
export type KeyFilter = KeyType | readonly KeyType[] | KeyPredicate;
/** Native keyboard events supported by {@link useKeyPress}. @public */
export type KeyEvent = 'keydown' | 'keyup' | 'keypress';
/** A direct target, ref-like target, lazy target, or an empty target. @public */
export type KeyPressTarget = EventTarget | {
    readonly current: EventTarget | null;
} | (() => EventTarget | null | undefined) | null | undefined;
/** The callback invoked for a matching keyboard event. @public */
export type KeyPressHandler = (event: KeyboardEvent, key: KeyType) => void;
/** Options for {@link useKeyPress}. @public */
export interface UseKeyPressOptions {
    /** Native event(s) to observe. Defaults to `keydown`. */
    readonly events?: KeyEvent | readonly KeyEvent[];
    /** Event target; defaults to `window` in a browser. */
    readonly target?: KeyPressTarget;
    /** Alias for `target`, useful when passing a React ref. */
    readonly ref?: KeyPressTarget;
    /** Requires no unlisted modifier keys when true. */
    readonly exactMatch?: boolean;
    /** Whether native listeners use capture. */
    readonly capture?: boolean;
    /** Alias for `capture` when matching an existing event-listener option shape. */
    readonly useCapture?: boolean;
    /** Disables the subscription while false. */
    readonly enabled?: boolean;
    /** Observes predicate or handler failures before the original error escapes. */
    readonly onError?: HookErrorHandler;
}
/**
 * Runs a callback for matching keyboard events. Filters support key strings,
 * legacy numeric key codes, arrays of alternatives, predicates, and modifier
 * combinations expressed as strings such as `ctrl.s` or `ctrl+s`. Arrays are
 * always independent alternatives and never form a modifier combination.
 *
 * @public
 */
export declare function useKeyPress(keyFilter: KeyFilter, handler: KeyPressHandler, options?: UseKeyPressOptions): void;