lib/amd/src/tree.js

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
/**
 * Implement an accessible aria tree widget, from a nested unordered list.
 * Based on http://oaa-accessibility.org/example/41/.
 *
 * @module     core/tree
 * @copyright  2015 Damyon Wiese <damyon@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
define(['jquery'], function($) {
    // Private variables and functions.
    var SELECTORS = {
        ITEM: '[role=treeitem]',
        GROUP: '[role=treeitem]:has([role=group]), [role=treeitem][aria-owns], [role=treeitem][data-requires-ajax=true]',
        CLOSED_GROUP: '[role=treeitem]:has([role=group])[aria-expanded=false], [role=treeitem][aria-owns][aria-expanded=false], ' +
                 '[role=treeitem][data-requires-ajax=true][aria-expanded=false]',
        FIRST_ITEM: '[role=treeitem]:first',
        VISIBLE_ITEM: '[role=treeitem]:visible',
        UNLOADED_AJAX_ITEM: '[role=treeitem][data-requires-ajax=true][data-loaded=false][aria-expanded=true]'
    };
    /**
     * Constructor.
     *
     * @param {String} selector
     * @param {function} selectCallback Called when the active node is changed.
     */
    var Tree = function(selector, selectCallback) {
        this.treeRoot = $(selector);
        this.treeRoot.data('activeItem', null);
        this.selectCallback = selectCallback;
        this.keys = {
            tab:      9,
            enter:    13,
            space:    32,
            pageup:   33,
            pagedown: 34,
            end:      35,
            home:     36,
            left:     37,
            up:       38,
            right:    39,
            down:     40,
            asterisk: 106
        };
        // Apply the standard default initialisation for all nodes, starting with the tree root.
        this.initialiseNodes(this.treeRoot);
        // Make the first item the active item for the tree so that it is added to the tab order.
        this.setActiveItem(this.treeRoot.find(SELECTORS.FIRST_ITEM));
        // Create the cache of the visible items.
        this.refreshVisibleItemsCache();
        // Create the event handlers for the tree.
        this.bindEventHandlers();
    };
    Tree.prototype.registerEnterCallback = function(callback) {
        this.enterCallback = callback;
    };
    /**
     * Find all visible tree items and save a cache of them on the tree object.
     *
     * @method refreshVisibleItemsCache
     */
    Tree.prototype.refreshVisibleItemsCache = function() {
        this.treeRoot.data('visibleItems', this.treeRoot.find(SELECTORS.VISIBLE_ITEM));
    };
    /**
     * Get all visible tree items.
     *
     * @method getVisibleItems
     * @return {Object} visible items
     */
    Tree.prototype.getVisibleItems = function() {
        return this.treeRoot.data('visibleItems');
    };
    /**
     * Mark the given item as active within the tree and fire the callback for when the active item is set.
     *
     * @method setActiveItem
     * @param {object} item jquery object representing an item on the tree.
     */
    Tree.prototype.setActiveItem = function(item) {
        var currentActive = this.treeRoot.data('activeItem');
        if (item === currentActive) {
            return;
        }
        // Remove previous active from tab order.
        if (currentActive) {
            currentActive.attr('tabindex', '-1');
            currentActive.attr('aria-selected', 'false');
        }
        item.attr('tabindex', '0');
        item.attr('aria-selected', 'true');
        // Set the new active item.
        this.treeRoot.data('activeItem', item);
        if (typeof this.selectCallback === 'function') {
            this.selectCallback(item);
        }
    };
    /**
     * Determines if the given item is a group item (contains child tree items) in the tree.
     *
     * @method isGroupItem
     * @param {object} item jquery object representing an item on the tree.
     * @returns {bool}
     */
    Tree.prototype.isGroupItem = function(item) {
        return item.is(SELECTORS.GROUP);
    };
    /**
     * Determines if the given item is a group item (contains child tree items) in the tree.
     *
     * @method isGroupItem
     * @param {object} item jquery object representing an item on the tree.
     * @returns {bool}
     */
    Tree.prototype.getGroupFromItem = function(item) {
        var ariaowns = this.treeRoot.find('#' + item.attr('aria-owns'));
        var plain = item.children('[role=group]');
        if (ariaowns.length > plain.length) {
            return ariaowns;
        } else {
            return plain;
        }
    };
    /**
     * Determines if the given group item (contains child tree items) is collapsed.
     *
     * @method isGroupCollapsed
     * @param {object} item jquery object representing a group item on the tree.
     * @returns {bool}
     */
    Tree.prototype.isGroupCollapsed = function(item) {
        return item.attr('aria-expanded') === 'false';
    };
    /**
     * Determines if the given group item (contains child tree items) can be collapsed.
     *
     * @method isGroupCollapsible
     * @param {object} item jquery object representing a group item on the tree.
     * @returns {bool}
     */
    Tree.prototype.isGroupCollapsible = function(item) {
        return item.attr('data-collapsible') !== 'false';
    };
    /**
     * Performs the tree initialisation for all child items from the given node,
     * such as removing everything from the tab order and setting aria selected
     * on items.
     *
     * @method initialiseNodes
     * @param {object} node jquery object representing a node.
     */
    Tree.prototype.initialiseNodes = function(node) {
        this.removeAllFromTabOrder(node);
        this.setAriaSelectedFalseOnItems(node);
        // Get all ajax nodes that have been rendered as expanded but haven't loaded the child items yet.
        var thisTree = this;
        node.find(SELECTORS.UNLOADED_AJAX_ITEM).each(function() {
            var unloadedNode = $(this);
            // Collapse and then expand to trigger the ajax loading.
            thisTree.collapseGroup(unloadedNode);
            thisTree.expandGroup(unloadedNode);
        });
    };
    /**
     * Removes all child DOM elements of the given node from the tab order.
     *
     * @method removeAllFromTabOrder
     * @param {object} node jquery object representing a node.
     */
    Tree.prototype.removeAllFromTabOrder = function(node) {
        node.find('*').attr('tabindex', '-1');
        this.getGroupFromItem($(node)).find('*').attr('tabindex', '-1');
    };
    /**
     * Find all child tree items from the given node and set the aria selected attribute to false.
     *
     * @method setAriaSelectedFalseOnItems
     * @param {object} node jquery object representing a node.
     */
    Tree.prototype.setAriaSelectedFalseOnItems = function(node) {
        node.find(SELECTORS.ITEM).attr('aria-selected', 'false');
    };
    /**
     * Expand all group nodes within the tree.
     *
     * @method expandAllGroups
     */
    Tree.prototype.expandAllGroups = function() {
        var thisTree = this;
        this.treeRoot.find(SELECTORS.CLOSED_GROUP).each(function() {
            var groupNode = $(this);
            thisTree.expandGroup($(this)).done(function() {
                thisTree.expandAllChildGroups(groupNode);
            });
        });
    };
    /**
     * Find all child group nodes from the given node and expand them.
     *
     * @method expandAllChildGroups
     * @param {Object} item is the jquery id of the group.
     */
    Tree.prototype.expandAllChildGroups = function(item) {
        var thisTree = this;
        this.getGroupFromItem(item).find(SELECTORS.CLOSED_GROUP).each(function() {
            var groupNode = $(this);
            thisTree.expandGroup($(this)).done(function() {
                thisTree.expandAllChildGroups(groupNode);
            });
        });
    };
    /**
     * Expand a collapsed group.
     *
     * Handles expanding nodes that are ajax loaded (marked with a data-requires-ajax attribute).
     *
     * @method expandGroup
     * @param {Object} item is the jquery id of the parent item of the group.
     * @return {Object} a promise that is resolved when the group has been expanded.
     */
    Tree.prototype.expandGroup = function(item) {
        var promise = $.Deferred();
        // Ignore nodes that are explicitly maked as not expandable or are already expanded.
        if (item.attr('data-expandable') !== 'false' && this.isGroupCollapsed(item)) {
            // If this node requires ajax load and we haven't already loaded it.
            if (item.attr('data-requires-ajax') === 'true' && item.attr('data-loaded') !== 'true') {
                item.attr('data-loaded', false);
                // Get the closes ajax loading module specificed in the tree.
                var moduleName = item.closest('[data-ajax-loader]').attr('data-ajax-loader');
                var thisTree = this;
                // Flag this node as loading.
                const p = item.find('p');
                p.addClass('loading');
                // Require the ajax module (must be AMD) and try to load the items.
                require([moduleName], function(loader) {
                    // All ajax module must implement a "load" method.
                    loader.load(item).done(function() {
                        item.attr('data-loaded', true);
                        // Set defaults on the newly constructed part of the tree.
                        thisTree.initialiseNodes(item);
                        thisTree.finishExpandingGroup(item);
                        // Make sure no child elements of the item we just loaded are tabbable.
                        p.removeClass('loading');
                        promise.resolve();
                    });
                });
            } else {
                this.finishExpandingGroup(item);
                promise.resolve();
            }
        } else {
            promise.resolve();
        }
        return promise;
    };
    /**
     * Perform the necessary DOM changes to display a group item.
     *
     * @method finishExpandingGroup
     * @param {Object} item is the jquery id of the parent item of the group.
     */
    Tree.prototype.finishExpandingGroup = function(item) {
        // Expand the group.
        var group = this.getGroupFromItem(item);
        group.removeAttr('aria-hidden');
        item.attr('aria-expanded', 'true');
        // Update the list of visible items.
        this.refreshVisibleItemsCache();
    };
    /**
     * Collapse an expanded group.
     *
     * @method collapseGroup
     * @param {Object} item is the jquery id of the parent item of the group.
     */
    Tree.prototype.collapseGroup = function(item) {
        // If the item is not collapsible or already collapsed then do nothing.
        if (!this.isGroupCollapsible(item) || this.isGroupCollapsed(item)) {
            return;
        }
        // Collapse the group.
        var group = this.getGroupFromItem(item);
        group.attr('aria-hidden', 'true');
        item.attr('aria-expanded', 'false');
        // Update the list of visible items.
        this.refreshVisibleItemsCache();
    };
    /**
     * Expand or collapse a group.
     *
     * @method toggleGroup
     * @param {Object} item is the jquery id of the parent item of the group.
     */
    Tree.prototype.toggleGroup = function(item) {
        if (item.attr('aria-expanded') === 'true') {
            this.collapseGroup(item);
        } else {
            this.expandGroup(item);
        }
    };
    /**
     * Handle a key down event - ie navigate the tree.
     *
     * @method handleKeyDown
     * @param {Event} e The event.
     */
     // This function should be simplified. In the meantime..
     // eslint-disable-next-line complexity
    Tree.prototype.handleKeyDown = function(e) {
        var item = $(e.target);
        var currentIndex = this.getVisibleItems()?.index(item);
        if ((e.altKey || e.ctrlKey || e.metaKey) || (e.shiftKey && e.keyCode != this.keys.tab)) {
            // Do nothing.
            return;
        }
        switch (e.keyCode) {
            case this.keys.home: {
                // Jump to first item in tree.
                this.getVisibleItems().first().focus();
                e.preventDefault();
                return;
            }
            case this.keys.end: {
                // Jump to last visible item.
                this.getVisibleItems().last().focus();
                e.preventDefault();
                return;
            }
            case this.keys.enter: {
                var links = item.children('a').length ? item.children('a') : item.children().not(SELECTORS.GROUP).find('a');
                if (links.length) {
                    if (links.first().data('overrides-tree-activation-key-handler')) {
                        // If the link overrides handling of activation keys, let it do so.
                        links.first().triggerHandler(e);
                    } else if (typeof this.enterCallback === 'function') {
                        // Use callback if there is one.
                        this.enterCallback(item);
                    } else {
                        window.location.href = links.first().attr('href');
                    }
                } else if (this.isGroupItem(item)) {
                    this.toggleGroup(item, true);
                }
                e.preventDefault();
                return;
            }
            case this.keys.space: {
                if (this.isGroupItem(item)) {
                    this.toggleGroup(item, true);
                } else if (item.children('a').length) {
                    var firstLink = item.children('a').first();
                    if (firstLink.data('overrides-tree-activation-key-handler')) {
                        firstLink.triggerHandler(e);
                    }
                }
                e.preventDefault();
                return;
            }
            case this.keys.left: {
                var focusParent = function(tree) {
                    // Get the immediate visible parent group item that contains this element.
                    tree.getVisibleItems().filter(function() {
                        return tree.getGroupFromItem($(this)).has(item).length;
                    }).focus();
                };
                // If this is a group item then collapse it and focus the parent group
                // in accordance with the aria spec.
                if (this.isGroupItem(item)) {
                    if (this.isGroupCollapsed(item)) {
                        focusParent(this);
                    } else {
                        this.collapseGroup(item);
                    }
                } else {
                    focusParent(this);
                }
                e.preventDefault();
                return;
            }
            case this.keys.right: {
                // If this is a group item then expand it and focus the first child item
                // in accordance with the aria spec.
                if (this.isGroupItem(item)) {
                    if (this.isGroupCollapsed(item)) {
                        this.expandGroup(item);
                    } else {
                        // Move to the first item in the child group.
                        this.getGroupFromItem(item).find(SELECTORS.ITEM).first().focus();
                    }
                }
                e.preventDefault();
                return;
            }
            case this.keys.up: {
                if (currentIndex > 0) {
                    var prev = this.getVisibleItems().eq(currentIndex - 1);
                    prev.focus();
                }
                e.preventDefault();
                return;
            }
            case this.keys.down: {
                if (currentIndex < this.getVisibleItems().length - 1) {
                    var next = this.getVisibleItems().eq(currentIndex + 1);
                    next.focus();
                }
                e.preventDefault();
                return;
            }
            case this.keys.asterisk: {
                // Expand all groups.
                this.expandAllGroups();
                e.preventDefault();
                return;
            }
        }
    };
    /**
     * Handle an item click.
     *
     * @param {Event} event the click event
     * @param {jQuery} item the item clicked
     */
    Tree.prototype.handleItemClick = function(event, item) {
        // Update the active item.
        item.focus();
        // If the item is a group node.
        if (this.isGroupItem(item)) {
            this.toggleGroup(item);
        }
    };
    /**
     * Handle a click (select).
     *
     * @method handleClick
     * @param {Event} event The event.
     */
    Tree.prototype.handleClick = function(event) {
        if (event.altKey || event.ctrlKey || event.shiftKey || event.metaKey) {
            // Do nothing.
            return;
        }
        // Get the closest tree item from the event target.
        var item = $(event.target).closest('[role="treeitem"]');
        if (!item.is(event.currentTarget)) {
            return;
        }
        this.handleItemClick(event, item);
    };
    /**
     * Handle a focus event.
     *
     * @method handleFocus
     * @param {Event} e The event.
     */
    Tree.prototype.handleFocus = function(e) {
        this.setActiveItem($(e.target));
    };
    /**
     * Bind the event listeners we require.
     *
     * @method bindEventHandlers
     */
    Tree.prototype.bindEventHandlers = function() {
        // Bind event handlers to the tree items. Use event delegates to allow
        // for dynamically loaded parts of the tree.
        this.treeRoot.on({
            click: this.handleClick.bind(this),
            keydown: this.handleKeyDown.bind(this),
            focus: this.handleFocus.bind(this),
        }, SELECTORS.ITEM);
    };
    return /** @alias module:core/tree */ Tree;
});