README

Shortcuts

Super performant and feature rich shortcuts management library.

Features

Super performant: it's about as fast as it gets, I don't think it's possible to do significantly better than this.
Sequences support: sequences (a.k.a. konami codes), are supported too, so you can bind actions to Up Right Down Left or whatever shortcuts sequence you want.
Shortcut to Accelerator: supported shortcuts can be converted to their Electron's Accelerator equivalent.
Shortcut to symbols: supported shortcuts can be converted to symbols (e.g. ⌘A), this is useful for providing shortcut hints in tooltips.

Install

npm install --save shortcuts

Usage

This library provides a Shortcuts class, which will manage your shortcuts, and a Shortcut object, which provides some utilities.

Shortcut Syntax

The following keys can be used when defining a shortcut:

Modifiers: Alt/Option, Cmd/Command/Meta, Ctrl/Control, Shift, CmdOrCtrl/CommandOrControl.
Digits: 1-9.
Alphabet letters: A-Z.
Function keys: F1-F24.
Numpad digits: Numpad0-Numpad9.
Special keys: Backspace, Capslock, Del/Delete, Down, End, Enter/Return, Esc/Escape, Home, Insert, Left, PageDown, PageUp, Right, Space/Spacebar, Tab, Up.
Punctuation keys: !, ", #, $, %, &, ', (, ), *, +/plus, ,, -, ., /, :, ;, <, =, >, ?, @, [, \, ], ^, _, `, {, |, }, ~.

Other keys are not supported.

ℹ️ Shortcuts are case insensitive.
ℹ️ Keys in a single shortcut must be joined by a plus sign (e.g. Ctrl+A).
ℹ️ Sequences of shortcuts must be joined by a space (e.g. Ctrl+K Ctrl+B).

Shortcuts Class

The Shortcuts class will be used for adding/removing/resetting/recording shortcuts. This is its interface:

class Shortcuts {
  constructor ( options?: { shortcuts?: ShortcutDescriptor[]: capture?: boolean, target?: Node, shouldHandleEvent?: event => boolean } );
  get (): ShortcutDescriptor[];
  add ( descriptors: ShortcutDescriptor | ShortcutDescriptor[] );
  remove ( descriptors: ShortcutDescriptor | ShortcutDescriptor[] );
  reset ();
  record ( handler: ( shortcut ) => any ): Function;
}

ℹ️ The shortcuts option accepts an optional array of shortcuts descriptors. More on this below.
ℹ️ The capture option governs whether events are attached for the capturing phase or for the bubbling phase of the propagation.
ℹ️ The target option accepts an optional DOM node, where the keyboard evenr listener will be attached to.
ℹ️ The shouldHandleEvent option accepts an optional function which will be used for determining, for each keyboard event, if it should be handled by this library. By default that function is: event => !event.defaultPrevented.

A shortcut descriptor looks like this:

{
  handler?: ( event: KeyboardEvent ) => boolean | void,
  shortcut: string
}

Usage:

import {Shortcuts} from 'shortcuts';

const shortcuts = new Shortcuts ();

function CtrlBHandler () {};

shortcuts.add ([ // Adding some shortcuts
  { shortcut: 'Ctrl+A', handler: event => {
    console.log ( event );
    return true; // Returning true because we don't want other handlers for the same shortcut to be called later
  }},
  { shortcut: 'Ctrl+B', handler: CtrlBHandler },
  { shortcut: 'CmdOrCtrl+K Shift+B', handler: () => {
    // Doing something...
    return true; // Returning true because we don't want other handlers for the same shortcut to be called later
  }},
  { shortcut: '-Ctrl+A' } // Removing the previous shortcut
]);

shortcuts.remove ({ shortcut: 'Ctrl-B', handler: CtrlBHandler }); // Removing a single handler
shortcuts.remove ({ shortcut: 'Ctrl-A' }); // Removing all handlers bound to this shortcut

shortcuts.reset (); // Removing all shortcuts

const dispose = shortcuts.record ( shortcut => { // Recording shortcuts
  console.log ( 'Shortcut recorded:', shortcut );
});

dispose (); // Stopping recording

ℹ️ Handlers are called from the bottom to the top, so an handler defined at the bottom will take precedence over an handler for the same shortcut defined at the top.
ℹ️ If multiple handlers are defined for the same shortcut all of them are executed until one of them returns true.
ℹ️ Adding a shortcut starting with an hyphen (e.g. -Ctrl-A) will actually remove that shortcut.
ℹ️ While recording no handlers will be called.

Shortcut Object

The Shortcut object provides some utilities that you might need in your application. This is its interface:

const Shortcut = {
  shortcut2id ( shortcut: string ): number[];
  shortcut2accelerator ( shortcut: string ): string;
  shortcut2symbols ( shortcut: string ): string;
};