import { IDisposable } from './dispose';
import { DomElementMethod, DomMethod } from './domImpl';
export type EventName = keyof HTMLElementEventMap;
export type EventType<E extends EventName | string> = E extends EventName ? HTMLElementEventMap[E] : Event;
export type EventCB<E extends Event = Event, T extends EventTarget = EventTarget> = (this: void, event: E, elem: T) => void;
/**
 * Listen to a DOM event, returning the listener object.
 * ```ts
 * const listener = dom.onElem(elem, 'click', (event, elem) => { ... });
 * ```
 *
 * To stop listening:
 * ```ts
 * listener.dispose();
 * ```
 *
 * Disposing the listener returned by `onElem()` is the only way to stop listening to an event. You
 * can use `autoDispose` to stop listening automatically when subscribing in a `Disposable` object:
 * ```ts
 * this.autoDispose(domevent.onElem(document, 'mouseup', callback));
 * ```
 *
 * If you need "once" semantics, i.e. to remove the callback on first call, here's a useful pattern:
 * ```ts
 * const lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
 * ```
 *
 * @param elem - DOM Element to listen to.
 * @param eventType - Event type to listen for (e.g. `'click'`).
 * @param callback - Callback to call as `callback(event, elem)`, where elem is `elem`.
 * @param options - `useCapture: boolean`: Add the listener in the capture phase. This should very
 *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
 * @returns Listener object whose `.dispose()` method will remove the event listener.
 */
export declare function onElem<E extends EventName | string, T extends EventTarget>(elem: T, eventType: E, callback: EventCB<EventType<E>, T>, { useCapture }?: {
    useCapture?: boolean | undefined;
}): IDisposable;
/**
 * Listen to a DOM event. It is typically used as an argument to the `dom()` function:
 * ```ts
 * dom('div', dom.on('click', (event, elem) => { ... }));
 * ```
 *
 * When the div is disposed, the listener is automatically removed.
 *
 * The callback is called with the event and the element to which it was attached. Unlike in, say,
 * JQuery, the callback's return value is ignored. Use `event.stopPropagation()` and
 * `event.preventDefault()` explicitly if needed.
 *
 * To listen to descendants of an element matching the given selector (what JQuery calls
 * "delegated events", see http://api.jquery.com/on/), see [`onMatch`](#onMatch).
 *
 * @param eventType - Event type to listen for (e.g. `'click'`).
 * @param callback - Callback to call as `callback(event, elem)`, where `elem` is the element this
 *    listener is attached to.
 * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
 */
export declare function on<E extends EventName | string, T extends EventTarget>(eventType: E, callback: EventCB<EventType<E>, T>, { useCapture }?: {
    useCapture?: boolean | undefined;
}): DomMethod<T>;
/**
 * Listen to a DOM event on descendants of the given elem matching the given selector.
 *
 * ```ts
 * const let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
 * ```
 *
 * @param elem - DOM Element to whose descendants to listen.
 * @param selector - CSS selector string to filter elements that trigger this event.
 *    JQuery calls it "delegated events" (http://api.jquery.com/on/). The callback will only be
 *    called when the event occurs for an element matching the given selector. If there are
 *    multiple elements matching the selector, the callback is only called for the innermost one.
 * @param eventType - Event type to listen for (e.g. 'click').
 * @param callback - Callback to call as `callback(event, elem)`, where elem is a
 *    descendent of `elem` which matches `selector`.
 * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
 * @returns Listener object whose `.dispose()` method will remove the event listener.
 */
export declare function onMatchElem(elem: EventTarget, selector: string, eventType: string, callback: EventCB, { useCapture }?: {
    useCapture?: boolean | undefined;
}): IDisposable;
/**
 * Listen to a DOM event on descendants of the given element matching the given selector.
 *
 * This is similar to JQuery's [delegated events](https://api.jquery.com/on/#direct-and-delegated-events)
 *
 * ```ts
 * dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
 * ```
 *
 * In this usage, the element passed to the callback will be a DOM element matching the given
 * selector. If there are multiple matches, the callback is only called for the innermost one.
 *
 * @param selector - CSS selector string to filter elements that trigger this event.
 * @param eventType - Event type to listen for (e.g. `'click'`).
 * @param callback - Callback to call as `callback(event, elem)`, where `elem` is an element
 *    matching `selector`.
 * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
 */
export declare function onMatch(selector: string, eventType: string, callback: EventCB, { useCapture }?: {
    useCapture?: boolean | undefined;
}): DomElementMethod;
export type KeyEventType = 'keypress' | 'keyup' | 'keydown';
export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
    [key: string]: (this: void, ev: KeyboardEvent, elem: T) => void;
}
/**
 * Listen to key events (typically 'keydown' or 'keypress'), with specified per-key callbacks.
 * Key names are listed at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
 *
 * By default, handled events are stopped from bubbling with stopPropagation() and
 * preventDefault(). If, however, you register a key with a "$" suffix (i.e. "Enter$" instead of
 * "Enter"), then the event is allowed to bubble normally.
 *
 * When this handler is set on an element, we automatically ensure that tabindex attribute is set,
 * to allow this element to receive keyboard events.
 *
 * For example:
 * ```
 *    dom('input', ...
 *      dom.onKeyDown({
 *        Enter: (e, elem) => console.log("Enter pressed"),
 *        Escape: (e, elem) => console.log("Escape pressed"),
 *        Delete$: (e, elem) => console.log("Delete pressed, will bubble"),
 *      })
 *    )
 * ```
 */
export declare function onKeyElem<T extends HTMLElement>(elem: T, evType: KeyEventType, keyHandlers: IKeyHandlers<T>): IDisposable;
/**
 * Add listeners to `"keypress"` events. See [`onKeyElem`](#onKeyElem) for details.
 */
export declare function onKeyPress<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T>;
/**
 * Add listeners to `"keydown"` events. See [`onKeyElem`](#onKeyElem) for details.
 */
export declare function onKeyDown<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T>;