Proyectos de Subversion Moodle

// 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/>.

/**

 * Tab locking system.

 *

 * This is based on code and examples provided in the ARIA specification.

 * https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html

 *

 * @module     core/local/aria/focuslock

 * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

import Selectors from './selectors';

const lockRegionStack = [];

const initialFocusElementStack = [];

const finalFocusElementStack = [];

let lastFocus = null;

let ignoreFocusChanges = false;

let isLocked = false;

/**

 * The lock handler.

 *

 * This is the item that does a majority of the work.

 * The overall logic from this comes from the examles in the WCAG guidelines.

 *

 * The general idea is that if the focus is not held within by an Element within the lock region, then we replace focus

 * on the first element in the lock region. If the first element is the element previously selected prior to the

 * user-initiated focus change, then instead jump to the last element in the lock region.

 *

 * This gives us a solution which supports focus locking of any kind, which loops in both directions, and which

 * prevents the lock from escaping the modal entirely.

 *

 * If no event is supplied then this function can be used to focus the first element in the lock region, or the

 * last element if the first element is already focused.

 *

 * @method

 * @param {Event} [event] The event from the focus change

 */

const lockHandler = event => {

    if (ignoreFocusChanges) {

        // The focus change was made by an internal call to set focus.

        return;

    }

    // Find the current lock region.

    let lockRegion = getCurrentLockRegion();

    while (lockRegion) {

        if (document.contains(lockRegion)) {

            break;

        }

        // The lock region does not exist.

        // Perhaps it was removed without being untrapped.

        untrapFocus();

        lockRegion = getCurrentLockRegion();

    }

    if (!lockRegion) {

        return;

    }

    if (event && lockRegion.contains(event.target)) {

        lastFocus = event.target;

    } else {

        focusFirstDescendant();

        if (lastFocus == document.activeElement) {

            focusLastDescendant();

        }

        lastFocus = document.activeElement;

    }

};

/**

 * Gets all the focusable elements in the document that are not set to display:none. This is useful

 * because sometimes, a nested modal dialog may be left in the DOM but set to display:none, and you

 * can't actually focus display:none elements.

 *

 * @returns {HTMLElement[]} All focusable elements that aren't display:none, in DOM order

 */

const getAllFocusableElements = () => {

    const allFocusable = document.querySelectorAll(Selectors.elements.focusable);

    // The offsetParent check is a well-perfoming way to ensure that an element in the document

    // does not have display:none.

    return Array.from(allFocusable).filter(focusable => !!focusable.offsetParent);

};

/**

 * Catch event for any keydown during focus lock.

 *

 * This is used to detect situations when the user would be tabbing out to the browser UI. In that

 * case, no 'focus' event is generated, so we need to trap it before it happens via the keydown

 * event.

 *

 * @param {KeyboardEvent} event

 */

const keyDownHandler = event => {

    // We only care about Tab keypresses and only if there is a current lock region.

    if (event.key !== 'Tab' || !getCurrentLockRegion()) {

        return;

    }

    if (!event.shiftKey) {

        // Have they already focused the last focusable element in the document?

        const allFocusable = getAllFocusableElements();

        if (document.activeElement === allFocusable[allFocusable.length - 1]) {

            // When the last thing is focused, focus would go to browser UI next, instead use

            // lockHandler to put focus back on the first element in lock region.

            lockHandler();

            event.preventDefault();

        }

    } else {

        // Have they already focused the first focusable element in the lock region?

        const lockRegion = getCurrentLockRegion();

        const firstFocusable = lockRegion.querySelector(Selectors.elements.focusable);

        if (document.activeElement === firstFocusable) {

            // When the first thing is focused, use lockHandler which will focus the last element

            // in lock region. We do this here rather than using lockHandler to get the focus event

            // because (a) there would be no focus event if the current element is the first in

            // document, and (b) temporarily focusing outside the region could result in unexpected

            // scrolling.

            lockHandler();

            event.preventDefault();

        }

    }

};

/**

 * Focus the first descendant of the current lock region.

 *

 * @method

 * @returns {Bool} Whether a node was focused

 */

const focusFirstDescendant = () => {

    const lockRegion = getCurrentLockRegion();

    // Grab all elements in the lock region and attempt to focus each element until one is focused.

    // We can capture most of this in the query selector, but some cases may still reject focus.

    // For example, a disabled text area cannot be focused, and it becomes difficult to provide a decent query selector

    // to capture this.

    // The use of Array.some just ensures that we stop as soon as we have a successful focus.

    const focusableElements = Array.from(lockRegion.querySelectorAll(Selectors.elements.focusable));

    // The lock region itself may be focusable. This is particularly true on Moodle's older dialogues.

    // We must include it in the calculation of descendants to ensure that looping works correctly.

    focusableElements.unshift(lockRegion);

    return focusableElements.some(focusableElement => attemptFocus(focusableElement));

};

/**

 * Focus the last descendant of the current lock region.

 *

 * @method

 * @returns {Bool} Whether a node was focused

 */

const focusLastDescendant = () => {

    const lockRegion = getCurrentLockRegion();

    // Grab all elements in the lock region, reverse them, and attempt to focus each element until one is focused.

    // We can capture most of this in the query selector, but some cases may still reject focus.

    // For example, a disabled text area cannot be focused, and it becomes difficult to provide a decent query selector

    // to capture this.

    // The use of Array.some just ensures that we stop as soon as we have a successful focus.

    const focusableElements = Array.from(lockRegion.querySelectorAll(Selectors.elements.focusable)).reverse();

    // The lock region itself may be focusable. This is particularly true on Moodle's older dialogues.

    // We must include it in the calculation of descendants to ensure that looping works correctly.

    focusableElements.push(lockRegion);

    return focusableElements.some(focusableElement => attemptFocus(focusableElement));

};

/**

 * Check whether the supplied focusTarget is actually focusable.

 * There are cases where a normally focusable element can reject focus.

 *

 * Note: This example is a wholesale copy of the WCAG example.

 *

 * @method

 * @param {HTMLElement} focusTarget

 * @returns {Bool}

 */

const isFocusable = focusTarget => {

    if (focusTarget.tabIndex > 0 || (focusTarget.tabIndex === 0 && focusTarget.getAttribute('tabIndex') !== null)) {

        return true;

    }

    if (focusTarget.disabled) {

        return false;

    }

    switch (focusTarget.nodeName) {

        case 'A':

            return !!focusTarget.href && focusTarget.rel != 'ignore';

        case 'INPUT':

            return focusTarget.type != 'hidden' && focusTarget.type != 'file';

        case 'BUTTON':

        case 'SELECT':

        case 'TEXTAREA':

            return true;

        default:

            return false;

    }

};

/**

 * Attempt to focus the supplied focusTarget.

 *

 * Note: This example is a heavily inspired by the WCAG example.

 *

 * @method

 * @param {HTMLElement} focusTarget

 * @returns {Bool} Whether focus was successful o rnot.

 */

const attemptFocus = focusTarget => {

    if (!isFocusable(focusTarget)) {

        return false;

    }

    // The ignoreFocusChanges variable prevents the focus event handler from interfering and entering a fight with itself.

    ignoreFocusChanges = true;

    try {

        focusTarget.focus();

    } catch (e) {

        // Ignore failures. We will just try to focus the next element in the list.

    }

    ignoreFocusChanges = false;

    // If focus was successful the activeElement will be the one we focused.

    return (document.activeElement === focusTarget);

};

/**

 * Get the current lock region from the top of the stack.

 *

 * @method

 * @returns {HTMLElement}

 */

const getCurrentLockRegion = () => {

    return lockRegionStack[lockRegionStack.length - 1];

};

/**

 * Add a new lock region to the stack.

 *

 * @method

 * @param {HTMLElement} newLockRegion

 */

const addLockRegionToStack = newLockRegion => {

    if (newLockRegion === getCurrentLockRegion()) {

        return;

    }

    lockRegionStack.push(newLockRegion);

    const currentLockRegion = getCurrentLockRegion();

    // Append an empty div which can be focused just outside of the item locked.

    // This locks tab focus to within the tab region, and does not allow it to extend back into the window by

    // guaranteeing the existence of a tabable item after the lock region which can be focused but which will be caught

    // by the handler.

    const element = document.createElement('div');

    element.tabIndex = 0;

    element.style.position = 'fixed';

    element.style.top = 0;

    element.style.left = 0;

    const initialNode = element.cloneNode();

    currentLockRegion.parentNode.insertBefore(initialNode, currentLockRegion);

    initialFocusElementStack.push(initialNode);

    const finalNode = element.cloneNode();

    currentLockRegion.parentNode.insertBefore(finalNode, currentLockRegion.nextSibling);

    finalFocusElementStack.push(finalNode);

};

/**

 * Remove the top lock region from the stack.

 *

 * @method

 */

const removeLastLockRegionFromStack = () => {

    // Take the top element off the stack, and replce the current lockRegion value.

    lockRegionStack.pop();

    const finalNode = finalFocusElementStack.pop();

    if (finalNode) {

        // The final focus element may have been removed if it was part of a parent item.

        finalNode.remove();

    }

    const initialNode = initialFocusElementStack.pop();

    if (initialNode) {

        // The initial focus element may have been removed if it was part of a parent item.

        initialNode.remove();

    }

};

/**

 * Whether any region is left in the stack.

 *

 * @return {Bool}

 */

const hasTrappedRegionsInStack = () => {

    return !!lockRegionStack.length;

};

/**

 * Start trapping the focus and lock it to the specified newLockRegion.

 *

 * @method

 * @param {HTMLElement} newLockRegion The container to lock focus to

 */

export const trapFocus = newLockRegion => {

    // Update the lock region stack.

    // This allows us to support nesting.

    addLockRegionToStack(newLockRegion);

    if (!isLocked) {

        // Add the focus handler.

        document.addEventListener('focus', lockHandler, true);

        document.addEventListener('keydown', keyDownHandler, true);

    }

    // Attempt to focus on the first item in the lock region.

    if (!focusFirstDescendant()) {

        const currentLockRegion = getCurrentLockRegion();

        // No focusable descendants found in the region yet.

        // This can happen when the region is locked before content is generated.

        // Focus on the region itself for now.

        const originalRegionTabIndex = currentLockRegion.tabIndex;

        currentLockRegion.tabIndex = 0;

        attemptFocus(currentLockRegion);

        currentLockRegion.tabIndex = originalRegionTabIndex;

    }

    // Keep track of the last item focused.

    lastFocus = document.activeElement;

    isLocked = true;

};

/**

 * Stop trapping the focus.

 *

 * @method

 */

export const untrapFocus = () => {

    // Remove the top region from the stack.

    removeLastLockRegionFromStack();

    if (hasTrappedRegionsInStack()) {

        // The focus manager still has items in the stack.

        return;

    }

    document.removeEventListener('focus', lockHandler, true);

    document.removeEventListener('keydown', keyDownHandler, true);

    lastFocus = null;

    ignoreFocusChanges = false;

    isLocked = false;

};