feat: basic inert attribute support (#130)

Author: jlp-craigmorten

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidepup/virtual-screen-reader",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Virtual Screen Reader driver for unit test automation.",
   "author": "Craig Morten <[email protected]>",
   "license": "MIT",

src/createAccessibilityTree.ts

@@ -4,7 +4,7 @@ import { getNodeAccessibilityData } from "./getNodeAccessibilityData/index";
 import { getNodeByIdRef } from "./getNodeByIdRef";
 import { isDialogRole } from "./isDialogRole";
 import { isElement } from "./isElement";
-import { isInaccessible } from "dom-accessibility-api";
+import { isHiddenFromAccessibilityTree } from "./isHiddenFromAccessibilityTree";
 
 export interface AccessibilityNode {
   accessibleAttributeLabels: string[];
@@ -15,6 +15,7 @@ export interface AccessibilityNode {
   allowedAccessibilityChildRoles: string[][];
   alternateReadingOrderParents: Node[];
   childrenPresentational: boolean;
+  isInert: boolean;
   node: Node;
   parentAccessibilityNodeTree: AccessibilityNodeTree | null;
   parent: Node | null;
@@ -125,33 +126,6 @@ function getOwnedNodes(node: Node, container: Node) {
   return ownedNodes;
 }
 
-const TEXT_NODE = 3;
-
-function isHiddenFromAccessibilityTree(node: Node | null): node is null {
-  if (!node) {
-    return true;
-  }
-
-  // `node.textContent` is only `null` for `document` and `doctype`.
-   
-  if (node.nodeType === TEXT_NODE && node.textContent!.trim()) {
-    return false;
-  }
-
-  if (!isElement(node)) {
-    return true;
-  }
-
-  try {
-    return isInaccessible(node);
-  } catch {
-    // Some elements aren't supported by DOM implementations such as JSDOM.
-    // E.g. `<math>`, see https://github.com/jsdom/jsdom/issues/3515
-    // We ignore these nodes at the moment as we can't support them.
-    return true;
-  }
-}
-
 function growTree(
   node: Node,
   tree: Omit<
@@ -198,7 +172,7 @@ function growTree(
 
     const alternateReadingOrderParents = alternateReadingOrderMap.has(childNode)
       ? // `alternateReadingOrderMap.has(childNode)` null guards here.
-         
+
         Array.from(alternateReadingOrderMap.get(childNode)!)
       : [];
 
@@ -209,14 +183,14 @@ function growTree(
       allowedAccessibilityChildRoles,
       childrenPresentational,
       isExplicitPresentational,
+      isInert,
       role,
       spokenRole,
     } = getNodeAccessibilityData({
       allowedAccessibilityRoles: tree.allowedAccessibilityChildRoles,
-      alternateReadingOrderParents,
-      container,
-      node: childNode,
+      inheritedImplicitInert: tree.isInert,
       inheritedImplicitPresentational: tree.childrenPresentational,
+      node: childNode,
     });
 
     const childTree = growTree(
@@ -229,6 +203,7 @@ function growTree(
         alternateReadingOrderParents,
         children: [],
         childrenPresentational,
+        isInert,
         node: childNode,
         parentAccessibilityNodeTree: null, // Added during flattening
         parent: node,
@@ -266,7 +241,7 @@ function growTree(
 
     const alternateReadingOrderParents = alternateReadingOrderMap.has(childNode)
       ? // `alternateReadingOrderMap.has(childNode)` null guards here.
-         
+
         Array.from(alternateReadingOrderMap.get(childNode)!)
       : [];
 
@@ -276,15 +251,15 @@ function growTree(
       accessibleValue,
       allowedAccessibilityChildRoles,
       childrenPresentational,
+      isInert,
       isExplicitPresentational,
       role,
       spokenRole,
     } = getNodeAccessibilityData({
       allowedAccessibilityRoles: tree.allowedAccessibilityChildRoles,
-      alternateReadingOrderParents,
-      container,
-      node: childNode,
+      inheritedImplicitInert: tree.isInert,
       inheritedImplicitPresentational: tree.childrenPresentational,
+      node: childNode,
     });
 
     const childTree = growTree(
@@ -297,6 +272,7 @@ function growTree(
         alternateReadingOrderParents,
         children: [],
         childrenPresentational,
+        isInert,
         node: childNode,
         parentAccessibilityNodeTree: null, // Added during flattening
         parent: node,
@@ -334,14 +310,14 @@ export function createAccessibilityTree(
     accessibleValue,
     allowedAccessibilityChildRoles,
     childrenPresentational,
+    isInert,
     role,
     spokenRole,
   } = getNodeAccessibilityData({
     allowedAccessibilityRoles: [],
-    alternateReadingOrderParents: [],
-    container: node,
     node,
     inheritedImplicitPresentational: false,
+    inheritedImplicitInert: false,
   });
 
   const tree = growTree(
@@ -354,6 +330,7 @@ export function createAccessibilityTree(
       alternateReadingOrderParents: [],
       children: [],
       childrenPresentational,
+      isInert,
       node,
       parentAccessibilityNodeTree: null,
       parent: null,

src/flattenTree.ts

@@ -57,10 +57,11 @@ export function flattenTree(
   };
 
   const isAnnounced =
-    !!treeNodeWithAttributeLabels.accessibleName ||
-    !!treeNodeWithAttributeLabels.accessibleDescription ||
-    treeNodeWithAttributeLabels.accessibleAttributeLabels.length > 0 ||
-    !!treeNodeWithAttributeLabels.spokenRole;
+    !treeNodeWithAttributeLabels.isInert &&
+    (!!treeNodeWithAttributeLabels.accessibleName ||
+      !!treeNodeWithAttributeLabels.accessibleDescription ||
+      treeNodeWithAttributeLabels.accessibleAttributeLabels.length > 0 ||
+      !!treeNodeWithAttributeLabels.spokenRole);
 
   const ignoreChildren = shouldIgnoreChildren(tree);
 

src/getNodeAccessibilityData/index.ts

@@ -3,6 +3,7 @@ import { getRole, presentationRoles, synonymRolesMap } from "./getRole";
 import { getAccessibleDescription } from "./getAccessibleDescription";
 import { getAccessibleName } from "./getAccessibleName";
 import { getAccessibleValue } from "./getAccessibleValue";
+import { getLocalName } from "../getLocalName";
 import { isElement } from "../isElement";
 
 // TODO: swap out with the html-aria package once it supports `dpub-aam` /
@@ -62,14 +63,52 @@ const getSpokenRole = ({
   return role;
 };
 
+/**
+ * Nodes that are [inert](https://html.spec.whatwg.org/multipage/interaction.html#inert)
+ * are not exposed to an accessibility API.
+ *
+ * Note: an inert node can have descendants that are not inert. For example,
+ * a [modal dialog](https://html.spec.whatwg.org/multipage/interaction.html#modal-dialogs-and-inert-subtrees)
+ * can escape an inert subtree.
+ *
+ * REF: https://www.w3.org/TR/html-aam-1.0/#att-inert
+ */
+const getIsInert = ({
+  inheritedImplicitInert,
+  node,
+  role,
+}: {
+  inheritedImplicitInert: boolean;
+  node: Node;
+  role: string;
+}) => {
+  if (!isElement(node)) {
+    return inheritedImplicitInert;
+  }
+
+  // TODO: this doesn't cater to `<dialog>` elements which are model if opened
+  // by `show()` vs `showModal()`.
+  // REF: https://html.spec.whatwg.org/multipage/interaction.html#modal-dialogs-and-inert-subtrees
+  const isNativeModalDialog =
+    getLocalName(node) === "dialog" && node.hasAttribute("open");
+
+  const isNonNativeModalDialog =
+    role === "dialog" && node.hasAttribute("aria-modal");
+
+  const isModalDialog = isNonNativeModalDialog || isNativeModalDialog;
+  const isExplicitInert = node.hasAttribute("inert");
+
+  return isExplicitInert || (inheritedImplicitInert && !isModalDialog);
+};
+
 export function getNodeAccessibilityData({
   allowedAccessibilityRoles,
+  inheritedImplicitInert,
   inheritedImplicitPresentational,
   node,
 }: {
   allowedAccessibilityRoles: string[][];
-  alternateReadingOrderParents: Node[];
-  container: Node;
+  inheritedImplicitInert: boolean;
   inheritedImplicitPresentational: boolean;
   node: Node;
 }) {
@@ -147,13 +186,20 @@ export function getNodeAccessibilityData({
     isChildrenPresentationalRole ||
     childrenInheritPresentationExceptAllowedRoles;
 
+  const isInert = getIsInert({
+    inheritedImplicitInert,
+    node,
+    role,
+  });
+
   return {
     accessibleDescription: amendedAccessibleDescription,
     accessibleName,
     accessibleValue,
     allowedAccessibilityChildRoles,
     childrenPresentational,
     isExplicitPresentational,
+    isInert,
     role,
     spokenRole,
   };

src/isHiddenFromAccessibilityTree.ts

@@ -0,0 +1,46 @@
+import { isElement } from "./isElement";
+
+const TEXT_NODE = 3;
+
+export function isHiddenFromAccessibilityTree(node: Node | null): node is null {
+  if (!node) {
+    return true;
+  }
+
+  // `node.textContent` is only `null` for `document` and `doctype`.
+
+  if (node.nodeType === TEXT_NODE && node.textContent!.trim()) {
+    return false;
+  }
+
+  if (!isElement(node)) {
+    return true;
+  }
+
+  try {
+    if (node.hidden === true) {
+      return true;
+    }
+
+    if (node.getAttribute("aria-hidden") === "true") {
+      return true;
+    }
+
+    const getComputedStyle = node.ownerDocument.defaultView?.getComputedStyle;
+    const computedStyle = getComputedStyle?.(node);
+
+    if (
+      computedStyle?.visibility === "hidden" ||
+      computedStyle?.display === "none"
+    ) {
+      return true;
+    }
+  } catch {
+    // Some elements aren't supported by DOM implementations such as JSDOM.
+    // E.g. `<math>`, see https://github.com/jsdom/jsdom/issues/3515
+    // We ignore these nodes at the moment as we can't support them.
+    return true;
+  }
+
+  return false;
+}