igniteui-webcomponents
Version:
Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.
151 lines (150 loc) • 5.42 kB
TypeScript
import type { ReactiveController, ReactiveControllerHost } from 'lit';
import type { Ref } from 'lit/directives/ref.js';
export declare const arrowLeft: "ArrowLeft";
export declare const arrowRight: "ArrowRight";
export declare const arrowUp: "ArrowUp";
export declare const arrowDown: "ArrowDown";
export declare const enterKey: "Enter";
export declare const spaceBar: " ";
export declare const escapeKey: "Escape";
export declare const homeKey: "Home";
export declare const endKey: "End";
export declare const pageUpKey: "PageUp";
export declare const pageDownKey: "PageDown";
export declare const tabKey: "Tab";
export declare const altKey: "Alt";
export declare const ctrlKey: "Ctrl";
export declare const metaKey: "Meta";
export declare const shiftKey: "Shift";
export type KeyBindingHandler = (event: KeyboardEvent) => void;
export type KeyBindingObserverCleanup = {
unsubscribe: () => void;
};
/**
* Whether the current event should be ignored by the controller.
*
* @param node - The event target
* @param event - The event object
*
* When `true` is returned, the current event is ignored.
*/
export type KeyBindingSkipCallback = (node: Element, event: KeyboardEvent) => boolean;
/**
* The event type which will trigger the bound handler.
*
* @remarks
* `keydownRepeat` is similar to `keydown` with the exception
* that after the handler is invoked the pressed state of the key is reset
* in the controller.
*/
export type KeyBindingTrigger = 'keydown' | 'keyup' | 'keydownRepeat';
/**
* Configuration object for the controller.
* @ignore
*/
export interface KeyBindingControllerOptions {
/**
* By default, the controller listens for keypress events in the context of the host element.
* If you pass a `ref`, you can limit the observation to a certain DOM part of the host scope.
*/
ref?: Ref;
/**
* Option to ignore key press events.
*
* If passed an array of CSS selectors, it will ignore key presses originating from elements in the event composed path
* that match one of the selectors.
* Otherwise you can pass a {@link KeyBindingSkipCallback} function.
*
* Defaults to `['input', 'textarea', 'select']`.
*
* @example
* ```ts
* {
* // Skip events originating from elements with `readonly` attribute
* skip: ['[readonly]']
* }
* ...
* {
* // Same as above but with a callback
* skip: (node: Element) => node.hasAttribute('readonly')
* }
* ```
*/
skip?: string[] | KeyBindingSkipCallback;
/**
* A set of KeyBindingOptions configuration which is applied to every handler
* that is added to the controller.
*
* Any additional KeyBindingOptions values passed when `set` is called
* will be merged with `bindingDefaults`.
*/
bindingDefaults?: KeyBindingOptions;
}
/**
* Configuration object for customizing the behavior of
* the registered handler.
*/
export interface KeyBindingOptions {
/**
* The event type(s) on which the handler will be invoked.
*
* Defaults to `keydown` if not set.
*/
triggers?: KeyBindingTrigger[];
/**
* Whether to call `preventDefault` on the target event before the handler is invoked.
*/
preventDefault?: boolean;
/**
* Whether to call `stopPropagation` on the target event before the handler is invoked.
*/
stopPropagation?: boolean;
}
export declare function parseKeys(keys: string | string[]): {
keys: string[];
modifiers: string[];
};
declare class KeyBindingController implements ReactiveController {
protected _host: ReactiveControllerHost & Element;
protected _ref?: Ref;
protected _observedElement?: Element;
protected _options?: KeyBindingControllerOptions;
private bindings;
private pressedKeys;
protected get _element(): Element | undefined;
/**
* Sets the controller to listen for keyboard events on an arbitrary `element` in the page context.
* All the configuration and event handlers are applied as well.
*
* Returns an object with an `unsubscribe` function which should be called when the observing of keyboard
* events on the `element` should cease.
*/
observeElement(element: Element): KeyBindingObserverCleanup;
constructor(host: ReactiveControllerHost & Element, options?: KeyBindingControllerOptions);
/**
* Checks and executes any event modifiers that are present in the matched binding.
*/
private eventModifiersMatch;
private bindingMatches;
private shouldSkip;
handleEvent(event: KeyboardEvent): void;
/**
* Registers a keybinding handler.
*/
set(key: string | string[], handler: KeyBindingHandler, options?: KeyBindingOptions): this;
/**
* Register a handler function which is called when the target receives a key
* which "activates" it.
*
* In the browser context this is usually either an Enter and/or Space keypress.
*/
setActivateHandler(handler: KeyBindingHandler, options?: KeyBindingOptions): this;
hostConnected(): void;
hostDisconnected(): void;
}
/**
* Creates a keybinding controller and adds to it to the passed `element`
* with the provided `options`.
*/
export declare function addKeybindings(element: ReactiveControllerHost & Element, options?: KeyBindingControllerOptions): KeyBindingController;
export {};