feat: update active node for screen reader when focus is changed

Author: jlp-craigmorten

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/virtual-screen-reader",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Virtual screen reader driver for unit test automation.",
   "main": "lib/index.js",
   "author": "Craig Morten <craig.morten@hotmail.co.uk>",

src/Virtual.ts

@@ -32,7 +32,6 @@ const observedAttributes = [
   "disabled",
 ];
 
-// TODO: monitor focus change and update the screen reader active element.
 // TODO: handle aria-live, role="polite", role="alert", and other interruptions.
 
 const observeDOM = (function () {
@@ -84,15 +83,47 @@ export class Virtual implements ScreenReader {
   #getAccessibilityTree() {
     if (!this.#treeCache) {
       this.#treeCache = createAccessibilityTree(this.#container);
+      this.#attachFocusListeners();
     }
 
     return this.#treeCache;
   }
 
   #invalidateTreeCache() {
+    this.#detachFocusListeners();
     this.#treeCache = null;
   }
 
+  #attachFocusListeners() {
+    this.#getAccessibilityTree().forEach((treeNode) => {
+      treeNode.node.addEventListener(
+        "focus",
+        this.#handleFocusChange.bind(this)
+      );
+    });
+  }
+
+  #detachFocusListeners() {
+    this.#getAccessibilityTree().forEach((treeNode) => {
+      treeNode.node.removeEventListener(
+        "focus",
+        this.#handleFocusChange.bind(this)
+      );
+    });
+  }
+
+  #handleFocusChange({ target }: FocusEvent) {
+    const tree = this.#getAccessibilityTree();
+    const nextIndex = tree.findIndex(({ node }) => node === target);
+
+    if (nextIndex === -1) {
+      return;
+    }
+
+    const newActiveNode = tree.at(nextIndex);
+    this.#updateState(newActiveNode);
+  }
+
   #updateState(accessibilityNode: AccessibilityNode) {
     const { accessibleDescription, accessibleName, role } = accessibilityNode;
     const spokenPhrase = [role, accessibleName, accessibleDescription]

test/int/click.int.test.ts

@@ -1,7 +1,31 @@
 import { getByText, queryByText } from "@testing-library/dom";
-import { setupButtonPage } from "../utils";
 import { virtual } from "../../src";
 
+function setupButtonPage() {
+  document.body.innerHTML = `
+  <p id="status">Not Clicked</p>
+  <div id="hidden" style="display: none;">Hidden</div>
+  `;
+
+  const button = document.createElement("button");
+
+  button.addEventListener("click", function (event) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    document.getElementById(
+      "status"
+    )!.innerHTML = `Clicked ${event.detail} Time(s)`;
+  });
+
+  button.innerHTML = "Click Me";
+
+  document.body.appendChild(button);
+
+  document.body.addEventListener("contextmenu", () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    document.getElementById("status")!.innerHTML = `Right Clicked`;
+  });
+}
+
 describe("click", () => {
   beforeEach(() => {
     setupButtonPage();

test/int/focus.int.test.ts

@@ -0,0 +1,77 @@
+import { getByText } from "@testing-library/dom";
+import { virtual } from "../../src";
+
+function setupFocusChangePage() {
+  document.body.innerHTML = `
+  <div id="container">
+    <button id="1">1</button>
+    <button id="2">2</button>
+    <label for="3">3 label</label>
+    <input id="3" type="text" value="3" />
+    <label for="4">4 label</label>
+    <input id="4" type="button" value="4" />
+    <textarea id="5">5</textarea>
+    <a id="6" href="#">6</a>
+    <button id="hidden1" aria-hidden="true">hidden 1</button>
+  </div>
+  <button id="outside1">outside 1</button>
+  `;
+}
+
+describe("click", () => {
+  beforeEach(() => {
+    setupFocusChangePage();
+  });
+
+  it("should update the screen reader position when a node not currently active for the screen reader is focussed", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const container = document.querySelector("#container")! as HTMLElement;
+
+    await virtual.start({ container });
+
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 1");
+
+    getByText(container, "4").focus();
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 4");
+
+    await virtual.previous();
+    await virtual.previous();
+    expect(await virtual.lastSpokenPhrase()).toEqual("textbox, 3 label");
+
+    getByText(container, "6").focus();
+    expect(await virtual.lastSpokenPhrase()).toEqual("link, 6");
+
+    await virtual.previous();
+    expect(await virtual.lastSpokenPhrase()).toEqual("end of textbox");
+
+    await virtual.stop();
+  });
+
+  it("should not shift the screen reader active node if focus shifted outside the container", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const container = document.querySelector("#container")! as HTMLElement;
+
+    await virtual.start({ container });
+
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 1");
+
+    getByText(document.body, "outside 1").focus();
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 1");
+
+    await virtual.stop();
+  });
+
+  it("should not shift the screen reader active node if focus shifted to a node hidden from screen readers", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const container = document.querySelector("#container")! as HTMLElement;
+
+    await virtual.start({ container });
+
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 1");
+
+    getByText(document.body, "hidden 1").focus();
+    expect(await virtual.lastSpokenPhrase()).toEqual("button, 1");
+
+    await virtual.stop();
+  });
+});

test/utils.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-non-null-assertion */
-
 export function setupBasicPage() {
   document.body.innerHTML = `
   <nav>Nav Text</nav>
@@ -17,26 +15,3 @@ export function setupBasicPage() {
   <footer>Footer</footer>
   `;
 }
-
-export function setupButtonPage() {
-  document.body.innerHTML = `
-  <p id="status">Not Clicked</p>
-  <div id="hidden" style="display: none;">Hidden</div>
-  `;
-
-  const button = document.createElement("button");
-
-  button.addEventListener("click", function (event) {
-    document.getElementById(
-      "status"
-    )!.innerHTML = `Clicked ${event.detail} Time(s)`;
-  });
-
-  button.innerHTML = "Click Me";
-
-  document.body.appendChild(button);
-
-  document.body.addEventListener("contextmenu", () => {
-    document.getElementById("status")!.innerHTML = `Right Clicked`;
-  });
-}