[Annotations] Add some aria-owns in the text layer to link to annotations (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.

src/display/annotation_layer.js

@@ -29,6 +29,7 @@ import {
   warn,
 } from "../shared/util.js";
 import {
+  AnnotationPrefix,
   DOMSVGFactory,
   getFilenameFromUrl,
   PDFDateString,
@@ -1901,7 +1902,8 @@ class PopupElement {
     }
     if (this.hideElement.hidden) {
       this.hideElement.hidden = false;
-      this.container.style.zIndex += 1;
+      this.container.style.zIndex =
+        parseInt(this.container.style.zIndex) + 1000;
     }
   }
 
@@ -1918,7 +1920,8 @@ class PopupElement {
     }
     if (!this.hideElement.hidden && !this.pinned) {
       this.hideElement.hidden = true;
-      this.container.style.zIndex -= 1;
+      this.container.style.zIndex =
+        parseInt(this.container.style.zIndex) - 1000;
     }
   }
 }
@@ -2465,6 +2468,19 @@ class FileAttachmentAnnotationElement extends AnnotationElement {
  */
 
 class AnnotationLayer {
+  static #appendElement(element, id, div, accessibilityManager) {
+    const contentElement = element.firstChild || element;
+    contentElement.id = `${AnnotationPrefix}${id}`;
+
+    div.append(element);
+    accessibilityManager?.moveElementInDOM(
+      div,
+      element,
+      contentElement,
+      /* isRemovable = */ false
+    );
+  }
+
   /**
    * Render a new annotation layer with all annotation elements.
    *
@@ -2473,9 +2489,10 @@ class AnnotationLayer {
    * @memberof AnnotationLayer
    */
   static render(parameters) {
-    const { annotations, div, viewport } = parameters;
+    const { annotations, div, viewport, accessibilityManager } = parameters;
 
     this.#setDimensions(div, viewport);
+    let zIndex = 0;
 
     for (const data of annotations) {
       if (data.annotationType !== AnnotationType.POPUP) {
@@ -2508,15 +2525,33 @@ class AnnotationLayer {
         }
         if (Array.isArray(rendered)) {
           for (const renderedElement of rendered) {
-            div.append(renderedElement);
+            renderedElement.style.zIndex = zIndex++;
+            AnnotationLayer.#appendElement(
+              renderedElement,
+              data.id,
+              div,
+              accessibilityManager
+            );
           }
         } else {
+          // The accessibility manager will move the annotation in the DOM in
+          // order to match the visual ordering.
+          // But if an annotation is above an other one, then we must draw it
+          // after the other one whatever the order is in the DOM, hence the
+          // use of the z-index.
+          rendered.style.zIndex = zIndex++;
+
           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 {
-            div.append(rendered);
+            AnnotationLayer.#appendElement(
+              rendered,
+              data.id,
+              div,
+              accessibilityManager
+            );
           }
         }
       }

src/display/display_utils.js

@@ -23,6 +23,8 @@ import { BaseException, stringToBytes, Util, warn } from "../shared/util.js";
 
 const SVG_NS = "http://www.w3.org/2000/svg";
 
+const AnnotationPrefix = "pdfjs_internal_id_";
+
 class PixelsPerInch {
   static CSS = 96.0;
 
@@ -652,6 +654,7 @@ function getCurrentTransformInverse(ctx) {
 }
 
 export {
+  AnnotationPrefix,
   binarySearchFirstItem,
   deprecated,
   DOMCanvasFactory,

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);
@@ -53,14 +57,8 @@ class AnnotationEditorLayer {
 
   #isCleaningUp = false;
 
-  #textLayerMap = new WeakMap();
-
-  #textNodes = new Map();
-
   #uiManager;
 
-  #waitingEditors = new Set();
-
   static _initialized = false;
 
   /**
@@ -78,43 +76,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
@@ -228,7 +194,7 @@ class AnnotationEditorLayer {
 
   detach(editor) {
     this.#editors.delete(editor.id);
-    this.removePointerInTextLayer(editor);
+    this.#accessibilityManager?.removePointerInTextLayer(editor.contentDiv);
   }
 
   /**
@@ -281,147 +247,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
@@ -437,11 +262,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
@@ -658,7 +492,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();
   }
 
@@ -679,15 +513,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);
   }
 

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}

src/display/editor/freetext.js

@@ -385,11 +385,6 @@ class FreeTextEditor extends AnnotationEditor {
     this.editorDiv.setAttribute("aria-multiline", true);
   }
 
-  /** @inheritdoc */
-  getIdForTextLayer() {
-    return this.editorDiv.id;
-  }
-
   /** @inheritdoc */
   render() {
     if (this.div) {

src/display/editor/ink.js

@@ -488,7 +488,7 @@ class InkEditor extends AnnotationEditor {
 
     // When commiting, the position of this editor is changed, hence we must
     // move it to the right position in the DOM.
-    this.parent.moveDivInDOM(this);
+    this.parent.moveEditorInDOM(this);
     // After the div has been moved in the DOM, the focus may have been stolen
     // by document.body, hence we just keep it here.
     this.div.focus();

src/display/editor/tools.js

@@ -428,8 +428,6 @@ class AnnotationEditorUIManager {
 
   #boundOnPageChanging = this.onPageChanging.bind(this);
 
-  #boundOnTextLayerRendered = this.onTextLayerRendered.bind(this);
-
   #previousStates = {
     isEditing: false,
     isEmpty: true,
@@ -474,14 +472,12 @@ class AnnotationEditorUIManager {
     this.#eventBus = eventBus;
     this.#eventBus._on("editingaction", this.#boundOnEditingAction);
     this.#eventBus._on("pagechanging", this.#boundOnPageChanging);
-    this.#eventBus._on("textlayerrendered", this.#boundOnTextLayerRendered);
   }
 
   destroy() {
     this.#removeKeyboardManager();
     this.#eventBus._off("editingaction", this.#boundOnEditingAction);
     this.#eventBus._off("pagechanging", this.#boundOnPageChanging);
-    this.#eventBus._off("textlayerrendered", this.#boundOnTextLayerRendered);
     for (const layer of this.#allLayers.values()) {
       layer.destroy();
     }
@@ -497,12 +493,6 @@ class AnnotationEditorUIManager {
     this.#currentPageIndex = pageNumber - 1;
   }
 
-  onTextLayerRendered({ pageNumber }) {
-    const pageIndex = pageNumber - 1;
-    const layer = this.#allLayers.get(pageIndex);
-    layer?.onTextLayerRendered();
-  }
-
   focusMainContainer() {
     this.#container.focus();
   }

test/integration-boot.js

@@ -32,6 +32,7 @@ async function runTests(results) {
       "find_spec.js",
       "freetext_editor_spec.js",
       "ink_editor_spec.js",
+      "a11y_spec.js",
     ],
   });
 

test/integration/accessibility_spec.js

@@ -66,4 +66,44 @@ describe("accessibility", () => {
       );
     });
   });
+
+  describe("Annotation", () => {
+    let pages;
+
+    beforeAll(async () => {
+      pages = await loadAndWait(
+        "tracemonkey_a11y.pdf",
+        ".textLayer .endOfContent"
+      );
+    });
+
+    afterAll(async () => {
+      await closePages(pages);
+    });
+
+    function getSpans(page) {
+      return page.evaluate(() => {
+        const elements = document.querySelectorAll(
+          `.textLayer span[aria-owns]:not([role="presentation"])`
+        );
+        const results = [];
+        for (const element of elements) {
+          results.push(element.innerText);
+        }
+        return results;
+      });
+    }
+
+    it("must check that some spans are linked to some annotations thanks to aria-owns", async () => {
+      await Promise.all(
+        pages.map(async ([browserName, page]) => {
+          const spanContents = await getSpans(page);
+
+          expect(spanContents)
+            .withContext(`In ${browserName}`)
+            .toEqual(["Languages", "@intel.com", "Abstract", "Introduction"]);
+        })
+      );
+    });
+  });
 });

test/integration/freetext_editor_spec.js

@@ -15,7 +15,7 @@
 
 const {
   closePages,
-  editorPrefix,
+  getEditorSelector,
   getSelectedEditors,
   loadAndWait,
 } = require("./test_utils.js");
@@ -51,9 +51,9 @@ describe("Editor", () => {
 
           const data = "Hello PDF.js World !!";
           await page.mouse.click(rect.x + 100, rect.y + 100);
-          await page.type(`${editorPrefix}0 .internal`, data);
+          await page.type(`${getEditorSelector(0)} .internal`, data);
 
-          const editorRect = await page.$eval(`${editorPrefix}0`, el => {
+          const editorRect = await page.$eval(getEditorSelector(0), el => {
             const { x, y, width, height } = el.getBoundingClientRect();
             return {
               x,
@@ -73,7 +73,7 @@ describe("Editor", () => {
             .withContext(`In ${browserName}`)
             .toEqual(1);
 
-          const content = await page.$eval(`${editorPrefix}0`, el =>
+          const content = await page.$eval(getEditorSelector(0), el =>
             el.innerText.trimEnd()
           );
           expect(content).withContext(`In ${browserName}`).toEqual(data);
@@ -84,7 +84,7 @@ describe("Editor", () => {
     it("must copy/paste", async () => {
       await Promise.all(
         pages.map(async ([browserName, page]) => {
-          const editorRect = await page.$eval(`${editorPrefix}0`, el => {
+          const editorRect = await page.$eval(getEditorSelector(0), el => {
             const { x, y, width, height } = el.getBoundingClientRect();
             return { x, y, width, height };
           });
@@ -107,11 +107,11 @@ describe("Editor", () => {
             .withContext(`In ${browserName}`)
             .toEqual(2);
 
-          const content = await page.$eval(`${editorPrefix}0`, el =>
+          const content = await page.$eval(getEditorSelector(0), el =>
             el.innerText.trimEnd()
           );
 
-          let pastedContent = await page.$eval(`${editorPrefix}1`, el =>
+          let pastedContent = await page.$eval(getEditorSelector(1), el =>
             el.innerText.trimEnd()
           );
 
@@ -131,7 +131,7 @@ describe("Editor", () => {
             .withContext(`In ${browserName}`)
             .toEqual(3);
 
-          pastedContent = await page.$eval(`${editorPrefix}2`, el =>
+          pastedContent = await page.$eval(getEditorSelector(2), el =>
             el.innerText.trimEnd()
           );
           expect(pastedContent)
@@ -155,7 +155,7 @@ describe("Editor", () => {
           for (const n of [0, 1, 2]) {
             const hasEditor = await page.evaluate(sel => {
               return !!document.querySelector(sel);
-            }, `${editorPrefix}${n}`);
+            }, getEditorSelector(n));
 
             expect(hasEditor).withContext(`In ${browserName}`).toEqual(false);
           }
@@ -177,9 +177,9 @@ describe("Editor", () => {
 
           const data = "Hello PDF.js World !!";
           await page.mouse.click(rect.x + 100, rect.y + 100);
-          await page.type(`${editorPrefix}3 .internal`, data);
+          await page.type(`${getEditorSelector(3)} .internal`, data);
 
-          const editorRect = await page.$eval(`${editorPrefix}3`, el => {
+          const editorRect = await page.$eval(getEditorSelector(3), el => {
             const { x, y, width, height } = el.getBoundingClientRect();
             return { x, y, width, height };
           });
@@ -205,7 +205,7 @@ describe("Editor", () => {
 
           let hasEditor = await page.evaluate(sel => {
             return !!document.querySelector(sel);
-          }, `${editorPrefix}4`);
+          }, getEditorSelector(4));
 
           expect(hasEditor).withContext(`In ${browserName}`).toEqual(true);
 
@@ -215,7 +215,7 @@ describe("Editor", () => {
 
           hasEditor = await page.evaluate(sel => {
             return !!document.querySelector(sel);
-          }, `${editorPrefix}4`);
+          }, getEditorSelector(4));
 
           expect(hasEditor).withContext(`In ${browserName}`).toEqual(false);
 
@@ -227,7 +227,7 @@ describe("Editor", () => {
 
           let length = await page.evaluate(sel => {
             return document.querySelectorAll(sel).length;
-          }, `${editorPrefix}5, ${editorPrefix}6`);
+          }, `${getEditorSelector(5)}, ${getEditorSelector(6)}`);
           expect(length).withContext(`In ${browserName}`).toEqual(2);
 
           for (let i = 0; i < 2; i++) {
@@ -238,7 +238,7 @@ describe("Editor", () => {
 
           length = await page.evaluate(sel => {
             return document.querySelectorAll(sel).length;
-          }, `${editorPrefix}5, ${editorPrefix}6`);
+          }, `${getEditorSelector(5)}, ${getEditorSelector(6)}`);
           expect(length).withContext(`In ${browserName}`).toEqual(0);
         })
       );
@@ -273,7 +273,7 @@ describe("Editor", () => {
             stacksRect.x + stacksRect.width + 1,
             stacksRect.y + stacksRect.height / 2
           );
-          await page.type(`${editorPrefix}7 .internal`, data);
+          await page.type(`${getEditorSelector(7)} .internal`, data);
 
           // Commit.
           await page.keyboard.press("Escape");
@@ -283,9 +283,9 @@ describe("Editor", () => {
             return span?.getAttribute("aria-owns") || null;
           });
 
-          expect(ariaOwns)
+          expect(ariaOwns.endsWith("_7-editor"))
             .withContext(`In ${browserName}`)
-            .toEqual(`${editorPrefix}7-editor`.slice(1));
+            .toEqual(true);
         })
       );
     });
@@ -308,9 +308,9 @@ describe("Editor", () => {
 
           const data = "Hello PDF.js World !!";
           await page.mouse.click(rect.x + 100, rect.y + 100);
-          await page.type(`${editorPrefix}8 .internal`, data);
+          await page.type(`${getEditorSelector(8)} .internal`, data);
 
-          const editorRect = await page.$eval(`${editorPrefix}8`, el => {
+          const editorRect = await page.$eval(getEditorSelector(8), el => {
             const { x, y, width, height } = el.getBoundingClientRect();
             return { x, y, width, height };
           });
@@ -385,9 +385,9 @@ describe("Editor", () => {
               rect.x + (i + 1) * 100,
               rect.y + (i + 1) * 100
             );
-            await page.type(`${editorPrefix}${i} .internal`, data);
+            await page.type(`${getEditorSelector(i)} .internal`, data);
 
-            const editorRect = await page.$eval(`${editorPrefix}${i}`, el => {
+            const editorRect = await page.$eval(getEditorSelector(i), el => {
               const { x, y, width, height } = el.getBoundingClientRect();
               return {
                 x,

test/integration/test_utils.js

@@ -73,19 +73,17 @@ function getComputedStyleSelector(id) {
   return `getComputedStyle(${getQuerySelector(id)})`;
 }
 exports.getComputedStyleSelector = getComputedStyleSelector;
-
+exports.getEditorSelector = n => `#pdfjs_internal_editor_${n}`;
-const editorPrefix = "#pdfjs_internal_editor_";
-exports.editorPrefix = editorPrefix;
 
 function getSelectedEditors(page) {
-  return page.evaluate(prefix => {
+  return page.evaluate(() => {
     const elements = document.querySelectorAll(".selectedEditor");
     const results = [];
     for (const { id } of elements) {
-      results.push(parseInt(id.slice(prefix.length)));
+      results.push(parseInt(id.split("_").at(-1)));
     }
     results.sort();
     return results;
-  }, editorPrefix.slice(1));
+  });
 }
 exports.getSelectedEditors = getSelectedEditors;

test/pdfs/.gitignore

@@ -534,3 +534,4 @@
 !bug1675139.pdf
 !issue15092.pdf
 !bug1782186.pdf
+!tracemonkey_a11y.pdf

web/annotation_editor_layer_builder.js

@@ -21,6 +21,8 @@
 /** @typedef {import("../src/display/editor/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("./text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 /** @typedef {import("./interfaces").IL10n} IL10n */
 
 import { AnnotationEditorLayer } from "pdfjs-lib";
@@ -31,6 +33,7 @@ import { NullL10n } from "./l10n_utils.js";
  * @property {number} mode - Editor mode
  * @property {HTMLDivElement} pageDiv
  * @property {PDFPageProxy} pdfPage
+ * @property {TextAccessibilityManager} accessibilityManager
  * @property {AnnotationStorage} annotationStorage
  * @property {IL10n} l10n - Localization service.
  * @property {AnnotationEditorUIManager} uiManager
@@ -46,6 +49,7 @@ class AnnotationEditorLayerBuilder {
     this.pageDiv = options.pageDiv;
     this.pdfPage = options.pdfPage;
     this.annotationStorage = options.annotationStorage || null;
+    this.accessibilityManager = options.accessibilityManager;
     this.l10n = options.l10n || NullL10n;
     this.annotationEditorLayer = null;
     this.div = null;
@@ -83,6 +87,7 @@ class AnnotationEditorLayerBuilder {
       uiManager: this.#uiManager,
       div: this.div,
       annotationStorage: this.annotationStorage,
+      accessibilityManager: this.accessibilityManager,
       pageIndex: this.pdfPage._pageIndex,
       l10n: this.l10n,
       viewport: clonedViewport,

web/annotation_layer_builder.css

@@ -210,7 +210,6 @@
 
 .annotationLayer .popup {
   position: absolute;
-  z-index: 200;
   max-width: calc(180px * var(--scale-factor));
   background-color: rgba(255, 255, 153, 1);
   box-shadow: 0 calc(2px * var(--scale-factor)) calc(5px * var(--scale-factor))

web/annotation_layer_builder.js

@@ -19,6 +19,8 @@
 /** @typedef {import("./interfaces").IDownloadManager} IDownloadManager */
 /** @typedef {import("./interfaces").IL10n} IL10n */
 /** @typedef {import("./interfaces").IPDFLinkService} IPDFLinkService */
+// eslint-disable-next-line max-len
+/** @typedef {import("./textaccessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 
 import { AnnotationLayer } from "pdfjs-lib";
 import { NullL10n } from "./l10n_utils.js";
@@ -40,6 +42,7 @@ import { NullL10n } from "./l10n_utils.js";
  *   [fieldObjectsPromise]
  * @property {Object} [mouseState]
  * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap]
+ * @property {TextAccessibilityManager} accessibilityManager
  */
 
 class AnnotationLayerBuilder {
@@ -60,6 +63,7 @@ class AnnotationLayerBuilder {
     fieldObjectsPromise = null,
     mouseState = null,
     annotationCanvasMap = null,
+    accessibilityManager = null,
   }) {
     this.pageDiv = pageDiv;
     this.pdfPage = pdfPage;
@@ -74,6 +78,7 @@ class AnnotationLayerBuilder {
     this._fieldObjectsPromise = fieldObjectsPromise;
     this._mouseState = mouseState;
     this._annotationCanvasMap = annotationCanvasMap;
+    this._accessibilityManager = accessibilityManager;
 
     this.div = null;
     this._cancelled = false;
@@ -112,6 +117,7 @@ class AnnotationLayerBuilder {
       fieldObjects,
       mouseState: this._mouseState,
       annotationCanvasMap: this._annotationCanvasMap,
+      accessibilityManager: this._accessibilityManager,
     };
 
     if (this.div) {

web/base_viewer.js

@@ -30,6 +30,8 @@
 // eslint-disable-next-line max-len
 /** @typedef {import("./interfaces").IPDFTextLayerFactory} IPDFTextLayerFactory */
 /** @typedef {import("./interfaces").IPDFXfaLayerFactory} IPDFXfaLayerFactory */
+// eslint-disable-next-line max-len
+/** @typedef {import("./text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 
 import {
   AnnotationEditorType,
@@ -1637,6 +1639,7 @@ class BaseViewer {
    * @property {boolean} [enhanceTextSelection]
    * @property {EventBus} eventBus
    * @property {TextHighlighter} highlighter
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -1650,6 +1653,7 @@ class BaseViewer {
     enhanceTextSelection = false,
     eventBus,
     highlighter,
+    accessibilityManager = null,
   }) {
     return new TextLayerBuilder({
       textLayerDiv,
@@ -1660,6 +1664,7 @@ class BaseViewer {
         ? false
         : enhanceTextSelection,
       highlighter,
+      accessibilityManager,
     });
   }
 
@@ -1698,6 +1703,7 @@ class BaseViewer {
    *   [fieldObjectsPromise]
    * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
    *   annotation ids with canvases used to render them.
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -1716,6 +1722,7 @@ class BaseViewer {
     mouseState = this._scriptingManager?.mouseState,
     fieldObjectsPromise = this.pdfDocument?.getFieldObjects(),
     annotationCanvasMap = null,
+    accessibilityManager = null,
   }) {
     return new AnnotationLayerBuilder({
       pageDiv,
@@ -1731,6 +1738,7 @@ class BaseViewer {
       mouseState,
       fieldObjectsPromise,
       annotationCanvasMap,
+      accessibilityManager,
     });
   }
 
@@ -1741,6 +1749,7 @@ class BaseViewer {
    * @property {PDFPageProxy} pdfPage
    * @property {IL10n} l10n
    * @property {AnnotationStorage} [annotationStorage] - Storage for annotation
+   * @property {TextAccessibilityManager} [accessibilityManager]
    *   data in forms.
    */
 
@@ -1752,6 +1761,7 @@ class BaseViewer {
     uiManager = this.#annotationEditorUIManager,
     pageDiv,
     pdfPage,
+    accessibilityManager = null,
     l10n,
     annotationStorage = this.pdfDocument?.annotationStorage,
   }) {
@@ -1760,6 +1770,7 @@ class BaseViewer {
       pageDiv,
       pdfPage,
       annotationStorage,
+      accessibilityManager,
       l10n,
     });
   }

web/debugger.css

@@ -92,6 +92,10 @@
   box-sizing: border-box;
 }
 
+#viewer.textLayer-visible .textLayer span[aria-owns] {
+  background-color: rgba(255, 0, 0, 0.3);
+}
+
 #viewer.textLayer-hover .textLayer span:hover {
   background-color: rgba(255, 255, 255, 1);
   color: rgba(0, 0, 0, 1);

web/default_factory.js

@@ -30,6 +30,8 @@
 /** @typedef {import("./interfaces").IPDFTextLayerFactory} IPDFTextLayerFactory */
 /** @typedef {import("./interfaces").IPDFXfaLayerFactory} IPDFXfaLayerFactory */
 /** @typedef {import("./text_highlighter").TextHighlighter} TextHighlighter */
+// eslint-disable-next-line max-len
+/** @typedef {import("./text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 
 import { AnnotationEditorLayerBuilder } from "./annotation_editor_layer_builder.js";
 import { AnnotationLayerBuilder } from "./annotation_layer_builder.js";
@@ -60,6 +62,7 @@ class DefaultAnnotationLayerFactory {
    *   [fieldObjectsPromise]
    * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
    *   annotation ids with canvases used to render them.
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -78,6 +81,7 @@ class DefaultAnnotationLayerFactory {
     mouseState = null,
     fieldObjectsPromise = null,
     annotationCanvasMap = null,
+    accessibilityManager = null,
   }) {
     return new AnnotationLayerBuilder({
       pageDiv,
@@ -92,6 +96,7 @@ class DefaultAnnotationLayerFactory {
       fieldObjectsPromise,
       mouseState,
       annotationCanvasMap,
+      accessibilityManager,
     });
   }
 }
@@ -107,6 +112,7 @@ class DefaultAnnotationEditorLayerFactory {
    * @property {PDFPageProxy} pdfPage
    * @property {IL10n} l10n
    * @property {AnnotationStorage} [annotationStorage] - Storage for annotation
+   * @property {TextAccessibilityManager} [accessibilityManager]
    *   data in forms.
    */
 
@@ -118,6 +124,7 @@ class DefaultAnnotationEditorLayerFactory {
     uiManager = null,
     pageDiv,
     pdfPage,
+    accessibilityManager = null,
     l10n,
     annotationStorage = null,
   }) {
@@ -125,6 +132,7 @@ class DefaultAnnotationEditorLayerFactory {
       uiManager,
       pageDiv,
       pdfPage,
+      accessibilityManager,
       l10n,
       annotationStorage,
     });
@@ -163,6 +171,7 @@ class DefaultTextLayerFactory {
    * @property {boolean} [enhanceTextSelection]
    * @property {EventBus} eventBus
    * @property {TextHighlighter} highlighter
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -176,6 +185,7 @@ class DefaultTextLayerFactory {
     enhanceTextSelection = false,
     eventBus,
     highlighter,
+    accessibilityManager = null,
   }) {
     return new TextLayerBuilder({
       textLayerDiv,
@@ -184,6 +194,7 @@ class DefaultTextLayerFactory {
       enhanceTextSelection,
       eventBus,
       highlighter,
+      accessibilityManager,
     });
   }
 }

web/interfaces.js

@@ -29,6 +29,8 @@
 /** @typedef {import("./text_layer_builder").TextLayerBuilder} TextLayerBuilder */
 /** @typedef {import("./ui_utils").RenderingStates} RenderingStates */
 /** @typedef {import("./xfa_layer_builder").XfaLayerBuilder} XfaLayerBuilder */
+// eslint-disable-next-line max-len
+/** @typedef {import("./text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 
 /**
  * @interface
@@ -162,6 +164,7 @@ class IPDFTextLayerFactory {
    * @property {boolean} [enhanceTextSelection]
    * @property {EventBus} eventBus
    * @property {TextHighlighter} highlighter
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -175,6 +178,7 @@ class IPDFTextLayerFactory {
     enhanceTextSelection = false,
     eventBus,
     highlighter,
+    accessibilityManager,
   }) {}
 }
 
@@ -199,6 +203,7 @@ class IPDFAnnotationLayerFactory {
    *   [fieldObjectsPromise]
    * @property {Map<string, HTMLCanvasElement>} [annotationCanvasMap] - Map some
    *   annotation ids with canvases used to render them.
+   * @property {TextAccessibilityManager} [accessibilityManager]
    */
 
   /**
@@ -217,6 +222,7 @@ class IPDFAnnotationLayerFactory {
     mouseState = null,
     fieldObjectsPromise = null,
     annotationCanvasMap = null,
+    accessibilityManager = null,
   }) {}
 }
 
@@ -231,6 +237,7 @@ class IPDFAnnotationEditorLayerFactory {
    * @property {PDFPageProxy} pdfPage
    * @property {IL10n} l10n
    * @property {AnnotationStorage} [annotationStorage] - Storage for annotation
+   * @property {TextAccessibilityManager} [accessibilityManager]
    *   data in forms.
    */
 
@@ -244,6 +251,7 @@ class IPDFAnnotationEditorLayerFactory {
     pdfPage,
     l10n,
     annotationStorage = null,
+    accessibilityManager,
   }) {}
 }
 

web/pdf_page_view.js

@@ -51,6 +51,7 @@ import {
 } from "./ui_utils.js";
 import { compatibilityParams } from "./app_options.js";
 import { NullL10n } from "./l10n_utils.js";
+import { TextAccessibilityManager } from "./text_accessibility.js";
 
 /**
  * @typedef {Object} PDFPageViewOptions
@@ -697,6 +698,7 @@ class PDFPageView {
 
     let textLayer = null;
     if (this.textLayerMode !== TextLayerMode.DISABLE && this.textLayerFactory) {
+      this._accessibilityManager ||= new TextAccessibilityManager();
       const textLayerDiv = document.createElement("div");
       textLayerDiv.className = "textLayer";
       textLayerDiv.style.width = canvasWrapper.style.width;
@@ -716,6 +718,7 @@ class PDFPageView {
           this.textLayerMode === TextLayerMode.ENABLE_ENHANCE,
         eventBus: this.eventBus,
         highlighter: this.textHighlighter,
+        accessibilityManager: this._accessibilityManager,
       });
     }
     this.textLayer = textLayer;
@@ -733,6 +736,7 @@ class PDFPageView {
           renderForms: this.#annotationMode === AnnotationMode.ENABLE_FORMS,
           l10n: this.l10n,
           annotationCanvasMap: this._annotationCanvasMap,
+          accessibilityManager: this._accessibilityManager,
         });
     }
 
@@ -824,6 +828,7 @@ class PDFPageView {
                       pageDiv: div,
                       pdfPage,
                       l10n: this.l10n,
+                      accessibilityManager: this._accessibilityManager,
                     }
                   );
                 this._renderAnnotationEditorLayer();

web/text_accessibility.js

@@ -0,0 +1,246 @@
+/* Copyright 2022 Mozilla Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { binarySearchFirstItem } from "pdfjs-lib";
+
+/**
+ * This class aims to provide some methods:
+ *  - to reorder elements in the DOM with respect to the visual order;
+ *  - to create a link, using aria-owns, between spans in the textLayer and
+ *    annotations in the annotationLayer. The goal is to help to know
+ *    where the annotations are in the text flow.
+ */
+class TextAccessibilityManager {
+  #enabled = false;
+
+  #textChildren = null;
+
+  #textNodes = new Map();
+
+  #waitingElements = new Map();
+
+  setTextMapping(textDivs) {
+    this.#textChildren = textDivs;
+  }
+
+  /**
+   * 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.width === 0 && rect1.height === 0) {
+      return +1;
+    }
+
+    if (rect2.width === 0 && rect2.height === 0) {
+      return -1;
+    }
+
+    const top1 = rect1.y;
+    const bot1 = rect1.y + rect1.height;
+    const mid1 = rect1.y + rect1.height / 2;
+
+    const top2 = rect2.y;
+    const bot2 = rect2.y + rect2.height;
+    const mid2 = rect2.y + rect2.height / 2;
+
+    if (mid1 <= top2 && mid2 >= bot1) {
+      return -1;
+    }
+
+    if (mid2 <= top1 && mid1 >= bot2) {
+      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.
+   */
+  enable() {
+    if (this.#enabled) {
+      throw new Error("TextAccessibilityManager is already enabled.");
+    }
+    if (!this.#textChildren) {
+      throw new Error("Text divs and strings have not been set.");
+    }
+
+    this.#enabled = true;
+    this.#textChildren = this.#textChildren.slice();
+    this.#textChildren.sort(TextAccessibilityManager.#compareElementPositions);
+
+    if (this.#textNodes.size > 0) {
+      // Some links have been made before this manager has been disabled, hence
+      // we restore them.
+      const textChildren = this.#textChildren;
+      for (const [id, nodeIndex] of this.#textNodes) {
+        this.#addIdToAriaOwns(id, textChildren[nodeIndex]);
+      }
+    }
+
+    for (const [element, isRemovable] of this.#waitingElements) {
+      this.addPointerInTextLayer(element, isRemovable);
+    }
+    this.#waitingElements.clear();
+  }
+
+  disable() {
+    if (!this.#enabled) {
+      return;
+    }
+
+    // Don't clear this.#textNodes which is used to rebuild the aria-owns
+    // in case it's re-enabled at some point.
+
+    this.#waitingElements.clear();
+    this.#textChildren = null;
+    this.#enabled = false;
+  }
+
+  /**
+   * Remove an aria-owns id from a node in the text layer.
+   * @param {HTMLElement} element
+   */
+  removePointerInTextLayer(element) {
+    if (!this.#enabled) {
+      this.#waitingElements.delete(element);
+      return;
+    }
+
+    const children = this.#textChildren;
+    if (!children || children.length === 0) {
+      return;
+    }
+
+    const { id } = element;
+    const nodeIndex = this.#textNodes.get(id);
+    if (nodeIndex === undefined) {
+      return;
+    }
+
+    const node = children[nodeIndex];
+
+    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");
+      }
+    }
+  }
+
+  #addIdToAriaOwns(id, node) {
+    const owns = node.getAttribute("aria-owns");
+    if (!owns?.includes(id)) {
+      node.setAttribute("aria-owns", owns ? `${owns} ${id}` : id);
+    }
+    node.removeAttribute("role");
+  }
+
+  /**
+   * 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 {HTMLElement} element
+   * @param {boolean} isRemovable
+   */
+  addPointerInTextLayer(element, isRemovable) {
+    const { id } = element;
+    if (!id) {
+      return;
+    }
+
+    if (!this.#enabled) {
+      // The text layer needs to be there, so we postpone the association.
+      this.#waitingElements.set(element, isRemovable);
+      return;
+    }
+
+    if (isRemovable) {
+      this.removePointerInTextLayer(element);
+    }
+
+    const children = this.#textChildren;
+    if (!children || children.length === 0) {
+      return;
+    }
+
+    const index = binarySearchFirstItem(
+      children,
+      node =>
+        TextAccessibilityManager.#compareElementPositions(element, node) < 0
+    );
+
+    const nodeIndex = Math.max(0, index - 1);
+    this.#addIdToAriaOwns(id, children[nodeIndex]);
+    this.#textNodes.set(id, nodeIndex);
+  }
+
+  /**
+   * Move a div in the DOM in order to respect the visual order.
+   * @param {HTMLDivElement} element
+   */
+  moveElementInDOM(container, element, contentElement, isRemovable) {
+    this.addPointerInTextLayer(contentElement, isRemovable);
+
+    if (!container.hasChildNodes()) {
+      container.append(element);
+      return;
+    }
+
+    const children = Array.from(container.childNodes).filter(
+      node => node !== element
+    );
+
+    if (children.length === 0) {
+      return;
+    }
+
+    const elementToCompare = contentElement || element;
+    const index = binarySearchFirstItem(
+      children,
+      node =>
+        TextAccessibilityManager.#compareElementPositions(
+          elementToCompare,
+          node
+        ) < 0
+    );
+
+    if (index === 0) {
+      children[0].before(element);
+    } else {
+      children[index - 1].after(element);
+    }
+  }
+}
+
+export { TextAccessibilityManager };

web/text_layer_builder.js

@@ -17,6 +17,8 @@
 /** @typedef {import("../src/display/display_utils").PageViewport} PageViewport */
 /** @typedef {import("./event_utils").EventBus} EventBus */
 /** @typedef {import("./text_highlighter").TextHighlighter} TextHighlighter */
+// eslint-disable-next-line max-len
+/** @typedef {import("./text_accessibility.js").TextAccessibilityManager} TextAccessibilityManager */
 
 import { renderTextLayer } from "pdfjs-lib";
 
@@ -32,6 +34,7 @@ const EXPAND_DIVS_TIMEOUT = 300; // ms
  *   highlighting text from the find controller.
  * @property {boolean} enhanceTextSelection - Option to turn on improved
  *   text selection.
+ * @property {TextAccessibilityManager} [accessibilityManager]
  */
 
 /**
@@ -47,6 +50,7 @@ class TextLayerBuilder {
     viewport,
     highlighter = null,
     enhanceTextSelection = false,
+    accessibilityManager = null,
   }) {
     this.textLayerDiv = textLayerDiv;
     this.eventBus = eventBus;
@@ -60,6 +64,7 @@ class TextLayerBuilder {
     this.textLayerRenderTask = null;
     this.highlighter = highlighter;
     this.enhanceTextSelection = enhanceTextSelection;
+    this.accessibilityManager = accessibilityManager;
 
     this._bindMouse();
   }
@@ -97,6 +102,7 @@ class TextLayerBuilder {
 
     this.textDivs.length = 0;
     this.highlighter?.setTextMapping(this.textDivs, this.textContentItemsStr);
+    this.accessibilityManager?.setTextMapping(this.textDivs);
 
     const textLayerFrag = document.createDocumentFragment();
     this.textLayerRenderTask = renderTextLayer({
@@ -114,6 +120,7 @@ class TextLayerBuilder {
         this.textLayerDiv.append(textLayerFrag);
         this._finishRendering();
         this.highlighter?.enable();
+        this.accessibilityManager?.enable();
       },
       function (reason) {
         // Cancelled or failed to render text layer; skipping errors.
@@ -130,6 +137,7 @@ class TextLayerBuilder {
       this.textLayerRenderTask = null;
     }
     this.highlighter?.disable();
+    this.accessibilityManager?.disable();
   }
 
   setTextContentStream(readableStream) {