tiny-shosho

Tiny ShoSho

A simple shortcuts management library.

This library is a subset of the much more powerful ShoSho that just handles simple shortcuts, but at 10% of the size.

Shortcut Syntax

The following keys can be used when defining a shortcut:

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

Please note that:

• Other keys are not supported.
• Shortcuts are type-checked for correctness.
• Keys in a shortcut must be joined by a plus sign (e.g. Ctrl+A).
• 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 tiny-shosho

Usage

import TinyShoSho from 'tiny-shosho';

// Let's create a shortcuts manager

const shortcuts = new TinyShoSho ({
  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;
});

// 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 ();

License

MIT Fabio Spampinato