{"id":19714391,"url":"https://github.com/peternaydenov/shortcuts","last_synced_at":"2025-07-23T04:35:40.515Z","repository":{"id":183130813,"uuid":"669653040","full_name":"PeterNaydenov/shortcuts","owner":"PeterNaydenov","description":"Define a context based keyboard-shortcuts and describe a mouse clicks. Switch among contexts.","archived":false,"fork":false,"pushed_at":"2025-07-04T06:44:32.000Z","size":1002,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-04T07:34:14.583Z","etag":null,"topics":["context","js","mouse","mouse-clicks","shortcuts","switching"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PeterNaydenov.png","metadata":{"files":{"readme":"README-v.2.x.x.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-23T01:53:40.000Z","updated_at":"2025-07-04T06:44:35.000Z","dependencies_parsed_at":"2023-07-23T03:45:10.406Z","dependency_job_id":"2f4cdb8e-f2a2-402c-8d80-c56e939640bc","html_url":"https://github.com/PeterNaydenov/shortcuts","commit_stats":null,"previous_names":["peternaydenov/shortcuts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PeterNaydenov/shortcuts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fshortcuts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fshortcuts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fshortcuts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fshortcuts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PeterNaydenov","download_url":"https://codeload.github.com/PeterNaydenov/shortcuts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fshortcuts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266618957,"owners_count":23957273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["context","js","mouse","mouse-clicks","shortcuts","switching"],"created_at":"2024-11-11T22:31:25.578Z","updated_at":"2025-07-23T04:35:40.492Z","avatar_url":"https://github.com/PeterNaydenov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shortcuts (@peter.naydenov/shortcuts)\n\n![version](https://img.shields.io/github/package-json/v/peterNaydenov/shortcuts)\n![license](https://img.shields.io/github/license/peterNaydenov/shortcuts)\n![GitHub issues](https://img.shields.io/github/issues/peterNaydenov/shortcuts)\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40peter.naydenov%2Fshortcuts)\n\n\n\nDefine a context based keyboard-shortcuts and describe a mouse clicks. Switch among contexts.\n\n\n\n## Shortcut Description Rules\nThe shortcuts definition includes a context name and a set of rules(object). The rules are a set of key-value pairs. The key is a shortcut name and the value is a function or array of functions, to be executed when the shortcut is triggered (action function).\n\n```js\n// { context: { shortcutName: actionFunction } }\n// or\n// { context: { shortcutName: [ actionFunction1, actionFunction2 ] }}\n\n// Shortcut definition object:\n{\n    contextName : {\n                    shortcutName : function () {\n                                                // do something\n                                        }\n                    , shortcutName : [ \n                                              function action1() {\n                                                        // do something\n                                                }\n                                            , function action2() {\n                                                        // do something\n                                                }\n                                    ]\n                }\n}\n```\n\nLoad a shortcut definition by calling `load` method.\n\n```js\n// for es6 module projects:\ninclude shortcuts from '@peter.naydenov/shortcuts'\n// for commonjs projects:\nconst shortcuts = require('@peter.naydenov/shortcuts')\n\n\n\nconst short = shortcuts ();\nshort.load ( shortcutDefinition )\n```\n\nShortcuts are working only if contex is active. To activate a context call `changeContext` method.\n\n```js\nshort.changeContext ( contextName )\n```\n\nTo deactivate a context without starting other context, call `changeContext` method without arguments.\n\n```js\nshort.changeContext ()\n``` \n\nShortcuts context has `note` that works like sub-contexts. Every shortcut function receives a context and note as arguments, so you can have fine control over the context.\n\n```js\nshort.setNote ( 'special' ) // set note to 'special'\nshort.setNote () // remove the note\n```\n\nThe idea of `note` is to minimize the number of contexts if they are very simular. You can use same context but change the `note` and control the shortcut execution from inside of the action function by checking the `note`.\n\n```js\n{\n    contextName : {\n                    shortcutName : function ( {context, note} ) {\n                                        if ( note === 'special' ) {\n                                                        // do something\n                                            }\n                                    }\n                }\n}\n```\n\nContext and notes are available inside action functions but you can check them from outside too.\nCheck current context by calling `getContext` method.\n\n```js\nshort.getContext ()\n```\n\nCheck notes by calling `getNote` method.\n\n```js\nshort.getNote ()\n```\n\n\n\n\n\n## Mouse Event Descriptions\nMouse event name is build from the following parts:\n```js\n // mouse-click-\u003cmouse button\u003e-\u003cnumber of clicks\u003e\n // example:\n // mouse-click-left-2 -\u003e for double click with left mouse button\n // mouse-click-right-3 -\u003e for triple click with right mouse button\n\n // mouse button options: left, right, middle\n```\n\nThe modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the mouse event by sign `+`:\n\n```js\n // example:\n // ctrl+mouse-click-left-1 -\u003e for single click with left mouse button and ctrl key pressed\n```\nOrder of describing mouse event and modifier keys is not important.\n\n```js\n // example:\n // mouse-click-left-1+ctrl -\u003e same as above\n\n // These 3 descriptions are equal:\n // mouse-click-left-1+ctrl+alt+shift\n // alt+shift+mouse-click-left-1+ctrl\n // mouse-click-left-1+shift+ctrl+alt\n```\n\nMultiple clicks are detected automatically by time interval between clicks. The default interval is 320ms but you can change it by setting `mouseWait` option. Read more in section `Options`.\n\n\n## Define a mouse targets\nTarget HTML elements for `shortcuts` are defined by `data-click` attribute. The value of the attribute is the name of the target. Example:\n\n```html\n\u003cbutton data-click=\"id\"\u003eClick me\u003c/button\u003e\n\u003c!-- target name is 'id' --\u003e\n```\n\nAttribute is customizable by setting `clickTarget` option. Read more in section `Options`.\n\nIf current shortcuts context contain definition for 2 or more clicks, this may slow down the execution of single shortcuts because `shortcuts` will wait for the time interval to detect multiple clicks. To avoid this for specific targets, you can set `data-quick-click` attribute to the target element. Example:\n\n```html\n\u003cbutton data-click=\"id\" data-quick-click\u003eClick me\u003c/button\u003e\n\u003c!-- target name is 'id' and will not wait for more then 1 click --\u003e\n```\nUsing a \u003ca\u003e tag is a special case. It's always recognized as a target, and always with attribute `data-quick-click`. No need to set it manually. Example:\n\n```html\n\u003ca href=\"#\"\u003eClick me\u003c/a\u003e\n\u003c!-- Recognized as a target and will not wait for more then 1 click --\u003e\n\u003c!-- Take care for the action from shortcut `mouse-click-left-1`. --\u003e\n```\n\nClicking on \u003ca\u003e tag will not execute anything. All events are blocked by default. In your `mouse-click-left-1` action function you can write a code to execute the default action. Example:\n\n```js\n{\n    contextName : {\n                    'mouse-click-left-1' : function ( {target, event} ) {\n                                        if ( target.tagName === 'A' ) { // All targets that are \u003ca\u003e tags will execute the default action\n                                                  window.location.href = target.href  // Go to the link\n                                            }\n                                    }\n                }\n}\n```\n\n\n\n## Keyboard Event Descriptions\nKeyboard event description contains a key name and a modifier keys if they are used. The modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the keyboard event by sign `+`:\n\n```js\n // example:\n // ctrl+alt+shift+a -\u003e for key 'a' with ctrl, alt and shift keys pressed\n```\n\nKeyboard event description support a shortcut sequenses. These means that you can press a sequence of keys to trigger a shortcut. The sequence elements are separated by sign \",\" ( coma ):\n\n```js\n // example:\n // a,b,c -\u003e for key 'a' then key 'b' then key 'c'\n\n // g+shift,o,t,o -\u003e for key 'g' with shift, then key 'o', then key 't' then key 'o'\n```\n\nOrder of describing keyboard event and modifier keys is not important, but sequence elements are:\n\n```js\n // example:\n // a+ctrl,l,o,t -\u003e a with ctrl, then l, then o, then t\n // this is equal to:\n // ctrl+a,l,o,t\n // but not equal to:\n // ctrl+a,o,t,l\n```\n\nKeyboard sequence is detected automatically by time interval between key presses. The default interval is 480ms but you can change it by setting `keyWait` option. Read more in section `Options`. \n\nThere is a way to disable automatic sequence detection and mark the begining and the end of the sequense by using a keyboard action functions. Read more in section `Keyboard Action Functions`.\n\nSpecial characters that are available for your shortcut descriptions:\n- 'left' - left arrow key\n- 'right' - right arrow key\n- 'up' - up arrow key\n- 'down' - down arrow key\n- 'enter' - enter key\n- 'space' - space key\n- 'esc' - escape key\n- 'tab' - tab key\n- 'backspace' - backspace key\n- '=' - equal key\n- F1 - F12 - function keys\n- '/' - slash key\n- '\\\\' - backslash key\n- '[' - open square bracket key\n- ']' - close square bracket key\n- '`' - backtick key\n\n**Warning**: For keys with two symbols, in shortcut description use the lower one. Examples: Use '=' instead of '+', use '/' instead of '?', etc. Modifier keys are available for special characters too.\n\n**Warining**: Some of the shortcuts are used by OS and the browswer, so they are not available.\n\n\n\n## Action Functions\nAction functions are called when a shortcut is triggered. They is a difference between keyboard and mouse action functions. Arguments are slightly different.\n\n\n\n### Keyboard Action Functions\nDescription of keyboard action functions is:\n```js\nfunction myKeyHandler ({\n                  context   // (string) Name of the current context;\n                , note      // (string) Name of the note or null if note isn't set;\n                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;\n                , wait      // (function). Call it to stop a sequence timer and write shortcut sequence without a timer.\n                , end       // (function). Recover the sequence timer;\n                , ignore    // (function). Call it to ignore the current shortcut from the sequence;\n                , isWaiting // (boolean). True if the sequence timer is active;\n                        }) {\n    // Body of the handler. Do something...\n}\n```\n\n\n\n\n### Mouse Action Functions\nMouse action functions can be described like:\n\n```js\nfunction myMouseHandler ({\n                  context     // (string) Name of the current context;\n                , note        // (string) Name of the note or null if note isn't set;\n                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;\n                , target      // (DOM element). Target element of the mouse event;\n                , targetProps // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;\n                , x           // (number). X coordinate of the target element;\n                , y           // (number). Y coordinate of the target element;\n                , event       // (object). Original mouse event object;\n          }) {\n    // Body of the handler. Do something...\n}\n```\n\n\n\n\n\n## Methods\n\nDescription of the methods of shortcut instance:\n\n```js\n  load            : 'Load and extend a shortcut definition.'\n, unload          : 'Remove a shortcut context with all its shortcuts.'\n, changeContext   : 'Switch to existing shortcut context.'\n, emit            : 'Trigger a shortcut or custom event programmatically.'\n, pause           : 'Stop listening for shortcuts.'\n, resume          : 'Resume listening for shortcuts.'\n, listContexts    : 'Return list of available contexts.'\n, listShortcuts   : 'Return list of shortcuts per context.'\n, getContext      : 'Return a name of current context or null if there is no context selected'\n, getNote         : `Return a name of current note or null if note isn't set`\n, setNote         : 'Set a note to current context.'\n, setDependencies : 'Set dependencies that will be available in action functions.'\n, getDependencies : 'Return dependencies object.'\n```\n\n### How to 'pause' and 'resume'?\nWhen you want to stop execution of shortcuts, call `short.pause()`. It's equal to `short.pause('*')`. Will stop all shortcuts in the active context. Stop for single shortcut is by calling `short.pause('shortcutName')`. To resume shortcuts execution call `short.resume()`. It's equal to `short.resume('*')`. Will resume all shortcuts in the active context. Resume for single shortcut is by calling `short.resume('shortcutName')`.\n\n```js\n// pause all shortcuts in the active context\nshort.pause () // will stop all shortcuts in the active context\nshort.resume ( 'shift+a' ) // will resume only 'shift+a' shortcut\n\nshort.resume ('*') // will resume all shortcuts\n```\n\n\n\n## Options\n\nBy `options` you can customize the behavior of the shortcuts. Here is the list of available options:\n\n```js\n  mouseWait     : 'Timeout for entering multiple mouse events. Default value - 320.'\n, keyWait       : 'Timeout for entering shortcut sequence in ms. Default value - 480'\n, clickTarget   : 'Data attribute name to recognize click items in HTML. Default value - click' // data attribute 'click' means attribute ( data-click='someName' )\n, listenFor     : `List input signal sources. Default value - [ 'mouse', 'keyboard' ]`\n, onShortcut    : 'False or a callback function that is called when a shortcut is triggered. Default value - false'\n, streamKeys    : 'False or a callback function that is called when a key is pressed. Default value - false'\n```\n\nYou can request default list of options with their default values:\n\n```js\nshortcuts.getDefaults ()\n// Note: This method is availalble on the original shortcuts object, not on the shortcuts instance.\n\n// start a shortcuts with default options\nconst short = shortcuts ()\nconst short = shortcuts ( shortcuts.getDefaults () ) // same as above\n// The idea behind getDefaults is to see what options are available and what are their default values.\n```\n\n\n\n### onShortcut option\n```js\n function onShortcut ({ shortcut, context, note, dependencies }) {\n        // shortcut - (string) Triggered shortcut name\n        // context - (string) Name of the current context\n        // note - (string) Name of the note or null if note isn't set\n        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method\n    }\n```\n\n\n\n### streamKeys option\n```js\n function streamKeys ({ key, context, note, dependencies }) {\n        // key - (string) Pressed key name\n        // context - (string) Name of the current context\n        // note - (string) Name of the note or null if note isn't set\n        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method\n    }\n```\n\n\n\n## Links\n\n- [History of changes](https://github.com/PeterNaydenov/shortcuts/blob/main/Changelog.md)\n- [Migration guide](https://github.com/PeterNaydenov/shortcuts/blob/main/Migration.guide.md)\n\n\n\n## Credits\n'@peter.naydenov/shortcuts' was created and supported by Peter Naydenov.\n\n\n\n## License\n'@peter.naydenov/shortcuts' is released under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeternaydenov%2Fshortcuts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeternaydenov%2Fshortcuts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeternaydenov%2Fshortcuts/lists"}