@peter.naydenov/shortcuts 3.5.1 → 4.0.0

package/src/plugins/key/_listenDOM.js

@@ -2,28 +2,45 @@
 
 
 
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for keyboard events
+ * @param {Object} dependencies - Dependencies object containing ev, _specialChars, _readKeyEvent, extra, resetState
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ * 
+ * @typedef {Object} KeyEventData
+ * @property {Function} wait - Function to wait for keys (disables key sequence)
+ * @property {Function} end - Function to end waiting for keys (enables key sequence)
+ * @property {Function} ignore - Function to ignore the last key in sequence
+ * @property {Function} isWaiting - Function to check if currently waiting for keys
+ * @property {string|null} note - Current context note
+ * @property {string} context - Current context name
+ * @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 {string} type - Event type ('key')
+ */
 function _listenDOM ( dependencies, state ) {
-// Listen for input signals and generate event titles  
+// Listen for input signals and generate event titles
     const { 
-                ev
+                  ev
                 , _specialChars
                 , _readKeyEvent
-                , mainDependencies
+                , extra
+                , resetState
             } = dependencies
         , {
                   currentContext
                 , streamKeys
                 , listenOptions
             } = state
-        , {
-                  keyWait
-            } = listenOptions
         ;
     
     let 
           r = []
         , keyTimer = null    // Timer for key sequence or null
-        , sequence = true
+        , sequence = true    // Is false only when time limitter is off - waitKeys ()
         , ignore   = false   // Use to trigger a single callback without adding the key to the sequence.
         ;
 
@@ -39,7 +56,8 @@ function _listenDOM ( dependencies, state ) {
 
 
     function keySequenceEnd () {   // Execute when key sequence ends
-                    let res =  r.map ( x => ([x.join('+')])   )
+                    const res =  r.map ( x => ([x.join('+')])   )
+                    
                     const data = {
                                       wait: waitKeys
                                     , end:endKeys
@@ -47,23 +65,38 @@ function _listenDOM ( dependencies, state ) {
                                     , isWaiting:waitingKeys
                                     , note: currentContext.note
                                     , context: currentContext.name
-                                    , dependencies : mainDependencies.extra
+                                    , dependencies : extra
+                                    , options : state.listenOptions
+                                    , viewport : { 
+                                              X : window.scrollX
+                                            , Y : window.scrollY
+                                            , width:window.innerWidth
+                                            , height:window.innerHeight 
+                                        }
                                     , type : 'key'
                             };
+
                     if ( !sequence ) {
-                            let signal = res.at(-1);
-                            ev.emit ( signal, data )    
-                            if ( ignore ) {
-                                        res = res.slice ( 0, -1 )
-                                        ignore = false
-                                }
+                             const signal = `KEY:${res.at(-1).join('+')}`;
+                             ev.emit ( signal, data )
+                             if ( ignore ) {
+                                         r = r.slice ( 0, -1 )
+                                         ignore = false
+                                 }
                         }
                             
                     if ( sequence ) {
                             const signal = `KEY:${res.join(',')}`
                             ev.emit ( signal, data )
+                            if ( ignore ) {
+                                         r = r.slice ( 0, -1 )
+                                         ignore = false
+                                 }
                             // Reset:
                             r = []
+                            clearTimeout ( state.keyIgnore )
+                            state.keyIgnore = null
+                            clearTimeout ( keyTimer )
                             keyTimer = null
                         }
         } // keySequeceEnd func.
@@ -72,42 +105,43 @@ function _listenDOM ( dependencies, state ) {
     
     function listenForSpecialKeys ( event ) { // Listen for special keyboard keys
                 clearTimeout ( keyTimer )
-                let _sp = _specialChars ()
+                const _sp = _specialChars ()
                 if ( _sp.hasOwnProperty(event.code) )   r.push ( _readKeyEvent ( event, _specialChars ))
-                else                                             return
+                else                                    return
                 if ( streamKeys )   streamKeys ({ key:event.key, context:currentContext.name, note:currentContext.note, dependencies:dependencies.extra })
-                if ( listenOptions.keyIgnore ) {
-                            clearTimeout ( listenOptions.keyIgnore )
-                            listenOptions.keyIgnore = setTimeout ( () => listenOptions.keyIgnore=null, keyWait )
+                if ( state.keyIgnore ) {
+                            clearTimeout ( state.keyIgnore )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
+                            r.pop ()
                             return 
                     }
-                if ( sequence && r.length === listenOptions.maxSequence ) {      
+                if ( sequence && r.length === state.maxSequence ) {      
                             keySequenceEnd ()
-                            listenOptions.keyIgnore = setTimeout ( () => listenOptions.keyIgnore=null, keyWait )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
                             return
                     }
-                if ( sequence   )   keyTimer = setTimeout ( keySequenceEnd, keyWait )
+                if ( sequence   )   keyTimer = setTimeout ( keySequenceEnd, listenOptions.keyWait )
                 else                keySequenceEnd ()
         } // listenForSpecialKeys func.
 
     
 
     function listenForRegularKeys ( event ) {  // Listen for regular keyboard keys
-                if ( _specialChars().hasOwnProperty(event.code) )   return            
+                if ( _specialChars().hasOwnProperty ( event.code ))   return            
                 clearTimeout ( keyTimer )
                 if ( streamKeys )   streamKeys ({ key:event.key, context:currentContext.name, note:currentContext.note, dependencies:dependencies.extra })
-                if ( listenOptions.keyIgnore ) {
-                            clearTimeout ( listenOptions.keyIgnore )
-                            listenOptions.keyIgnore = setTimeout ( () => listenOptions.keyIgnore=null, keyWait )
+                if ( state.keyIgnore ) {
+                            clearTimeout ( state.keyIgnore )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
                             return 
                     }
                 r.push ( _readKeyEvent ( event, _specialChars ))
-                if ( sequence && r.length === listenOptions.maxSequence ) {
+                if ( sequence && r.length === state.maxSequence ) {
                             keySequenceEnd ()
-                            listenOptions.keyIgnore = setTimeout ( () => listenOptions.keyIgnore=null, keyWait )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
                             return
                     }
-                if ( sequence )   keyTimer = setTimeout ( keySequenceEnd, keyWait )
+                if ( sequence )   keyTimer = setTimeout ( keySequenceEnd, listenOptions.keyWait )
                 else              keySequenceEnd ()
         } // listenForRegularKeys func.
 
@@ -131,9 +165,9 @@ function _listenDOM ( dependencies, state ) {
                                 clearTimeout ( keyTimer )
                                 keyTimer = null
                         }
-                        if ( listenOptions.keyIgnore ) {
-                                clearTimeout ( listenOptions.keyIgnore )
-                                listenOptions.keyIgnore = null
+                        if ( state.keyIgnore ) {
+                                clearTimeout ( state.keyIgnore )
+                                state.keyIgnore = null
                         }
                         // Reset all state variables to prevent interference between tests
                         r = []

package/src/plugins/key/_normalizeShortcutName.js

@@ -7,9 +7,10 @@ function _normalizeShortcutName ( name ) {
                 , isKeyboardShortcut = regex.test ( upperCase )
                 , sliceIndex = upperCase.indexOf ( ':' )
                 ;
-
-            if ( !isKeyboardShortcut )   return name
-            let shortcut = upperCase
+            
+            if ( !isKeyboardShortcut          )   return name
+            if ( upperCase.includes ( 'SETUP'))   return 'KEY:SETUP'
+            const shortcut = upperCase
                                .slice(sliceIndex+1)
                                .split(',')
                                .map ( key => key.trim() )

package/src/plugins/key/_readKeyEvent.js

@@ -1,7 +1,7 @@
 'use strict'
 
 function _readKeyEvent ( event, _specialChars ) {
-    let
+    const
           { shiftKey, altKey, ctrlKey } = event
         , falseKeys = [ 'ControlLeft','ControlRight', 'ShiftLeft', 'ShiftRight', 'AltLeft', 'AltRight', 'Meta' ]
         , _sp = _specialChars ()

package/src/plugins/key/_registerShortcutEvents.js

@@ -1,23 +1,52 @@
 'use strict'
 
+/**
+ * @function _registerShortcutEvents
+ * @description Register keyboard shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex
+ * @param {Object} pluginState - Plugin state containing currentContext, shortcuts
+ * @returns {number} - Number of registered shortcuts
+ * 
+ * @typedef {Object} KeySetupData
+ * @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
         , { 
-                  listenOptions
-                , currentContext : { name: contextName }
+                  currentContext : { name: contextName }
                 , shortcuts 
            } = pluginState
         ;
+
 if ( contextName == null )   return 0
 Object.entries ( shortcuts[contextName] ).forEach ( ([shortcutName, list ]) => {   // Enable new context shortcuts and set a listenOptions 'maxSequence'      
-                let isKeyboardEv = regex.test ( shortcutName );
+                const isKeyboardEv = regex.test ( shortcutName );
                 if ( !isKeyboardEv ) return
+                if ( shortcutName === 'KEY:SETUP' ) {
+                                hasSetup = true
+                                const updateOptions = list.reduce ( ( res, fn ) => {
+                                                const r = fn ({ 
+                                                                dependencies : dependencies.extra, 
+                                                                defaults     : structuredClone(pluginState.defaultOptions),
+                                                                options      : pluginState.listenOptions 
+                                                        })
+                                                return Object.assign ( res, r )
+                                        }, df )
+                                Object.assign ( pluginState.listenOptions, updateOptions )
+                                return
+                    }
                 count++
-                let sequenceArraySize = shortcutName.slice(4).split(',').length;
-                if ( listenOptions.maxSequence < sequenceArraySize )   listenOptions.maxSequence = sequenceArraySize
+                const sequenceArraySize = shortcutName.slice(4).split(',').length;
+                if ( pluginState.maxSequence < sequenceArraySize )   pluginState.maxSequence = sequenceArraySize
         })
+
+if ( !hasSetup )   Object.assign ( pluginState.listenOptions, df )
 return count
 } // _registerShortcutEvents func.
 

package/src/plugins/key/_specialChars.js

@@ -1,3 +1,8 @@
+/**
+ * @function _specialChars
+ * @description Get mapping of special keyboard characters to their normalized names
+ * @returns {Object} - Object mapping keyboard event keys to normalized names
+ */
 function _specialChars () {
 return {
   'ArrowLeft'   : 'LEFT'

package/src/plugins/key/index.js

@@ -1,5 +1,7 @@
 'use strict'
 
+
+
 // import all plugin files here
 import _listenDOM              from './_listenDOM.js'
 import _normalizeShortcutName  from './_normalizeShortcutName.js'
@@ -12,67 +14,50 @@ import _specialChars           from './_specialChars.js'
 /**
  * @function pluginKey
  * @description Plugin for keyboard 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.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
-                , { inAPI } = dependencies
-                , deps = {
-                             ev: dependencies.ev
-                             , _specialChars
+function pluginKey ( setupPlugin, options = {} ) {
+        const 
+                  deps = {
+                               _specialChars
                              , _readKeyEvent
-                             , mainDependencies : dependencies
                              , regex : /KEY\s*\:/i
                         }
                 , pluginState = {
-                            currentContext
-                          , shortcuts
-                          , active : false
+                            active : false
+                          , maxSequence   : 1  // How many keys can be pressed in a sequence. Controlled automatically by 'changeContext' function.
+                          , keyIgnore     : null   // Timer for ignoring key presses after max sequence or null. Not a public option.
+                          , defaultOptions : {
+                                        keyWait : 480 // 480 ms
+                                } 
                           , listenOptions  : {
-                                                  keyWait       : options.keyWait ? options.keyWait : 480   // 480 ms
-                                                , maxSequence   : 1  // How many keys can be pressed in a sequence. Controlled automatically by 'changeContext' function.
-                                                , keyIgnore     : null   // Timer for ignoring key presses after max sequence or null. Not a public option.
-                                        }
+                                        // Filled from 'key: setup' event in the context
+                                        // or getting from the plugin the defaults
+                                        keyWait : 480 // 480 ms // TODO: WHY is need initialization? Register function should fullfill it
+                                }
                           , streamKeys     : (options.streamKeys && ( typeof options.streamKeys === 'function')) ? options.streamKeys : false   // Keyboard stream function
-                          , exposeShortcut
-                }; // state
-                
-        // Read shortcuts names from all context entities and normalize entries related to the plugin
-        inAPI._normalizeWithPlugins ( _normalizeShortcutName )
-                
-        let 
-             keysListener   = _listenDOM ( deps, pluginState )
-           , countShortcuts = _registerShortcutEvents ( deps, pluginState )
-           ;
-           
-        if ( countShortcuts > 0 )   keysListener.start ()
-       
-        let pluginAPI = {
-                               getPrefix      : () => 'key'
-                             , shortcutName  : key => {   // Format a key string according plugin needs
-                                                     return _normalizeShortcutName ( key )   
-                                                }
-                             , contextChange : contextName  => {
-                                                countShortcuts = _registerShortcutEvents ( deps, pluginState )
-                                                if ( countShortcuts < 1 ) {  // Remove DOM listener if there are no shortcuts in the current context
-                                                                keysListener.stop ()
-                                                        }
-                                                if ( countShortcuts > 0 ) { // Add DOM listener if there are shortcuts in the current context
-                                                                keysListener.start ()
-                                                        }
-                                        }
-                             , mute          : () => keysListener.stop ()
-                             , unmute        : () => keysListener.start ()
-                             , destroy       : () => keysListener.stop ()
-                        };
-        Object.freeze ( pluginAPI )
-        return pluginAPI
+                        } // state
+                ;
+        
+        function resetState () {
+                    pluginState.active = false
+                    pluginState.keyIgnore = null
+                    pluginState.maxSequence = 1
+            } // resetState func.
+        deps.resetState = resetState
+
+        return setupPlugin ( {
+                                prefix : 'key'
+                              , _normalizeShortcutName  
+                              , _registerShortcutEvents 
+                              , _listenDOM              
+                              , pluginState          
+                              , deps                    
+                        })
 } // pluginKey func.
 
 

package/src/plugins/scroll/_listenDOM.js

@@ -0,0 +1,141 @@
+
+
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for scroll events
+ * @param {Object} dependencies - Dependencies object containing ev, resetState, extra
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ * 
+ * @typedef {Object} ScrollEventData
+ * @property {number} x - Current scroll X position
+ * @property {number} y - Current scroll Y position
+ * @property {string} direction - Scroll direction ('up', 'down', 'left', 'right')
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @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 {string} type - Event type ('scroll')
+ */
+function _listenDOM ( dependencies, state ) {
+    const { 
+              ev
+            , resetState
+            , extra 
+          } = dependencies;
+    let 
+          waitForScroll = null    // Timeout for reducing scroll events 
+        , waitForEndScroll = null // Timeout for setting scroll end event
+        ;
+
+function listenForScroll ( event ) {
+        const
+              x = event.clientX
+            , y = event.clientY
+            , {
+                    lastPosition
+                  , lastDirection
+                  , listenOptions
+                  , currentContext
+                } = state
+            , {
+                      scrollWait
+                    , endScrollWait
+                    , minSpace
+                } = listenOptions
+            ;
+
+        
+
+        if ( !lastPosition ) return; // No previous position to compare
+
+        let direction = null;
+        const
+              currentX = window.scrollX
+            , currentY = window.scrollY
+            , verticalChange   = Math.abs ( currentY - lastPosition.y )
+            , horizontalChange = Math.abs ( currentX - lastPosition.x )
+            ;
+
+        // Reduce scroll events by space
+        if ( verticalChange < minSpace && horizontalChange < minSpace )   return
+        
+        const directions = [];
+        
+        // Check vertical scroll
+        if ( verticalChange >= minSpace ) {
+                if ( currentY > lastPosition.y )   directions.push('down')
+                else                               directions.push('up')
+        }
+        
+        // Check horizontal scroll
+        if ( horizontalChange >= minSpace ) {
+                if ( currentX > lastPosition.x )   directions.push('right')
+                else                               directions.push('left')
+        }
+        
+        // Use first direction for single direction compatibility
+        direction = directions[0] || null;
+
+        const getData = (dir) => ({
+                          x: currentX
+                        , y: currentY
+                        , direction: dir
+                        , context: currentContext.name
+                        , note: currentContext.note
+                        , dependencies: extra
+                        , options: state.listenOptions
+                        , viewport : {                // Viewport scroll positions and sizes
+                                  X: currentX
+                                , Y: currentY
+                                , width: window.innerWidth
+                                , height: window.innerHeight
+                            }
+                        , type: 'scroll'
+                })
+
+        // Emit events for each direction detected
+        directions.forEach(dir => {
+                        const signal = `SCROLL:${dir.toUpperCase()}`
+                        ev.emit ( signal, getData(dir) )
+                })
+        
+        // Set up end scroll timeout (only once)
+        clearTimeout ( waitForScroll )
+        clearTimeout ( waitForEndScroll )
+        const finalDirection = directions[directions.length - 1] || null
+        waitForScroll    = setTimeout ( () => {}, scrollWait ) // Keep for compatibility
+        waitForEndScroll = setTimeout ( () => ev.emit ( 'SCROLL:END', getData(finalDirection) ), endScrollWait )
+
+        // Update last position
+        state.lastPosition = { x: currentX, y: currentY }
+        state.lastDirection = direction
+
+    } // listenForScroll func.
+
+
+function start () {
+        if ( state.active ) return
+        // Initialize last position
+        state.lastPosition = { x: window.scrollX, y: window.scrollY }
+        window.addEventListener ( 'scroll' , listenForScroll )
+        state.active = true
+    }
+
+
+function stop () {
+        if ( !state.active ) return
+        window.removeEventListener ( 'scroll' , listenForScroll )
+        resetState ()
+    }
+
+return { start, stop }
+
+} // _listenDOM func.
+
+
+
+export default _listenDOM
+
+

package/src/plugins/scroll/_normalizeShortcutName.js

@@ -0,0 +1,21 @@
+'use strict'
+
+function _normalizeShortcutName ( name ) {
+            const 
+                  upperCase = name.toUpperCase ()
+                , regex = /SCROLL\s*\:/i
+                , isHoverShortcut = regex.test ( upperCase )
+                ;   
+                
+            const sliceIndex = upperCase.indexOf ( ':' );
+
+            if ( !isHoverShortcut )   return name
+            const shortcut = upperCase.slice(sliceIndex+1).trim ()                            
+            return `SCROLL:${shortcut}` 
+} // _normalizeShortcutName func.
+
+
+
+export default _normalizeShortcutName
+
+

package/src/plugins/scroll/_registerShortcutEvents.js

@@ -0,0 +1,50 @@
+/**
+ * @function _registerShortcutEvents
+ * @description Register scroll shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex
+ * @param {Object} pluginState - Plugin state containing currentContext, shortcuts
+ * @returns {number} - Number of registered shortcuts
+ * 
+ * @typedef {Object} ScrollSetupData
+ * @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
+        , {
+                  currentContext : { name: contextName }
+                , shortcuts
+           } = pluginState
+        ;
+    if ( contextName == null )   return count   // No context
+    Object.entries ( shortcuts[contextName] ).forEach ( ([shortcutName, list ]) => {
+                        const isScrollEv = regex.test ( shortcutName );
+                        if ( !isScrollEv ) return
+                        if ( shortcutName === 'SCROLL:SETUP' ) {
+                                      hasSetup = true
+                                      const updateOptions = list.reduce ( ( res, fn ) => {
+                                                      const r = fn ({ 
+                                                                      dependencies : dependencies.extra, 
+                                                                      defaults     : structuredClone(pluginState.defaultOptions),
+                                                                      options      : pluginState.listenOptions 
+                                                              })
+                                                      return Object.assign ( res, r )
+                                              }, df )
+                                      Object.assign ( pluginState.listenOptions, updateOptions )
+                                      return
+                              }
+                        count++
+                })
+    if ( !hasSetup )   Object.assign ( pluginState.listenOptions, df )
+    return count
+} // _registerShortcutEvents func.
+
+
+export default _registerShortcutEvents
+
+

package/src/plugins/scroll/index.js

@@ -0,0 +1,61 @@
+'use strict'
+
+import _listenDOM from "./_listenDOM"
+import _normalizeShortcutName from "./_normalizeShortcutName"
+import _registerShortcutEvents from "./_registerShortcutEvents"
+
+
+
+/**
+ * @function pluginScroll
+ * @description Plugin for scroll event shortcuts
+ * @param {function} setupPlugin - Plugin setup function from the library
+ * @param {Object} [options={}] - Plugin options
+ * @param {number} [options.scrollWait=50] - Delay between scroll events in ms
+ * @param {number} [options.endScrollWait=400] - Delay when scroll was stopped in ms
+ * @param {number} [options.minSpace=40] - Minimum distance between scroll events in px
+ * @returns {PluginAPI} Plugin API
+ */
+function pluginScroll ( setupPlugin, options={} ) {
+    // up, down, left, right
+        const 
+                 deps = {
+                          regex : /SCROLL\s*\:/i
+                        }
+                , pluginState = {
+                                  active : false        // Is plugin active?
+                                , lastPosition  : null  // Last scroll position
+                                , lastDirection : null  // Last scroll direction
+                                , defaultOptions : {
+                                                scrollWait    : 50  // 50 ms. Delay between scroll events 
+                                              , endScrollWait : 400 // 400 ms. When scroll was stopped.
+                                              , minSpace      : 40  // 40 px. Minimum distance between scroll events
+                                    }
+                                , listenOptions  : {
+                                                scrollWait    : 50  // 50 ms. Delay between scroll events 
+                                              , endScrollWait : 400 // 400 ms. When scroll was stopped.
+                                              , minSpace      : 40  // 40 px. Minimum distance between scroll events
+                                        }
+                            } // pluginState
+                ;
+        
+        function resetState () {
+                        pluginState.active = false
+            } // resetState func.
+        deps.resetState = resetState
+
+        return setupPlugin ( {
+                                  prefix : 'scroll'
+                                , _normalizeShortcutName
+                                , _registerShortcutEvents
+                                , _listenDOM
+                                , pluginState
+                                , deps
+                        })
+} // pluginScroll func.
+
+
+
+export default pluginScroll
+
+