tor-browser

keyboard.js (14689B)

---

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

"use strict";

loader.lazyRequireGetter(
 this,
 "CssLogic",
 "resource://devtools/server/actors/inspector/css-logic.js",
 true
);
loader.lazyRequireGetter(
 this,
 "getMatchingCSSRules",
 "resource://devtools/shared/inspector/css-logic.js",
 true
);
loader.lazyRequireGetter(
 this,
 "nodeConstants",
 "resource://devtools/shared/dom-node-constants.js"
);
loader.lazyRequireGetter(
 this,
 ["isDefunct", "getAriaRoles"],
 "resource://devtools/server/actors/utils/accessibility.js",
 true
);

const {
 accessibility: {
   AUDIT_TYPE: { KEYBOARD },
   ISSUE_TYPE: {
     [KEYBOARD]: {
       FOCUSABLE_NO_SEMANTICS,
       FOCUSABLE_POSITIVE_TABINDEX,
       INTERACTIVE_NO_ACTION,
       INTERACTIVE_NOT_FOCUSABLE,
       MOUSE_INTERACTIVE_ONLY,
       NO_FOCUS_VISIBLE,
     },
   },
   SCORES: { FAIL, WARNING },
 },
} = require("resource://devtools/shared/constants.js");

// Accessible action for showing long description.
const CLICK_ACTION = "click";

/**
* Focus specific pseudo classes that the keyboard audit simulates to determine
* focus styling.
*/
const FOCUS_PSEUDO_CLASS = ":focus";
const MOZ_FOCUSRING_PSEUDO_CLASS = ":-moz-focusring";

const KEYBOARD_FOCUSABLE_ROLES = new Set([
 Ci.nsIAccessibleRole.ROLE_BUTTONMENU,
 Ci.nsIAccessibleRole.ROLE_CHECKBUTTON,
 Ci.nsIAccessibleRole.ROLE_COMBOBOX,
 Ci.nsIAccessibleRole.ROLE_EDITCOMBOBOX,
 Ci.nsIAccessibleRole.ROLE_ENTRY,
 Ci.nsIAccessibleRole.ROLE_LINK,
 Ci.nsIAccessibleRole.ROLE_LISTBOX,
 Ci.nsIAccessibleRole.ROLE_PASSWORD_TEXT,
 Ci.nsIAccessibleRole.ROLE_PUSHBUTTON,
 Ci.nsIAccessibleRole.ROLE_RADIOBUTTON,
 Ci.nsIAccessibleRole.ROLE_SLIDER,
 Ci.nsIAccessibleRole.ROLE_SEARCHBOX,
 Ci.nsIAccessibleRole.ROLE_SPINBUTTON,
 Ci.nsIAccessibleRole.ROLE_SUMMARY,
 Ci.nsIAccessibleRole.ROLE_SWITCH,
 Ci.nsIAccessibleRole.ROLE_TOGGLE_BUTTON,
]);

const INTERACTIVE_ROLES = new Set([
 ...KEYBOARD_FOCUSABLE_ROLES,
 Ci.nsIAccessibleRole.ROLE_CHECK_MENU_ITEM,
 Ci.nsIAccessibleRole.ROLE_CHECK_RICH_OPTION,
 Ci.nsIAccessibleRole.ROLE_COMBOBOX_OPTION,
 Ci.nsIAccessibleRole.ROLE_MENUITEM,
 Ci.nsIAccessibleRole.ROLE_OPTION,
 Ci.nsIAccessibleRole.ROLE_OUTLINE,
 Ci.nsIAccessibleRole.ROLE_OUTLINEITEM,
 Ci.nsIAccessibleRole.ROLE_PAGETAB,
 Ci.nsIAccessibleRole.ROLE_PARENT_MENUITEM,
 Ci.nsIAccessibleRole.ROLE_RADIO_MENU_ITEM,
 Ci.nsIAccessibleRole.ROLE_RICH_OPTION,
]);

const INTERACTIVE_IF_FOCUSABLE_ROLES = new Set([
 // If article is focusable, we can assume it is inside a feed.
 Ci.nsIAccessibleRole.ROLE_ARTICLE,
 // Column header can be focusable.
 Ci.nsIAccessibleRole.ROLE_COLUMNHEADER,
 Ci.nsIAccessibleRole.ROLE_GRID_CELL,
 Ci.nsIAccessibleRole.ROLE_MENUBAR,
 Ci.nsIAccessibleRole.ROLE_MENUPOPUP,
 Ci.nsIAccessibleRole.ROLE_PAGETABLIST,
 // Row header can be focusable.
 Ci.nsIAccessibleRole.ROLE_ROWHEADER,
 Ci.nsIAccessibleRole.ROLE_SCROLLBAR,
 Ci.nsIAccessibleRole.ROLE_SEPARATOR,
 Ci.nsIAccessibleRole.ROLE_TOOLBAR,
]);

/**
* Determine if a node is dead or is not an element node.
*
* @param   {DOMNode} node
*          Node to be tested for validity.
*
* @returns {boolean}
*          True if the node is either dead or is not an element node.
*/
function isInvalidNode(node) {
 return (
   !node ||
   Cu.isDeadWrapper(node) ||
   node.nodeType !== nodeConstants.ELEMENT_NODE ||
   !node.ownerGlobal
 );
}

/**
* Determine if accessible is focusable with the keyboard.
*
* @param   {nsIAccessible} accessible
*          Accessible for which to determine if it is keyboard focusable.
*
* @returns {boolean}
*          True if focusable with the keyboard.
*/
function isKeyboardFocusable(accessible) {
 const state = {};
 accessible.getState(state, {});
 // State will be focusable even if the tabindex is negative.
 return (
   state.value & Ci.nsIAccessibleStates.STATE_FOCUSABLE &&
   // Platform accessibility will still report STATE_FOCUSABLE even with the
   // tabindex="-1" so we need to check that it is >= 0 to be considered
   // keyboard focusable.
   accessible.DOMNode.tabIndex > -1
 );
}

/**
* Determine if a current node has focus specific styling by applying a
* focus-related pseudo class (such as :focus or :-moz-focusring) to a focusable
* node.
*
* @param   {DOMNode} focusableNode
*          Node to apply focus-related pseudo class to.
* @param   {DOMNode} currentNode
*          Node to be checked for having focus specific styling.
* @param   {string} pseudoClass
*          A focus related pseudo-class to be simulated for style comparison.
*
* @returns {boolean}
*          True if the currentNode has focus specific styling.
*/
function hasStylesForFocusRelatedPseudoClass(
 focusableNode,
 currentNode,
 pseudoClass
) {
 const defaultRules = getMatchingCSSRules(currentNode);

 InspectorUtils.addPseudoClassLock(focusableNode, pseudoClass);

 // Determine a set of properties that are specific to CSS rules that are only
 // present when a focus related pseudo-class is locked in.
 const tempRules = getMatchingCSSRules(currentNode);
 const properties = new Set();
 for (const rule of tempRules) {
   if (!defaultRules.includes(rule)) {
     for (let index = 0; index < rule.style.length; index++) {
       properties.add(rule.style.item(index));
     }
   }
 }

 // If there are no focus specific CSS rules or properties, currentNode does
 // node have any focus specific styling, we are done.
 if (properties.size === 0) {
   InspectorUtils.removePseudoClassLock(focusableNode, pseudoClass);
   return false;
 }

 // Determine values for properties that are focus specific.
 const tempStyle = CssLogic.getComputedStyle(currentNode);
 const focusStyle = {};
 for (const name of properties.values()) {
   focusStyle[name] = tempStyle.getPropertyValue(name);
 }

 InspectorUtils.removePseudoClassLock(focusableNode, pseudoClass);

 // If values for focus specific properties are different from default style
 // values, assume we have focus spefic styles for the currentNode.
 const defaultStyle = CssLogic.getComputedStyle(currentNode);
 for (const name of properties.values()) {
   if (defaultStyle.getPropertyValue(name) !== focusStyle[name]) {
     return true;
   }
 }

 return false;
}

/**
* Check if an element node (currentNode) has distinct focus styling. This
* function also takes into account a case when focus styling is applied to a
* descendant too.
*
* @param   {DOMNode} focusableNode
*          Node to apply focus-related pseudo class to.
* @param   {DOMNode} currentNode
*          Node to be checked for having focus specific styling.
*
* @returns {boolean}
*          True if the node or its descendant has distinct focus styling.
*/
function hasFocusStyling(focusableNode, currentNode) {
 if (isInvalidNode(currentNode)) {
   return false;
 }

 // Check if an element node has distinct :-moz-focusring styling.
 const hasStylesForMozFocusring = hasStylesForFocusRelatedPseudoClass(
   focusableNode,
   currentNode,
   MOZ_FOCUSRING_PSEUDO_CLASS
 );
 if (hasStylesForMozFocusring) {
   return true;
 }

 // Check if an element node has distinct :focus styling.
 const hasStylesForFocus = hasStylesForFocusRelatedPseudoClass(
   focusableNode,
   currentNode,
   FOCUS_PSEUDO_CLASS
 );
 if (hasStylesForFocus) {
   return true;
 }

 // If no element specific focus styles where found, check if its element
 // children have them.
 for (
   let child = currentNode.firstElementChild;
   child;
   child = currentNode.nextnextElementSibling
 ) {
   if (hasFocusStyling(focusableNode, child)) {
     return true;
   }
 }

 return false;
}

/**
* A rule that determines if a focusable accessible object has appropriate focus
* styling.
*
* @param  {nsIAccessible} accessible
*         Accessible to be checked for being focusable and having focus
*         styling.
*
* @return {null | object}
*         Null if accessible has keyboard focus styling, audit report object
*         otherwise.
*/
function focusStyleRule(accessible) {
 const { DOMNode } = accessible;
 if (isInvalidNode(DOMNode)) {
   return null;
 }

 // Ignore non-focusable elements.
 if (!isKeyboardFocusable(accessible)) {
   return null;
 }

 if (hasFocusStyling(DOMNode, DOMNode)) {
   return null;
 }

 // If no browser or author focus styling was found, check if the node is a
 // widget that is themed by platform native theme.
 if (InspectorUtils.isElementThemed(DOMNode)) {
   return null;
 }

 return { score: WARNING, issue: NO_FOCUS_VISIBLE };
}

/**
* A rule that determines if an interactive accessible has any associated
* accessible actions with it. If the element is interactive but and has no
* actions, assistive technology users will not be able to interact with it.
*
* @param  {nsIAccessible} accessible
*         Accessible to be checked for being interactive and having accessible
*         actions.
*
* @return {null | object}
*         Null if accessible is not interactive or if it is and it has
*         accessible action associated with it, audit report object otherwise.
*/
function interactiveRule(accessible) {
 if (!INTERACTIVE_ROLES.has(accessible.role)) {
   return null;
 }

 if (accessible.actionCount > 0) {
   return null;
 }

 return { score: FAIL, issue: INTERACTIVE_NO_ACTION };
}

/**
* A rule that determines if an interactive accessible is also focusable when
* not disabled.
*
* @param  {nsIAccessible} accessible
*         Accessible to be checked for being interactive and being focusable
*         when enabled.
*
* @return {null | object}
*         Null if accessible is not interactive or if it is and it is focusable
*         when enabled, audit report object otherwise.
*/
function focusableRule(accessible) {
 if (!KEYBOARD_FOCUSABLE_ROLES.has(accessible.role)) {
   return null;
 }

 const state = {};
 accessible.getState(state, {});
 // We only expect in interactive accessible object to be focusable if it is
 // not disabled.
 if (state.value & Ci.nsIAccessibleStates.STATE_UNAVAILABLE) {
   return null;
 }

 if (isKeyboardFocusable(accessible)) {
   return null;
 }

 const ariaRoles = getAriaRoles(accessible);
 if (
   ariaRoles &&
   (ariaRoles.includes("combobox") || ariaRoles.includes("listbox"))
 ) {
   // Do not force ARIA combobox or listbox to be focusable.
   return null;
 }

 return { score: FAIL, issue: INTERACTIVE_NOT_FOCUSABLE };
}

/**
* A rule that determines if a focusable accessible has an associated
* interactive role.
*
* @param  {nsIAccessible} accessible
*         Accessible to be checked for having an interactive role if it is
*         focusable.
*
* @return {null | object}
*         Null if accessible is not interactive or if it is and it has an
*         interactive role, audit report object otherwise.
*/
function semanticsRule(accessible) {
 if (
   INTERACTIVE_ROLES.has(accessible.role) ||
   // Visible listboxes will have focusable state when inside comboboxes.
   accessible.role === Ci.nsIAccessibleRole.ROLE_COMBOBOX_LIST
 ) {
   return null;
 }

 if (isKeyboardFocusable(accessible)) {
   if (INTERACTIVE_IF_FOCUSABLE_ROLES.has(accessible.role)) {
     return null;
   }

   // ROLE_TABLE is used for grids too which are considered interactive.
   if (accessible.role === Ci.nsIAccessibleRole.ROLE_TABLE) {
     const ariaRoles = getAriaRoles(accessible);
     if (ariaRoles && ariaRoles.includes("grid")) {
       return null;
     }
   }

   return { score: WARNING, issue: FOCUSABLE_NO_SEMANTICS };
 }

 const state = {};
 accessible.getState(state, {});
 if (
   // Ignore text leafs.
   accessible.role === Ci.nsIAccessibleRole.ROLE_TEXT_LEAF ||
   // Ignore accessibles with no accessible actions.
   accessible.actionCount === 0 ||
   // Ignore labels that have a label for relation with their target because
   // they are clickable.
   (accessible.role === Ci.nsIAccessibleRole.ROLE_LABEL &&
     accessible.getRelationByType(Ci.nsIAccessibleRelation.RELATION_LABEL_FOR)
       .targetsCount > 0) ||
   // Ignore images that are inside an anchor (have linked state).
   (accessible.role === Ci.nsIAccessibleRole.ROLE_GRAPHIC &&
     state.value & Ci.nsIAccessibleStates.STATE_LINKED)
 ) {
   return null;
 }

 // Ignore anything but a click action in the list of actions.
 for (let i = 0; i < accessible.actionCount; i++) {
   if (accessible.getActionName(i) === CLICK_ACTION) {
     return { score: FAIL, issue: MOUSE_INTERACTIVE_ONLY };
   }
 }

 return null;
}

/**
* A rule that determines if an element associated with a focusable accessible
* has a positive tabindex.
*
* @param  {nsIAccessible} accessible
*         Accessible to be checked for having an element with positive tabindex
*         attribute.
*
* @return {null | object}
*         Null if accessible is not focusable or if it is and its element's
*         tabindex attribute is less than 1, audit report object otherwise.
*/
function tabIndexRule(accessible) {
 const { DOMNode } = accessible;
 if (isInvalidNode(DOMNode)) {
   return null;
 }

 if (!isKeyboardFocusable(accessible)) {
   return null;
 }

 if (DOMNode.tabIndex > 0) {
   return { score: WARNING, issue: FOCUSABLE_POSITIVE_TABINDEX };
 }

 return null;
}

function auditKeyboard(accessible) {
 if (isDefunct(accessible)) {
   return null;
 }
 // Do not test anything on accessible objects for documents or frames.
 if (
   accessible.role === Ci.nsIAccessibleRole.ROLE_DOCUMENT ||
   accessible.role === Ci.nsIAccessibleRole.ROLE_INTERNAL_FRAME
 ) {
   return null;
 }

 // Check if interactive accessible can be used by the assistive
 // technology.
 let issue = interactiveRule(accessible);
 if (issue) {
   return issue;
 }

 // Check if interactive accessible is also focusable when enabled.
 issue = focusableRule(accessible);
 if (issue) {
   return issue;
 }

 // Check if accessible object has an element with a positive tabindex.
 issue = tabIndexRule(accessible);
 if (issue) {
   return issue;
 }

 // Check if a focusable accessible has interactive semantics.
 issue = semanticsRule(accessible);
 if (issue) {
   return issue;
 }

 // Check if focusable accessible has associated focus styling.
 issue = focusStyleRule(accessible);
 if (issue) {
   return issue;
 }

 return issue;
}

module.exports.auditKeyboard = auditKeyboard;