keanu.js

var keanu;

(function (exports) {
    // CommonJS
    if (typeof module !== "undefined" && module.exports) {
        module.exports = exports;
    }
    // AMD
    else if (typeof define === "function") {
        define(exports);
    }
    // <script>
    else {
        keanu = exports;
    }
}((function () {
    var exports = {};

    exports.name = 'keanu.js';
    exports.version = '0.3';

    var MODIFIERS = [
            '17', 'Ctrl',
            '224', 'Cmd'
        ],
        // Cancel if these are pressed
        CANCEL_ON = [
            '0',  // Escape
            '27', // Escape
            '8',  // Backspace
            '46'  // Delete
        ],
        // Special character transforms for displaying properly
        TRANSFORMS = {
            16: 'Shift',
            17: 'Ctrl',
            18: 'Alt',
            28:  '\\',
            32:  'Space',
            92:  'Win',
            224: 'Cmd'
        };

    var webkit_transforms = {
        13:  'Enter',
        37:  'Left',
        38:  'Up',
        39:  'Down',
        40:  'Right',
        91:  'Cmd',
        112: 'F1',
        113: 'F2',
        114: 'F3',
        115: 'F4',
        116: 'F5',
        117: 'F6',
        118: 'F7',
        119: 'F8',
        120: 'F9',
        121: 'F10',
        122: 'F11',
        123: 'F12',
        186: ';',
        187: '=',
        188: ',',
        189: '-',
        190: '.',
        191: '/',
        192: '`',
        219: '[',
        220: '\\',
        221: ']',
        222: '\''
    };

    // Merge the transforms
    for(var key in webkit_transforms)
        TRANSFORMS[key] = webkit_transforms[key];

    MODIFIERS.push('16');
    MODIFIERS.push('Shift');
    //
    MODIFIERS.push('18');
    MODIFIERS.push('Alt');

    // Add the reverse transform relationships
    for(var transform_key in TRANSFORMS){
        if(TRANSFORMS.hasOwnProperty(transform_key)){
            TRANSFORMS[TRANSFORMS[transform_key]] = transform_key;
        }
    }


    // Test whether a key is a modifier
    function is_modifier(which){
        return (
            MODIFIERS.indexOf(which) !== -1 ||
            MODIFIERS.indexOf(String(which)) !== -1
        );
    }


    function transform_which(which){
        return TRANSFORMS[which] || String.fromCharCode(Number(which));
    }


    // Sort an array of which entities
    function sort_which(a, b){
        if( is_modifier(a) === is_modifier(b) ){
            return a - b;
        }

        // A is modifier
        else if(is_modifier(a)){
            return -1;
        }

        // Last case is that B is a modifier
        return 1;
    }


    // Transform a key hash map to a sorted shortcut string
    function keyarray_to_shortcut(keyarray){
        if(typeof keyarray === 'undefined' || keyarray.length === 0){
            return;
        }

        return keyarray.sort(sort_which).join('_');
    }


    // Given a shortcut string, return a shortcut array
    function shortcut_to_keyarray(shortcut){
        return shortcut.split('_').map(function(elem){
            return String(elem);
        }).sort(sort_which);
    }


    // Handle the actual dispatching of events
    function dispatch_update(callback, keyarray){
        if(typeof(callback) !== 'undefined'){
            callback(
                keyarray.length ? keyarray_to_shortcut(keyarray) : false
            );
        }
    }

    function has_non_modifier(keyarray){
        for(var i = 0; i < keyarray.length; i++){
            if(!is_modifier(keyarray[i])){
                return true;
            }
        }
        return false;
    }

    function has_modifier(keyarray){
        for(var i = 0; i < keyarray.length; i++){
            if(is_modifier(keyarray[i])){
                return true;
            }
        }
        return false;
    }

    function has_function_key(keyarray){
        var friendlyShortcut = get_friendly_shortcut(keyarray_to_shortcut(keyarray));
        return 'F1?[0-9]'.search(friendlyShortcut) != -1;
    }

    // Determine if a key event should be considered valid
    function validate_event(event){
        var which = String(event.which);

        if (event.type === 'keydown') {
            return which;
        }

        return false;
    }


    // Listen for new shortcuts being set
    function get_shortcut(options, passed_doc) {
        var // Internal tracking of keys pressed
            keyarray  = [],
            // What to attach key events to
            doc = typeof passed_doc === 'undefined' ? window : passed_doc,
            // Options
            max_keys = typeof(options.max_keys) === 'undefined' ? 0 : options.max_keys;


        function keydown_listener(event){
            event.preventDefault();
            var which = validate_event(event);

            if(which){
                if(CANCEL_ON.indexOf(which) !== -1){
                    return cancel(event);
                }

                else if(
                    keyarray.indexOf(which) === -1 &&
                    // And we cant go over max keys
                    keyarray.length < max_keys
                ){
                    keyarray.push(which);
                    dispatch_update(options.on_update, keyarray);
                }
            }

        }


        function keyup_listener(event){
            event.preventDefault();
            return tear_down();
        }


        // Cancel everything
        function cancel(event){
            if(event){
                event.preventDefault();
                event.stopPropagation();
            }
            keyarray = [];
            return tear_down();
        }


        function tear_down(){
            if(!has_non_modifier(keyarray)){
                keyarray = [];
            }

            if(options.on_set){
                dispatch_update(options.on_set, keyarray);
            }

            keyarray = [];

            doc.removeEventListener('keypress', keydown_listener, true);
            doc.removeEventListener('keydown', keydown_listener, true);
            doc.removeEventListener('keyup', keyup_listener, true);

            doc.removeEventListener('mousedown', cancel, true);
            doc.removeEventListener('blur', cancel, true);
            doc.removeEventListener('focus', cancel, true);

            if(options.on_complete){
                options.on_complete();
            }
        }


        doc.addEventListener('keypress', keydown_listener, true);
        doc.addEventListener('keydown', keydown_listener, true);
        doc.addEventListener('keyup', keyup_listener, true);

        // Entering or leaving the doc should cancel anything going on
        doc.addEventListener('mousedown', cancel, true);
        doc.addEventListener('blur', cancel, true);
        doc.addEventListener('focus', cancel, true);
    }


    function listen(callback, passed_doc){
        var keyarray = [],
            doc = typeof passed_doc === 'undefined' ? window : passed_doc;


        function keydown_listener(event){
            var which = validate_event(event),
                whichNotInArr = keyarray.indexOf(which) === -1,
                eventIsValid = (
                    !event.target ||
                    event.target.tagName == 'BODY' ||
                    event.target.tagName == 'HTML' ||
                    event.target.tagName == 'html' ||
                    event.target.tagName == 'DIV' ||
                    event.target.tagName == 'ARTICLE' ||
                    event.target.tagName == 'div' ||
                    event.target == document.documentElement
                );

            //Sites like gmail and Twitter have text inputs that are just divs
            //with contenteditable set to true. Shortcuts should not fire for
            //them. This should only run once we know the event is otherwise
            //valid.
            if (eventIsValid) {
                if (event.target.getAttribute('contenteditable')) {
                    eventIsValid = false;
                }
            }

            if (which && whichNotInArr && eventIsValid) {
                if (CANCEL_ON.indexOf(which) !== -1){
                    return cancel();
                }

                keyarray.push(which);
                dispatch_update(callback, keyarray);
            }
        }


        function keyup_listener(event){
            if(keyarray.length){
                dispatch_update(callback, keyarray);
                keyarray = [];
            }
        }


        function cancel(){
            keyarray = [];
            return false;
        }


        function stop(){
            keyarray = [];

            doc.removeEventListener('keypress', keydown_listener, true);
            doc.removeEventListener('keydown', keydown_listener, true);
            doc.removeEventListener('keyup', keyup_listener, true);

            doc.removeEventListener('blur', cancel);
            doc.removeEventListener('focus', cancel);
        }

        doc.addEventListener('keypress', keydown_listener, true);
        doc.addEventListener('keydown', keydown_listener, true);
        doc.addEventListener('keyup', keyup_listener, true);

        // Entering and leaving the doc should cancel any active presses
        doc.addEventListener('blur', cancel, true);
        doc.addEventListener('focus', cancel, true);

        return {
            stop: stop
        };
    }


    function get_friendly_shortcut (shortcut) {
        var friendlyShortcut = '',
            shortcutArr = keanu.shortcut_to_keyarray(shortcut),
            which = null;

        for (var i = 0; i < shortcutArr.length; i += 1) {
            which = shortcutArr[i];
            friendlyShortcut += keanu.transform_which(which);

            if (i < shortcutArr.length -1) {
                friendlyShortcut += ' + ';
            }
        }
        return friendlyShortcut;
    }


    function shortcut_to_firefox_hotkey(shortcut) {
        function transform_names(match) {
            switch(match) {
                case 'cmd':
                    return 'meta';
                case 'ctrl':
                    return 'control';
                default:
                    return match;
            }
        }
        var friendlyShortcut = get_friendly_shortcut(shortcut).toLowerCase().replace(/ \+ /g, '-');
        return friendlyShortcut.replace(/cmd|ctrl/gi, transform_names);
    }


    function firefox_to_friendly(shortcut) {
        if(shortcut == null) {
            return null;
        }
        function transform_names(match) {
            switch(match) {
                case 'meta':
                    return 'Cmd';
                case 'control':
                    return 'Ctrl';
                case 'shift':
                    return 'Shift';
                case 'alt':
                    return 'Alt';
                default:
                    return match;
            }
        }
        var output = shortcut.toLowerCase().replace(/-/g, ' + ');
        output = output.replace(/meta|control|shift|alt/gi, transform_names);
        return output;
    }

    // TODO: We might just want to declare each function as a member of exports
    // instead of doing it here.
    exports.listen = listen;
    exports.get_shortcut = get_shortcut;
    exports.keyarray_to_shortcut = keyarray_to_shortcut;
    exports.shortcut_to_keyarray = shortcut_to_keyarray;
    exports.transform_which = transform_which;
    exports.is_modifier = is_modifier;
    exports.has_modifier = has_modifier;
    exports.has_function_key = has_function_key;
    exports.has_non_modifier = has_non_modifier;
    exports.get_friendly_shortcut = get_friendly_shortcut;
    exports.shortcut_to_firefox_hotkey = shortcut_to_firefox_hotkey;
    exports.firefox_to_friendly = firefox_to_friendly;

    return exports;
}())));