feat: support announcing dialogs when entered

Author: jlp-craigmorten

examples/vue/src/ModalComponent.vue

@@ -0,0 +1,58 @@
+<template>
+  <OverlayComponent :show="isOpen">
+    <div role="dialog" aria-modal="true" aria-labelledby="modal-title" class="modal">
+      <button @click="$emit('close')" id="modal-close-button">Close Modal</button>
+      <h1 id="modal-title">Modal Title</h1>
+      <slot></slot>
+    </div>
+  </OverlayComponent>
+</template>
+
+<script lang="ts">
+import { defineComponent } from 'vue'
+import OverlayComponent from './OverlayComponent.vue'
+
+export default defineComponent({
+  name: 'ModalComponent',
+  components: {
+    OverlayComponent
+  },
+  watch: {
+    open: {
+      handler(isOpen: boolean): void {
+        this.isOpen = isOpen
+
+        if (isOpen) {
+          setTimeout(() => {
+            const closeButton = document.querySelector('#modal-close-button') as HTMLButtonElement;
+
+            closeButton.focus();
+          }, 0)
+        }
+      }
+    }
+  },
+  props: {
+    open: {
+      type: Boolean,
+      required: false,
+      default: false
+    }
+  },
+  data() {
+    return {
+      isOpen: false
+    }
+  }
+})
+</script>
+
+<style>
+.modal {
+  background-color: grey;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+}
+</style>

examples/vue/src/OpenModal.vue

@@ -0,0 +1,21 @@
+<template>
+  <button @click="isOpen = true">Open Modal</button>
+  <ModalComponent :open="isOpen" @close="isOpen = false">Example Modal Content</ModalComponent>
+</template>
+
+<script lang="ts">
+import { defineComponent } from 'vue'
+import ModalComponent from './ModalComponent.vue'
+
+export default defineComponent({
+  name: 'ModalExample',
+  components: {
+    ModalComponent
+  },
+  data() {
+    return {
+      isOpen: false
+    }
+  }
+})
+</script>

examples/vue/src/OverlayComponent.vue

@@ -0,0 +1,36 @@
+<template>
+  <span v-if="show">
+    <teleport to="body">
+      <span class="overlay">
+        <slot />
+      </span>
+    </teleport>
+  </span>
+</template>
+
+<script lang="ts">
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  name: 'OverlayComponent',
+  props: {
+    show: {
+      type: Boolean,
+      required: true,
+      default: false
+    }
+  }
+})
+</script>
+
+<style>
+.overlay {
+  display: block;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: #00000030
+}
+</style>

examples/vue/src/__tests__/OpenModal.spec.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { render } from '@testing-library/vue'
+import ModalExample from '../OpenModal.vue'
+
+/**
+ * Replace with:
+ *
+ * import { virtual } from '@guidepup/virtual-screen-reader'
+ *
+ * in your own code.
+ */
+import { virtual } from '../../../../src'
+
+describe('Open Modal', () => {
+  afterEach(async () => {
+    await virtual.stop()
+  })
+
+  it('announces the modal as a dialog', async () => {
+    render(ModalExample)
+
+    await virtual.start({ container: document.body })
+
+    // Navigate to the button and interact to open Modal
+    await virtual.next()
+    await virtual.act()
+
+    // Navigate through the modal
+    await virtual.next()
+    await virtual.next()
+    await virtual.next()
+
+    expect(await virtual.spokenPhraseLog()).toMatchInlineSnapshot(`
+      [
+        "document",
+        "button, Open Modal",
+        "dialog, Modal Title, modal",
+        "button, Close Modal",
+        "heading, Modal Title, level 1",
+        "Example Modal Content",
+        "end of dialog, Modal Title, modal",
+      ]
+    `)
+  })
+})

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/virtual-screen-reader",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Virtual Screen Reader driver for unit test automation.",
   "main": "lib/index.js",
   "author": "Craig Morten <[email protected]>",

src/Virtual.ts

@@ -182,14 +182,14 @@ export class Virtual implements ScreenReader {
 
     this.#invalidateTreeCache();
     const tree = this.#getAccessibilityTree();
-    const nextIndex = tree.findIndex(({ node }) => node === target);
 
     // This is called when an element in the tree receives focus so it stands
     // that we should be able to find said element in the tree (unless it can
     // be removed somehow between the focus event firing and this code
-    // executing?).
+    // executing... we are waiting for event loop tick so perhaps there is a
+    // race condition here?).
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const newActiveNode = tree.at(nextIndex)!;
+    const newActiveNode = tree.find(({ node }) => node === target);
 
     this.#updateState(newActiveNode, true);
   }
@@ -228,11 +228,42 @@ export class Virtual implements ScreenReader {
   }
 
   #updateState(accessibilityNode: AccessibilityNode, ignoreIfNoChange = false) {
-    const spokenPhrase = getSpokenPhrase(accessibilityNode);
-    const itemText = getItemText(accessibilityNode);
+    /**
+     * When the dialog is correctly labeled and focus is moved to an element
+     * (often an interactive element, such as a button) inside the dialog,
+     * screen readers should announce the dialog's accessible role, name and
+     * optionally description, along with announcing the focused element.
+     *
+     * REF: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role#possible_effects_on_user_agents_and_assistive_technology
+     */
+    if (
+      accessibilityNode.parentDialog !== null &&
+      accessibilityNode.parentDialog !== this.#activeNode.parentDialog
+    ) {
+      // One of the few cases where you will get two logs for a single
+      // interaction.
+      //
+      // We don't need to perform the `ignoreIfNoChange` check as this will
+      // only fire if the parent dialog element has changed, and if that
+      // happens we can be fairly confident that item under the virtual
+      // cursor has changed.
+      const tree = this.#getAccessibilityTree();
+      const parentDialogNode = tree.find(
+        ({ node }) => node === accessibilityNode.parentDialog
+      );
+
+      const spokenPhrase = getSpokenPhrase(parentDialogNode);
+      const itemText = getItemText(parentDialogNode);
+
+      this.#itemTextLog.push(itemText);
+      this.#spokenPhraseLog.push(spokenPhrase);
+    }
 
     this.#activeNode = accessibilityNode;
 
+    const spokenPhrase = getSpokenPhrase(accessibilityNode);
+    const itemText = getItemText(accessibilityNode);
+
     if (
       ignoreIfNoChange &&
       spokenPhrase === this.#spokenPhraseLogWithoutLiveRegions().at(-1) &&

src/createAccessibilityTree.ts

@@ -2,6 +2,7 @@ import { getIdRefsByAttribute } from "./getIdRefsByAttribute";
 import { getNodeAccessibilityData } from "./getNodeAccessibilityData";
 import { getNodeByIdRef } from "./getNodeByIdRef";
 import { HTMLElementWithValue } from "./getNodeAccessibilityData/getAccessibleValue";
+import { isDialogRole } from "./isDialogRole";
 import { isElement } from "./isElement";
 import { isInaccessible } from "dom-accessibility-api";
 
@@ -15,6 +16,7 @@ export interface AccessibilityNode {
   childrenPresentational: boolean;
   node: Node;
   parent: Node | null;
+  parentDialog: Node | null;
   role: string;
   spokenRole: string;
 }
@@ -182,6 +184,7 @@ function flattenTree(tree: AccessibilityNodeTree): AccessibilityNode[] {
       childrenPresentational: treeNode.childrenPresentational,
       node: treeNode.node,
       parent: treeNode.parent,
+      parentDialog: treeNode.parentDialog,
       role: treeNode.role,
       spokenRole: `end of ${treeNode.spokenRole}`,
     });
@@ -213,6 +216,8 @@ function growTree(
 
   visitedNodes.add(node);
 
+  const parentDialog = isDialogRole(tree.role) ? tree.node : tree.parentDialog;
+
   node.childNodes.forEach((childNode) => {
     if (isHiddenFromAccessibilityTree(childNode)) {
       return;
@@ -260,6 +265,7 @@ function growTree(
           childrenPresentational,
           node: childNode,
           parent: node,
+          parentDialog,
           role,
           spokenRole,
         },
@@ -323,6 +329,7 @@ function growTree(
           childrenPresentational,
           node: childNode,
           parent: node,
+          parentDialog,
           role,
           spokenRole,
         },
@@ -373,6 +380,7 @@ export function createAccessibilityTree(node: Node | null) {
       childrenPresentational,
       node,
       parent: null,
+      parentDialog: null,
       role,
       spokenRole,
     },

src/isDialogRole.ts

@@ -0,0 +1,2 @@
+export const isDialogRole = (role: string) =>
+  ["dialog", "alertdialog"].includes(role);