@peter.naydenov/shortcuts 3.4.0 → 3.5.0

package/src/main.js

@@ -1,19 +1,52 @@
 'use strict'
 
 /**
- *  Shortcuts
- *  ========
- * 
- *  Create shortcuts for your web application based on keyboard and mouse and DOM events.
- *  Repository: https://github.com/PeterNaydenov/shortcuts
- * 
- *  History notes:
- *  - Development was started on June 21st, 2023
- *  - First version was published on August 14th, 2023
- *  - Method 'emit' was added on September 30st, 2023
- *  - Version 2.0.0 was published on October 16th, 2023
- *  - Version 3.0.0. Plugin system. Published on March 5th, 2024
- *  - Version 3.2.0. Added plugin 'form'. Published on August 15th, 2025
+ * @typedef {Object} PluginAPI
+ * @property {function(): string} getPrefix - Get plugin prefix
+ * @property {function(string): string} shortcutName - Format shortcut name
+ * @property {function(string): void} contextChange - Handle context change
+ * @property {function(): void} mute - Mute the plugin
+ * @property {function(): void} unmute - Unmute the plugin
+ * @property {function(): void} destroy - Destroy the plugin
+ */
+
+/**
+ * @typedef {Object} ShortcutsAPI
+ * @property {function(function, Object): void} enablePlugin - Enable a plugin
+ * @property {function(string): void} disablePlugin - Disable a plugin
+ * @property {function(string): number} mutePlugin - Mute a plugin
+ * @property {function(string): number} unmutePlugin - Unmute a plugin
+ * @property {function(): string[]} listPlugins - List enabled plugins
+ * @property {function(): string|null} getContext - Get current context name
+ * @property {function(): string|null} getNote - Get current context note
+ * @property {function(string|null): void} setNote - Set current context note
+ * @property {function(string): void} pause - Pause shortcuts in current context
+ * @property {function(string): void} resume - Resume shortcuts in current context
+ * @property {function(string, ...any): void} emit - Emit event for shortcut
+ * @property {function(): string[]} listContexts - List all context names
+ * @property {function(Object): void} setDependencies - Set external dependencies
+ * @property {function(): Object} getDependencies - Get external dependencies
+ * @property {function(): void} reset - Reset the library instance
+ * @property {function(string|boolean): void} changeContext - Change current context
+ * @property {function(string|null): string[]|Object[]} listShortcuts - List shortcuts
+ * @property {function(Object): void} load - Load shortcuts into contexts
+ * @property {function(string): void} unload - Unload a context
+ */
+
+/**
+ * Shortcuts
+ * =========
+ *
+ * Create shortcuts for your web application based on keyboard and mouse and DOM events.
+ * Repository: https://github.com/PeterNaydenov/shortcuts
+ *
+ * History notes:
+ * - Development was started on June 21st, 2023
+ * - First version was published on August 14th, 2023
+ * - Method 'emit' was added on September 30st, 2023
+ * - Version 2.0.0 was published on October 16th, 2023
+ * - Version 3.0.0. Plugin system. Published on March 5th, 2024
+ * - Version 3.2.0. Added plugin 'form'. Published on August 15th, 2025
  */
 
 
@@ -30,6 +63,14 @@ import pluginForm from './plugins/form/index.js'
 
 
 
+/**
+ * @function shortcuts
+ * @description Create a shortcuts instance
+ * @param {Object} [options={}] - Configuration options
+ * @param {function} [options.onShortcut] - Function to log shortcut events
+ * @param {string} [options.errorEventName='@shortcuts-error'] - Name for error events
+ * @returns {ShortcutsAPI} The shortcuts API
+ */
 function main ( options = {} ) {
     let  
           inAPI = {}      // API for internal methods
@@ -38,10 +79,11 @@ function main ( options = {} ) {
     const
           ev = notice ()  // Event emitter instance
         , state = {
-                      currentContext : { name: null, note: null } // Context data container
-                    , shortcuts      : {}   // shortcuts = { contextName : { shortcut :  callback[] } }
-                    , plugins        : [] // Array of active plugins
-                    , exposeShortcut : (options.onShortcut && ( typeof options.onShortcut === 'function')) ? options.onShortcut : false   // Keyboard shortcut log function
+                      currentContext   : { name: null, note: null } // Context data container
+                    , shortcuts        : {}   // shortcuts = { contextName : { shortcut :  callback[] } }
+                    , plugins          : [] // Array of active plugins
+                    , exposeShortcut   : (options.onShortcut && ( typeof options.onShortcut === 'function')) ? options.onShortcut : false   // Keyboard shortcut log function
+                    , ERROR_EVENT_NAME : ( options.errorEventName ) ? options.errorEventName : '@shortcuts-error'
               } // state
         ;
     let dependencies = { 
@@ -60,16 +102,20 @@ function main ( options = {} ) {
      * @returns {void}
      */
     API.enablePlugin = ( plugin, options={}) => {
+                if ( typeof plugin !== 'function' ) return
+                let plugApp = plugin ( dependencies, state, options )
                 const 
-                      name = plugin.name.replace ( 'plugin', '' ).toLowerCase ()
+                      name = plugApp.getPrefix ()
                     , ix = inAPI._systemAction ( name, 'none' )
                     ;
 
                 if ( ix === -1 ) {   // If plugin is not registered
                             // Started instance of the plugin
-                            let plugApp = plugin ( dependencies, state, options )
                             state.plugins.push ( plugApp )
                     }
+                else {
+                            plugApp.destroy ()
+                    }
       } // enable func.
 
 
@@ -100,8 +146,15 @@ function main ( options = {} ) {
     API.unmutePlugin = pluginName => inAPI._systemAction ( pluginName, 'unmute' )
 
 
-    
+    /**
+     * @function listPlugins
+     * @description List all enabled plugins
+     * @returns {string[]} - Array of plugin names
+     */
+    API.listPlugins = () => state.plugins.map ( plugin => plugin.getPrefix() )
+
 
+    
     // ----------------------  > PUBLIC METHODS < ---------------------- //
     /**
      * @function getContext
@@ -208,6 +261,7 @@ function main ( options = {} ) {
 
 
 
+/** @type {function} */
 export { main as shortcuts }
 export { 
             pluginKey

package/src/methods/changeContext.js

@@ -5,6 +5,7 @@ const
           { 
                 shortcuts
               , currentContext
+              , ERROR_EVENT_NAME
           } = state
         , { ev } = dependencies
         ;
@@ -37,7 +38,7 @@ return function changeContext ( contextName = false ) {
                 }
         if ( current === contextName ) return   // Do nothing if contextName is the same as current
         if ( !shortcuts [ contextName ] ) {   // If contextName is not defined
-                        ev.emit ( '@shortcuts-error', `Context '${ contextName }' does not exist` )
+                        ev.emit ( ERROR_EVENT_NAME, `Context '${ contextName }' does not exist` )
                         return
                 }
         if ( shortcuts[current] ) {

package/src/methods/load.js

@@ -7,9 +7,10 @@ const
                 API : { changeContext, getContext }
           } = dependencies;
 /**
- *  Load a context with shortcuts object
- *  @param {Object} shortcutsUpdate - Context description object: { contextName : { shortcut : callback[] }
- *  @returns {void}
+ * @function load
+ * @description Load a context with shortcuts object
+ * @param {Object} shortcutsUpdate - Context description object: { contextName : { shortcut : callback[] } }
+ * @returns {void}
  */
 return function load ( shortcutsUpdate ) {
     const

package/src/methods/unload.js

@@ -2,7 +2,7 @@
 
 function unload ( dependencies, state ) {
 const 
-     { currentContext, shortcuts } = state
+     { currentContext, shortcuts, ERROR_EVENT_NAME } = state
    , { ev } = dependencies
    ;
 /**
@@ -14,11 +14,11 @@ const
 return function unload ( contextName ) {
         const current = currentContext.name;
         if ( current === contextName ) {
-                    ev.emit ( 'shortcuts-error', `Context '${ contextName }' can't be removed during is current active context. Change the context first` )
+                    ev.emit ( ERROR_EVENT_NAME, `Context '${ contextName }' can't be removed during is current active context. Change the context first` )
                     return
             }
         if ( !shortcuts [ contextName ] ) {
-                    ev.emit ( 'shortcuts-error', `Context '${ contextName }' does not exist` )
+                    ev.emit ( ERROR_EVENT_NAME, `Context '${ contextName }' does not exist` )
                     return
             }
         delete shortcuts [ contextName ]

package/src/plugins/click/_listenDOM.js

@@ -38,7 +38,7 @@ function _listenDOM ( dependencies, state ) {
                         ev.emit ( mouseEvent, data )
                         // Reset:
                         mouseTimer = null
-                        mouseIgnore = null
+                        mouseIgnore = null  // Timeout timer or null. Ignore mouse clicks until timer expires
                         mouseTarget = null
                         mouseDomEvent = null
                         count = 0

package/src/plugins/click/index.js

@@ -9,6 +9,16 @@ import _registerShortcutEvents from "./_registerShortcutEvents"
 
 
 
+/**
+ * @function pluginClick
+ * @description Plugin for mouse click shortcuts
+ * @param {Object} dependencies - Internal dependencies
+ * @param {Object} state - Library state
+ * @param {Object} [options={}] - Plugin options
+ * @param {number} [options.mouseWait=320] - Time to wait for click sequence in ms
+ * @param {string} [options.clickTarget='click'] - Data attribute name for click targets
+ * @returns {PluginAPI} Plugin API
+ */
 function pluginClick ( dependencies, state, options ) {
         let 
                   { currentContext, shortcuts } = state

package/src/plugins/form/index.js

@@ -8,20 +8,15 @@ import _defaults from './_defaults.js'
 
 
 
+/**
+ * @function pluginForm
+ * @description Plugin for form element shortcuts
+ * @param {Object} dependencies - Internal dependencies
+ * @param {Object} state - Library state
+ * @param {Object} [options={}] - Plugin options
+ * @returns {PluginAPI} Plugin API
+ */
 function pluginForm ( dependencies, state, options ) {
-  /**
-   * 'form: watch' - A function. Should return a string. Define a selection that will be watched for changes. example: 'input, select.color, textarea, #name'
-   * 'form: define' - A function that receives every watched element. Should return text value that represents the type of the
-   *                  element according custom specification. Types could be specific for every single form.
-   * 'form:action' - List of Callback objects.
-   *  Callback definition object:
-   * {
-   *   fn: function to be called
-   *   type: fn should be executed on type of the element
-   *   timing: 'in' | 'out' | 'instant' - when to execute the function 
-   *   wait: time in milliseconds to wait before executing the function again. Works only with mode 'instant'.
-   * }
-   */
 
     let 
                   { currentContext, shortcuts } = state

package/src/plugins/key/index.js

@@ -9,6 +9,16 @@ import _specialChars           from './_specialChars.js'
 
 
 
+/**
+ * @function pluginKey
+ * @description Plugin for keyboard shortcuts
+ * @param {Object} dependencies - Internal dependencies
+ * @param {Object} state - Library state
+ * @param {Object} [options={}] - Plugin options
+ * @param {number} [options.keyWait=480] - Time to wait for key sequence in ms
+ * @param {function} [options.streamKeys] - Function to stream key presses
+ * @returns {PluginAPI} Plugin API
+ */
 function pluginKey ( dependencies, state, options={} ) {
         let 
                   { currentContext, shortcuts, exposeShortcut } = state

package/test/01-general.test.js

@@ -37,7 +37,8 @@ const contextDefinition = {
                             ' key : shift+a': [ 
                                         () => a = true, 
                                         () => c = 'triggered' 
-                                      ]
+                                      ],
+                            '@shortcuts-error' : ( m ) =>  c = m
                         }
                 , touch : {
                               // Single click with left button
@@ -88,6 +89,64 @@ describe ( "Shortcuts", () => {
             }) // afterEach
 
 
+
+        it ( 'Load and unload context', async () => {
+                      let ls = short.listContexts ()
+                      expect ( ls ).to.includes ( 'general' )
+
+                      short.changeContext ( 'general' )
+                      // Can't not to unload current active context - sends an error on @shortcuts-error
+                      // @shortcuts-error is a system error event used accross the library
+                      short.unload ( 'general' )
+                      expect ( c ).to.be.equal ( `Context 'general' can't be removed during is current active context. Change the context first` )
+                      
+                      // Try to change context to non-existent one
+                      // Message goes to @shortcuts-error                   
+                      short.changeContext ( 'hhm' )
+                      expect ( c ).to.be.equal ( `Context 'hhm' does not exist` )
+
+                      // Change to something that exists
+                      short.changeContext ( 'extra' )
+                      // Free to unload 'general'
+                      short.unload ( 'general' )
+                      ls = short.listContexts ()
+                      // Unload success
+                      expect ( ls ).to.not.includes ( 'general' )
+            }) // it load and unload context
+
+
+        
+        it ( 'List enabled plugins. Disable and enable plugins', async () => {
+                     expect ( short.listPlugins () ).to.be.deep.equal ( [] )
+                     // Enable list of plugins
+                     let myPlugins = [ pluginKey, pluginClick ]
+                     myPlugins.forEach ( plugin =>  short.enablePlugin ( plugin )   )
+                     expect ( short.listPlugins () ).to.be.deep.equal ( [ 'key', 'click' ] )
+                     // Method disablePlugin require plugin name (prefix)
+                     short.disablePlugin ( 'click' )
+                     expect ( short.listPlugins () ).to.be.deep.equal ( [ 'key' ] )
+                     // Method enablePlugin require the plugin as a function
+                     short.enablePlugin ( pluginClick )
+                     expect ( short.listPlugins () ).to.be.deep.equal ( [ 'key', 'click' ] )
+            }) // it list enabled plugins
+
+
+
+        it ( 'Unload non existing context', () => {
+                      let change = false;
+                      let ls = short.listContexts ()
+                      short.load ( {
+                              local : {
+                                      'click : leff-1' : () => console.log ( 'nothing' ),
+                                      '@shortcuts-error': () => change = true
+                                  }
+                          })
+                      short.changeContext ( 'local' )
+                      short.unload ( 'unknown' )
+                      expect ( change ).to.be.true
+            }) // it unload non existing context
+        
+        
         
         it ( 'Emit custom event', () => {
                             // TODO: Check arguments for the custom event handlers
@@ -113,8 +172,8 @@ describe ( "Shortcuts", () => {
 
                       let general =  short.listShortcuts ('general');
                       expect ( general ).to.be.an ( 'array' )
-                      expect ( general ).to.have.lengthOf ( 1 )
-                      expect ( general[0] ).to.be.equal ( 'KEY:A+SHIFT' )
+                      expect ( general ).to.have.lengthOf ( 2 )
+                      expect ( general ).to.include ( 'KEY:A+SHIFT' )
                       
                       let fail = short.listShortcuts ( 'somethingNotExisting' );
                       expect ( fail ).to.be.null
@@ -127,8 +186,8 @@ describe ( "Shortcuts", () => {
                       expect ( all[0] ).to.have.property ( 'context' )
                       expect ( all[0] ).to.have.property ( 'shortcuts' )
                       expect ( all[0].shortcuts ).to.be.an ( 'array' )
-                      expect ( all[0].shortcuts ).to.have.lengthOf ( 1 )
-                      expect ( all[0].shortcuts[0] ).to.be.equal ( 'KEY:A+SHIFT' )
+                      expect ( all[0].shortcuts ).to.have.lengthOf ( 2 )
+                      expect ( all[0].shortcuts ).to.include ( 'KEY:A+SHIFT' )
                       expect ( all[0].context ).to.be.equal ( 'general' )
             }) // it list shortcuts
 

package/test/02-key.test.js

@@ -47,9 +47,9 @@ const contextDefinition = {
                               // Single click with right button
                               'click: right-1': () => b = true
                         }
-                , extra : {    
-                            'key : p,r,o,b,a': () => b = true                        
-                        }
+                 , extra : {
+                             'key : p,r,o,b,a': () => b = true
+                         }
                 , extend : {
                               'form : watch' : () => 'input'
                             , 'form : define' : () => 'input'
@@ -121,54 +121,152 @@ describe ( 'Key plugin', () => {
 
 
 
-    it ( 'Key sequence', async () => {
-                      // enable key plugin and normalize shortcuts related to the plugin 'key'
+     it ( 'Key sequence', async () => {
+                       // enable key plugin and normalize shortcuts related to the plugin 'key'
                       short.enablePlugin ( pluginKey )
                       short.changeContext ( 'extra' )
                       // Execute key sequence: 'p,r,o,b,a'
                       await userEvent.keyboard ( 'proba' )
-                      await wait ( 12 )
+                      await wait ( 480 )
                       await waitFor ( () => {
                                 expect ( b ).to.equal ( true )
                       }, { timeout: 1000, interval: 12 })
-        }) // it key sequence
+         }) // it key sequence
+
+
+
+
+    it ( 'Mute and unmute key plugin', async () => {
+                const result = [];
+                let i = 0;
+                result.push ( 'init' )
 
+                short.enablePlugin ( pluginKey )
+                short.setDependencies ({ result })
+                short.load ({
+                      'local': {
+                                  'key: x,y,z' : ({ dependencies }) => {
+                                                    let { result } = dependencies;
+                                                    result.push ( i++ )
+                                                }
+                                }
+                        })
+
+                short.changeContext ( 'local' )
+
+                // Test 1: Plugin should work normally
+                await userEvent.keyboard ( 'xyz' )
+                await waitFor ( () => {
+                          // We checking if the shortcut works
+                          expect ( result ).to.have.lengthOf ( 2 )
+                          expect ( i ).to.equal ( 1 )
+                    }, { timeout: 1000, interval: 12 })
+
+                // Test 2: Mute plugin - should not trigger
+                short.mutePlugin ( 'key' )
+                await userEvent.keyboard ( 'xyz' )
+                await waitFor ( () => {
+                          // Plugin is muted, so we don't expect any changes
+                          expect ( result ).to.have.lengthOf ( 2 )
+                          expect ( i ).to.equal ( 1 )
+                    }, { timeout: 1000, interval: 12 })
+
+                // Test 3: Unmute plugin - should work again
+                short.unmutePlugin ( 'key' )
+                await userEvent.keyboard ( 'xyz' )
+                await waitFor ( () => {
+                          // Plugin is unmuted, should work again
+                          expect ( result ).to.have.lengthOf ( 3 )
+                          expect ( i ).to.equal ( 2 )
+                    }, { timeout: 1000, interval: 12 })
+          }) // it mute and unmute key plugin
+
+
+
+    it ( 'Arguments of key handler', async () => {
+                /**
+                *    Need to know arguments for 'key' handler
+                *    function myKeyHandler ({
+                *                         wait        // (function). Function to pause key sequence processing
+                *                       , end         // (function). Function to end key sequence processing
+                *                       , ignore      // (function). Function to ignore current key in sequence
+                *                       , isWaiting   // (function). Check if sequence is waiting
+                *                       , note        // (string). Current context note or null
+                *                       , context     // (string). Current context name
+                *                       , dependencies // (object). External dependencies object
+                *                       , type        // (string). Event type ('key')
+                *                  }) {
+                *            // Body of the handler. Do something...
+                *       }
+                */
+                let test = [];
+                let i = 0;
+                short.enablePlugin ( pluginKey )
+                short.setDependencies ({ test })
+                short.load ({
+                        'local' : {
+                              'key: a' : ({
+                                           wait
+                                         , end
+                                         , ignore
+                                         , isWaiting
+                                         , note
+                                         , context
+                                         , dependencies
+                                         , type
+                                       }) => {
+                                                const
+                                                    { test } = dependencies
+                                                  , result = {
+                                                                    wait: typeof wait
+                                                                  , end: typeof end
+                                                                  , ignore: typeof ignore
+                                                                  , isWaiting: typeof isWaiting
+                                                                  , note
+                                                                  , context
+                                                                  , type
+                                                              }
+                                                    ;
+                                                test.push ( result )
+                                                i++
+                                          }
+                            } // local
+                      })
+                short.changeContext ( 'local' )
+                await userEvent.keyboard ( 'a' )
+                await wait ( 50 )  // Wait for key processing
+                await waitFor ( () => {
+                            expect ( i ).to.be.equal ( 1 )
+                            let result = test[0];
+                            expect ( result.wait ).to.be.equal ( 'function' )
+                            expect ( result.end ).to.be.equal ( 'function' )
+                            expect ( result.ignore ).to.be.equal ( 'function' )
+                            expect ( result.isWaiting ).to.be.equal ( 'function' )
+                            expect ( result.context ).to.be.equal ( 'local' )
+                            expect ( result.type ).to.be.equal ( 'key' )
+                      }, { timeout: 1000, interval: 12 })
+          }) // it arguments of key handler
 
 
-    it ( 'Mute key plugin', async () => {
+     it ( 'Pause and resume', async () => {
                           short.enablePlugin ( pluginKey )
-                          const result = [];
-                          let i = 0;
-                          result.push ( 'init' )
-
-                          short.setDependencies ({ result })
-                          short.load ({
-                                'local': {
-                                        'key: g,t,i ' : ({dependencies}) => {
-                                                  let { result } = dependencies;
-                                                  result.push ( i++ )
-                                              }
-                                      }
-                              })
-                          
-                          short.changeContext ( 'local' )
-                          await userEvent.keyboard ( 'gti' )
+                          expect ( b ).to.be.equal ( false )
+                          short.changeContext ( 'extra' )
+                          // Shortcut name will be normalized by the plugin
+                          short.pause ( 'key : p,r,o,b,a' )
+                          // Execute key sequence: 'p,r,o,b,a'
+                          await userEvent.keyboard ( 'proba' )
+                          await wait ( 500 )
                           await waitFor ( () => {
-                                    // We checking if the shortcut works
-                                    expect ( result ).to.have.lengthOf ( 2 )
-                                    expect ( i ).to.equal ( 1 )
-                              }, { timeout: 1000, interval: 12 })
+                                      expect ( b ).to.be.equal ( false )
+                                }, { timeout: 1000, interval: 30 })
 
-                          short.mutePlugin ( 'key' )
-                          await userEvent.keyboard ( 'gti' )
+                          short.resume ( 'key : p,r,o,b,a' )
+                          await userEvent.keyboard ( 'proba' )
+                          await wait ( 500 )
                           await waitFor ( () => {
-                                    // Plugin is muted, so we don't expect any changes
-                                    expect ( result ).to.have.lengthOf ( 2 )
-                                    expect ( i ).to.equal ( 1 )
-                              }, { timeout: 1000, interval: 12 })
-        }) // it mute key plugin
-    
-    
-
+                                      expect ( b ).to.be.equal ( true )
+                               }, { timeout: 1000, interval: 30 })
+            }) // it pause and resume
 
 })