[Annotations] Add some aria-owns in the text layer to link to annotat…

…ions (bug 1780375) This patch doesn't structurally change the text layer: it just adds some aria-owns attributes to some spans. The aria-owns attribute expect to have an element id, hence it's why it adds back an id on the element rendering an annotation, but this id is built in using crypto.randomUUID to avoid any potential issues with the hash in the url. The elements in the annotation layer are moved into the DOM in order to have them in the same "order" as they visually are. The overall goal is to help screen readers to present to the user the annotations as they visually are and as they come in the text flow. It is clearly not perfect, but it should improve readability for some people with visual disabilities.
mozilla · Aug 4, 2022 · 38a0e2f · 38a0e2f
1 parent e88c90e
commit 38a0e2f
Show file tree

Hide file tree

Showing 22 changed files with 433 additions and 243 deletions.
diff --git a/src/display/annotation_layer.js b/src/display/annotation_layer.js
@@ -31,6 +31,7 @@ import {
 import {
   DOMSVGFactory,
   getFilenameFromUrl,
+  IdRandomPrefix,
   PDFDateString,
 } from "./display_utils.js";
 import { AnnotationStorage } from "./annotation_storage.js";
@@ -2473,7 +2474,7 @@ class AnnotationLayer {
    * @memberof AnnotationLayer
    */
   static render(parameters) {
-    const { annotations, div, viewport } = parameters;
+    const { annotations, div, viewport, accessibilityManager } = parameters;
 
     this.#setDimensions(div, viewport);
 
@@ -2525,15 +2526,34 @@ class AnnotationLayer {
         }
         if (Array.isArray(rendered)) {
           for (const renderedElement of rendered) {
+            const contentElement =
+              renderedElement.firstChild || renderedElement;
+            contentElement.id = `${IdRandomPrefix}${data.id}`;
+
             div.append(renderedElement);
+            accessibilityManager?.moveElementInDOM(
+              div,
+              rendered,
+              contentElement,
+              /* isRemovable = */ false
+            );
           }
         } else {
           if (element instanceof PopupAnnotationElement) {
             // Popup annotation elements should not be on top of other
             // annotation elements to prevent interfering with mouse events.
             div.prepend(rendered);
           } else {
+            const contentElement = rendered.firstChild || rendered;
+            contentElement.id = `${IdRandomPrefix}${data.id}`;
+
             div.append(rendered);
+            accessibilityManager?.moveElementInDOM(
+              div,
+              rendered,
+              contentElement,
+              /* isRemovable = */ false
+            );
           }
         }
       }

diff --git a/src/display/display_utils.js b/src/display/display_utils.js
@@ -23,6 +23,19 @@ import { BaseException, stringToBytes, Util, warn } from "../shared/util.js";
 
 const SVG_NS = "http://www.w3.org/2000/svg";
 
+const IdRandomPrefix = (() => {
+  if (typeof globalThis.crypto !== "undefined") {
+    return `${globalThis.crypto.randomUUID()}-`;
+  }
+
+  const digits = new Array(36)
+    .fill(null)
+    .map(() => Math.floor(Math.random() * 16).toString(16));
+  digits[8] = digits[13] = digits[18] = digits[23] = "-";
+
+  return digits.join("");
+})();
+
 class PixelsPerInch {
   static CSS = 96.0;
 
@@ -653,6 +666,7 @@ export {
   getPdfFilenameFromUrl,
   getRGB,
   getXfaPageViewport,
+  IdRandomPrefix,
   isDataScheme,
   isPdfFile,
   isValidFetchUrl,

diff --git a/src/display/editor/annotation_editor_layer.js b/src/display/editor/annotation_editor_layer.js
@@ -18,11 +18,12 @@
 /** @typedef {import("./tools.js").AnnotationEditorUIManager} AnnotationEditorUIManager */
 // eslint-disable-next-line max-len
 /** @typedef {import("../annotation_storage.js").AnnotationStorage} AnnotationStorage */
+// eslint-disable-next-line max-len
+/** @typedef {import("../../web/text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 /** @typedef {import("../../web/interfaces").IL10n} IL10n */
 
-import { AnnotationEditorType, shadow } from "../../shared/util.js";
 import { bindEvents, KeyboardManager } from "./tools.js";
-import { binarySearchFirstItem } from "../display_utils.js";
+import { AnnotationEditorType } from "../../shared/util.js";
 import { FreeTextEditor } from "./freetext.js";
 import { InkEditor } from "./ink.js";
 
@@ -33,6 +34,7 @@ import { InkEditor } from "./ink.js";
  * @property {AnnotationEditorUIManager} uiManager
  * @property {boolean} enabled
  * @property {AnnotationStorage} annotationStorage
+ * @property {TextAccessibilityManager} [accessibilityManager]
  * @property {number} pageIndex
  * @property {IL10n} l10n
  */
@@ -41,6 +43,8 @@ import { InkEditor } from "./ink.js";
  * Manage all the different editors on a page.
  */
 class AnnotationEditorLayer {
+  #accessibilityManager;
+
   #allowClick = false;
 
   #boundPointerup = this.pointerup.bind(this);
@@ -51,14 +55,8 @@ class AnnotationEditorLayer {
 
   #isCleaningUp = false;
 
-  #textLayerMap = new WeakMap();
-
-  #textNodes = new Map();
-
   #uiManager;
 
-  #waitingEditors = new Set();
-
   static _initialized = false;
 
   /**
@@ -76,43 +74,11 @@ class AnnotationEditorLayer {
     this.annotationStorage = options.annotationStorage;
     this.pageIndex = options.pageIndex;
     this.div = options.div;
+    this.#accessibilityManager = options.accessibilityManager;
 
     this.#uiManager.addLayer(this);
   }
 
-  get textLayerElements() {
-    // When zooming the text layer is removed from the DOM and sometimes
-    // it's rebuilt hence the nodes are no longer valid.
-
-    const textLayer = this.div.parentNode
-      .getElementsByClassName("textLayer")
-      .item(0);
-
-    if (!textLayer) {
-      return shadow(this, "textLayerElements", null);
-    }
-
-    let textChildren = this.#textLayerMap.get(textLayer);
-    if (textChildren) {
-      return textChildren;
-    }
-
-    textChildren = textLayer.querySelectorAll(`span[role="presentation"]`);
-    if (textChildren.length === 0) {
-      return shadow(this, "textLayerElements", null);
-    }
-
-    textChildren = Array.from(textChildren);
-    textChildren.sort(AnnotationEditorLayer.#compareElementPositions);
-    this.#textLayerMap.set(textLayer, textChildren);
-
-    return textChildren;
-  }
-
-  get #hasTextLayer() {
-    return !!this.div.parentNode.querySelector(".textLayer .endOfContent");
-  }
-
   /**
    * Update the toolbar if it's required to reflect the tool currently used.
    * @param {number} mode
@@ -226,7 +192,7 @@ class AnnotationEditorLayer {
 
   detach(editor) {
     this.#editors.delete(editor.id);
-    this.removePointerInTextLayer(editor);
+    this.#accessibilityManager?.removePointerInTextLayer(editor.contentDiv);
   }
 
   /**
@@ -279,147 +245,6 @@ class AnnotationEditorLayer {
     }
   }
 
-  /**
-   * Compare the positions of two elements, it must correspond to
-   * the visual ordering.
-   *
-   * @param {HTMLElement} e1
-   * @param {HTMLElement} e2
-   * @returns {number}
-   */
-  static #compareElementPositions(e1, e2) {
-    const rect1 = e1.getBoundingClientRect();
-    const rect2 = e2.getBoundingClientRect();
-
-    if (rect1.y + rect1.height <= rect2.y) {
-      return -1;
-    }
-
-    if (rect2.y + rect2.height <= rect1.y) {
-      return +1;
-    }
-
-    const centerX1 = rect1.x + rect1.width / 2;
-    const centerX2 = rect2.x + rect2.width / 2;
-
-    return centerX1 - centerX2;
-  }
-
-  /**
-   * Function called when the text layer has finished rendering.
-   */
-  onTextLayerRendered() {
-    this.#textNodes.clear();
-    for (const editor of this.#waitingEditors) {
-      if (editor.isAttachedToDOM) {
-        this.addPointerInTextLayer(editor);
-      }
-    }
-    this.#waitingEditors.clear();
-  }
-
-  /**
-   * Remove an aria-owns id from a node in the text layer.
-   * @param {AnnotationEditor} editor
-   */
-  removePointerInTextLayer(editor) {
-    if (!this.#hasTextLayer) {
-      this.#waitingEditors.delete(editor);
-      return;
-    }
-
-    const { id } = editor;
-    const node = this.#textNodes.get(id);
-    if (!node) {
-      return;
-    }
-
-    this.#textNodes.delete(id);
-    let owns = node.getAttribute("aria-owns");
-    if (owns?.includes(id)) {
-      owns = owns
-        .split(" ")
-        .filter(x => x !== id)
-        .join(" ");
-      if (owns) {
-        node.setAttribute("aria-owns", owns);
-      } else {
-        node.removeAttribute("aria-owns");
-        node.setAttribute("role", "presentation");
-      }
-    }
-  }
-
-  /**
-   * Find the text node which is the nearest and add an aria-owns attribute
-   * in order to correctly position this editor in the text flow.
-   * @param {AnnotationEditor} editor
-   */
-  addPointerInTextLayer(editor) {
-    if (!this.#hasTextLayer) {
-      // The text layer needs to be there, so we postpone the association.
-      this.#waitingEditors.add(editor);
-      return;
-    }
-
-    this.removePointerInTextLayer(editor);
-
-    const children = this.textLayerElements;
-    if (!children) {
-      return;
-    }
-    const { contentDiv } = editor;
-    const id = editor.getIdForTextLayer();
-
-    const index = binarySearchFirstItem(
-      children,
-      node =>
-        AnnotationEditorLayer.#compareElementPositions(contentDiv, node) < 0
-    );
-    const node = children[Math.max(0, index - 1)];
-    const owns = node.getAttribute("aria-owns");
-    if (!owns?.includes(id)) {
-      node.setAttribute("aria-owns", owns ? `${owns} ${id}` : id);
-    }
-    node.removeAttribute("role");
-
-    this.#textNodes.set(id, node);
-  }
-
-  /**
-   * Move a div in the DOM in order to respect the visual order.
-   * @param {HTMLDivElement} div
-   */
-  moveDivInDOM(editor) {
-    this.addPointerInTextLayer(editor);
-
-    const { div, contentDiv } = editor;
-    if (!this.div.hasChildNodes()) {
-      this.div.append(div);
-      return;
-    }
-
-    const children = Array.from(this.div.childNodes).filter(
-      node => node !== div
-    );
-
-    if (children.length === 0) {
-      return;
-    }
-
-    const index = binarySearchFirstItem(
-      children,
-      node =>
-        AnnotationEditorLayer.#compareElementPositions(contentDiv, node) < 0
-    );
-
-    if (index === 0) {
-      children[0].before(div);
-    } else {
-      children[index - 1].after(div);
-    }
-  }
-
   /**
    * Add a new editor in the current view.
    * @param {AnnotationEditor} editor
@@ -435,11 +260,20 @@ class AnnotationEditorLayer {
       editor.isAttachedToDOM = true;
     }
 
-    this.moveDivInDOM(editor);
+    this.moveEditorInDOM(editor);
     editor.onceAdded();
     this.addToAnnotationStorage(editor);
   }
 
+  moveEditorInDOM(editor) {
+    this.#accessibilityManager?.moveElementInDOM(
+      this.div,
+      editor.div,
+      editor.contentDiv,
+      /* isRemovable = */ true
+    );
+  }
+
   /**
    * Add an editor in the annotation storage.
    * @param {AnnotationEditor} editor
@@ -645,7 +479,7 @@ class AnnotationEditorLayer {
     const endY = event.clientY - rect.y;
 
     editor.translate(endX - editor.startX, endY - editor.startY);
-    this.moveDivInDOM(editor);
+    this.moveEditorInDOM(editor);
     editor.div.focus();
   }
 
@@ -666,15 +500,13 @@ class AnnotationEditorLayer {
     }
 
     for (const editor of this.#editors.values()) {
-      this.removePointerInTextLayer(editor);
+      this.#accessibilityManager?.removePointerInTextLayer(editor.contentDiv);
       editor.isAttachedToDOM = false;
       editor.div.remove();
       editor.parent = null;
     }
-    this.#textNodes.clear();
     this.div = null;
     this.#editors.clear();
-    this.#waitingEditors.clear();
     this.#uiManager.removeLayer(this);
   }
 

diff --git a/src/display/editor/editor.js b/src/display/editor/editor.js
@@ -489,14 +489,6 @@ class AnnotationEditor {
    */
   enableEditing() {}
 
-  /**
-   * Get the id to use in aria-owns when a link is done in the text layer.
-   * @returns {string}
-   */
-  getIdForTextLayer() {
-    return this.id;
-  }
-
   /**
    * Get some properties to update in the UI.
    * @returns {Object}