fix: better unsupported attribute support for aria-roledescription

build/tasks/aria-supported.js

@@ -32,6 +32,46 @@ module.exports = function(grunt) {
 				return [...out, ...Object.keys(rule.props)];
 			}, []);
 			const aQaria = new Set(axe.utils.uniqueArray(roleAriaKeys, ariaKeys));
+			let footnotes;
+
+			/**
+			 * Parse a list of unsupported exception elements and add a footnote
+			 * detailing which HTML elements are supported.
+			 * @param {Array<String|Object>} elements List of supported elements
+			 */
+			const generateSupportFootnote = elements => {
+				let supportedElements = elements.map(element => {
+					if (typeof element === 'string') {
+						return `\`<${element}>\``;
+					}
+
+					/**
+					 * if element is not a string it will be an object with structure:
+					 	{
+							nodeName: string,
+							properties: {
+								type: {string|string[]}
+							}
+					 	}
+					 */
+					return Object.keys(element.properties).map(prop => {
+						const value = element.properties[prop];
+
+						// the 'type' property can be a string or an array
+						if (typeof value === 'string') {
+							return `\`<${element.nodeName} ${prop}="${value}">\``;
+						}
+
+						// output format for an array of types:
+						// <input type="button" | "checkbox">
+						let values = value.map(v => `"${v}"`).join(' | ');
+						return `\`<${element.nodeName} ${prop}=${values}>\``;
+					});
+				});
+				footnotes.push(
+					'Supported on elements: ' + supportedElements.join(', ')
+				);
+			};
 
 			/**
 			 * Given a `base` Map and `subject` Map object,
@@ -60,6 +100,13 @@ module.exports = function(grunt) {
 									!subject.hasOwnProperty(key)
 								) {
 									out.push([`${key}`, 'No']);
+								} else if (
+									subject[key] &&
+									subject[key].unsupported &&
+									subject[key].unsupported.exceptions
+								) {
+									out.push([`${key}`, `Mixed[^${footnotes.length + 1}]`]);
+									generateSupportFootnote(subject[key].unsupported.exceptions);
 								}
 								break;
 							case 'all':
@@ -77,11 +124,18 @@ module.exports = function(grunt) {
 					}, []);
 			};
 
-			const getMdContent = (heading, rolesTable, attributesTable) => {
-				return `${heading}\n\n## Roles\n\n${rolesTable}\n\n## Attributes\n\n${attributesTable}`;
+			const getMdContent = (
+				heading,
+				rolesTable,
+				attributesTable,
+				footnotes
+			) => {
+				return `${heading}\n\n## Roles\n\n${rolesTable}\n\n## Attributes\n\n${attributesTable}\n\n${footnotes}`;
 			};
 
 			const generateDoc = () => {
+				footnotes = [];
+
 				const content = getMdContent(
 					`# ARIA Roles and Attributes ${
 						listType === 'all' ? 'available' : listType
@@ -102,7 +156,8 @@ module.exports = function(grunt) {
 					mdTable([
 						['aria-attribute', 'axe-core support'],
 						...getDiff(aQaria, axe.commons.aria.lookupTable.attributes)
-					])
+					]),
+					footnotes.map((footnote, index) => `[^${index + 1}]: ${footnote}`)
 				);
 
 				// Format the content so Prettier doesn't create a diff after running.

doc/aria-supported.md

@@ -18,4 +18,6 @@ For a detailed description about how accessibility support is decided, see [How
 | -------------------- | ---------------- |
 | aria-describedat     | No               |
 | aria-details         | No               |
-| aria-roledescription | No               |
+| aria-roledescription | Mixed[^1]        |
+
+[^1]: Supported on elements: `<button>`, `<input type="button" | "checkbox" | "image" | "radio" | "reset" | "submit">`, `<img>`, `<select>`, `<summary>`

lib/checks/aria/unsupportedattr.js

@@ -1,16 +1,33 @@
-let unsupported = Array.from(node.attributes)
-	.filter(candidate => {
-		// filter out unsupported attributes
-		return axe.commons.aria.validateAttr(candidate.name, {
-			flagUnsupported: true
-		});
+const nodeName = node.nodeName.toUpperCase();
+const lookupTable = axe.commons.aria.lookupTable;
+const role = axe.commons.aria.getRole(node);
+
+const unsupportedAttrs = Array.from(node.attributes)
+	.filter(({ name }) => {
+		const attribute = lookupTable.attributes[name];
+		if (!axe.commons.aria.validateAttr(name) || !attribute.unsupported) {
+			return false;
+		}
+
+		const unsupported = attribute.unsupported;
+
+		if (typeof unsupported === 'boolean' || !unsupported.exceptions) {
+			return true;
+		}
+
+		// validate attributes and conditions (if any) from allowedElement to given node
+		let out = axe.commons.matches(node, unsupported.exceptions);
+
+		// if given node type has complex condition to evaluate a given aria-role, execute the same
+		if (Object.keys(lookupTable.evaluateRoleForElement).includes(nodeName)) {
+			return !lookupTable.evaluateRoleForElement[nodeName]({ node, role, out });
+		}
+		return !out;
 	})
-	.map(candidate => {
-		return candidate.name.toString();
-	});
+	.map(candidate => candidate.name.toString());
 
-if (unsupported.length) {
-	this.data(unsupported);
+if (unsupportedAttrs.length) {
+	this.data(unsupportedAttrs);
 	return true;
 }
 return false;

lib/commons/aria/attributes.js

@@ -37,13 +37,9 @@ aria.allowedAttr = function(role) {
  * @memberof axe.commons.aria
  * @instance
  * @param  {String} att The attribute name
- * @param  {Object} options Use `flagUnsupported: true` to report unsupported attributes
  * @return {Boolean}
  */
-aria.validateAttr = function(att, { flagUnsupported = false } = {}) {
+aria.validateAttr = function validateAttr(att) {
 	const attrDefinition = aria.lookupTable.attributes[att];
-	if (flagUnsupported && attrDefinition) {
-		return !!attrDefinition.unsupported;
-	}
 	return !!attrDefinition;
 };

lib/commons/aria/index.js

@@ -196,7 +196,22 @@ lookupTable.attributes = {
 		unsupported: false
 	},
 	'aria-roledescription': {
-		unsupported: true
+		type: 'string',
+		allowEmpty: true,
+		unsupported: {
+			exceptions: [
+				'button',
+				{
+					nodeName: 'input',
+					properties: {
+						type: ['button', 'checkbox', 'image', 'radio', 'reset', 'submit']
+					}
+				},
+				'img',
+				'select',
+				'summary'
+			]
+		}
 	},
 	'aria-rowcount': {
 		type: 'int',

test/checks/aria/unsupportedattr.js

@@ -49,4 +49,66 @@ describe('unsupportedattr', function() {
 		);
 		assert.isFalse(check.evaluate.apply(checkContext, params));
 	});
+
+	it('should return false if applied to an element that matches the unsupported "exceptions" list', function() {
+		axe.commons.aria.lookupTable.attributes['aria-mccheddarton'] = {
+			unsupported: {
+				exceptions: ['button']
+			}
+		};
+		var params = checkSetup(
+			'<button id="target" aria-mccheddarton="true">Contents</div>'
+		);
+		assert.isFalse(check.evaluate.apply(checkContext, params));
+	});
+
+	it('should return false if applied to an element that matches the unsupported "exceptions" list using complex conditions', function() {
+		axe.commons.aria.lookupTable.attributes['aria-mccheddarton'] = {
+			unsupported: {
+				exceptions: [
+					{
+						nodeName: 'input',
+						properties: {
+							type: 'checkbox'
+						}
+					}
+				]
+			}
+		};
+		var params = checkSetup(
+			'<input type="checkbox" id="target" aria-mccheddarton="true">Contents</div>'
+		);
+		assert.isFalse(check.evaluate.apply(checkContext, params));
+	});
+
+	it('should return true if applied to an element that does not match the unsupported "exceptions" list', function() {
+		axe.commons.aria.lookupTable.attributes['aria-mccheddarton'] = {
+			unsupported: {
+				exceptions: ['button']
+			}
+		};
+		var params = checkSetup(
+			'<div id="target" aria-mccheddarton="true">Contents</div>'
+		);
+		assert.isTrue(check.evaluate.apply(checkContext, params));
+	});
+
+	it('should return true if applied to an element that does not match the unsupported "exceptions" list using complex conditions', function() {
+		axe.commons.aria.lookupTable.attributes['aria-mccheddarton'] = {
+			unsupported: {
+				exceptions: [
+					{
+						nodeName: 'input',
+						properties: {
+							type: 'checkbox'
+						}
+					}
+				]
+			}
+		};
+		var params = checkSetup(
+			'<input type="radio" id="target" aria-mccheddarton="true">Contents</div>'
+		);
+		assert.isTrue(check.evaluate.apply(checkContext, params));
+	});
 });

test/checks/aria/valid-attr.js

@@ -21,7 +21,7 @@ describe('aria-valid-attr', function() {
 		assert.deepEqual(checkContext._data, ['aria-cats', 'aria-dogs']);
 	});
 
-	it('should return false if no invalid ARIA attributes are found', function() {
+	it('should return true if no invalid ARIA attributes are found', function() {
 		var node = document.createElement('div');
 		node.id = 'test';
 		node.tabIndex = 1;
@@ -54,6 +54,21 @@ describe('aria-valid-attr', function() {
 		axe.commons.aria.validateAttr = orig;
 	});
 
+	it('should return true for unsupported ARIA attributes', function() {
+		axe.commons.aria.lookupTable.attributes['aria-mccheddarton'] = {
+			unsupported: true
+		};
+
+		var node = document.createElement('div');
+		node.id = 'test';
+		node.tabIndex = 1;
+		node.setAttribute('aria-mccheddarton', 'true');
+		fixture.appendChild(node);
+
+		assert.isTrue(checks['aria-valid-attr'].evaluate.call(checkContext, node));
+		assert.isNull(checkContext._data);
+	});
+
 	describe('options', function() {
 		it('should exclude provided attribute names', function() {
 			fixture.innerHTML =