feat(aria): support role=image as a synonym for role=img

Add a reusable synonym mechanism: the image role is defined as a synonym
of img (ARIA 1.3, w3c/aria#1370) and getExplicitRole/getRole resolve
synonym roles to their canonical role by default, with a noSynonym opt
out. The role-img-alt selector and aria-allowed-role role resolution are
updated so role=image behaves like role=img.

Closes #4656

Author: chutchins25

lib/commons/aria/get-element-unallowed-roles.js

@@ -2,6 +2,7 @@ import isValidRole from './is-valid-role';
 import getImplicitRole from './implicit-role';
 import getRoleType from './get-role-type';
 import isAriaRoleAllowedOnElement from './is-aria-role-allowed-on-element';
+import standards from '../../standards';
 import { tokenList, isHtmlElement, nodeLookup } from '../../core/utils';
 
 // dpub roles which are subclassing roles that are implicit on some native
@@ -41,8 +42,11 @@ function getRoleSegments(vNode) {
     roles = roles.concat(nodeRoles);
   }
 
-  // filter invalid roles
-  return roles.filter(role => isValidRole(role));
+  // filter invalid roles and resolve synonym roles (e.g. `image` -> `img`)
+  // so the allowed-role check compares against the canonical role
+  return roles
+    .filter(role => isValidRole(role))
+    .map(role => standards.ariaRoles[role]?.synonym || role);
 }
 
 /**

lib/commons/aria/get-explicit-role.js

@@ -1,8 +1,9 @@
 import isValidRole from './is-valid-role';
+import standards from '../../standards';
 import { getNodeFromTree, tokenList } from '../../core/utils';
 import AbstractVirtuaNode from '../../core/base/virtual-node/abstract-virtual-node';
 
-function getExplicitRole(vNode, { fallback, abstracts, dpub } = {}) {
+function getExplicitRole(vNode, { fallback, abstracts, dpub, noSynonym } = {}) {
   vNode = vNode instanceof AbstractVirtuaNode ? vNode : getNodeFromTree(vNode);
 
   if (vNode.props.nodeType !== 1) {
@@ -20,7 +21,18 @@ function getExplicitRole(vNode, { fallback, abstracts, dpub } = {}) {
     return isValidRole(role, { allowAbstract: abstracts });
   });
 
-  return firstValidRole || null;
+  if (!firstValidRole) {
+    return null;
+  }
+
+  // Resolve synonym roles (e.g. `image` -> `img`) to their canonical role
+  // unless the caller explicitly wants the literal role.
+  const synonym = standards.ariaRoles[firstValidRole]?.synonym;
+  if (!noSynonym && synonym) {
+    return synonym;
+  }
+
+  return firstValidRole;
 }
 
 export default getExplicitRole;

lib/commons/aria/get-role.js

@@ -171,6 +171,7 @@ function resolveRole(node, { noImplicit, ...roleOptions } = {}) {
  * @param {boolean} options.dpub  Allow role to be any (valid) doc-* roles
  * @param {boolean} options.noPresentational return null if role is presentation or none
  * @param {boolean} options.chromium Include implicit roles from chromium-based browsers in role result
+ * @param {boolean} options.noSynonym Return the literal role rather than resolving a synonym role (e.g. `image`) to its canonical role (`img`)
  * @returns {string|null} Role or null
  *
  * @deprecated noImplicit option is deprecated. Use aria.getExplicitRole instead.

lib/rules/role-img-alt.json

@@ -1,7 +1,7 @@
 {
   "id": "role-img-alt",
   "impact": "serious",
-  "selector": "[role='img']:not(img, area, input, object)",
+  "selector": "[role='img']:not(img, area, input, object), [role='image']:not(img, area, input, object)",
   "matches": "html-namespace-matches",
   "tags": [
     "cat.text-alternatives",

lib/standards/aria-roles.js

@@ -267,6 +267,18 @@ const ariaRoles = {
     accessibleNameRequired: false,
     nameFromContent: true
   },
+  image: {
+    type: 'structure',
+    // Synonym of img, added in ARIA 1.3 (w3c/aria#1370). Kept as a full
+    // definition so code paths that read the role directly (without
+    // normalizing the synonym) still behave identically to img.
+    synonym: 'img',
+    // Spec difference: Aria-expanded removed in 1.2
+    allowedAttrs: ['aria-expanded'],
+    superclassRole: ['section'],
+    accessibleNameRequired: true,
+    childrenPresentational: true
+  },
   img: {
     type: 'structure',
     // Spec difference: Aria-expanded removed in 1.2

test/commons/aria/get-element-unallowed-roles.js

@@ -214,4 +214,18 @@ describe('aria.getElementUnallowedRoles', () => {
     assert.isNotEmpty(actual);
     assert.include(actual, 'application');
   });
+
+  it('returns empty for the synonym role=image on an svg elm', () => {
+    const node = document.createElement('svg');
+    node.setAttribute('role', 'image');
+    flatTreeSetup(node);
+    assert.isEmpty(getElementUnallowedRoles(node));
+  });
+
+  it('returns empty for the synonym role=image on an embed elm', () => {
+    const node = document.createElement('embed');
+    node.setAttribute('role', 'image');
+    flatTreeSetup(node);
+    assert.isEmpty(getElementUnallowedRoles(node));
+  });
 });

test/commons/aria/get-explicit-role.js

@@ -141,4 +141,34 @@ describe('aria.getExplicitRole', () => {
       );
     });
   });
+
+  describe('synonym roles', () => {
+    it('resolves the synonym role `image` to `img`', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'image');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getExplicitRole(vNode), 'img');
+    });
+
+    it('returns the literal role with the `noSynonym` option', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'image');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getExplicitRole(vNode, { noSynonym: true }), 'image');
+    });
+
+    it('leaves the canonical role `img` unchanged', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'img');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getExplicitRole(vNode), 'img');
+    });
+
+    it('resolves the synonym when it is the first valid fallback role', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'foo image');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getExplicitRole(vNode, { fallback: true }), 'img');
+    });
+  });
 });

test/commons/aria/get-role.js

@@ -465,4 +465,20 @@ describe('aria.getRole', () => {
       });
     });
   });
+
+  describe('synonym roles', () => {
+    it('resolves the synonym role `image` to `img`', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'image');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getRole(vNode), 'img');
+    });
+
+    it('returns the literal role with the `noSynonym` option', () => {
+      const node = document.createElement('div');
+      node.setAttribute('role', 'image');
+      const vNode = flatTreeSetup(node)[0];
+      assert.equal(aria.getRole(vNode, { noSynonym: true }), 'image');
+    });
+  });
 });

test/commons/aria/is-valid-role.js

@@ -27,4 +27,8 @@ describe('aria.isValidRole', () => {
       axe.commons.aria.isValidRole('input', { allowAbstract: true })
     );
   });
+
+  it('returns true for the synonym role `image`', () => {
+    assert.isTrue(axe.commons.aria.isValidRole('image'));
+  });
 });

test/integration/rules/aria-allowed-role/aria-allowed-role.html

@@ -38,6 +38,7 @@ <h1 id="pass-h1-role-doc-subtitle" role="doc-subtitle"></h1>
 <header id="pass-header-valid-role" role="group"></header>
 <footer id="pass-footer-valid-role" role="group"></footer>
 <embed id="pass-embed-valid-role" role="img" />
+<embed id="pass-embed-synonym-role-image" role="image" />
 <input type="text" role="textbox" id="pass-input-text-redundant-role" />
 <input type="text" role="textbox combobox" id="pass-input-multiple-roles" />
 <input