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.

Features

• Define all your shortcuts in a json file and load them from there
• Subscribe/unsubscribe to/from Actions
• UMD library, so supports ES6 imports, CommonJS, AMD and browser directly (with no module bundler)
• Fully tested and covered
• Manually add/remove actions and Combos

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

Examples

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

fromJson(json, options)

options: defaults to

{
  debug: false
}

subscribe(actionName, callback)

unsubscribe(actionName, callback?)

If callback is not specified, it will unregister all callbacks

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)

Credits

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