feat(aria-label): new rule to flag incorrect use of aria-label, aria-labelledby, and aria-describeby

doc/rule-descriptions.md

@@ -82,6 +82,7 @@ Rules that do not necessarily conform to WCAG success criterion but are industry
 | [accesskeys](https://dequeuniversity.com/rules/axe/4.1/accesskeys?application=RuleDescription)                                                   | Ensures every accesskey attribute value is unique                                                          | Serious            | cat.keyboard, best-practice                     | failure                    |
 | [aria-allowed-role](https://dequeuniversity.com/rules/axe/4.1/aria-allowed-role?application=RuleDescription)                                     | Ensures role attribute has an appropriate value for the element                                            | Minor              | cat.aria, best-practice                         | failure, needs review |
 | [aria-dialog-name](https://dequeuniversity.com/rules/axe/4.1/aria-dialog-name?application=RuleDescription)                                       | Ensures every ARIA dialog and alertdialog node has an accessible name                                      | Serious            | cat.aria, best-practice                         | failure, needs review |
+| [aria-label](https://dequeuniversity.com/rules/axe/4.1/aria-label?application=RuleDescription)                                                   | Ensure aria-label(ledby) is only used on non-static elements                                               | Serious            | cat.aria, best-practice                         | failure                    |
 | [aria-treeitem-name](https://dequeuniversity.com/rules/axe/4.1/aria-treeitem-name?application=RuleDescription)                                   | Ensures every ARIA treeitem node has an accessible name                                                    | Serious            | cat.aria, best-practice                         | failure, needs review |
 | [empty-heading](https://dequeuniversity.com/rules/axe/4.1/empty-heading?application=RuleDescription)                                             | Ensures headings have discernible text                                                                     | Minor              | cat.name-role-value, best-practice              | failure, needs review |
 | [frame-tested](https://dequeuniversity.com/rules/axe/4.1/frame-tested?application=RuleDescription)                                               | Ensures <iframe> and <frame> elements contain the axe-core script                              | Critical           | cat.structure, review-item, best-practice       | failure, needs review |

lib/checks/aria/aria-label-valid-use-evaluate.js

@@ -0,0 +1,22 @@
+import { getRole } from '../../commons/aria';
+import { isFocusable } from '../../commons/dom';
+import { getAriaRolesByType } from '../../commons/standards';
+
+function ariaLabelValidUseEvaluate(node, options, virtualNode) {
+  const role = getRole(virtualNode);
+
+  // @see https://developer.paciellogroup.com/blog/2017/07/short-note-on-aria-label-aria-labelledby-and-aria-describedby/
+  if (
+    isFocusable(virtualNode) ||
+    getAriaRolesByType('landmark').includes(role) ||
+    getAriaRolesByType('widget').includes(role) ||
+    getAriaRolesByType('composite').includes(role) ||
+    ['img', 'frame', 'iframe'].includes(virtualNode.props.nodeName)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export default ariaLabelValidUseEvaluate;

lib/checks/aria/aria-label-valid-use.json

@@ -0,0 +1,11 @@
+{
+  "id": "aria-label-valid-use",
+  "evaluate": "aria-label-valid-use-evaluate",
+  "metadata": {
+    "impact": "serious",
+    "messages": {
+      "pass": "aria-label used on a supported role",
+      "fail": "aria-label used on a static element or role"
+    }
+  }
+}

lib/core/base/metadata-function-map.js

@@ -4,6 +4,7 @@ import ariaAllowedAttrEvaluate from '../../checks/aria/aria-allowed-attr-evaluat
 import ariaAllowedRoledEvaluate from '../../checks/aria/aria-allowed-role-evaluate';
 import ariaErrormessageEvaluate from '../../checks/aria/aria-errormessage-evaluate';
 import ariaHiddenBodyEvaluate from '../../checks/aria/aria-hidden-body-evaluate';
+import ariaLabelValidUseEvaluate from '../../checks/aria/aria-label-valid-use-evaluate';
 import ariaRequiredAttrEvaluate from '../../checks/aria/aria-required-attr-evaluate';
 import ariaRequiredChildrenEvaluate from '../../checks/aria/aria-required-children-evaluate';
 import ariaRequiredParentEvaluate from '../../checks/aria/aria-required-parent-evaluate';
@@ -174,6 +175,7 @@ const metadataFunctionMap = {
   'aria-allowed-role-evaluate': ariaAllowedRoledEvaluate,
   'aria-errormessage-evaluate': ariaErrormessageEvaluate,
   'aria-hidden-body-evaluate': ariaHiddenBodyEvaluate,
+  'aria-label-valid-use-evaluate': ariaLabelValidUseEvaluate,
   'aria-required-attr-evaluate': ariaRequiredAttrEvaluate,
   'aria-required-children-evaluate': ariaRequiredChildrenEvaluate,
   'aria-required-parent-evaluate': ariaRequiredParentEvaluate,

lib/rules/aria-label.json

@@ -0,0 +1,12 @@
+{
+  "id": "aria-label",
+  "selector": "[aria-label], [aria-labelledby], [aria-describedby]",
+  "tags": ["cat.aria", "best-practice"],
+  "metadata": {
+    "description": "Ensure aria-label(ledby) is only used on non-static elements",
+    "help": "Use aria-label, aria-labelledby, and aria-describedby on elements with non-static roles"
+  },
+  "all": [],
+  "any": ["aria-label-valid-use"],
+  "none": []
+}

test/checks/aria/aria-label-valid-use.js

@@ -0,0 +1,86 @@
+describe('aria-label-valid-use tests', function() {
+  'use strict';
+
+  var fixture = document.querySelector('#fixture');
+  var queryFixture = axe.testUtils.queryFixture;
+  var ariaLabelValid = axe.testUtils.getCheckEvaluate('aria-label-valid-use');
+
+  afterEach(function() {
+    fixture.innerHTML = '';
+  });
+
+  it('should return true when used on a focusable element', function() {
+    var vNode = queryFixture('<button id="target" aria-label="foo"></button>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<a href="#" id="target" aria-label="foo"></a>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<input id="target" aria-label="foo" />');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+  });
+
+  it('should return true when used on a landmark role', function() {
+    var vNode = queryFixture('<main id="target" aria-label="foo"></main>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture(
+      '<div id="target" role="main" aria-label="foo"></div>'
+    );
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<form id="target" aria-label="foo"></form>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+  });
+
+  it('should return true when used on a widget role', function() {
+    var vNode = queryFixture(
+      '<div id="target" role="button" aria-label="foo"></div>'
+    );
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture(
+      '<div id="target" role="slider" aria-label="foo"></div>'
+    );
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+  });
+
+  it('should return true when used on a composite role', function() {
+    var vNode = queryFixture(
+      '<div id="target" role="combobox" aria-label="foo"></div>'
+    );
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture(
+      '<div id="target" role="tablist" aria-label="foo"></div>'
+    );
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+  });
+
+  it('should return true when used on image and iframe', function() {
+    var vNode = queryFixture('<img id="target" aria-label="foo"></img>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<iframe id="target" aria-label="foo"></iframe>');
+    assert.isTrue(ariaLabelValid(null, null, vNode));
+  });
+
+  it('should return false if used on static elements', function() {
+    var vNode = queryFixture('<p id="target" aria-label="foo"></p>');
+    assert.isFalse(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<div id="target" aria-label="foo"></div>');
+    assert.isFalse(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<i id="target" aria-label="foo"></i>');
+    assert.isFalse(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture('<span id="target" aria-label="foo"></span>');
+    assert.isFalse(ariaLabelValid(null, null, vNode));
+
+    vNode = queryFixture(
+      '<div id="target" role="term" aria-label="foo"></div>'
+    );
+    assert.isFalse(ariaLabelValid(null, null, vNode));
+  });
+});

test/integration/rules/aria-label/aria-label.html

@@ -0,0 +1,24 @@
+<div id="pass1" role="alert" aria-label="value"></div>
+<div role="menu">
+  <div id="pass2" role="menuitem" aria-label="Save"></div>
+</div>
+<div id="pass3" role="dialog" aria-labelledby="pass5"></div>
+<dialog id="pass4" open role="alertdialog" aria-describedby="pass5"></dialog>
+<div id="pass5" aria-label="country" role="combobox">England</div>
+<div
+  id="pass6"
+  role="slider"
+  aria-label="Choose a value"
+  aria-valuemin="1"
+  aria-valuemax="7"
+  aria-valuenow="2"
+></div>
+<button id="pass7" aria-label="value"></button>
+<main id="pass8" aria-label="value"></main>
+<div id="pass9" role="main" aria-label="value"></div>
+
+<button>
+  <i id="fail1" aria-label="value" class="fa fa-cog"></i>
+</button>
+<span id="fail2" aria-labelledby="fail1"></span>
+<div id="fail3" aria-describedby="fail1"></div>

test/integration/rules/aria-label/aria-label.json

@@ -0,0 +1,16 @@
+{
+  "description": "aria-label tests",
+  "rule": "aria-label",
+  "violations": [["#fail1"], ["#fail2"], ["#fail3"]],
+  "passes": [
+    ["#pass1"],
+    ["#pass2"],
+    ["#pass3"],
+    ["#pass4"],
+    ["#pass5"],
+    ["#pass6"],
+    ["#pass7"],
+    ["#pass8"],
+    ["#pass9"]
+  ]
+}