feat: support (some) context based roles

Author: cmorten

src/getLiveSpokenPhrase.ts

@@ -49,7 +49,7 @@ enum Relevant {
   TEXT = "text",
 }
 
-const RELEVANT_VALUES = Object.values(Relevant);
+const RELEVANT_VALUES = new Set(Object.values(Relevant));
 const DEFAULT_ATOMIC = false;
 const DEFAULT_LIVE = Live.OFF;
 const DEFAULT_RELEVANT = [Relevant.ADDITIONS, Relevant.TEXT];
@@ -60,7 +60,7 @@ function getSpokenPhraseForNode(node: Node) {
     getAccessibleValue(node) ||
     // `node.textContent` is only `null` if the `node` is a `document` or a
     // `doctype`. We don't consider either.
-     
+
     sanitizeString(node.textContent!)
   );
 }
@@ -229,12 +229,12 @@ function getLiveRegionAttributes(
   if (typeof relevant === "undefined" && target.hasAttribute("aria-relevant")) {
     // The `target.hasAttribute("aria-relevant")` check is sufficient to guard
     // against the `target.getAttribute("aria-relevant")` being null.
-     
+
     relevant = target
       .getAttribute("aria-relevant")!
       .split(" ")
       .filter(
-        (token) => !!RELEVANT_VALUES.includes(token as Relevant)
+        (token) => !!RELEVANT_VALUES.has(token as Relevant)
       ) as Relevant[];
 
     if (relevant.includes(Relevant.ALL)) {

src/getNodeAccessibilityData/getAccessibleAttributeLabels/getAttributesByRole.ts

@@ -1,7 +1,7 @@
 import { ARIARoleDefinitionKey, roles } from "aria-query";
 import { globalStatesAndProperties } from "../getRole";
 
-const ignoreAttributesWithAccessibleValue = ["aria-placeholder"];
+const ignoreAttributesWithAccessibleValue = new Set(["aria-placeholder"]);
 
 export const getAttributesByRole = ({
   accessibleValue,
@@ -27,8 +27,7 @@ export const getAttributesByRole = ({
     .filter((attribute) => !prohibitedAttributes.includes(attribute))
     .filter(
       (attribute) =>
-        !accessibleValue ||
-        !ignoreAttributesWithAccessibleValue.includes(attribute)
+        !accessibleValue || !ignoreAttributesWithAccessibleValue.has(attribute)
     );
 
   return uniqueAttributes.map((attribute) => [

src/getNodeAccessibilityData/getAccessibleAttributeLabels/getLabelFromImplicitHtmlElementValue/index.ts

@@ -63,6 +63,8 @@ const getNodeSet = ({
   });
 };
 
+const levelItemRoles = new Set(["listitem", "treeitem"]);
+
 type Mapper = ({
   node,
   tree,
@@ -112,7 +114,7 @@ const mapHtmlElementAriaToImplicitValue: Record<string, Mapper> = {
       });
     }
 
-    if (["listitem", "treeitem"].includes(role)) {
+    if (levelItemRoles.has(role)) {
       return getLevelFromDocumentStructure({
         role,
         tree,

src/getNodeAccessibilityData/getAccessibleAttributeLabels/postProcessAriaValueNow.ts

@@ -1,4 +1,4 @@
-const percentageBasedValueRoles = ["progressbar", "scrollbar"];
+const percentageBasedValueRoles = new Set(["progressbar", "scrollbar"]);
 
 const isNumberLike = (value: string) => {
   return !isNaN(parseFloat(value));
@@ -24,7 +24,7 @@ export const postProcessAriaValueNow = ({
   role: string;
   value: string;
 }) => {
-  if (!percentageBasedValueRoles.includes(role)) {
+  if (!percentageBasedValueRoles.has(role)) {
     return value;
   }
 

src/getNodeAccessibilityData/getAccessibleValue.ts

@@ -11,8 +11,8 @@ export type HTMLElementWithValue =
   | HTMLProgressElement
   | HTMLParamElement;
 
-const ignoredInputTypes = ["checkbox", "radio"];
-const allowedLocalNames = [
+const ignoredInputTypes = new Set(["checkbox", "radio"]);
+const allowedLocalNames = new Set([
   "button",
   "data",
   "input",
@@ -21,7 +21,7 @@ const allowedLocalNames = [
   "option",
   "progress",
   "param",
-];
+]);
 
 function getSelectValue(node: HTMLSelectElement) {
   const selectedOptions = [...node.options].filter(
@@ -42,7 +42,7 @@ function getSelectValue(node: HTMLSelectElement) {
 }
 
 function getInputValue(node: HTMLInputElement) {
-  if (ignoredInputTypes.includes(node.type)) {
+  if (ignoredInputTypes.has(node.type)) {
     return "";
   }
 
@@ -55,7 +55,7 @@ function getValue(node: HTMLElementWithValue) {
   // TODO: handle use of explicit roles where a value taken from content is
   // expected, e.g. combobox.
   // See core-aam/combobox-value-calculation-manual.html
-  if (!allowedLocalNames.includes(localName)) {
+  if (!allowedLocalNames.has(localName)) {
     return "";
   }
 

src/getNodeAccessibilityData/getRole.ts

@@ -1,4 +1,5 @@
 import {
+  type AncestorList,
   getRole as getImplicitRole,
   type TagName,
   type VirtualElement,
@@ -7,14 +8,16 @@ import { getLocalName } from "../getLocalName";
 import { isElement } from "../isElement";
 import { roles } from "aria-query";
 
-export const presentationRoles = ["presentation", "none"];
+export const presentationRoles = new Set(["presentation", "none"]);
 
-const allowedNonAbstractRoles = roles
-  .entries()
-  .filter(([, { abstract }]) => !abstract)
-  .map(([key]) => key) as string[];
+const allowedNonAbstractRoles = new Set(
+  roles
+    .entries()
+    .filter(([, { abstract }]) => !abstract)
+    .map(([key]) => key) as string[]
+);
 
-const rolesRequiringName = ["form", "region"];
+const rolesRequiringName = new Set(["form", "region"]);
 
 export const globalStatesAndProperties = [
   "aria-atomic",
@@ -90,7 +93,7 @@ function getExplicitRole({
      *
      * REF: https://www.w3.org/TR/wai-aria-1.2/#document-handling_author-errors_roles
      */
-    .filter((role) => allowedNonAbstractRoles.includes(role))
+    .filter((role) => allowedNonAbstractRoles.has(role))
     /**
      * Certain landmark roles require names from authors. In situations where
      * an author has not specified names for these landmarks, it is
@@ -105,7 +108,7 @@ function getExplicitRole({
      *
      * REF: https://www.w3.org/TR/wai-aria-1.2/#document-handling_author-errors_roles
      */
-    .filter((role) => !!accessibleName || !rolesRequiringName.includes(role));
+    .filter((role) => !!accessibleName || !rolesRequiringName.has(role));
 
   /**
    * If an allowed child element has an explicit non-presentational role, user
@@ -152,7 +155,7 @@ function getExplicitRole({
      * REF: https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none
      */
     .filter((role) => {
-      if (!presentationRoles.includes(role)) {
+      if (!presentationRoles.has(role)) {
         return true;
       }
 
@@ -182,6 +185,57 @@ function virtualizeElement(element: HTMLElement): VirtualElement {
   return { tagName, attributes };
 }
 
+const rolesDependentOnHierarchy = new Set([
+  "footer",
+  "header",
+  "li",
+  "td",
+  "th",
+  "tr",
+]);
+const ignoredAncestors = new Set(["body", "document"]);
+
+// TODO: Thought needed if the `getAncestors()` can limit the number of parents
+// it enumerates? Presumably as ancestors only matter for a limited number of
+// roles, there might be a ceiling to the amount of nesting that is even valid,
+// and therefore put an upper bound on how far to backtrack without having to
+// stop at the document level for every single element.
+//
+// Another thought is that we special case each element so the backtracking can
+// exit early if an ancestor with a relevant role has already been found.
+//
+// Alternatively see if providing an element that is part of a DOM can be
+// traversed by the `html-aria` library itself so these concerns are
+// centralised.
+function getAncestors(node: HTMLElement): AncestorList | undefined {
+  if (!rolesDependentOnHierarchy.has(getLocalName(node))) {
+    return undefined;
+  }
+
+  const ancestors: AncestorList = [];
+
+  let target: HTMLElement | null = node;
+  let targetLocalName: string;
+
+  while (true) {
+    target = target.parentElement;
+
+    if (!target) {
+      break;
+    }
+
+    targetLocalName = getLocalName(target);
+
+    if (ignoredAncestors.has(targetLocalName)) {
+      break;
+    }
+
+    ancestors.push({ tagName: targetLocalName as TagName });
+  }
+
+  return ancestors;
+}
+
 export function getRole({
   accessibleName,
   allowedAccessibilityRoles,
@@ -222,21 +276,9 @@ export function getRole({
 
   const baseImplicitRole = isBodyElement
     ? "document"
-    : // TODO: explore whether can supply ancestors without encountering
-      // performance issues.
-      //
-      // `getImplicitRole(virtualizeElement(target, { ancestors: getAncestors(node) }));`
-      //
-      // Thought needed if the `getAncestors()` can limit the number of parents
-      // it enumerates. Presumably as ancestors only matter for a limited
-      // number of roles, there might be a ceiling to the amount of nesting
-      // that is even valid, and therefore put an upper bound on how far to
-      // backtrack without having to stop at the document level for every
-      // single element.
-      //
-      // Alternatively see if providing an element that is part of a DOM can be
-      // traversed by the `html-aria` library itself.
-      getImplicitRole(virtualizeElement(target)) ?? "";
+    : getImplicitRole(virtualizeElement(target), {
+        ancestors: getAncestors(node),
+      }) ?? "";
 
   const implicitRole = mapAliasedRoles(baseImplicitRole);
 

src/getNodeAccessibilityData/index.ts

@@ -5,10 +5,12 @@ import { getAccessibleName } from "./getAccessibleName";
 import { getAccessibleValue } from "./getAccessibleValue";
 import { isElement } from "../isElement";
 
-const childrenPresentationalRoles = roles
-  .entries()
-  .filter(([, { childrenPresentational }]) => childrenPresentational)
-  .map(([key]) => key) as string[];
+const childrenPresentationalRoles = new Set(
+  roles
+    .entries()
+    .filter(([, { childrenPresentational }]) => childrenPresentational)
+    .map(([key]) => key) as string[]
+);
 
 const getSpokenRole = ({
   isGeneric,
@@ -72,8 +74,8 @@ export function getNodeAccessibilityData({
   const amendedAccessibleDescription =
     accessibleDescription === accessibleName ? "" : accessibleDescription;
 
-  const isExplicitPresentational = presentationRoles.includes(explicitRole);
-  const isPresentational = presentationRoles.includes(role);
+  const isExplicitPresentational = presentationRoles.has(explicitRole);
+  const isPresentational = presentationRoles.has(role);
   const isGeneric = role === "generic";
 
   const spokenRole = getSpokenRole({
@@ -103,8 +105,7 @@ export function getNodeAccessibilityData({
    *
    * REF: https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
    */
-  const isChildrenPresentationalRole =
-    childrenPresentationalRoles.includes(role);
+  const isChildrenPresentationalRole = childrenPresentationalRoles.has(role);
 
   /**
    * When an explicit or inherited role of presentation is applied to an

src/isDialogRole.ts

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

test/int/multipleInstances.int.test.ts

@@ -40,12 +40,10 @@ describe("Multiple Instances", () => {
       "Section Text",
       "end of paragraph",
       "article",
-      "banner",
       "heading, Article Header Heading 1, level 1",
       "paragraph",
       "Article Header Text",
       "end of paragraph",
-      "end of banner",
       "paragraph",
       "Article Text",
       "end of paragraph",
@@ -68,12 +66,10 @@ describe("Multiple Instances", () => {
       "end of paragraph",
       "Article Text",
       "paragraph",
-      "end of banner",
       "end of paragraph",
       "Article Header Text",
       "paragraph",
       "heading, Article Header Heading 1, level 1",
-      "banner",
       "article",
       "end of paragraph",
       "Section Text",

test/int/next.int.test.ts

@@ -31,13 +31,11 @@ describe("next", () => {
       "Section Text",
       "",
       "",
-      "",
       "Article Header Heading 1",
       "",
       "Article Header Text",
       "",
       "",
-      "",
       "Article Text",
       "",
       "",
@@ -59,12 +57,10 @@ describe("next", () => {
       "Section Text",
       "end of paragraph",
       "article",
-      "banner",
       "heading, Article Header Heading 1, level 1",
       "paragraph",
       "Article Header Text",
       "end of paragraph",
-      "end of banner",
       "paragraph",
       "Article Text",
       "end of paragraph",