bb-drummer / siteapp

js/util/siteapp.util.keyboard.js

/*******************************************
 *                                         *
 * This util was created by Marius Olbertz *
 * Please thank Marius on GitHub /owlbertz *
 * or the web http://www.mariusolbertz.de/ *
 *                                         *
 ******************************************/

'use strict';

import { rtl as Rtl } from './siteapp.util.core';

const keyCodes = {
    9 : 'TAB',
    13: 'ENTER',
    27: 'ESCAPE',
    32: 'SPACE',
    35: 'END',
    36: 'HOME',
    37: 'ARROW_LEFT',
    38: 'ARROW_UP',
    39: 'ARROW_RIGHT',
    40: 'ARROW_DOWN'
}

let commands = {}

// Functions pulled out to be referenceable from internals
function findFocusable($element) {
    if(!$element) {return false; }
    return $element.find('a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), iframe, object, embed, *[tabindex], *[contenteditable]').filter(function() {
        if (!$(this).is(':visible') || $(this).attr('tabindex') < 0) { return false; } //only have visible elements and those that have a tabindex greater or equal 0
        return true;
    });
}

function parseKey(event) {
    var key = keyCodes[event.which || event.keyCode] || String.fromCharCode(event.which).toUpperCase();

    // Remove un-printable characters, e.g. for `fromCharCode` calls for CTRL only events
    key = key.replace(/\W+/, '');

    if (event.shiftKey)  key = `SHIFT_${key}`;

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

    if (event.ctrlKey)   key = `CTRL_${key}`;

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

    if (event.altKey)    key = `ALT_${key}`;

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

    if (event.metaKey)   key = `META_${key}`;

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

    // Remove trailing underscore, in case only modifiers were used (e.g. only `CTRL_ALT`)
    key = key.replace(/_$/, '');

    return key;
}

const Keyboard = {
		
    /**
     * @var {object} keys - keycodes map
     */
    keys: getKeyCodes(keyCodes),

    /**
     * Parses the (keyboard) event and returns a String that represents its key
     * Can be used like Foundation.parseKey(event) === Foundation.keys.SPACE
     * @param {Event} event - the event generated by the event handler
     * @return String key - String that represents the key pressed
     */
    parseKey: parseKey,

    /**
     * Handles the given (keyboard) event
     * @param {Event} event - the event generated by the event handler
     * @param {String} component - Foundation component's name, e.g. Slider or Reveal
     * @param {Objects} functions - collection of functions that are to be executed
     */
    handleKey(event, component, functions) {
        var commandList = commands[component],
            keyCode = this.parseKey(event),
            cmds,
            command,
            fn;

        if (!commandList) return console.warn('Component not defined!');

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

        if (typeof commandList.ltr === 'undefined') { // this component does not differentiate between ltr and rtl
            cmds = commandList; // use plain list
        } else { // merge ltr and rtl: if document is rtl, rtl overwrites ltr and vice versa
            if (Rtl()) cmds = $.extend({}, commandList.ltr, commandList.rtl);

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

            else cmds = $.extend({}, commandList.rtl, commandList.ltr);
        }
        command = cmds[keyCode];

        fn = functions[command];
        if (fn && typeof fn === 'function') { // execute function  if exists
            var returnValue = fn.apply(null, [event]);
            if (functions.handled || typeof functions.handled === 'function') { // execute function when event was handled

There is no return statement if functions.handled || typeof functions.handled === "function" is false. Are you sure this is correct? If so, consider adding return; explicitly.

                functions.handled(returnValue);

There is no return statement in this branch, but you do return something in other branches. Did you maybe miss it? If you do not want to return anything, consider adding return undefined; explicitly.

            }
        } else {
            if (functions.unhandled || typeof functions.unhandled === 'function') { // execute function when event was not handled

There is no return statement if functions.unhandled || typeof functions.unhandled === "function" is false. Are you sure this is correct? If so, consider adding return; explicitly.

                functions.unhandled();

There is no return statement in this branch, but you do return something in other branches. Did you maybe miss it? If you do not want to return anything, consider adding return undefined; explicitly.

            }
        }
    },

    /**
     * Finds all focusable elements within the given `$element`
     * @param {jQuery} $element - jQuery object to search within
     * @return {jQuery} $focusable - all focusable elements within `$element`
     */

    findFocusable: findFocusable,

    /**
     * Stores set of commands mapped to handler names in a given namespace
     * 
     * @param {string} namespace - keyboard event/command namespace
     * @param {object} cmds - handler name to command map
     */

    register (namespace, cmds) {
        commands[namespace] = cmds;
        //console.//log('registered keyboard component:', namespace, cmds, commands);
    },


    // TODO9438: These references to Keyboard need to not require global. Will 'this' work in this context?
    //
    /**
     * Traps the focus in the given element.
     * @param  {jQuery} $element  jQuery object to trap the foucs into.
     */
    trapFocus($element) {
        var $focusable = findFocusable($element),
            $firstFocusable = $focusable.eq(0),
            $lastFocusable = $focusable.eq(-1);

        $element.on('keydown.'+Keyboard._ns+'.trapfocus', function(event) {
            if (event.target === $lastFocusable[0] && parseKey(event) === 'TAB') {
                event.preventDefault();
                $firstFocusable.focus();
            }
            else if (event.target === $firstFocusable[0] && parseKey(event) === 'SHIFT_TAB') {
                event.preventDefault();
                $lastFocusable.focus();
            }
        });
    },
  
    /**
     * Releases the trapped focus from the given element.
     * @param  {jQuery} $element  jQuery object to release the focus for.
     */
    releaseFocus($element) {
        $element.off('keydown.'+Keyboard._ns+'.trapfocus');
    },
    
    /**
     * Removes keyboard event handlers. If no namespace is given, all 
     * keyboard handlers will be removed.
     * 
     * @param {string} namespace - keyboard event namespace
     */
    unregister( namespace ) {
    	if (namespace != '') {
    		$(window).off('keydown.'+this.application.appName+'.'+namespace);
    		if (typeof commands[namespace] != 'undefined') {
    			delete commands[namespace];
    		}
    	} else {
    		$(window).off('keydown.'+this.application.appName);
    		commands = {};
    	}
    },
  
    /**
     * Adds keyboard event handlers.
     * 
     * handlers := {
     *    '[KEY(S)]' : function myAction (event e) {...},
     *    ...
     * }
     * 
     * @param {object} handlers - key(s) to action map
     * @param {string} namespace - keyboard event namespace
     */
    addKeyHandlers( handlers, namespace ) {

        var $this   = this,
            $app    = this._app,

The variable $app seems to be never used. Consider removing it.

            eventTrigger = 'keydown.'+this._ns,
            registeredKeys = {},
            registeredHandlers = {}
        ;

    	if ('' == namespace) {
    		let namespace = '_'+Siteapp.sys.genUUID(6);

The variable Siteapp seems to be never declared. If this is a global, consider adding a /** global: Siteapp */ comment.

The variable namespace seems to be never used. Consider removing it.

    	}
		eventTrigger = eventTrigger+'.'+namespace;
        
    	// build 'reg keys' and 'hdl keys' maps
		for ( var key in handlers ) {
			if (handlers.hasOwnProperty(key)) {
				var handleName = namespace+''+key;
				registeredKeys[key] = handleName;
				registeredHandlers[handleName] = handlers[key];
			}
		}
    	
        $(window).on(eventTrigger, function(e){

    	    this.id = namespace+''+Siteapp.sys.genUUID(6);

The variable Siteapp seems to be never declared. If this is a global, consider adding a /** global: Siteapp */ comment.

    	    
    	    // ignore [TAB] key
	        // if (e.which === 9) return;
	
	        // handle keyboard event with keyboard util
	        $this.handleKey(e, namespace, registeredHandlers);

	        
        });

        // register keyboard keys mapping
        this.register(namespace, registeredKeys);
        
    }
  
};

/*
 * Constants for easier comparing.
 * Can be used like Foundation.parseKey(event) === Foundation.keys.SPACE
 */
function getKeyCodes(kcs) {
    var k = {};
    for (var kc in kcs) k[kcs[kc]] = kcs[kc];

A for in loop automatically includes the property of any prototype object, consider checking the key using hasOwnProperty.

Curly braces around statements make for more readable code and help prevent bugs when you add further statements.

    return k;
}

export {Keyboard};