@peter.naydenov/shortcuts 2.1.0 → 3.0.0

package/Changelog.md

@@ -1,6 +1,30 @@
 ## Release History
 
 
+
+### 3.0.0 ( 2024-03-05 )
+- [x] Mouse events don't have `preventDefault` by default anymore. Handle it in the action function if needed. Take a look on `Mouse Action Function` argument description. Object `event` is available;
+- [x] Plugin system where plugins role is to convert DOM events to shortcut strings, then the core part will trigger the action functions related to the shortcut.
+- [x] Plugin can be enable/disable;
+- [x] Plugin can be mute/unmute;
+- [x] Plugin prefix in shortcut description is required. Keyboard plugin will take care for events started with ‘key:’ for example. Required because we should know the plugin that will handle the event;
+- [x] Start a plugin: enablePlugin ( pluginCode, pluginOptions );
+- [x] Function to destroy(remove) a plugin - disablePlugin();
+- [x] Mute/unmute a plugin. It’s like disable all events for a specific plugin;
+- [x] Plugin system documentation;
+- [x] Plugin interface: getPrefix, shortcutName, contextChange, mute, unmute, destroy;
+- [x] Plugin options - specific for each plugin;
+
+
+
+
+### 2.2.0 ( 2024-02-10 )
+- [x] Folder 'dist' was added to the project. Includes commonjs, umd and esm versions of the library;
+- [x] Package.json: "exports" section was added. Allows you to use package as commonjs or es6 module without additional configuration;
+- [x] Rollup was added to the project. Used to build the library versions;
+
+
+
 ### 2.1.0 ( 2023-10-17 )
 - [x] Method `setDependencies` to add more external objects available in all action functions;
 - [x] Method `getDependencies` to look at existing `dependencies` list;

package/How..to.make.plugins.md

@@ -0,0 +1,41 @@
+# Shortcut plugins
+
+Shortcut plugin should be a function that receives 3 arguments: dependencies, state and options. Shoud return an shortcut plugin API object.
+
+```js
+function plugin ( dependencies, state, options ) {
+  // Normalize all shortcuts related to this plugin
+  // Setup some internal state
+  // Start listening to DOM events if current context has shortcuts related to this plugin
+  // ...
+  return {
+        // API
+          getPrefix: function () {
+                            // return a plugin prefix
+                        },
+          shortcutName : function ( shortcutName ) {
+                            // normalize shortcut name
+                            // return normalized shortcut name
+                        },
+            contextChange: function ( context ) {
+                            // How plugin should react to context change
+                            // return void
+                        },
+            mute: function () {
+                            // Function that will stop DOM events from being triggered
+                        },
+            unmute: function () {
+                            // Function that will resume DOM events
+                        },
+            destroy: function () {
+                            // Destroy plugin instance
+                        }
+        }
+} // plugin
+```
+
+State and dependencies are objects coming from the main library. **Dependencies** contains the library event emitter ( dependencies.ev). From state object you have access to the current context object state and loaded shortcuts contextes. Object **options** contains a plugin options provided by the user.
+
+If you need see an example of a shortcut plugin, check the available plugins in the library: key and click.
+
+

package/Migration.guide.md

@@ -1,5 +1,82 @@
 # Migration Guides
 
+
+## From version 2.x.x to version 3.x.x
+
+Reason for significant refactoring of the code was my desire to make the library extensible with a plugins. Plugins role is to convert DOM events to shortcut strings, then the core part will trigger the action functions related to the shortcut. Now we have a core, plugin interface and plugins. All listener for `keyboard` and `mouse clicks` are moved to plugins. Mouse events are tracked by `click` plugin and keyboard events are tracked by `key` plugin. 
+
+We starting with only two plugins that cover the existing functionality of the library but plans are to extend the library with more plugins. For example we can add `'scroll`, `drag-drop`, `input events`, etc. Whould be great to make possible to describe all possible page events as shortcuts.
+
+### Package structure
+Package contains the library and these two plugins.
+
+```js
+// Import the library and plugins
+// Version 2.x.x
+import shortcuts  from 'shortcuts';
+const short2 =  shortcuts({listenFor: ['mouse', 'keyboard']}) // Start listening for mouse and keyboard events
+// Version 3.x.x
+// Package provides access to the library and plugins. No default import anymore.
+import { shortcuts, click, key } from 'shortcuts';
+const short3 = shortcuts () // Start library without any plugins
+// Enable plugins if you need them:
+shorts3.enablePlugin(click)
+shorts3.enablePlugin(key)
+```
+
+### Global Options
+Part of the options are moved to the plugin options. 
+```js
+// Version 2 options:
+  mouseWait     : '-> Moved to click plugin options'
+, keyWait       : '-> Moved to key plugin options'
+, clickTarget   : '-> Moved to click plugin options'
+, listenFor     : `x  Removed. Use enablePlugin() method to start listening for a plugin`
+, onShortcut    : 'No changes. Available as global option'
+, streamKeys    : '-> Moved to key plugin options'
+```
+The method `shortcuts.getDefaults()` was removed. No reasons to exist anymore.
+
+### Shortcut names
+Because we have plugins now, we need to address somehow the plugin that will take care about the shortcut. Introducing plugin prefix.
+```js
+// Description of the shortcut
+// Version 2.x.x
+const description2 = {
+    contextName : {
+                        'shortcutName' : 'actionFunction'
+                    }
+        }
+// Version 3.x.x    
+const description3 ={
+    contextName : {
+                        'pluginPrefix:shortcutName' : 'actionFunction'
+                    }
+        }
+
+// Here is an example:
+//v.2.x.x
+const desc2 = {
+    myContext : {
+                    'shift+f' : r => console.log(r)
+                }
+        }
+//v.3.x.x
+const desc3 = {
+    myContext : {
+                    'key:shift+f' : r => console.log(r)
+                }
+        }
+```
+
+
+### Mouse events
+Prevent default is not called by default anymore. Handle it manually in the action function if needed. Object `event` is available in arguments object of action function. That will allow you to use default browser behavior without writing additional code.
+
+
+
+
+
 ## From version 1.x.x to version 2.x.x
 There are 2 breaking changes: in action functions and in emit method.
 ### Action functions

package/README-v.2.x.x.md

@@ -0,0 +1,375 @@
+# Shortcuts (@peter.naydenov/shortcuts)
+
+![version](https://img.shields.io/github/package-json/v/peterNaydenov/shortcuts)
+![license](https://img.shields.io/github/license/peterNaydenov/shortcuts)
+![GitHub issues](https://img.shields.io/github/issues/peterNaydenov/shortcuts)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40peter.naydenov%2Fshortcuts)
+
+
+
+Define a context based keyboard-shortcuts and describe a mouse clicks. Switch among contexts.
+
+
+
+## Shortcut Description Rules
+The 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).
+
+```js
+// { context: { shortcutName: actionFunction } }
+// or
+// { context: { shortcutName: [ actionFunction1, actionFunction2 ] }}
+
+// Shortcut definition object:
+{
+    contextName : {
+                    shortcutName : function () {
+                                                // do something
+                                        }
+                    , shortcutName : [ 
+                                              function action1() {
+                                                        // do something
+                                                }
+                                            , function action2() {
+                                                        // do something
+                                                }
+                                    ]
+                }
+}
+```
+
+Load a shortcut definition by calling `load` method.
+
+```js
+// for es6 module projects:
+include shortcuts from '@peter.naydenov/shortcuts'
+// for commonjs projects:
+const shortcuts = require('@peter.naydenov/shortcuts')
+
+
+
+const short = shortcuts ();
+short.load ( shortcutDefinition )
+```
+
+Shortcuts are working only if contex is active. To activate a context call `changeContext` method.
+
+```js
+short.changeContext ( contextName )
+```
+
+To deactivate a context without starting other context, call `changeContext` method without arguments.
+
+```js
+short.changeContext ()
+``` 
+
+Shortcuts 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.
+
+```js
+short.setNote ( 'special' ) // set note to 'special'
+short.setNote () // remove the note
+```
+
+The 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`.
+
+```js
+{
+    contextName : {
+                    shortcutName : function ( {context, note} ) {
+                                        if ( note === 'special' ) {
+                                                        // do something
+                                            }
+                                    }
+                }
+}
+```
+
+Context and notes are available inside action functions but you can check them from outside too.
+Check current context by calling `getContext` method.
+
+```js
+short.getContext ()
+```
+
+Check notes by calling `getNote` method.
+
+```js
+short.getNote ()
+```
+
+
+
+
+
+## Mouse Event Descriptions
+Mouse event name is build from the following parts:
+```js
+ // mouse-click-<mouse button>-<number of clicks>
+ // example:
+ // mouse-click-left-2 -> for double click with left mouse button
+ // mouse-click-right-3 -> for triple click with right mouse button
+
+ // mouse button options: left, right, middle
+```
+
+The modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the mouse event by sign `+`:
+
+```js
+ // example:
+ // ctrl+mouse-click-left-1 -> for single click with left mouse button and ctrl key pressed
+```
+Order of describing mouse event and modifier keys is not important.
+
+```js
+ // example:
+ // mouse-click-left-1+ctrl -> same as above
+
+ // These 3 descriptions are equal:
+ // mouse-click-left-1+ctrl+alt+shift
+ // alt+shift+mouse-click-left-1+ctrl
+ // mouse-click-left-1+shift+ctrl+alt
+```
+
+Multiple 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`.
+
+
+## Define a mouse targets
+Target HTML elements for `shortcuts` are defined by `data-click` attribute. The value of the attribute is the name of the target. Example:
+
+```html
+<button data-click="id">Click me</button>
+<!-- target name is 'id' -->
+```
+
+Attribute is customizable by setting `clickTarget` option. Read more in section `Options`.
+
+If 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:
+
+```html
+<button data-click="id" data-quick-click>Click me</button>
+<!-- target name is 'id' and will not wait for more then 1 click -->
+```
+Using a <a> 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:
+
+```html
+<a href="#">Click me</a>
+<!-- Recognized as a target and will not wait for more then 1 click -->
+<!-- Take care for the action from shortcut `mouse-click-left-1`. -->
+```
+
+Clicking on <a> 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:
+
+```js
+{
+    contextName : {
+                    'mouse-click-left-1' : function ( {target, event} ) {
+                                        if ( target.tagName === 'A' ) { // All targets that are <a> tags will execute the default action
+                                                  window.location.href = target.href  // Go to the link
+                                            }
+                                    }
+                }
+}
+```
+
+
+
+## Keyboard Event Descriptions
+Keyboard 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 `+`:
+
+```js
+ // example:
+ // ctrl+alt+shift+a -> for key 'a' with ctrl, alt and shift keys pressed
+```
+
+Keyboard 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 ):
+
+```js
+ // example:
+ // a,b,c -> for key 'a' then key 'b' then key 'c'
+
+ // g+shift,o,t,o -> for key 'g' with shift, then key 'o', then key 't' then key 'o'
+```
+
+Order of describing keyboard event and modifier keys is not important, but sequence elements are:
+
+```js
+ // example:
+ // a+ctrl,l,o,t -> a with ctrl, then l, then o, then t
+ // this is equal to:
+ // ctrl+a,l,o,t
+ // but not equal to:
+ // ctrl+a,o,t,l
+```
+
+Keyboard 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`. 
+
+There 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`.
+
+Special characters that are available for your shortcut descriptions:
+- 'left' - left arrow key
+- 'right' - right arrow key
+- 'up' - up arrow key
+- 'down' - down arrow key
+- 'enter' - enter key
+- 'space' - space key
+- 'esc' - escape key
+- 'tab' - tab key
+- 'backspace' - backspace key
+- '=' - equal key
+- F1 - F12 - function keys
+- '/' - slash key
+- '\\' - backslash key
+- '[' - open square bracket key
+- ']' - close square bracket key
+- '`' - backtick key
+
+**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.
+
+**Warining**: Some of the shortcuts are used by OS and the browswer, so they are not available.
+
+
+
+## Action Functions
+Action functions are called when a shortcut is triggered. They is a difference between keyboard and mouse action functions. Arguments are slightly different.
+
+
+
+### Keyboard Action Functions
+Description of keyboard action functions is:
+```js
+function myKeyHandler ({
+                  context   // (string) Name of the current context;
+                , note      // (string) Name of the note or null if note isn't set;
+                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
+                , wait      // (function). Call it to stop a sequence timer and write shortcut sequence without a timer.
+                , end       // (function). Recover the sequence timer;
+                , ignore    // (function). Call it to ignore the current shortcut from the sequence;
+                , isWaiting // (boolean). True if the sequence timer is active;
+                        }) {
+    // Body of the handler. Do something...
+}
+```
+
+
+
+
+### Mouse Action Functions
+Mouse action functions can be described like:
+
+```js
+function myMouseHandler ({
+                  context     // (string) Name of the current context;
+                , note        // (string) Name of the note or null if note isn't set;
+                , dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
+                , target      // (DOM element). Target element of the mouse event;
+                , targetProps // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
+                , x           // (number). X coordinate of the target element;
+                , y           // (number). Y coordinate of the target element;
+                , event       // (object). Original mouse event object;
+          }) {
+    // Body of the handler. Do something...
+}
+```
+
+
+
+
+
+## Methods
+
+Description of the methods of shortcut instance:
+
+```js
+  load            : 'Load and extend a shortcut definition.'
+, unload          : 'Remove a shortcut context with all its shortcuts.'
+, changeContext   : 'Switch to existing shortcut context.'
+, emit            : 'Trigger a shortcut or custom event programmatically.'
+, pause           : 'Stop listening for shortcuts.'
+, resume          : 'Resume listening for shortcuts.'
+, listContexts    : 'Return list of available contexts.'
+, listShortcuts   : 'Return list of shortcuts per context.'
+, getContext      : 'Return a name of current context or null if there is no context selected'
+, getNote         : `Return a name of current note or null if note isn't set`
+, setNote         : 'Set a note to current context.'
+, setDependencies : 'Set dependencies that will be available in action functions.'
+, getDependencies : 'Return dependencies object.'
+```
+
+### How to 'pause' and 'resume'?
+When 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')`.
+
+```js
+// pause all shortcuts in the active context
+short.pause () // will stop all shortcuts in the active context
+short.resume ( 'shift+a' ) // will resume only 'shift+a' shortcut
+
+short.resume ('*') // will resume all shortcuts
+```
+
+
+
+## Options
+
+By `options` you can customize the behavior of the shortcuts. Here is the list of available options:
+
+```js
+  mouseWait     : 'Timeout for entering multiple mouse events. Default value - 320.'
+, keyWait       : 'Timeout for entering shortcut sequence in ms. Default value - 480'
+, clickTarget   : 'Data attribute name to recognize click items in HTML. Default value - click' // data attribute 'click' means attribute ( data-click='someName' )
+, listenFor     : `List input signal sources. Default value - [ 'mouse', 'keyboard' ]`
+, onShortcut    : 'False or a callback function that is called when a shortcut is triggered. Default value - false'
+, streamKeys    : 'False or a callback function that is called when a key is pressed. Default value - false'
+```
+
+You can request default list of options with their default values:
+
+```js
+shortcuts.getDefaults ()
+// Note: This method is availalble on the original shortcuts object, not on the shortcuts instance.
+
+// start a shortcuts with default options
+const short = shortcuts ()
+const short = shortcuts ( shortcuts.getDefaults () ) // same as above
+// The idea behind getDefaults is to see what options are available and what are their default values.
+```
+
+
+
+### onShortcut option
+```js
+ function onShortcut ({ shortcut, context, note, dependencies }) {
+        // shortcut - (string) Triggered shortcut name
+        // context - (string) Name of the current context
+        // note - (string) Name of the note or null if note isn't set
+        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
+    }
+```
+
+
+
+### streamKeys option
+```js
+ function streamKeys ({ key, context, note, dependencies }) {
+        // key - (string) Pressed key name
+        // context - (string) Name of the current context
+        // note - (string) Name of the note or null if note isn't set
+        // dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
+    }
+```
+
+
+
+## Links
+
+- [History of changes](https://github.com/PeterNaydenov/shortcuts/blob/main/Changelog.md)
+- [Migration guide](https://github.com/PeterNaydenov/shortcuts/blob/main/Migration.guide.md)
+
+
+
+## Credits
+'@peter.naydenov/shortcuts' was created and supported by Peter Naydenov.
+
+
+
+## License
+'@peter.naydenov/shortcuts' is released under the MIT License.