@peter.naydenov/shortcuts 1.0.0

package/src/listen.js

@@ -0,0 +1,186 @@
+'use strict'
+
+
+
+function listen ( dependencies, options, currentContext ) {   // Listen for input signals and generate event titles
+    const { 
+              specialChars 
+            , readKeyEvent
+            , readMouseEvent
+            , findTarget
+            , ev
+            , exposeShortcut
+            , streamKeys
+        } = dependencies
+        , { 
+                  mouseWait
+                , keyWait
+                , clickTarget
+                , listenFor
+            } = options
+        ;
+    
+    let 
+          r = []
+        , mouseTarget = null // Dom element or null
+        , mouseDomEvent = null
+        , keyTimer = null    // Timer for key sequence or null
+        , mouseTimer = null  // Timer for mouse sequence or null
+        , mouseIgnore = null // Timer for ignoring mouse clicks or null
+        , sequence = true
+        , ignore   = false   // Use to trigger a single callback without adding the key to the sequence.
+        , count    = 0
+        ;
+    
+
+
+
+    const  
+           waitKeys   = () => sequence = false  
+        ,  endKeys    = () => sequence = true  
+        , ignoreKeys  = () => ignore   = true
+        , waitingKeys = () => sequence === false
+        ;
+    
+
+
+    function keySequenceEnd () {   // Execute when key sequence ends
+                    let res =  r.map ( x => ([x.join('+')])   );
+                    if ( !sequence ) {
+                            let signal = res.at(-1);
+                            ev.emit ( signal, { wait:waitKeys, end:endKeys, ignore:ignoreKeys, isWaiting:waitingKeys, note: currentContext.note, context: currentContext.name })
+                            if ( ignore ) {
+                                        res = res.slice ( 0, -1 )
+                                        ignore = false
+                                }
+                        }
+
+                    if ( sequence ) { 
+                            ev.emit ( res.join(','), { wait: waitKeys, end:endKeys, ignore:ignoreKeys, isWaiting:waitingKeys, note: currentContext.note, context: currentContext.name })   
+                            if ( exposeShortcut )   exposeShortcut ( res.join(','), currentContext.name, currentContext.note ) // TODO: Add a context information...?
+                            // Reset:
+                            r = []
+                            keyTimer = null
+                        }
+        } // keySequeceEnd func.
+
+
+
+    function mouseSequenceEnd () {   // Execute when mouse sequence ends
+                    const 
+                          mouseEvent = readMouseEvent ( mouseDomEvent, count )
+                        , data = { 
+                                  target : mouseTarget
+                                , targetProps : mouseTarget ? mouseTarget.getBoundingClientRect() : null
+                                , x       : mouseDomEvent.clientX
+                                , y       : mouseDomEvent.clientY
+                                , context : currentContext.name
+                                , note    : currentContext.note
+                                , event   : mouseDomEvent
+                            }
+                        ;
+                    ev.emit ( mouseEvent.join('+'), data )
+                    if ( exposeShortcut )   exposeShortcut ( mouseEvent.join('+'), currentContext.name, currentContext.note )
+                    // Reset:
+                    mouseTimer = null
+                    mouseIgnore = null
+                    mouseTarget = null
+                    mouseDomEvent = null
+                    count = 0
+        } // mouseSequenceEnd func.
+
+
+
+    function listenMouse () {
+                        window.addEventListener ( 'contextmenu', event => {   // Listen for right mouse clicks
+                                        clearTimeout ( mouseTimer )
+                                        if ( mouseIgnore ) {
+                                                    clearTimeout ( mouseIgnore )
+                                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                                    return
+                                            }
+                                        if ( count === options.maxClicks ) {  
+                                                    mouseSequenceEnd ()
+                                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                                    return
+                                            }
+                                        event.preventDefault ()
+                                        mouseTarget = findTarget (event.target, clickTarget )
+                                        mouseDomEvent = event
+                                        count++
+                                        mouseTimer = setTimeout ( mouseSequenceEnd, mouseWait )
+                                })
+
+                        document.addEventListener ( 'click', event => {  // Listen for left and middle mouse clicks
+                                        clearTimeout ( mouseTimer )
+                                        if ( mouseIgnore ) {
+                                                    clearTimeout ( mouseIgnore )
+                                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                                    return
+                                            }
+                                        if ( count === options.maxClicks ) {
+                                                    mouseSequenceEnd ()
+                                                    mouseIgnore = setTimeout ( () => mouseIgnore=null, mouseWait )
+                                                    return
+                                            }
+                                        mouseTarget = findTarget ( event.target, clickTarget )
+                                        mouseDomEvent = event
+                                        count++
+                                        mouseTimer = setTimeout ( mouseSequenceEnd, mouseWait )
+                                })
+        } // listenMouse func.
+
+
+
+    function listenKeyboard () {
+                        document.addEventListener ( 'keydown', event => {   // Listen for special keyboard keys
+                                        clearTimeout ( keyTimer )
+                                        if ( specialChars.hasOwnProperty(event.code) )   r.push ( readKeyEvent ( event, specialChars ))
+                                        else                                             return
+                                        if ( streamKeys )   streamKeys ( event.key, currentContext.name, currentContext.note )
+                                        if ( options.keyIgnore ) {
+                                                    clearTimeout ( options.keyIgnore )
+                                                    options.keyIgnore = setTimeout ( () => options.keyIgnore=null, keyWait )
+                                                    return 
+                                            }
+                                        if ( sequence && r.length === options.maxSequence ) {                                                    
+                                                    keySequenceEnd ()
+                                                    options.keyIgnore = setTimeout ( () => options.keyIgnore=null, keyWait )
+                                                    return
+                                            }
+                                        if ( sequence   )   keyTimer = setTimeout ( keySequenceEnd, keyWait )
+                                        else                keySequenceEnd ()
+                                })
+
+                        document.addEventListener ( 'keypress', event => {  // Listen for regular keyboard keys
+                                        if ( specialChars.hasOwnProperty(event.code) )   return            
+                                        clearTimeout ( keyTimer )
+                                        if ( streamKeys )   streamKeys ( event.key, currentContext.name, currentContext.note )
+                                        if ( options.keyIgnore ) {
+                                                    clearTimeout ( options.keyIgnore )
+                                                    options.keyIgnore = setTimeout ( () => options.keyIgnore=null, keyWait )
+                                                    return 
+                                            }
+                                        r.push ( readKeyEvent ( event, specialChars ))
+                                        if ( sequence && r.length === options.maxSequence ) {
+                                                    keySequenceEnd ()
+                                                    options.keyIgnore = setTimeout ( () => options.keyIgnore=null, keyWait )
+                                                    return
+                                            }
+                                        if ( sequence )   keyTimer = setTimeout ( keySequenceEnd, keyWait )
+                                        else              keySequenceEnd ()
+                                })
+        } // listenKeyboard func.
+    
+    
+
+    if ( listenFor.includes('mouse')    )   listenMouse ()
+    if ( listenFor.includes('keyboard') )   listenKeyboard ()
+
+} // listen func.
+
+
+
+export default listen
+
+

package/src/load.js

@@ -0,0 +1,32 @@
+'use strict'
+
+
+
+function load ( shortcuts, readShortcut, changeContext, getContext ) {
+return function load ( obj ) {
+    const
+           currentContextName = getContext ()
+         , contextList = Object.keys ( obj )
+         ;
+    let hasChanges = false;
+    contextList.forEach ( contextName => {
+                    const description = Object.entries ( obj [ contextName ] );
+                    if ( contextName === currentContextName ) hasChanges = true;
+                    shortcuts [ contextName ] = {}
+                    description.forEach ( ([ title, callbackList ]) => {
+                                    const name = readShortcut ( title );
+                                    if ( callbackList instanceof Function ) callbackList = [ callbackList ]
+                                    shortcuts [contextName][ name ] = callbackList
+                            }) // shortcuts.forEach
+        }) // contextList.forEach
+     if ( hasChanges ) {  // Reload context shortcuts after loading process if context was active
+                changeContext ()
+                changeContext ( currentContextName )
+        }
+}} // load func.
+
+
+
+export default load
+
+

package/src/main.js

@@ -0,0 +1,92 @@
+'use strict'
+
+/**
+ *  Shortcuts
+ *  ========
+ *  Create shortcuts for your web application based on keyboard and mouse events.
+ *  Repository: https://github.com/PeterNaydenov/shortcuts
+ * 
+ *  History notes:
+ *  - Development was started on June 21st, 2023
+ *  - First version was published on August 14th, 2023
+ */
+
+
+
+import notice from '@peter.naydenov/notice'   // Docs: https://github.com/PeterNaydenov/notice
+
+import listen         from './listen.js'
+import readShortcut   from './readShortcut.js'
+import readKeyEvent   from './readKeyEvent.js'
+import readMouseEvent from './readMouseEvent.js'
+import findTarget from './findTarget.js'
+import specialChars from './specialChars.js'
+import load from './load.js'
+import unload from './unload.js'
+import changeContext from './changeContext.js'
+
+
+
+
+
+function main ( options = {} ) {
+    const
+          ev = notice ()  // Event emitter instance
+        , currentContext = { name: null, note: null } // Context data container
+        , exposeShortcut = (options.onShortcut && ( typeof options.onShortcut === 'function')) ? options.onShortcut : false
+        , streamKeys     = (options.streamKeys && ( typeof options.streamKeys === 'function')) ? options.streamKeys : false
+        , listenOptions = {
+                              mouseWait     : options.mouseWait ? options.mouseWait : 320   // 320 ms
+                            , maxClicks     : 1  // The maximum number of clicks in a sequence. Controlled automatically by 'changeContext' function.
+                            , keyWait       : options.keyWait ? options.keyWait : 480   // 480 ms
+                            , maxSequence   : 1  // How many keys can be pressed in a sequence. Controlled automatically by 'changeContext' function.
+                            , clickTarget   : options.clickTarget ? options.clickTarget :  'click' // Data-attribute name for click target ( data-click )
+                            , listenFor     : (options.listenFor && Array.isArray(options.listenFor)) ? options.listenFor : [ 'mouse', 'keyboard' ] // What to listen for: ['mouse'], ['keyboard'], ['mouse', 'keyboard']
+                            , keyIgnore     : null   // Timer for ignoring key presses after max sequence or null. Not a public option.
+                       }
+        , shortcuts = {}   // shortcuts = { contextName : { shortcut :  callback[] } }
+        , getContext = () => currentContext.name
+        , getNote    = () => currentContext.note
+        , setNote    = (note=null) => { if (typeof note === 'string' || note == null )   currentContext.note = note }
+        , dependencies = { 
+                              specialChars 
+                            , readKeyEvent
+                            , readMouseEvent
+                            , findTarget
+                            , ev
+                            , exposeShortcut
+                            , streamKeys
+                        }
+        ;
+    
+    listen ( dependencies, listenOptions, currentContext )
+
+    return {  // shortcuts API
+        load          : load ( shortcuts, readShortcut, changeContext( shortcuts, listenOptions, ev, currentContext ), getContext )      
+      , unload        : unload ( shortcuts, ev, currentContext )
+      , changeContext : changeContext ( shortcuts, listenOptions, ev, currentContext )
+      , pause         : () => ev.stop ()
+      , resume        : () => ev.start ()
+      , listContexts  : () => Object.keys ( shortcuts )
+      , getContext
+      , getNote 
+      , setNote
+    }
+} // main func.
+
+
+
+main.getDefaults = () => ({
+                          mouseWait     : 320     // 320 ms   // TODO: Slow down. It's too fast at the moment.
+                        , keyWait       : 480     // 480 ms
+                        , clickTarget   : 'click' // Data-attribute name for click target ( data-click )
+                        , listenFor     : [ 'mouse', 'keyboard' ]
+                        , onShortcut    : false   // Shortcut log function or false 
+                        , streamKeys    : false   // Stream keys function or false
+                    })
+
+
+
+export default main
+
+

package/src/readKeyEvent.js

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

package/src/readMouseEvent.js

@@ -0,0 +1,24 @@
+'use strict'
+
+
+function readMouseEvent ( event, count ) {
+    let
+          { shiftKey, altKey, ctrlKey, key, button } = event
+        , mouseNames = [ 'LEFT', 'MIDDLE', 'RIGHT' ]
+        , mouseEvent = `MOUSE-CLICK-${mouseNames[button]}-${count}`
+        , res = []
+        ;
+    
+    res.push ( mouseEvent )
+    if ( ctrlKey )   res.push ( 'CTRL' )
+    if ( shiftKey )  res.push ( 'SHIFT' )
+    if ( altKey )    res.push ( 'ALT' )
+
+    return res.sort ()
+} // readMouseEvent func.
+
+
+
+export default readMouseEvent
+
+

package/src/readShortcut.js

@@ -0,0 +1,16 @@
+'use strict'
+// [ crtl+s, shift+alt+o]
+function readShortcut ( txt ) {
+        const r = txt
+                    .split ( ',' )
+                    .map ( (x) => x.trim() )
+                    .map ( (x) => x.split ( '+' ).map(x => x.toUpperCase()).sort().join('+') )
+                    .join ( ',' );
+    return r
+} // readShortcut func.
+
+
+
+export default readShortcut
+
+

package/src/specialChars.js

@@ -0,0 +1,31 @@
+export default {
+      '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'
+}

package/src/unload.js

@@ -0,0 +1,23 @@
+'use strict'
+
+
+
+function unload ( shortcuts, ev, currentContext ) {
+return function unload ( contextName ) {
+        const current = currentContext.name;
+        if ( current === contextName ) {
+                    ev.emit ( 'shortcuts-error', `Context '${ contextName }' can't be removed during is current active context. Change the context first` )
+                    return
+            }
+        if ( !shortcuts [ contextName ] ) {
+                    ev.emit ( 'shortcuts-error', `Context '${ contextName }' does not exist` )
+                    return
+            }
+        delete shortcuts [ contextName ]
+}} // unload func.
+
+
+
+export default unload
+
+

package/style.css

@@ -0,0 +1,97 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+#app {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.vanilla:hover {
+  filter: drop-shadow(0 0 2em #f7df1eaa);
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

package/test/01-general.cy.js

@@ -0,0 +1,111 @@
+
+import Block from '../test-components/Block.jsx'
+import '../test-components/style.css'
+import shortcuts from '../src/main.js'
+import { expect } from 'chai'
+
+let
+       a = false
+     , b = false
+     ;
+const short = shortcuts ({onShortcut : ( shortcut, context, note ) => console.log (shortcut, context, note)});
+short.load ({
+                  general : {
+                            'shift+a': [ () => a = true ]
+                        }
+                , extra : {    
+                            'shift+a,p,r,o,b,a,ctrl+m' : () => b = true 
+                        }
+        })
+
+
+describe ( 'Shortcuts', () => {
+
+beforeEach ( () => {
+    cy.mount ( Block ()  )
+    a = false, b = false
+}) // beforeEach
+
+it ( 'Simple shortcut', done => {
+            let res = false;
+            short.changeContext ( 'general' )
+            cy.get('body').type ( '{shift}a' )
+            cy.wait ( 100 )   // Default wait sequence timeout is 480 ms
+              .then ( () => { 
+                                expect ( a ).to.be.true 
+                                done ()
+                        })            
+    }) // it first test
+
+
+
+it ( 'Check context switching and shortcut sequences', done => {
+    expect ( a ).to.be.false
+    expect ( b ).to.be.false
+    
+    short.changeContext ( 'extra' )
+    cy.get('body').type ( '{shift}a' )
+    cy.wait ( 500 )   // Default wait sequence timeout is 480 ms. Context 'extra' has a sequence of 7 keys. Need to wait for timeout
+      .then ( () => {
+                        expect ( a ).to.be.false
+                        
+                        cy.get('body')
+                                .type ( '{shift}a' )
+                                .type('proba')
+                                .type('{ctrl}M')
+                        return cy.wait ( 1 )   // Shortuct sequence is 7 keys - the maximum number of keys for this context. Don't need to wait for timeout
+            })
+      .then ( () => {
+                        expect ( b ).to.be.true
+
+                        short.changeContext ( 'general' )
+                        cy.get('body').type ( '{shift}a' )
+                        return cy.wait ( 2 )  // Context 'general' has a sequence of 1 key. Don't need to wait for timeout
+                })
+        .then ( () => {
+                        expect ( a ).to.be.true
+                        done ()
+                })
+}) // it context and shortcut sequences
+
+
+
+it ( 'Single mouse click', done => {
+    expect ( a ).to.be.false
+    expect ( b ).to.be.false
+    short.load ({ 'extra' : { 
+                            'mouse-click-left-1' : () => a = true 
+                        } 
+            })
+    short.changeContext ( 'extra' )
+    cy.get('#rspan').click ()
+    cy.wait ( 350 ) // Default wait mouse timeout is 320 ms
+      .then ( () => {
+                        expect ( a ).to.be.true
+                        done ()
+            })
+}) // it mouse click
+
+
+
+it ( 'Double mouse click', done => {
+    expect ( a ).to.be.false
+    expect ( b ).to.be.false
+    
+    short.changeContext ( 'extra' )
+    
+    short.load ({   
+                    'extra' : {   // load will overwrite existing 'extra' context definition
+                                  'mouse-click-left-2' : () => a = true
+                              } 
+                }) // load will restart the selected context
+                   
+    cy.get('#rspan').click().click ().click () // Third click is ignored. Max clicks according definition is 2.
+    cy.wait ( 350 ) // Default wait mouse timeout is 320 ms
+      .then ( () => {
+                    expect ( a ).to.be.true
+                    done ()
+        })
+}) // it double mouse click
+
+}) // describe

package/test-components/Block.jsx

@@ -0,0 +1,11 @@
+function Block () {
+return <>
+    <div className="block" data-click="red"><span id='rspan'>Red</span> </div>
+    <button className="big-btn" data-click="mega">Mega button</button>
+</> 
+}
+
+
+export default Block
+
+

package/test-components/style.css

@@ -0,0 +1,21 @@
+.block {
+    width: 100px;
+    height: 100px;
+    padding: 20px;
+    background-color: red;
+}
+
+.block span { 
+    color: white;
+    font-size: 20px;
+    font-weight: bold;
+    font-family: Arial, Helvetica, sans-serif;
+}
+
+.big-btn {
+    width: 200px;
+    height: 200px;
+    margin-left: 230px;
+    background-color: skyblue;
+    border-radius: 10px;
+}