ShortcutJS

Keyboard manager for javascript and typescript, made for humans 😎

Do you have a very interactive app with lots of shortcuts? ShortcutJS makes defining all your shortcuts very easy, by defining Combos bound to Actions. Even better, you can define them all in JSON file.

Usage

yarn add shortcutjs
# or
npm install shortcutjs --save

Define a shortcuts.json file with all your shortcuts

[
  {
    "combo": "ctrl a",
    "action": "selectAll"
  },
  {
    "combo": "ctrl alt f",
    "action": "find"
  }
]

Note: action means just an action name to subscribe to

// --> main.js
import { shortcutJS } from 'shortcutjs'
import shortcuts from './shortcuts.json'

// optional debug param
shortcutJS.fromJson(shortcuts, { debug: true })


// --> yourComponent.js (any other file)
import { shortcutJS } from 'shortcutjs'

// Subscribe to the action created from the json
shortcutJS.subscribe('selectAll', ev => console.log('ctrl a have been triggered!', ev))

Checkout the Full API documentation

Combos and Supported keys

A combo is composed by 1 or more state keys (ctrl, alt, shift, cmd) plus 1 or more supported keys. They're case insensitive.

Supported keys:

• Basic letters (a-z)
• Numbers (0-9)
• Navigation keys (left, up, enter, backspace, end...)
• Function keys (f1, f2...)
• Numpad keys (num0, num1, num*, num/...)

You can see all available keys in keyMap of key-container.ts.

Options

When initializing shortcutJS by calling fromJson or init, you can pass an options object:

{
  debug: false, // Prints debug notes in the console
  preventDefault: false, // Automatically calls ev.preventDefault() when an action is matched
  onlyStateCombos: false, // Only process combos which includes any state key (cmd, ctrl, alt, shift)
}

API

• fromJson(json[], options): initializes shortcutJS from a json array
• subscribe(actionName, cb): binds a callback to an action, given its name
• unsubscribe(actionName, cb?): unbinds a callback from an action, given its name. If no cb specified, unbinds all.
• pause(): pauses execution of shortcutJS
• resume()
• isPaused()
• addAction(action: Action): dynamically adds an action
• init(options): (don't use it if you've used fromJson). Initializes shortcutJS.
• reset(): resets shortcutJS, cleans variables and unbind events

Examples

When loading from json, you only need to use fromJson, subscribe and unsubscribe methods.

Pausing/Resuming

import { shortcutJS } from 'shortcutjs'
import shortcuts from './shortcuts.json'

shortcutJS.fromJson(shortcuts)

shortcutJS.pause()
console.log(shortcutJS.isPaused()) // true
shortcutJS.resume()
console.log(shortcutJS.isPaused()) // false

Manually creating Actions and Combos

import { shortcutJS, Action, KeyCombo } from 'shortcutjs'

shortcutJS.init({ debug: true }) // optional "options" parameter

// Add action
const openAction = new Action('open', KeyCombo.fromString('ctrl a'))
shortcutJS.addAction(openAction)

// --> From anotherComponent.js
const openCb = ev => console.log(ev)
shortcutJS.subscribe('open', openCb)

// Later, when leaving the view...
shortcutJS.unsubscribe('open', openCb)

Contribution guide

# Fork repo
git clone https://github.com/YOUR-USERNAME/ShortcutJS
yarn install # or npm install
# Start coding. For commit, use npm run commit (otherwise it will tell you to do it ;)
# Open a PR

Note: Use node 7.5, or <= 7.2. Because of a regression in Node 7.3, the tests would fail in Node 7.3 and 7.4

ShortcutJS project setup applies CI (with Travis) + CD (Semantic Release) using conventions (commitizen, with conventional-commit and conventional-changelog) and git hooks instead of large contribution rules.

As a suggestion, follow clean code practises

Credits

Made with ❤️ by @alexjoverm, supported by Coosto, @coostodev