tor-browser

accessibility.js (19745B)

---

/* 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";

const DevToolsUtils = require("resource://devtools/shared/DevToolsUtils.js");
const {
 getCurrentZoom,
} = require("resource://devtools/shared/layout/utils.js");
const {
 moveInfobar,
} = require("resource://devtools/server/actors/highlighters/utils/markup.js");
const { truncateString } = require("resource://devtools/shared/string.js");

const STRINGS_URI = "devtools/shared/locales/accessibility.properties";
loader.lazyRequireGetter(
 this,
 "LocalizationHelper",
 "resource://devtools/shared/l10n.js",
 true
);
DevToolsUtils.defineLazyGetter(
 this,
 "L10N",
 () => new LocalizationHelper(STRINGS_URI)
);

const {
 accessibility: {
   AUDIT_TYPE,
   ISSUE_TYPE: {
     [AUDIT_TYPE.KEYBOARD]: {
       FOCUSABLE_NO_SEMANTICS,
       FOCUSABLE_POSITIVE_TABINDEX,
       INTERACTIVE_NO_ACTION,
       INTERACTIVE_NOT_FOCUSABLE,
       MOUSE_INTERACTIVE_ONLY,
       NO_FOCUS_VISIBLE,
     },
     [AUDIT_TYPE.TEXT_LABEL]: {
       AREA_NO_NAME_FROM_ALT,
       DIALOG_NO_NAME,
       DOCUMENT_NO_TITLE,
       EMBED_NO_NAME,
       FIGURE_NO_NAME,
       FORM_FIELDSET_NO_NAME,
       FORM_FIELDSET_NO_NAME_FROM_LEGEND,
       FORM_NO_NAME,
       FORM_NO_VISIBLE_NAME,
       FORM_OPTGROUP_NO_NAME_FROM_LABEL,
       FRAME_NO_NAME,
       HEADING_NO_CONTENT,
       HEADING_NO_NAME,
       IFRAME_NO_NAME_FROM_TITLE,
       IMAGE_NO_NAME,
       INTERACTIVE_NO_NAME,
       MATHML_GLYPH_NO_NAME,
       TOOLBAR_NO_NAME,
     },
   },
   SCORES,
 },
} = require("resource://devtools/shared/constants.js");

// Max string length for truncating accessible name values.
const MAX_STRING_LENGTH = 50;

/**
* The AccessibleInfobar is a class responsible for creating the markup for the
* accessible highlighter. It is also reponsible for updating content within the
* infobar such as role and name values.
*/
class Infobar {
 constructor(highlighter) {
   this.highlighter = highlighter;
   this.audit = new Audit(this);
 }

 get markup() {
   return this.highlighter.markup;
 }

 get document() {
   return this.highlighter.win.document;
 }

 get bounds() {
   return this.highlighter._bounds;
 }

 get options() {
   return this.highlighter.options;
 }

 get win() {
   return this.highlighter.win;
 }

 /**
  * Move the Infobar to the right place in the highlighter.
  *
  * @param  {Element} container
  *         Container of infobar.
  */
 _moveInfobar(container) {
   // Position the infobar using accessible's bounds
   const { left: x, top: y, bottom, width } = this.bounds;
   const infobarBounds = { x, y, bottom, width };

   moveInfobar(container, infobarBounds, this.win);
 }

 /**
  * Build markup for infobar.
  *
  * @param  {Element} root
  *         Root element to build infobar with.
  */
 buildMarkup(root) {
   const container = this.markup.createNode({
     parent: root,
     attributes: {
       class: "accessible-infobar-container",
       id: "accessible-infobar-container",
       "aria-hidden": "true",
       hidden: "true",
     },
   });

   const infobar = this.markup.createNode({
     parent: container,
     attributes: {
       class: "accessible-infobar",
       id: "accessible-infobar",
     },
   });

   const infobarText = this.markup.createNode({
     parent: infobar,
     attributes: {
       class: "accessible-infobar-text",
       id: "accessible-infobar-text",
     },
   });

   this.markup.createNode({
     nodeType: "span",
     parent: infobarText,
     attributes: {
       class: "accessible-infobar-role",
       id: "accessible-infobar-role",
     },
   });

   this.markup.createNode({
     nodeType: "span",
     parent: infobarText,
     attributes: {
       class: "accessible-infobar-name",
       id: "accessible-infobar-name",
     },
   });

   this.audit.buildMarkup(infobarText);
 }

 /**
  * Destroy the Infobar's highlighter.
  */
 destroy() {
   this.highlighter = null;
   this.audit.destroy();
   this.audit = null;
 }

 /**
  * Gets the element with the specified ID.
  *
  * @param  {string} id
  *         Element ID.
  * @return {Element} The element with specified ID.
  */
 getElement(id) {
   return this.highlighter.getElement(id);
 }

 /**
  * Gets the text content of element.
  *
  * @param  {string} id
  *          Element ID to retrieve text content from.
  * @return {string} The text content of the element.
  */
 getTextContent(id) {
   const anonymousContent = this.markup.content;
   return anonymousContent.root.getElementById(id).textContent;
 }

 /**
  * Hide the accessible infobar.
  */
 hide() {
   const container = this.getElement("accessible-infobar-container");
   container.setAttribute("hidden", "true");
 }

 /**
  * Show the accessible infobar highlighter.
  */
 show() {
   const container = this.getElement("accessible-infobar-container");

   // Remove accessible's infobar "hidden" attribute. We do this first to get the
   // computed styles of the infobar container.
   container.removeAttribute("hidden");

   // Update the infobar's position and content.
   this.update(container);
 }

 /**
  * Update content of the infobar.
  */
 update(container) {
   const { audit, name, role } = this.options;

   this.updateRole(role, this.getElement("accessible-infobar-role"));
   this.updateName(name, this.getElement("accessible-infobar-name"));
   this.audit.update(audit);

   // Position the infobar.
   this._moveInfobar(container);
 }

 /**
  * Sets the text content of the specified element.
  *
  * @param  {Element} el
  *         Element to set text content on.
  * @param  {string} text
  *         Text for content.
  */
 setTextContent(el, text) {
   el.setTextContent(text);
 }

 /**
  * Show the accessible's name message.
  *
  * @param  {string} name
  *         Accessible's name value.
  * @param  {Element} el
  *         Element to set text content on.
  */
 updateName(name, el) {
   const nameText = name ? `"${truncateString(name, MAX_STRING_LENGTH)}"` : "";
   this.setTextContent(el, nameText);
 }

 /**
  * Show the accessible's role.
  *
  * @param  {string} role
  *         Accessible's role value.
  * @param  {Element} el
  *         Element to set text content on.
  */
 updateRole(role, el) {
   this.setTextContent(el, role);
 }
}

/**
* Audit component used within the accessible highlighter infobar. This component is
* responsible for rendering and updating its containing AuditReport components that
* display various audit information such as contrast ratio score.
*/
class Audit {
 constructor(infobar) {
   this.infobar = infobar;

   // A list of audit reports to be shown on the fly when highlighting an accessible
   // object.
   this.reports = {
     [AUDIT_TYPE.CONTRAST]: new ContrastRatio(this),
     [AUDIT_TYPE.KEYBOARD]: new Keyboard(this),
     [AUDIT_TYPE.TEXT_LABEL]: new TextLabel(this),
   };
 }

 get markup() {
   return this.infobar.markup;
 }

 buildMarkup(root) {
   const audit = this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-infobar-audit",
       id: "accessible-infobar-audit",
     },
   });

   Object.values(this.reports).forEach(report => report.buildMarkup(audit));
 }

 update(audit = {}) {
   const el = this.getElement("accessible-infobar-audit");
   el.setAttribute("hidden", true);

   let updated = false;
   Object.values(this.reports).forEach(report => {
     if (report.update(audit)) {
       updated = true;
     }
   });

   if (updated) {
     el.removeAttribute("hidden");
   }
 }

 getElement(id) {
   return this.infobar.getElement(id);
 }

 setTextContent(el, text) {
   return this.infobar.setTextContent(el, text);
 }

 destroy() {
   this.infobar = null;
   Object.values(this.reports).forEach(report => report.destroy());
   this.reports = null;
 }
}

/**
* A common interface between audit report components used to render accessibility audit
* information for the currently highlighted accessible object.
*/
class AuditReport {
 constructor(audit) {
   this.audit = audit;
 }

 get markup() {
   return this.audit.markup;
 }

 getElement(id) {
   return this.audit.getElement(id);
 }

 setTextContent(el, text) {
   return this.audit.setTextContent(el, text);
 }

 destroy() {
   this.audit = null;
 }
}

/**
* Contrast ratio audit report that is used to display contrast ratio score as part of the
* inforbar,
*/
class ContrastRatio extends AuditReport {
 buildMarkup(root) {
   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-contrast-ratio-label",
       id: "accessible-contrast-ratio-label",
     },
   });

   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-contrast-ratio-error",
       id: "accessible-contrast-ratio-error",
     },
     text: L10N.getStr("accessibility.contrast.ratio.error"),
   });

   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-contrast-ratio",
       id: "accessible-contrast-ratio-min",
     },
   });

   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-contrast-ratio-separator",
       id: "accessible-contrast-ratio-separator",
     },
   });

   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-contrast-ratio",
       id: "accessible-contrast-ratio-max",
     },
   });
 }

 _fillAndStyleContrastValue(el, { value, className, color, backgroundColor }) {
   value = value.toFixed(2);
   this.setTextContent(el, value);
   el.classList?.add(className);
   el.setAttribute(
     "style",
     `--accessibility-highlighter-contrast-ratio-color: rgba(${color});` +
       `--accessibility-highlighter-contrast-ratio-bg: rgba(${backgroundColor});`
   );
   el.removeAttribute("hidden");
 }

 /**
  * Update contrast ratio score infobar markup.
  *
  * @param  {object}
  *         Audit report for a given highlighted accessible.
  * @return {boolean}
  *         True if the contrast ratio markup was updated correctly and infobar audit
  *         block should be visible.
  */
 update(audit) {
   const els = {};
   for (const key of ["label", "min", "max", "error", "separator"]) {
     const el = (els[key] = this.getElement(
       `accessible-contrast-ratio-${key}`
     ));
     if (["min", "max"].includes(key)) {
       Object.values(SCORES).forEach(className =>
         el.classList?.remove(className)
       );
       this.setTextContent(el, "");
     }

     el.setAttribute("hidden", true);
     el.removeAttribute("style");
   }

   if (!audit) {
     return false;
   }

   const contrastRatio = audit[AUDIT_TYPE.CONTRAST];
   if (!contrastRatio) {
     return false;
   }

   const { isLargeText, error } = contrastRatio;
   this.setTextContent(
     els.label,
     L10N.getStr(
       `accessibility.contrast.ratio.label${isLargeText ? ".large" : ""}`
     )
   );
   els.label.removeAttribute("hidden");
   if (error) {
     els.error.removeAttribute("hidden");
     return true;
   }

   if (contrastRatio.value) {
     const { value, color, score, backgroundColor } = contrastRatio;
     this._fillAndStyleContrastValue(els.min, {
       value,
       className: score,
       color,
       backgroundColor,
     });
     return true;
   }

   const {
     min,
     max,
     color,
     backgroundColorMin,
     backgroundColorMax,
     scoreMin,
     scoreMax,
   } = contrastRatio;
   this._fillAndStyleContrastValue(els.min, {
     value: min,
     className: scoreMin,
     color,
     backgroundColor: backgroundColorMin,
   });
   els.separator.removeAttribute("hidden");
   this._fillAndStyleContrastValue(els.max, {
     value: max,
     className: scoreMax,
     color,
     backgroundColor: backgroundColorMax,
   });

   return true;
 }
}

/**
* Keyboard audit report that is used to display a problem with keyboard
* accessibility as part of the inforbar.
*/
class Keyboard extends AuditReport {
 /**
  * A map from keyboard issues to annotation component properties.
  */
 static get ISSUE_TO_INFOBAR_LABEL_MAP() {
   return {
     [FOCUSABLE_NO_SEMANTICS]: "accessibility.keyboard.issue.semantics",
     [FOCUSABLE_POSITIVE_TABINDEX]: "accessibility.keyboard.issue.tabindex",
     [INTERACTIVE_NO_ACTION]: "accessibility.keyboard.issue.action",
     [INTERACTIVE_NOT_FOCUSABLE]: "accessibility.keyboard.issue.focusable",
     [MOUSE_INTERACTIVE_ONLY]: "accessibility.keyboard.issue.mouse.only",
     [NO_FOCUS_VISIBLE]: "accessibility.keyboard.issue.focus.visible",
   };
 }

 buildMarkup(root) {
   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-audit",
       id: "accessible-keyboard",
     },
   });
 }

 /**
  * Update keyboard audit infobar markup.
  *
  * @param  {object}
  *         Audit report for a given highlighted accessible.
  * @return {boolean}
  *         True if the keyboard markup was updated correctly and infobar audit
  *         block should be visible.
  */
 update(audit) {
   const el = this.getElement("accessible-keyboard");
   el.setAttribute("hidden", true);
   Object.values(SCORES).forEach(className => el.classList?.remove(className));

   if (!audit) {
     return false;
   }

   const keyboardAudit = audit[AUDIT_TYPE.KEYBOARD];
   if (!keyboardAudit) {
     return false;
   }

   const { issue, score } = keyboardAudit;
   this.setTextContent(
     el,
     L10N.getStr(Keyboard.ISSUE_TO_INFOBAR_LABEL_MAP[issue])
   );
   el.classList?.add(score);
   el.removeAttribute("hidden");

   return true;
 }
}

/**
* Text label audit report that is used to display a problem with text alternatives
* as part of the inforbar.
*/
class TextLabel extends AuditReport {
 /**
  * A map from text label issues to annotation component properties.
  */
 static get ISSUE_TO_INFOBAR_LABEL_MAP() {
   return {
     [AREA_NO_NAME_FROM_ALT]: "accessibility.text.label.issue.area",
     [DIALOG_NO_NAME]: "accessibility.text.label.issue.dialog",
     [DOCUMENT_NO_TITLE]: "accessibility.text.label.issue.document.title",
     [EMBED_NO_NAME]: "accessibility.text.label.issue.embed",
     [FIGURE_NO_NAME]: "accessibility.text.label.issue.figure",
     [FORM_FIELDSET_NO_NAME]: "accessibility.text.label.issue.fieldset",
     [FORM_FIELDSET_NO_NAME_FROM_LEGEND]:
       "accessibility.text.label.issue.fieldset.legend2",
     [FORM_NO_NAME]: "accessibility.text.label.issue.form",
     [FORM_NO_VISIBLE_NAME]: "accessibility.text.label.issue.form.visible",
     [FORM_OPTGROUP_NO_NAME_FROM_LABEL]:
       "accessibility.text.label.issue.optgroup.label2",
     [FRAME_NO_NAME]: "accessibility.text.label.issue.frame",
     [HEADING_NO_CONTENT]: "accessibility.text.label.issue.heading.content",
     [HEADING_NO_NAME]: "accessibility.text.label.issue.heading",
     [IFRAME_NO_NAME_FROM_TITLE]: "accessibility.text.label.issue.iframe",
     [IMAGE_NO_NAME]: "accessibility.text.label.issue.image",
     [INTERACTIVE_NO_NAME]: "accessibility.text.label.issue.interactive",
     [MATHML_GLYPH_NO_NAME]: "accessibility.text.label.issue.glyph",
     [TOOLBAR_NO_NAME]: "accessibility.text.label.issue.toolbar",
   };
 }

 buildMarkup(root) {
   this.markup.createNode({
     nodeType: "span",
     parent: root,
     attributes: {
       class: "accessible-audit",
       id: "accessible-text-label",
     },
   });
 }

 /**
  * Update text label audit infobar markup.
  *
  * @param  {object}
  *         Audit report for a given highlighted accessible.
  * @return {boolean}
  *         True if the text label markup was updated correctly and infobar
  *         audit block should be visible.
  */
 update(audit) {
   const el = this.getElement("accessible-text-label");
   el.setAttribute("hidden", true);
   Object.values(SCORES).forEach(className => el.classList?.remove(className));

   if (!audit) {
     return false;
   }

   const textLabelAudit = audit[AUDIT_TYPE.TEXT_LABEL];
   if (!textLabelAudit) {
     return false;
   }

   const { issue, score } = textLabelAudit;
   this.setTextContent(
     el,
     L10N.getStr(TextLabel.ISSUE_TO_INFOBAR_LABEL_MAP[issue])
   );
   el.classList?.add(score);
   el.removeAttribute("hidden");

   return true;
 }
}

/**
* A helper function that calculate accessible object bounds and positioning to
* be used for highlighting.
*
* @param  {object} win
*         window that contains accessible object.
* @param  {object} options
*         Object used for passing options:
*         - {Number} x
*           x coordinate of the top left corner of the accessible object
*         - {Number} y
*           y coordinate of the top left corner of the accessible object
*         - {Number} w
*           width of the the accessible object
*         - {Number} h
*           height of the the accessible object
* @return {object | null} Returns, if available, positioning and bounds information for
*                 the accessible object.
*/
function getBounds(win, { x, y, w, h }) {
 const { mozInnerScreenX, mozInnerScreenY, scrollX, scrollY } = win;
 const zoom = getCurrentZoom(win);
 let left = x;
 let right = x + w;
 let top = y;
 let bottom = y + h;

 left -= mozInnerScreenX - scrollX;
 right -= mozInnerScreenX - scrollX;
 top -= mozInnerScreenY - scrollY;
 bottom -= mozInnerScreenY - scrollY;

 left *= zoom;
 right *= zoom;
 top *= zoom;
 bottom *= zoom;

 const width = right - left;
 const height = bottom - top;

 return { left, right, top, bottom, width, height };
}

/**
* A helper function that calculate accessible object bounds and positioning to
* be used for highlighting in browser toolbox.
*
* @param  {object} win
*         window that contains accessible object.
* @param  {object} options
*         Object used for passing options:
*         - {Number} x
*           x coordinate of the top left corner of the accessible object
*         - {Number} y
*           y coordinate of the top left corner of the accessible object
*         - {Number} w
*           width of the the accessible object
*         - {Number} h
*           height of the the accessible object
*         - {Number} zoom
*           zoom level of the accessible object's parent window
* @return {object | null} Returns, if available, positioning and bounds information for
*                 the accessible object.
*/
function getBoundsXUL(win, { x, y, w, h, zoom }) {
 const { mozInnerScreenX, mozInnerScreenY } = win;
 let left = x;
 let right = x + w;
 let top = y;
 let bottom = y + h;

 left *= zoom;
 right *= zoom;
 top *= zoom;
 bottom *= zoom;

 left -= mozInnerScreenX;
 right -= mozInnerScreenX;
 top -= mozInnerScreenY;
 bottom -= mozInnerScreenY;

 const width = right - left;
 const height = bottom - top;

 return { left, right, top, bottom, width, height };
}

exports.MAX_STRING_LENGTH = MAX_STRING_LENGTH;
exports.getBounds = getBounds;
exports.getBoundsXUL = getBoundsXUL;
exports.Infobar = Infobar;