1.4.3 • Published 8 months ago
shosho v1.4.3
ShoSho
A modern and powerful shortcuts management library.
Features
- It is largely built on top of
KeyboardEvent#code
andKeyboardEvent#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 andO(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, likeCtrl+K Ctrl+F
. - It supports detecting which exact modifier key was pressed, like
ControlLeft
orControlRight
. - It supports common aliases for keys, like
Alt
/Option
, orEsc
/Escape
. - It supports some character-based shortcuts, like
Shift+#
, rather than the equivalent key-based shortcut, which might beShift+3
. - It supports automatically using
Command
under macOS andControl
elsewhere, by writing for exampleCommandOrControl+F
. - It supports multi-trigger shortcuts, like
Up+Right
orDown+Left
, except when theMeta
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
1.2.0
11 months ago
1.1.1
11 months ago
1.1.0
11 months ago
1.3.7
11 months ago
1.3.6
11 months ago
1.3.5
11 months ago
1.4.3
8 months ago
1.3.4
11 months ago
1.4.2
11 months ago
1.3.3
11 months ago
1.4.1
11 months ago
1.3.2
11 months ago
1.0.5
11 months ago
1.4.0
11 months ago
1.3.1
11 months ago
1.0.4
12 months ago
1.3.0
11 months ago
1.2.1
11 months ago
1.0.3
1 year ago
1.0.2
1 year ago
1.0.1
1 year ago
1.0.0
1 year ago