lib/amd/src/menu_navigation.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/>.

/**
 * Keyboard initialization for a given html node.
 *
 * @module     core/menu_navigation
 * @copyright  2021 Moodle
 * @author     Mathew May <mathew.solutions>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

const SELECTORS = {
    'menuitem': '[role="menuitem"]',
    'tab': '[role="tab"]',
    'dropdowntoggle': '[data-toggle="dropdown"]',
};

let openDropdownNode = null;

/**
 * Small helper function to check if a given node is null or not.
 *
 * @param {HTMLElement|null} item The node that we want to compare.
 * @param {HTMLElement} fallback Either the first node or final node that can be focused on.
 * @return {HTMLElement}
 */
const clickErrorHandler = (item, fallback) => {
    if (item !== null) {
        return item;
    } else {
        return fallback;
    }
};

/**
 * Control classes etc of the selected dropdown item and its' parent <a>
 *
 * @param {HTMLElement} src The node within the dropdown the user selected.
 */
const menuItemHelper = src => {
    let parent;

    // Do not apply any actions if the selected dropdown item is explicitly instructing to not display an active state.
    if (src.dataset.disableactive) {
        return;
    }
    // Handling for dropdown escapes.
    // A bulk of the handling is already done by aria.js just add polish.
    if (src.classList.contains('dropdown-item')) {
        parent = src.closest('.dropdown-menu');
        const dropDownToggle = document.getElementById(parent.getAttribute('aria-labelledby'));
        dropDownToggle.classList.add('active');
        dropDownToggle.setAttribute('tabindex', 0);
    } else if (src.matches(`${SELECTORS.tab},${SELECTORS.menuitem}`) && !src.matches(SELECTORS.dropdowntoggle)) {
        parent = src.parentElement.parentElement.querySelector('.dropdown-menu');
    } else {
        return;
    }
    // Remove active class from any other dropdown elements.
    Array.prototype.forEach.call(parent.children, node => {
        const menuItem = node.querySelector(SELECTORS.menuitem);
        if (menuItem !== null) {
            menuItem.classList.remove('active');
            // Remove aria selection state.
            menuItem.removeAttribute('aria-current');
        }
    });
    // Set the applicable element's selection state.
    if (src.getAttribute('role') === 'menuitem') {
        src.setAttribute('aria-current', 'true');
    }
};

/**
 * Defined keyboard event handling so we can remove listeners on nodes on resize etc.
 *
 * @param {event} e The triggering element and key presses etc.
 */
const keyboardListenerEvents = e => {
    const src = e.srcElement;
    const firstNode = e.currentTarget.firstElementChild;
    const lastNode = findUsableLastNode(e.currentTarget);

    // Handling for dropdown escapes.
    // A bulk of the handling is already done by aria.js just add polish.
    if (src.classList.contains('dropdown-item')) {
        if (e.key == 'ArrowRight' ||
            e.key == 'ArrowLeft') {
            e.preventDefault();
            if (openDropdownNode !== null) {
                openDropdownNode.parentElement.click();
            }
        }
        if (e.key == ' ' ||
            e.key == 'Enter') {
            e.preventDefault();

            menuItemHelper(src);

            if (!src.parentElement.classList.contains('dropdown')) {
                src.click();
            }
        }
    } else {
        const rtl = window.right_to_left();
        const arrowNext = rtl ? 'ArrowLeft' : 'ArrowRight';
        const arrowPrevious = rtl ? 'ArrowRight' : 'ArrowLeft';

        if (src.getAttribute('role') === 'menuitem') {
            // When not rendered within a dropdown menu, handle keyboard navigation if the element is rendered as a menu item.
            if (e.key == arrowNext) {
                e.preventDefault();
                setFocusNext(src, firstNode);
            }
            if (e.key == arrowPrevious) {
                e.preventDefault();
                setFocusPrev(src, lastNode);
            }
            // Let aria.js handle the dropdowns.
            if (e.key == 'ArrowUp' ||
                e.key == 'ArrowDown') {
                openDropdownNode = src;
                e.preventDefault();
            }
            if (e.key == 'Home') {
                e.preventDefault();
                setFocusHomeEnd(firstNode);
            }
            if (e.key == 'End') {
                e.preventDefault();
                setFocusHomeEnd(lastNode);
            }
        }

        if (e.key == ' ' ||
            e.key == 'Enter') {
            e.preventDefault();
            // Aria.js handles dropdowns etc.
            if (!src.parentElement.classList.contains('dropdown')) {
                src.click();
            }
        }
    }
};

/**
 * Defined click event handling so we can remove listeners on nodes on resize etc.
 *
 * @param {event} e The triggering element and key presses etc.
 */
const clickListenerEvents = e => {
    const src = e.srcElement;
    menuItemHelper(src);
};

/**
 * The initial entry point that a given module can pass a HTMLElement.
 *
 * @param {HTMLElement} elementRoot The menu to add handlers upon.
 */
export default elementRoot => {
    // Remove any and all instances of old listeners on the passed element.
    elementRoot.removeEventListener('keydown', keyboardListenerEvents);
    elementRoot.removeEventListener('click', clickListenerEvents);
    // (Re)apply our event listeners to the passed element.
    elementRoot.addEventListener('keydown', keyboardListenerEvents);
    elementRoot.addEventListener('click', clickListenerEvents);
};

/**
 * Handle the focusing to the next element in the dropdown.
 *
 * @param {HTMLElement|null} currentNode The node that we want to take action on.
 * @param {HTMLElement} firstNode The backup node to focus as a last resort.
 */
const setFocusNext = (currentNode, firstNode) => {
    const listElement = currentNode.parentElement;
    const nextListItem = ((el) => {
        do {
            el = el.nextElementSibling;
        } while (el && !el.offsetHeight); // We only work with the visible tabs.
        return el;
    })(listElement);
    const nodeToSelect = clickErrorHandler(nextListItem, firstNode);
    const parent = listElement.parentElement;
    const isTabList = parent.getAttribute('role') === 'tablist';
    const itemSelector = isTabList ? SELECTORS.tab : SELECTORS.menuitem;
    const menuItem = nodeToSelect.querySelector(itemSelector);
    menuItem.focus();
};

/**
 * Handle the focusing to the previous element in the dropdown.
 *
 * @param {HTMLElement|null} currentNode The node that we want to take action on.
 * @param {HTMLElement} lastNode The backup node to focus as a last resort.
 */
const setFocusPrev = (currentNode, lastNode) => {
    const listElement = currentNode.parentElement;
    const nextListItem = ((el) => {
        do {
            el = el.previousElementSibling;
        } while (el && !el.offsetHeight); // We only work with the visible tabs.
        return el;
    })(listElement);
    const nodeToSelect = clickErrorHandler(nextListItem, lastNode);
    const parent = listElement.parentElement;
    const isTabList = parent.getAttribute('role') === 'tablist';
    const itemSelector = isTabList ? SELECTORS.tab : SELECTORS.menuitem;
    const menuItem = nodeToSelect.querySelector(itemSelector);
    menuItem.focus();
};

/**
 * Focus on either the start or end of a nav list.
 *
 * @param {HTMLElement} node The element to focus on.
 */
const setFocusHomeEnd = node => {
    node.querySelector(SELECTORS.menuitem).focus();
};

/**
 * We need to look within the menu to find a last node we can add focus to.
 *
 * @param {HTMLElement} elementRoot Menu to find a final child node within.
 * @return {HTMLElement}
 */
const findUsableLastNode = elementRoot => {
    const lastNode = elementRoot.lastElementChild;

    // An example is the more menu existing but hidden on the page for the time being.
    if (!lastNode.classList.contains('d-none')) {
        return elementRoot.lastElementChild;
    } else {
        // Cast the HTMLCollection & reverse it.
        const extractedNodes = Array.prototype.map.call(elementRoot.children, node => {
            return node;
        }).reverse();

        // Get rid of any nodes we can not set focus on.
        const nodesToUse = extractedNodes.filter((node => {
            if (!node.classList.contains('d-none')) {
                return node;
            }
        }));

        // If we find no elements we can set focus on, fall back to the absolute first element.
        if (nodesToUse.length !== 0) {
            return nodesToUse[0];
        } else {
            return elementRoot.firstElementChild;
        }
    }
};