ShoSho

A modern and powerful shortcuts management library.

Features

• It is largely built on top of KeyboardEvent#code and KeyboardEvent#key, for great compatibility across browsers, platforms, languages and layouts.
• It is fast. Almost always this library will do O(1) registrations, O(1) disposals, O(1) lookups and O(1) resetting.
• It supports ~100 keyboard keys, including function keys and numpad keys.
• It supports mouse buttons too, which can be mixed in shortcts with keyboard keys, like Ctrl+ClickLeft.
• It supports simple shortcuts, like Ctrl+F, and shortcuts sequences, like Ctrl+K Ctrl+F.
• It supports detecting which exact modifier key was pressed, like ControlLeft or ControlRight.
• It supports common aliases for keys, like Alt/Option, or Esc/Escape.
• It supports some character-based shortcuts, like Shift+#, rather than the equivalent key-based shortcut, which might be Shift+3.
• It supports automatically using Command under macOS and Control elsewhere, by writing for example CommandOrControl+F.
• It supports multi-trigger shortcuts, like Up+Right or Down+Left, except when the Meta key is pressed, which is buggy in browsers.
• It supports Konami codes, a.k.a. cheatcode shortcuts, like Up Up Down Down Left Right Left Right B A.
• It supports formatting shortcuts in 10 different styles, including formatting for Electron and as symbols for hints/tooltips.
• It supports recording a shortcut, for customizing shortcuts easily.

Shortcut Syntax

The following keys can be used when defining a shortcut:

• Modifiers: Alt/Option, Cmd/Command/Meta, Ctrl/Control, Shift, CmdOrCtrl/CommandOrControl.
• Left modifiers: AltLeft/OptionLeft, CmdLeft/CommandLeft/MetaLeft, CtrlLeft/ControLeft, CmdLeftOrCtrlLeft/CommandLeftOrControlLeft.
• Right modifiers: AltRight/OptionRight, CmdRight/CommandRight/MetaRight, CtrlRight/ControRight, CmdRightOrCtrlRight/CommandRightOrControlRight.
• Digits: 0-9.
• Alphabet letters: A-Z.
• Function keys: F1-F24.
• Numpad digits: Numpad0-Numpad9.
• Numpad operators: NumpadAdd, NumpadComma, NumpadDecimal, NumpadDivide, NumpadEnter, NumpadEqual, NumpadMultiply, NumpadSubtract.
• Special keys: Backspace, Capslock, Del/Delete, Down, End, Enter/Return, Esc/Escape, Home, Insert, Left, PageDown, PageUp, Right, Space/Spacebar, Tab, Up, NumLock, ScrollLock.
• Punctuation keys: !, @, #, $, %, ^, &, *, ( , ), _, {, }, |, :, ", <, >, ?, ~.
• Mouse buttons: ClickLeft/MouseLeft, ClickMiddle/MouseMiddle, ClickRight/MouseRight, Mouse0-Mouse9.

Please note that:

• ℹ️ 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).
• ⚠️ Punctuation keys should be avoided when possible, especially when used in combination with Shift/Alt, as they may lead to somewhat different results across different layouts.

Install

npm install --save shosho

Usage

import ShoSho from 'shosho';

// Let's create a shortcuts manager

const shortcuts = new ShoSho ({
  capture: true,
  target: document,
  shouldHandleEvent ( event ) {
    // Return "true" if this event should be handled
    return true;
  }
});

// Let's register some shortcuts. Shortcuts handlers must return "true" if they actually handled the shortcut

shortcuts.register ( 'A', event => { // Single-key shortcut
  console.log ( 'Handling A' );
  return true;
});

shortcuts.register ( 'Ctrl+F', event => { // Simple modifier+trigger shortcut
  console.log ( 'Handling Ctrl+F' );
  return true;
});

shortcuts.register ( 'Ctrl+K Ctrl+F', event => { // Advanced sequence shortcut
  console.log ( 'Handling Ctrl+K Ctrl+F' );
  return true;
});

shortcuts.register ( 'ClickMiddle', event => { // Single-mouse-button shortcut
  console.log ( 'Skipping ClickMiddle actually' );
  return false; // Returning "false" tells the library to try other potential handlers for this shortcut
});

shortcuts.register ( 'CmdOrCtrl+ClickRight', event => { // Advanced mixed keyboard/mouse shortcut
  console.log ( 'Handling CmdOrCtrl+ClickRight' );
  return true;
});

// Let's register a Konami code, which basically is not affected by other registered shortcuts

shortcuts.register ( 'Up Up Down Down Left Right Left Right B A', event => { // A Konami code
  console.log ( 'Secret shortcut triggered 🚀' );
}, { konami: true } ); // Registering it as a Konami code

// Let's register a shortcut but then dispose of it

const dispose = shortcuts.register ( 'Shift+1', event => {
  console.log ( 'Handling Shift+1' );
  return true;
});

dispose (); // Unregistering that shortcut with that handler

// Let's trigger a shortcut programmatically, perhaps for debugging purposes

const handled = shortcuts.trigger ( 'Ctrl+F' );

console.log ( handled ); // => true

// Let's actually start listening for shortcuts

shortcuts.start ();

// Let's stop listening for shortcuts

shortcuts.stop ();

// Let's dispose of all registered shortcuts

shortcuts.reset ();

// Let's format a shortcut, with every supported format

ShoSho.format ( 'ControlLeft+A', 'electron' ); // => 'Ctrl+A'
ShoSho.format ( 'ControlLeft+A', 'symbols' ); // => '⌃A'
ShoSho.format ( 'ControlLeft+A', 'long-flexible-directional' ); // => 'CommandOrControlLeft+A'
ShoSho.format ( 'ControlLeft+A', 'long-flexible-nondirectional' ); // => 'CommandOrControl+A'
ShoSho.format ( 'ControlLeft+A', 'long-inflexible-directional' ); // => 'ControlLeft+A'
ShoSho.format ( 'ControlLeft+A', 'long-inflexible-nondirectional' ); // => 'Control+A'
ShoSho.format ( 'ControlLeft+A', 'short-flexible-directional' ); // => 'CmdOrCtrlLeft+A'
ShoSho.format ( 'ControlLeft+A', 'short-flexible-nondirectional' ); // => 'CmdOrCtrl+A'
ShoSho.format ( 'ControlLeft+A', 'short-inflexible-directional' ); // => 'CtrlLeft+A'
ShoSho.format ( 'ControlLeft+A', 'short-inflexible-nondirectional' ); // => 'Ctrl+A'

// Let's check if something is a valid shortcut

ShoSho.isShortcut ( 'Control+A' ); // => true
ShoSho.isShortcut ( 'ControlA' ); // => false

// Let's record a shortcut, which will require manual trimming and formatting

const dispose = ShoSho.record ( shortcut => {

  console.log ( shortcut ); // => It could be 'A', 'CtrlLeft+A', 'CtrlLeft+A CtrlRight', 'CtrlLeft+A CtrlRight+B' and so on...

  const trimmed = shortcut.replace ( /(^.*?)((?:Control(?:Left|Right)\+K )*\S+$)/, '$2' ); // Allowing only 'ControlLeft+K' and 'ControlRight+K' to not be the last shortcut in the sequence
  const formatted = ShoSho.format ( trimmed, 'long-inflexible-nondirectional' ); // Ensuring the final shortcut is formatted exactly how we want it

  console.log ( formatted ); // => It could be 'K', 'CtrlLeft+K', 'CtrlLeft+K CtrlRight', 'Ctrlleft+K CtrlRight+A' and so on...

});

// Let's stop recording

dispose ();

License

MIT © Fabio Spampinato