@peter.naydenov/shortcuts 3.5.1 → 4.0.0

package/src/plugins/form/_registerShortcutEvents.js

@@ -1,52 +1,128 @@
 'use strict'
 
+/**
+ * @function _registerShortcutEvents
+ * @description Register form shortcut events and handle setup
+ * @param {Object} dependencies - Dependencies object containing regex, _defaults, ev
+ * @param {Object} pluginState - Plugin state containing currentContext, shortcuts, callbacks, etc.
+ * @returns {number|false} - Number of registered shortcuts or false if no actions
+ * 
+ * @typedef {Object} FormWatchData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * 
+ * @typedef {Object} FormDefineData
+ * @property {Element} target - The DOM element being watched
+ * @property {string} context - Current context name
+ * @property {string|null} note - Current context note
+ * @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 {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ * 
+ * @typedef {Object} FormActionData
+ * @property {Object} dependencies - Extra dependencies object
+ * @property {Object} options - Plugin state listenOptions (reference to pluginState.listenOptions)
+ */
 function _registerShortcutEvents ( dependencies, pluginState ) {
 const 
           { regex, _defaults, ev } = dependencies
         , { 
-                  currentContext : { name: contextName }
+                  currentContext : { name: contextName, note }
                 , shortcuts 
                 , callbacks
+                , ERROR_EVENT_NAME
+                , defaultOptions 
            } = pluginState
         ;
-        let watch=[], define=[], action=[];
+        let watch=[], define=[], action=[], count = 0;
         if ( contextName == null )   return false
         Object.entries ( shortcuts[contextName] ).forEach ( ([shortcutName, list ]) => {   
-                        let isFormEv = regex.test ( shortcutName );
-                        if ( !isFormEv ) return                
+                        const isFormEv = regex.test ( shortcutName );
+                        if ( !isFormEv ) return
+                        if ( shortcutName.includes('SETUP' )) {
+                                        const updateOptions = list.reduce ( ( res, fn ) => {
+                                                        const r = fn ({ 
+                                                                        dependencies : dependencies.extra, 
+                                                                        defaults     : structuredClone ( pluginState.defaultOptions ),
+                                                                        options      : pluginState.listenOptions
+                                                                })
+                                                        return Object.assign ( res, r )
+                                                }, defaultOptions )
+                                        Object.assign ( pluginState.listenOptions, updateOptions )
+                                        return
+                                } 
                         if ( shortcutName === 'FORM:WATCH' )    watch = list
                         if ( shortcutName === 'FORM:DEFINE' )   define = list
                         if ( shortcutName === 'FORM:ACTION' )   action = list
+                        
                 })
         
-        if ( action.length === 0 )   return false
-        
-        let setTypes = new Set ();
+        if ( action.length === 0 )   return count
+   
+        const setTypes = new Set ();
         if ( define.length === 0 )  define = [ _defaults.define ]
         if ( watch.length === 0  )  watch  = [ _defaults.watch ] 
-        let watchList = watch.map ( el => el() )
+        const watchList = watch.map ( el => el ({ 
+                                                  dependencies : dependencies.extra 
+                                                , context : contextName 
+                                                , note
+                                                , options : pluginState.listenOptions
+                                        })   )
                                         .reduce ( ( res, el) => {
                                                 res.push ( el ) 
                                                 return res
                                         }, [])
         pluginState.watchList = document.querySelectorAll ( watchList )
-        pluginState.watchList.forEach ( el => setTypes.add (define[0](el)) ) 
+        pluginState.watchList.forEach ( el => {
+                                        const 
+                                                  { left, top, width, height } = el.getBoundingClientRect ()
+                                                , scrollX = window.scrollX
+                                                , scrollY = window.scrollY
+                                                ;
+                                        return setTypes.add ( define[0]({
+                                                                  target : el
+                                                                , context : contextName
+                                                                , note
+                                                                , dependencies : dependencies.extra
+                                                                , options : pluginState.listenOptions
+                                                                , viewport : {
+                                                                                X: scrollX
+                                                                              , Y: scrollY
+                                                                              , width: window.innerWidth
+                                                                              , height: window.innerHeight
+                                                                        }
+                                                                , sizes : { width , height }
+                                                                , position : { x:left, y:top }
+                                                                , pagePosition : { x:left+scrollX, y:top+scrollY }
+                                                                }) 
+                                                ) // setTypes
+                        }) // forEach watchList 
 
         pluginState.typeFn = define[0] ? define[0] : _defaults.define
+     
         action.forEach ( act => {
-                        
                         if ( !(act instanceof Function)) {  
-                                console.warn ( `Warning: The 'form:action' should be a function.` )
+                                ev.emit ( ERROR_EVENT_NAME, `The 'form:action' should be a function.` )
                                 return false
                            }
-                        let list = act ()
+                        
+                        const list = act ({ 
+                                 dependencies : dependencies.extra,
+                                 options      : pluginState.listenOptions
+                         })
+                        
                         if ( !(list instanceof Array) ) {
-                                console.warn ( `Warning: The 'form:action' function should RETURN an array.` )
+                                ev.emit ( ERROR_EVENT_NAME, `Warning: The 'form:action' function should RETURN an array.` )
                                 return false
                            }
-                        act().forEach ( ({fn, type, timing, wait=0 }) => {
+                        list.forEach ( ({fn, type, timing, wait=0 }) => {
                                         if ( setTypes.has ( type) && fn instanceof Function ) {
-                                                let key = `${type}/${timing}`
+                                                const key = `${type}/${timing}`
                                                 const hasProperty = callbacks.hasOwnProperty ( key );
                                                 hasProperty ? 
                                                                 callbacks[key].push ( fn ) :
@@ -60,8 +136,8 @@ const
                                         if ( timing === 'instant' )   pluginState.wait[`${type}`] = wait
                                 }) // for each act
                 }) // for each action
-        if ( Object.keys(pluginState.callbacks).length > 0 )   return true
-        else                                                   return false
+        count = Object.keys ( pluginState.callbacks ).length
+        return count
 } // _registerShortcutEvents func.
 
 

package/src/plugins/form/index.js

@@ -1,5 +1,7 @@
 'use strict'
 
+
+
 // import all plugin files here
 import _listenDOM from './_listenDOM.js'
 import _normalizeShortcutName from './_normalizeShortcutName.js'
@@ -11,29 +13,26 @@ import _defaults from './_defaults.js'
 /**
  * @function pluginForm
  * @description Plugin for form element 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
  * @returns {PluginAPI} Plugin API
  */
-function pluginForm ( dependencies, state, options ) {
+function pluginForm ( setupPlugin, options={} ) {
 
-    let 
-                  { currentContext, shortcuts } = state
-                , { inAPI } = dependencies
-                , deps = {
-                               ev: dependencies.ev
-                             , mainDependencies : dependencies
+    const 
+                 deps = {
+                               _defaults
                              , regex : /FORM\s*\:/i
-                             , _defaults
                         }
                 , pluginState = {
-                                  currentContext
-                                , shortcuts
-                                , callbacks : {} // Functions callbacks arranged by 'type/timing' : [ callback, ...otherCallbacks ]
-                                , typeFn    : '' // Type definition function
-                                , watchList : [] // list of watched elements
-                                , wait      : {} // wait time for 'instant' mode
+                                  callbacks      : {} // Functions callbacks arranged by 'type/timing' : [ callback, ...otherCallbacks ]
+                                , typeFn         : '' // Type definition function
+                                , watchList      : [] // list of watched elements
+                                , wait           : {} // wait time for 'instant' mode. Define by 'type'. 
+                                                      // Example: { 'input': 200 }, will update from 'input' type every 200ms
+                                                      // where 'input' is type received by 'define' function
+                                , defaultOptions : {}
+                                , listenOptions  : {}
                             } // pluginState
                 ;
     function resetState () {
@@ -42,37 +41,17 @@ function pluginForm ( dependencies, state, options ) {
             pluginState.watchList = []
             pluginState.wait      = {}
       } // resetState func.
-
-    // Read shortcuts names from all context entities and normalize entries related to the plugin
-    inAPI._normalizeWithPlugins ( _normalizeShortcutName )
-    let formListener = _listenDOM ( deps, pluginState );
-    
-    if ( currentContext.name ) {
-          let hasFormShortcuts = _registerShortcutEvents ( deps, pluginState )
-          if ( hasFormShortcuts )    formListener.start ()
-      }
-       
-    let pluginAPI = {
-                       getPrefix     : ( ) => 'form'
-                     , shortcutName  : key => {   // Format a key string according plugin needs
-                                             return _normalizeShortcutName ( key )   
-                                        }
-                     , contextChange : ( )  => {
-                                        resetState ()
-                                        let hasFormShortcuts = _registerShortcutEvents ( deps, pluginState )
-                                        if ( hasFormShortcuts )    formListener.start ()
-                                        else                       formListener.stop ()                                          
-                                }
-                     , mute          : () => formListener.stop ()
-                     , unmute        : () => formListener.start ()
-                     , destroy       : () => {
-                                          formListener.stop ()
-                                          // TODO: Clean up state of the plugin
-                                }
-                                        
-              }; // pluginAPI
-        Object.freeze ( pluginAPI )
-        return pluginAPI
+    deps.resetState = resetState
+
+    return setupPlugin ({
+                        prefix : 'form'
+                      , _normalizeShortcutName
+                      , _registerShortcutEvents
+                      , _listenDOM
+                      
+                      , pluginState
+                      , deps
+                  })
 } // pluginForm func.
 
 

package/src/plugins/hover/_findTarget.js

@@ -0,0 +1,26 @@
+'use strict'
+
+/**
+ * @function _findTarget
+ * @description Find the appropriate hover target element by checking if element has any of the target attributes
+ * @param {Object} dependencies - Dependencies object
+ * @param {Object} state - Plugin state containing listenOptions with hoverTarget array
+ * @param {Element} target - DOM element to start searching from
+ * @returns {Element|false} - Target element or false if not found
+ */
+function _findTarget ( dependencies, state, target ) {
+    const { listenOptions : {hoverTarget}} = state;
+
+    const t = target;
+    if ( t === document.body )   return false
+    if ( t === document      )   return false
+    const found = hoverTarget.some ( attr => ( t.hasAttribute ( attr ) ) )
+    if ( found ) return t
+    return   _findTarget ( dependencies, state, t.parentNode ) 
+} // _findTarget func.
+
+
+
+export default _findTarget
+
+

package/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/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/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/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
+
+