# ShortcutJS

Keyboard manager for javascript and typescript, made for humans :sunglasses:

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 :heart: by @alexjoverm, supported by Coosto, @coostodev

## Index

### External modules

- "action"
- "event-processor"
- "json-parser"
- "key-combo"
- "key-container"
- "options"
- "shortcut"
- "utils"

Generated using TypeDoc