@peter.naydenov/cuts 2.0.2 → 2.1.0

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/hover/_listenDOM.js

@@ -0,0 +1,154 @@
+
+/**
+ * @function _listenDOM
+ * @description Set up DOM event listeners for hover events
+ * @param {Object} dependencies - Dependencies object containing ev, _findTarget, resetState, extra
+ * @param {Object} state - Plugin state containing listenOptions and currentContext
+ * @returns {Object} - Object containing start and stop methods
+ * 
+ * @typedef {Object} HoverEventData
+ * @property {Element} target - The DOM element that is being hovered
+ * @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 ('hover')
+ */
+function _listenDOM ( dependencies, state ) {
+    const { 
+              ev
+            , _findTarget
+            , resetState
+            , extra 
+           } = dependencies;
+
+    function inside ( rect,  x,  y ) {
+        if ( !rect ) return false;
+        return (
+            x >= rect.left &&
+            x <= rect.right &&
+            y >= rect.top &&
+            y <= rect.bottom
+          );
+    } // inside func.
+
+
+
+function listenForHover ( event ) {
+        const
+            x = event.clientX
+          , y = event.clientY
+          ;
+        
+        const 
+              { 
+                  hovered
+                , hoverRectangle
+                , listenOptions
+                , hoverTimer
+                , leaveTimer
+                , lastEvent
+                , lastHoverTarget 
+                } = state
+            , target = _findTarget ( dependencies, state, event.target )
+            ;
+
+        if ( inside ( hoverRectangle, x, y ) )   return
+
+        function  getData (tg) {
+                    const 
+                          { left, top, width, height } = tg.getBoundingClientRect ()
+                        , scrollX = window.scrollX
+                        , scrollY = window.scrollY
+                        ;
+
+                    return {
+                                target : tg
+                                , context: state.currentContext.name
+                                , note   : state.currentContext.note
+                                , event
+                                , dependencies : extra
+                                , options : state.listenOptions
+                                , viewport : {                                    // Viewport scroll positions
+                                        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: 'hover'
+                        }
+                } // getData func.
+        
+
+        
+        if ( target !== hovered ) {  // When target is different from hovered
+                    if ( hovered && !target ) { // We have 'hovered' but no new target
+                            state.hovered = false
+                            state.hoverRectangle = null
+
+                            if ( hoverTimer ) {
+                                    clearTimeout ( hoverTimer )
+                                    state.hoverTimer = null
+                                }
+                            if ( lastEvent === 'off' )  return
+                            state.leaveTimer = setTimeout ( () => {
+                                                ev.emit ( 'HOVER:OFF', getData(hovered) )
+                                                state.leaveTimer = null
+                                                state.lastEvent = 'off'
+                                            }, listenOptions.wait )
+                            return
+                        } // if hovered
+
+                    if ( hovered ) {   // We have 'hovered' and new target
+                            // Close immediately the previous hover
+                            ev.emit ( 'HOVER:OFF', getData(hovered) ) 
+                            state.leaveTimer = null
+                            state.lastEvent = 'off'
+                        }
+                    
+                    clearTimeout ( leaveTimer )
+                    clearTimeout ( hoverTimer )
+                                        
+                    state.hovered = target
+                    state.hoverRectangle = target.getBoundingClientRect ()
+                    state.hoverTimer = setTimeout ( () => {
+                                                    ev.emit ( 'HOVER:ON', getData(target))
+                                                    state.hoverTimer = null
+                                                    state.lastHoverTarget = target
+                                                    state.lastEvent = 'on'
+                                            }, listenOptions.wait )
+
+            } // if target !== hovered
+    } // listenForHover func.
+
+
+function start () {
+        if ( state.active ) return
+        document.addEventListener ( 'mousemove' , listenForHover )
+        state.active = true
+    }
+
+
+function stop () {
+        if ( !state.active ) return
+        document.removeEventListener ( 'mousemove' , listenForHover )
+        resetState ()
+    }
+
+return { start, stop }
+
+} // _listenDOM func.
+
+
+
+export default _listenDOM
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/hover/_normalizeShortcutName.js

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

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/hover/_registerShortcutEvents.js

@@ -0,0 +1,51 @@
+/**
+ * @function _registerShortcutEvents
+ * @description Register hover shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex, _defaults, ev
+ * @param {Object} pluginState - Plugin state containing currentContext, shortcuts, ERROR_EVENT_NAME
+ * @returns {number} - Number of registered shortcuts
+ * 
+ * @typedef {Object} HoverSetupData
+ * @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, _defaults, ev } = dependencies
+    , { 
+              currentContext : { name: contextName }
+            , shortcuts 
+            , ERROR_EVENT_NAME
+        } = pluginState
+    ;
+    if ( contextName == null )   return count   // No context
+    Object.entries ( shortcuts[contextName] ).forEach ( ([shortcutName, list ]) => {   
+                        const isHoverEv = regex.test ( shortcutName );
+                        if ( !isHoverEv ) return
+                        if ( shortcutName === 'HOVER: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/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/hover/index.js

@@ -0,0 +1,71 @@
+'use strict'
+
+import _findTarget from "./_findTarget"
+import _listenDOM from "./_listenDOM"
+import _normalizeShortcutName from "./_normalizeShortcutName"
+import _registerShortcutEvents from "./_registerShortcutEvents"
+
+
+
+/**
+ * @function pluginHover
+ * @description Plugin for mouse hover shortcuts
+ * @param {function} setupPlugin - Plugin setup function from the library
+ * @param {Object} [options={}] - Plugin options
+ * @param {string[]} [options.hoverTarget=['data-hover']] - Array of attribute names for hover targets
+ * @param {number} [options.wait=320] - Time to wait for hover sequence in ms
+ * @returns {PluginAPI} Plugin API
+ */
+function pluginHover ( setupPlugin, options={} ) {
+        const 
+                 deps = {
+                               _findTarget
+                             , regex : /HOVER\s*\:/i
+                        }
+                , pluginState = {
+                                //   currentContext       // { name, note } of the current context
+                                  active : false          // Plugin activity state
+                                , hovered : false         // False or the hovered HTML element
+                                , hoverRectangle : null   // Hovered HTML element rectangle
+                                , hoverTimer : null       // Timeout for reducing hover on events
+                                , leaveTimer : null       // Timeout for reducing hover off events
+                                , lastEvent  : ''         // 'on' or 'off'. Last executed hover event 
+                                , lastHoverTarget : null  // Last hovered HTML element or null
+                                , defaultOptions : {
+                                                hoverTarget : [ 'data-hover' ],
+                                                wait : 320  // 320 ms
+                                                }
+                                , listenOptions  : {
+                                                hoverTarget : [ 'data-hover' ],
+                                                wait : 320  // 320 ms
+                                        }
+                            } // pluginState
+                ;
+        
+        function resetState () {
+                        pluginState.active = false
+                        pluginState.hovered = false
+                        pluginState.hoverRectangle = null
+                        clearTimeout ( pluginState.hoverTimer )
+                        clearTimeout ( pluginState.leaveTimer )
+                        pluginState.hoverTimer = null
+                        pluginState.leaveTimer = null
+                        pluginState.lastHoverTarget = null
+            } // resetState func.
+        deps.resetState = resetState
+
+        return setupPlugin ({
+                                  prefix : 'hover'
+                                , _normalizeShortcutName
+                                , _registerShortcutEvents
+                                , _listenDOM
+                                , pluginState
+                                , deps
+                        })
+} // pluginHover func.
+
+
+
+export default pluginHover
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/key/_listenDOM.js

@@ -0,0 +1,186 @@
+'use strict'
+
+
+
+/**
+ * @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
+    const { 
+                  ev
+                , _specialChars
+                , _readKeyEvent
+                , extra
+                , resetState
+            } = dependencies
+        , {
+                  currentContext
+                , streamKeys
+                , listenOptions
+            } = state
+        ;
+    
+    let 
+          r = []
+        , keyTimer = null    // Timer for key sequence or null
+        , 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.
+        ;
+
+
+    
+    const  
+           waitKeys   = () => sequence = false  
+        ,  endKeys    = () => sequence = true  
+        , ignoreKeys  = () => ignore   = true
+        , waitingKeys = () => sequence === false
+        ;
+    
+
+
+    function keySequenceEnd () {   // Execute when key sequence ends
+                    const res =  r.map ( x => ([x.join('+')])   )
+                    
+                    const data = {
+                                      wait: waitKeys
+                                    , end:endKeys
+                                    , ignore:ignoreKeys
+                                    , isWaiting:waitingKeys
+                                    , note: currentContext.note
+                                    , context: currentContext.name
+                                    , dependencies : extra
+                                    , options : state.listenOptions
+                                    , viewport : { 
+                                              X : window.scrollX
+                                            , Y : window.scrollY
+                                            , width:window.innerWidth
+                                            , height:window.innerHeight 
+                                        }
+                                    , type : 'key'
+                            };
+
+                    if ( !sequence ) {
+                             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.
+
+
+    
+    function listenForSpecialKeys ( event ) { // Listen for special keyboard keys
+                clearTimeout ( keyTimer )
+                const _sp = _specialChars ()
+                if ( _sp.hasOwnProperty(event.code) )   r.push ( _readKeyEvent ( event, _specialChars ))
+                else                                    return
+                if ( streamKeys )   streamKeys ({ key:event.key, context:currentContext.name, note:currentContext.note, dependencies:dependencies.extra })
+                if ( state.keyIgnore ) {
+                            clearTimeout ( state.keyIgnore )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
+                            r.pop ()
+                            return 
+                    }
+                if ( sequence && r.length === state.maxSequence ) {      
+                            keySequenceEnd ()
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
+                            return
+                    }
+                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            
+                clearTimeout ( keyTimer )
+                if ( streamKeys )   streamKeys ({ key:event.key, context:currentContext.name, note:currentContext.note, dependencies:dependencies.extra })
+                if ( state.keyIgnore ) {
+                            clearTimeout ( state.keyIgnore )
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
+                            return 
+                    }
+                r.push ( _readKeyEvent ( event, _specialChars ))
+                if ( sequence && r.length === state.maxSequence ) {
+                            keySequenceEnd ()
+                            state.keyIgnore = setTimeout ( () => state.keyIgnore=null, listenOptions.keyWait )
+                            return
+                    }
+                if ( sequence )   keyTimer = setTimeout ( keySequenceEnd, listenOptions.keyWait )
+                else              keySequenceEnd ()
+        } // listenForRegularKeys func.
+
+
+
+    function start () {
+                        if ( state.active ) return
+                        document.addEventListener ( 'keydown' , listenForSpecialKeys )
+                        document.addEventListener ( 'keypress', listenForRegularKeys )
+                        state.active = true
+        } 
+
+
+    function stop () {
+                        if ( !state.active ) return
+                        document.removeEventListener ( 'keydown' , listenForSpecialKeys )
+                        document.removeEventListener ( 'keypress', listenForRegularKeys )
+                        state.active = false
+                        // Clear any pending timers to prevent state pollution between tests
+                        if ( keyTimer ) {
+                                clearTimeout ( keyTimer )
+                                keyTimer = null
+                        }
+                        if ( state.keyIgnore ) {
+                                clearTimeout ( state.keyIgnore )
+                                state.keyIgnore = null
+                        }
+                        // Reset all state variables to prevent interference between tests
+                        r = []
+                        sequence = true
+                        ignore = false
+        }
+    
+    return { start, stop }
+
+} // _listenDOM func.
+
+
+
+export default _listenDOM
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/key/_normalizeShortcutName.js

@@ -0,0 +1,32 @@
+'use strict'
+
+function _normalizeShortcutName ( name ) {
+            const 
+                  upperCase = name.toUpperCase ()
+                , regex = /KEY\s*\:/i
+                , isKeyboardShortcut = regex.test ( upperCase )
+                , sliceIndex = upperCase.indexOf ( ':' )
+                ;
+            
+            if ( !isKeyboardShortcut          )   return name
+            if ( upperCase.includes ( 'SETUP'))   return 'KEY:SETUP'
+            const shortcut = upperCase
+                               .slice(sliceIndex+1)
+                               .split(',')
+                               .map ( key => key.trim() )
+                               .map ( key => {
+                                            return key
+                                                     .split ( '+' )
+                                                     .map ( key => key.trim() )
+                                                     .sort()
+                                                     .join ( '+' )
+                                        })
+                               .join(',');
+            return `KEY:${shortcut}`   
+} // _normalizeShortcutName func.
+
+
+
+export default _normalizeShortcutName
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/key/_readKeyEvent.js

@@ -0,0 +1,28 @@
+'use strict'
+
+function _readKeyEvent ( event, _specialChars ) {
+    const
+          { shiftKey, altKey, ctrlKey } = event
+        , falseKeys = [ 'ControlLeft','ControlRight', 'ShiftLeft', 'ShiftRight', 'AltLeft', 'AltRight', 'Meta' ]
+        , _sp = _specialChars ()
+        , key = event.code
+                     .replace ( 'Key', '' )
+                     .replace('Digit','')
+        , res = []
+        ;
+       
+    if ( ctrlKey )   res.push ( 'CTRL' )
+    if ( shiftKey )  res.push ( 'SHIFT' )
+    if ( altKey )    res.push ( 'ALT' )
+
+    if ( _sp.hasOwnProperty ( key )     )  res.push ( _sp[key].toUpperCase () )
+    else if ( !falseKeys.includes(key)  )  res.push ( key.toUpperCase () )
+
+    return res.sort ()
+} // _readKeyEvent func.
+
+
+
+export default _readKeyEvent
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/key/_registerShortcutEvents.js

@@ -0,0 +1,57 @@
+'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
+        , { 
+                  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'      
+                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++
+                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.
+
+
+
+export default _registerShortcutEvents
+
+

package/test-e2e/node_modules/@peter.naydenov/shortcuts/src/plugins/key/_specialChars.js

@@ -0,0 +1,43 @@
+/**
+ * @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'
+, 'ArrowUp'     : 'UP'
+, 'ArrowRight'  : 'RIGHT'
+, 'ArrowDown'   : 'DOWN'
+, 'Enter'       : 'ENTER'
+, 'NumpadEnter' : 'ENTER'
+, 'Escape'      : 'ESC' 
+, 'Backspace'   : 'BACKSPACE'
+, 'Space'       : 'SPACE'
+, 'Tab'         : 'TAB'
+, 'Backquote'   : '`'
+, 'BracketLeft' : '['
+, 'BracketRight': ']'
+, 'Equal'       : '='
+, 'Slash'       : '/'
+, 'Backslash'   : '\\'
+, 'IntlBackslash' : '`'
+, 'F1'  : 'F1'
+, 'F2'  : 'F2'
+, 'F3'  : 'F3'
+, 'F4'  : 'F4'
+, 'F5'  : 'F5'
+, 'F6'  : 'F6'
+, 'F7'  : 'F7'
+, 'F8'  : 'F8'
+, 'F9'  : 'F9'
+, 'F10' : 'F10'
+, 'F11' : 'F11'
+, 'F12' : 'F12'
+}}
+
+
+
+export default _specialChars
+
+