@peter.naydenov/shortcuts 3.5.2 → 4.0.1

package/src/plugins/click/_listenDOM.js

@@ -1,15 +1,36 @@
 'use strict'
 
 
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for click events
+ * @param {Object} dependencies - Dependencies object containing ev, _findTarget, _readClickEvent, extra, resetState
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ * 
+ * @typedef {Object} ClickEventData
+ * @property {Element} target - The DOM element that was clicked
+ * @property {number} x - X coordinate of the click event
+ * @property {number} y - Y coordinate of the click event
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * @property {Event} event - The original DOM event
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} viewport - Viewport information with X, Y, width, height
+ * @property {Object} sizes - Element dimensions with width, height
+ * @property {Object} position - Element position relative to viewport with x, y
+ * @property {Object} pagePosition - Element position relative to page with x, y
+ * @property {string} type - Event type ('click')
+ */
 function _listenDOM ( dependencies, state ) {
         const { 
                    ev
                 , _findTarget 
                 , _readClickEvent
-                , mainDependencies
+                , extra
                         } = dependencies
         const { listenOptions, currentContext } = state
-        const { mouseWait } = listenOptions
 
         let 
              mouseTarget = null // Dom element or null
@@ -20,17 +41,33 @@ function _listenDOM ( dependencies, state ) {
            ;
 
         function mouseSequenceEnd () {   // Execute when mouse sequence ends
+                        if ( !mouseTarget ) return  // No valid target found                        
                         const 
+                                { left, top, width, height } = mouseTarget.getBoundingClientRect ()
+                              , scrollX = window.scrollX
+                              , scrollY = window.scrollY
+                              ;
+                        
+                        const
                                   mouseEvent = _readClickEvent ( mouseDomEvent, count )
-                                , data = { 
+                                , data = {
                                           target : mouseTarget
-                                        , targetProps : mouseTarget ? mouseTarget.getBoundingClientRect() : null
                                         , x       : mouseDomEvent.clientX
                                         , y       : mouseDomEvent.clientY
                                         , context : currentContext.name
                                         , note    : currentContext.note
+                                        , options : state.listenOptions
                                         , event   : mouseDomEvent
-                                        , dependencies : mainDependencies.extra
+                                        , dependencies : extra
+                                        , viewport : {                                    // Viewport scroll positions and sizes
+                                                          X:scrollX
+                                                        , Y:scrollY 
+                                                        , width:window.innerWidth
+                                                        , height:window.innerHeight
+                                                }
+                                        , sizes    : { width, height }                     // Element sizes
+                                        , position : { x:left, y:top }                     // Position relative to viewport
+                                        , pagePosition : { x:left+scrollX, y:top+scrollY } // Position relative to page
                                         , type   : 'click'
                                 }
                                 ;
@@ -47,47 +84,49 @@ function _listenDOM ( dependencies, state ) {
 
 
         function listenLeftClick ( event ) {
-                        let targetMax = listenOptions.maxClicks;  // Maximum number of clicks per target
+                        let targetMax = state.maxLeftClicks;  // Maximum number of clicks per target
                         clearTimeout ( mouseTimer )
                         if ( mouseIgnore ) {
                                     clearTimeout ( mouseIgnore )
-                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, listenOptions.mouseWait )
                                     return
                             }
                         mouseTarget = _findTarget ( dependencies, state, event.target )
+                        if ( mouseTarget == null )   return
                         if ( mouseTarget && mouseTarget.dataset.hasOwnProperty('quickClick'))   targetMax = 1
                         if ( mouseTarget && mouseTarget.tagName === 'A'                     )   targetMax = 1
                         mouseDomEvent = event
                         count++
                         if ( count >= targetMax ) {
                                     mouseSequenceEnd ()
-                                    if ( targetMax > 1 )   mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                    if ( targetMax > 1 )   mouseIgnore = setTimeout ( () => mouseIgnore=null, listenOptions.mouseWait )
                                     return
                             }
-                        mouseTimer = setTimeout ( mouseSequenceEnd, mouseWait )
+                        mouseTimer = setTimeout ( mouseSequenceEnd, listenOptions.mouseWait )
             } // listenLeftClick func.
 
 
 
         function listenRightClick ( event ) {
-                        let targetMax = listenOptions.maxClicks;  // Maximum number of clicks per target
+                        let targetMax = state.maxRightClicks;  // Maximum number of clicks per target
                         clearTimeout ( mouseTimer )
                         if ( mouseIgnore ) {
                                     clearTimeout ( mouseIgnore )
-                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, listenOptions.mouseWait )
                                     return
                             }
                         mouseTarget = _findTarget ( dependencies, state, event.target )
+                        if ( mouseTarget == null )   return
                         if ( mouseTarget && mouseTarget.dataset.hasOwnProperty('quickClick'))   targetMax = 1
                         if ( mouseTarget && mouseTarget.tagName === 'A'                     )   targetMax = 1
                         mouseDomEvent = event
                         count++
-                        if ( count >= targetMax ) {  
+                        if ( count >= targetMax ) {
                                     mouseSequenceEnd ()
-                                    if ( targetMax > 1 )   mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                    if ( targetMax > 1 )   mouseIgnore = setTimeout ( () => mouseIgnore=null, listenOptions.mouseWait )
                                     return
                             }
-                        mouseTimer = setTimeout ( mouseSequenceEnd, mouseWait )
+                        mouseTimer = setTimeout ( mouseSequenceEnd, listenOptions.mouseWait )
             } // listenRightClick func.
 
 
@@ -105,15 +144,14 @@ function _listenDOM ( dependencies, state ) {
                         window.removeEventListener  ( 'contextmenu', listenRightClick )
                         document.removeEventListener ( 'click'      , listenLeftClick  )
                         state.active = false
-                        // Clear any pending timers to prevent state pollution between tests
-                        if ( mouseTimer ) {
-                                clearTimeout ( mouseTimer )
-                                mouseTimer = null
-                        }
+                        
                         if ( mouseIgnore ) {
                                 clearTimeout ( mouseIgnore )
                                 mouseIgnore = null
-                        }
+                            }
+                        // Reset all state variables to prevent pollution between tests
+                        mouseTarget = null
+                        mouseDomEvent = null
                         count = 0
                 } // stop func.
                 

package/src/plugins/click/_normalizeShortcutName.js

@@ -1,5 +1,11 @@
 'use strict'
 
+/**
+ * @function _normalizeShortcutName
+ * @description Normalize click shortcut name to standard format
+ * @param {string} name - Raw shortcut name
+ * @returns {string} - Normalized shortcut name
+ */
 function _normalizeShortcutName ( name ) {
             const 
                   upperCase = name.toUpperCase ()
@@ -10,15 +16,16 @@ function _normalizeShortcutName ( name ) {
                 ;   
             let
                   btn = null
-                , usedModifiers = []
                 , counter = 0
+                ; const usedModifiers = []
                 , sliceIndex = upperCase.indexOf ( ':' )
                 ;
 
             // Click event format: CLICK:LEFT-2-ALT-SHIFT-CTRL
 
-            if ( !isClickShortcut )   return name
-            let shortcutArray = upperCase.slice(sliceIndex+1).trim().split('-').map ( x => x.trim() );
+            if ( !isClickShortcut            )   return name
+            if ( upperCase.includes('SETUP') )   return 'CLICK:SETUP'
+            const shortcutArray = upperCase.slice(sliceIndex+1).trim().split('-').map ( x => x.trim() );
             shortcutArray.forEach ( item => {
                         if ( mouseNames.includes ( item )) { 
                                 btn = item
@@ -33,7 +40,7 @@ function _normalizeShortcutName ( name ) {
                                 return
                             }
                     }) // forEach
-                               
+                    
             return `CLICK:${btn}-${counter}${usedModifiers.length>0?'-':''}${usedModifiers.sort().join('-')}` 
 } // _normalizeShortcutName func.
 

package/src/plugins/click/_readClickEvent.js

@@ -1,7 +1,7 @@
 'use strict'
 
 function _readClickEvent ( event, count ) {
-    let
+    const
           { shiftKey, altKey, ctrlKey, key, button } = event
         , mouseNames = [ 'LEFT', 'MIDDLE', 'RIGHT' ]
         , mouseEvent = `CLICK:${mouseNames[button]}-${count}`

package/src/plugins/click/_registerShortcutEvents.js

@@ -1,7 +1,21 @@
 'use strict'
 
+/**
+ * @function _registerShortcutEvents
+ * @description Register click shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex
+ * @param {Object} pluginState - Plugin state containing listenOptions, currentContext, shortcuts, etc.
+ * @returns {number} - Number of registered shortcuts
+ * 
+ * @typedef {Object} ClickSetupData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} defaults - Default options (clone of pluginState.defaultOptions)
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ */
 function _registerShortcutEvents ( dependencies, pluginState ) {
 let count = 0;
+let hasSetup = false;
+const df = pluginState.defaultOptions;
 const 
           { regex } = dependencies
         , { 
@@ -11,15 +25,29 @@ const
             } = pluginState
         ;
 
-if ( contextName == null )   return 0
+if ( contextName == null )   return count
 Object.entries ( shortcuts[contextName] ).forEach ( ([shortcutName, list ]) => {   // Enable new context shortcuts and set a listenOptions 'maxSequence'      
-                let isClickEv = regex.test ( shortcutName );
+                const isClickEv = regex.test ( shortcutName );
                 if ( !isClickEv ) return
+                if ( shortcutName === 'CLICK:SETUP' ) {
+                                hasSetup = true
+                                const updateOptions = list.reduce ( ( res, fn ) => {
+                                                const r = fn ({ 
+                                                                dependencies : dependencies.extra, 
+                                                                defaults     : structuredClone(pluginState.defaultOptions),
+                                                                options      : listenOptions 
+                                                        })
+                                                return Object.assign ( res, r )
+                                        }, df )
+                                Object.assign ( pluginState.listenOptions, updateOptions )
+                                return
+                    }
                 count++
-                
-                let [ ,numberClicks ] = shortcutName.slice(6).split('-');
-                if ( listenOptions.maxClicks < numberClicks )   listenOptions.maxClicks = numberClicks
+                const [ button,numberClicks ] = shortcutName.slice(6).split('-');
+                if ( button === 'LEFT'  && pluginState.maxLeftClicks < numberClicks  )   pluginState.maxLeftClicks = numberClicks
+                if ( button === 'RIGHT' && pluginState.maxRightClicks < numberClicks )   pluginState.maxRightClicks = numberClicks
         })
+if ( !hasSetup )   Object.assign ( pluginState.listenOptions, df )
 return count
 } // _registerShortcutEvents func.
 

package/src/plugins/click/index.js

@@ -1,14 +1,6 @@
 'use strict'
 
-/**
- * @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
- */
+
 
 import _findTarget              from "./_findTarget"
 import _listenDOM              from "./_listenDOM"
@@ -22,69 +14,50 @@ import _registerShortcutEvents from "./_registerShortcutEvents"
 /**
  * @function pluginClick
  * @description Plugin for mouse click shortcuts
- * @param {Object} dependencies - Internal dependencies
- * @param {Object} state - Library state
+ * @param {function} setupPlugin - Plugin setup function from the library
  * @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
+ * @param {string[]} [options.clickTarget=['data-click', 'href']] - Array of attribute names for click targets
+ * @param {function} [options.streamKeys] - Function to stream key presses
  * @returns {PluginAPI} Plugin API
  */
-function pluginClick ( dependencies, state, options ) {
-        let 
-                  { currentContext, shortcuts } = state
-                , { inAPI } = dependencies
-                , deps = {
-                                ev: dependencies.ev
-                             , _findTarget
+function pluginClick ( setupPlugin, options = {}) {
+        const 
+                  deps = {
+                                _findTarget
                              , _readClickEvent
-                             , mainDependencies : dependencies
                              , regex : /CLICK\s*\:/i
                         }
                 , pluginState = {
-                                  currentContext
-                                , active : false
-                                , shortcuts
+                                  active : false
+                                , maxLeftClicks : 1  // How many clicks can be pressed in a sequence. Controlled automatically by '_registerShortcutEvents' function.
+                                , maxRightClicks: 1  // How many right clicks can be pressed in a sequence. Controlled automatically by '_registerShortcutEvents' function.
+                                , defaultOptions : {
+                                          mouseWait   : 320     // 320 ms
+                                        , clickTarget : ['data-click', 'href' ]   // Attribute names as click targets
+                                    }
                                 , listenOptions  : {
-                                                      mouseWait     : options.mouseWait ? options.mouseWait : 320   // 320 ms
-                                                    , maxClicks     : 1  // How many clicks can be pressed in a sequence. Controlled automatically by '_registerShortcutEvents' function.
-                                                    , clickTarget   : options.clickTarget ? options.clickTarget :  'click' // Data-attribute name for click target ( data-click )
+                                                      mouseWait     : 320   // 320 ms
+                                                    , clickTarget   : [ 'data-click', 'href' ]  // Attribute names as click targets
                                                 }
+                                , streamKeys     : (options.streamKeys && ( typeof options.streamKeys === 'function')) ? options.streamKeys : false   // Keyboard stream function
                             } // pluginState
-                ; 
+                ;
 
-        // Read shortcuts names from all context entities and normalize entries related to the plugin
-        inAPI._normalizeWithPlugins ( _normalizeShortcutName )
-        
-        let 
-             mouseListener = _listenDOM ( deps, pluginState )
-           , countShortcuts = _registerShortcutEvents ( deps, pluginState )
-           ;
-      
-        if ( countShortcuts > 0 )   mouseListener.start ()
-       
-        let pluginAPI = {
-                               getPrefix      : () => 'click'
-                             , shortcutName  : key => {   // Format a key string according plugin needs
-                                                        return _normalizeShortcutName ( key )
-                                                }
-                             , contextChange : () => {
-                                                countShortcuts = _registerShortcutEvents ( deps, pluginState )
-                                                if ( countShortcuts < 1 ) {  // Remove DOM listener if there are no shortcuts in the current context
-                                                                mouseListener.stop ()
-                                                    } 
-                                                if ( countShortcuts > 0 ) {  // Add DOM listener if there are shortcuts in the current context
-                                                                mouseListener.start ()
-                                                    }
-                                        }
-                            , mute    : () => {
-                                          
-                                          mouseListener.stop ()
-                                      }
-                            , unmute  : () => mouseListener.start ()
-                            , destroy : () => mouseListener.stop ()
-                        }; // pluginAPI
-        Object.freeze ( pluginAPI )
-        return pluginAPI
+        function resetState () {
+                  // TODO: No reset available at the moment
+            } // resetState func.
+        deps.resetState = resetState
+                
+        return setupPlugin ({
+                                prefix: 'click'
+                              , _normalizeShortcutName
+                              , _registerShortcutEvents
+                              , _listenDOM
+
+                              , pluginState
+                              , deps
+                      })
 } // pluginClick func.
 
 

package/src/plugins/form/_defaults.js

@@ -1,10 +1,20 @@
+/**
+ * @typedef {Object} _defaults
+ * @property {function} watch - Function that returns CSS selector for form elements to watch
+ * @property {function} define - Function that determines the type of form element
+ */
+
+/**
+ * @const {_defaults}
+ * @description Default configuration for form plugin
+ */
 const _defaults = {
       watch : () => 'input, select, textarea, button, a'
-    , define: (el) => {
-            if ( el.type === 'checkbox' || el.type === 'radio' ) {
+    , define: ({ target }) => {
+            if ( target.type === 'checkbox' || target.type === 'radio' ) {
                     return 'checkbox'
                 }
-            if ( el.type == 'button' || el.type=='submit' ) {
+            if ( target.type == 'button' || target.type=='submit' ) {
                     return 'button'
                 }
             return 'input'

package/src/plugins/form/_listenDOM.js

@@ -2,18 +2,52 @@
 
 
 
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for form events
+ * @param {Object} dependencies - Dependencies object containing ev
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ * 
+ * @typedef {Object} FormEventData
+ * @property {Element} target - The DOM element that triggered the form event
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Event} event - The original DOM event
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * @property {Object} viewport - Viewport information with X, Y, width, height
+ * @property {Object} sizes - Element dimensions with width, height
+ * @property {Object} position - Element position relative to viewport with x, y
+ * @property {Object} pagePosition - Element position relative to page with x, y
+ * @property {string} type - Event type ('form-in', 'form-out', 'form-instant')
+ */
 function _listenDOM ( dependencies, state ) {
         const { ev } = dependencies;
         let timeout = null; 
 
         function setupData ( dependencies, state, event, type) {
+                const 
+                      { left, top, width, height } = event.target.getBoundingClientRect ()
+                    , scrollX = window.scrollX
+                    , scrollY = window.scrollY
+                    ;
                 return {
                           target : event.target
-                          // TODO: Find if is possible to add some size and positioning data
                         , context : state.currentContext.name
                         , note    : state.currentContext.note
                         , event   
-                        , dependencies : dependencies.mainDependencies.extra
+                        , dependencies : dependencies.extra
+                        , options : state.listenOptions
+                        , viewport : {                                     // Viewport scroll positions and sizes
+                                  X:scrollX
+                                , Y:scrollY 
+                                , width:window.innerWidth
+                                , height:window.innerHeight
+                            }
+                        , sizes : { width, height }                        // Element sizes
+                        , position : { x:left, y:top }                     // Position relative to viewport
+                        , pagePosition : { x:left+scrollX, y:top+scrollY } // Position relative to page
                         , type
                     }
         } // setupData func.
@@ -22,8 +56,8 @@ function _listenDOM ( dependencies, state ) {
                 const 
                       { callbacks, typeFn } = state
                     , target = event.target
-                    , type = typeFn ( target )
-                    , prop = setupData ( dependencies, state, event, type )
+                    , prop = setupData ( dependencies, state, event, "form-in" )
+                    , type = typeFn ( prop )
                     , key = `${type}/in`
                     ;
                 if ( callbacks[key] == null )  return
@@ -34,8 +68,7 @@ function _listenDOM ( dependencies, state ) {
                 const
                       { callbacks, typeFn } = state
                     , prop   = setupData ( dependencies, state, event, "form-out" )
-                    , target = event.target
-                    , type   = typeFn ( target )
+                    , type   = typeFn ( prop )
                     , key    = `${type}/out`
                     ;
                 if ( callbacks[key] == null )  return
@@ -47,8 +80,7 @@ function _listenDOM ( dependencies, state ) {
                 const 
                       { callbacks, typeFn } = state
                     , prop   = setupData ( dependencies, state, event, "form-instant" )
-                    , target = event.target
-                    , type   = typeFn ( target )
+                    , type   = typeFn ( prop )
                     , wait   = state.wait[`${type}`]
                     , key    = `${type}/instant`
                     ;
@@ -57,7 +89,7 @@ function _listenDOM ( dependencies, state ) {
                         ev.emit ( key, prop, callbacks[key] )
                         return
                     }
-                let fn = () => ev.emit ( key, prop, callbacks[key] )
+                const fn = () => ev.emit ( key, prop, callbacks[key] )
                 clearTimeout ( timeout )
                 timeout = setTimeout ( fn, wait )
             } // input func.
@@ -78,6 +110,11 @@ function _listenDOM ( dependencies, state ) {
                 document.removeEventListener ( 'focusout', listenFocusOut );
                 document.removeEventListener ( 'input', listenInput );
                 state.active = false
+                // Clear any pending timeout to prevent state pollution between tests
+                if ( timeout ) {
+                        clearTimeout ( timeout )
+                        timeout = null
+                }
             } // stop func.
 
         return { start, stop }

package/src/plugins/form/_normalizeShortcutName.js

@@ -9,9 +9,9 @@ function _normalizeShortcutName ( name ) {
                 ;
 
             if ( !isKeyboardShortcut )   return name
-            let shortcut = upperCase.slice(sliceIndex+1).trim ()
+            const shortcut = upperCase.slice(sliceIndex+1).trim ()
                               
-            return `FORM:${shortcut}`   
+            return `FORM:${shortcut}`
 } // _normalizeShortcutName func.