docs: rename aria._lut, add to developer guide

doc/developer-guide.md

@@ -152,6 +152,21 @@ Common functions are an internal library used by the rules and checks.  If you h
 
 Core Utilities are an internal library that provides aXe with functionality used throughout its core processes. Most notably among these are the queue function and the DqElement constructor.
 
+#### ARIA Lookup Tables
+
+axe.commons.aria provides a namespace for ARIA-related utilities, including a lookupTable for attributes and roles.
+
+* `axe.commons.aria.lookupTable.attributes`
+* `axe.commons.aria.lookupTable.globalAttributes`
+* `axe.commons.aria.lookupTable.role`
+
+#### Common Utility Functions
+
+In addition to the ARIA lookupTable, there are also utility functions on the axe.commons.aria and axe.commons.dom namespaces:
+
+* `axe.commons.aria.implicitRole` - Get the implicit role for a given node
+* `axe.commons.aria.label` - Gets the accessible ARIA label text of a given element
+* `axe.commons.dom.isVisible` - Determine whether an element is visible
 
 #### Queue Function
 

lib/commons/aria/attributes.js

@@ -1,4 +1,4 @@
-/*global aria, axe, lookupTables */
+/*global aria, axe */
 
 /**
  * Get required attributes for a given role
@@ -10,7 +10,7 @@
  */
 aria.requiredAttr = function (role) {
 	'use strict';
-	var roles = lookupTables.role[role],
+	var roles = aria.lookupTable.role[role],
 		attr = roles && roles.attributes && roles.attributes.required;
 	return attr || [];
 };
@@ -25,11 +25,11 @@ aria.requiredAttr = function (role) {
  */
 aria.allowedAttr = function (role) {
 	'use strict';
-	var roles = lookupTables.role[role],
+	var roles = aria.lookupTable.role[role],
 		attr = (roles && roles.attributes && roles.attributes.allowed) || [],
 		requiredAttr = (roles && roles.attributes && roles.attributes.required) || [];
 
-	return attr.concat(lookupTables.globalAttributes).concat(requiredAttr);
+	return attr.concat(aria.lookupTable.globalAttributes).concat(requiredAttr);
 };
 
 /**
@@ -42,7 +42,7 @@ aria.allowedAttr = function (role) {
  */
 aria.validateAttr = function (att) {
 	'use strict';
-	return !!lookupTables.attributes[att];
+	return !!aria.lookupTable.attributes[att];
 };
 
 /**
@@ -60,7 +60,7 @@ aria.validateAttrValue = function (node, attr) {
 	var matches, list,
 		doc = document,
 		value = node.getAttribute(attr),
-		attrInfo = lookupTables.attributes[attr];
+		attrInfo = aria.lookupTable.attributes[attr];
 
 	if (!attrInfo) {
 		return true;

lib/commons/aria/index.js

@@ -5,9 +5,9 @@
  */
 
 var aria = commons.aria = {},
-	lookupTables = aria._lut = {};
+	lookupTable = aria.lookupTable = {};
 
-lookupTables.attributes = {
+lookupTable.attributes = {
 	'aria-activedescendant': {
 		type: 'idref'
 	},
@@ -171,14 +171,14 @@ lookupTables.attributes = {
 	}
 };
 
-lookupTables.globalAttributes = [
+lookupTable.globalAttributes = [
 	'aria-atomic', 'aria-busy', 'aria-controls', 'aria-current', 'aria-describedby',
 	'aria-disabled', 'aria-dropeffect', 'aria-flowto', 'aria-grabbed',
 	'aria-haspopup', 'aria-hidden', 'aria-invalid', 'aria-keyshortcuts', 'aria-label',
 	'aria-labelledby', 'aria-live', 'aria-owns', 'aria-relevant'
 ];
 
-lookupTables.role = {
+lookupTable.role = {
 	'alert': {
 		type: 'widget',
 		attributes: {

lib/commons/aria/roles.js

@@ -1,4 +1,4 @@
-/* global aria, lookupTables, axe */
+/* global aria, axe */
 
 /**
  * Check if a given role is valid
@@ -10,7 +10,7 @@
  */
 aria.isValidRole = function (role) {
 	'use strict';
-	if (lookupTables.role[role]) {
+	if (aria.lookupTable.role[role]) {
 		return true;
 	}
 
@@ -25,9 +25,9 @@ aria.isValidRole = function (role) {
  * @return {Array} Array of roles that match the type
  */
 aria.getRolesWithNameFromContents = function () {
-	return Object.keys(lookupTables.role).filter(function (r) {
-		return lookupTables.role[r].nameFrom &&
-			lookupTables.role[r].nameFrom.indexOf('contents') !== -1;
+	return Object.keys(aria.lookupTable.role).filter(function (r) {
+		return aria.lookupTable.role[r].nameFrom &&
+			aria.lookupTable.role[r].nameFrom.indexOf('contents') !== -1;
 	});
 };
 
@@ -40,8 +40,8 @@ aria.getRolesWithNameFromContents = function () {
  * @return {Array}           Array of roles that match the type
  */
 aria.getRolesByType = function (roleType) {
-	return Object.keys(lookupTables.role).filter(function (r) {
-		return lookupTables.role[r].type === roleType;
+	return Object.keys(aria.lookupTable.role).filter(function (r) {
+		return aria.lookupTable.role[r].type === roleType;
 	});
 };
 
@@ -54,7 +54,7 @@ aria.getRolesByType = function (roleType) {
  * @return {Mixed}       String if a matching role and its type are found, otherwise `null`
  */
 aria.getRoleType = function (role) {
-	var r = lookupTables.role[role];
+	var r = aria.lookupTable.role[role];
 
 	return (r && r.type) || null;
 };
@@ -70,7 +70,7 @@ aria.getRoleType = function (role) {
 aria.requiredOwned = function (role) {
 	'use strict';
 	var owned = null,
-		roles = lookupTables.role[role];
+		roles = aria.lookupTable.role[role];
 
 	if (roles) {
 		owned = axe.utils.clone(roles.owned);
@@ -89,7 +89,7 @@ aria.requiredOwned = function (role) {
 aria.requiredContext = function (role) {
 	'use strict';
 	var context = null,
-		roles = lookupTables.role[role];
+		roles = aria.lookupTable.role[role];
 
 	if (roles) {
 		context = axe.utils.clone(roles.context);
@@ -109,7 +109,7 @@ aria.implicitNodes = function (role) {
 	'use strict';
 
 	var implicit = null,
-		roles = lookupTables.role[role];
+		roles = aria.lookupTable.role[role];
 
 	if (roles && roles.implicit) {
 		implicit = axe.utils.clone(roles.implicit);
@@ -172,8 +172,8 @@ aria.implicitRole = function (node) {
 	/*
 	 * Create a list of { name / implicit } role mappings to filter on
 	 */
-	var roles = Object.keys(lookupTables.role).map( function (role) {
-		var lookup = lookupTables.role[role];
+	var roles = Object.keys(aria.lookupTable.role).map( function (role) {
+		var lookup = aria.lookupTable.role[role];
 		return { name: role, implicit: lookup && lookup.implicit };
 	});
 

test/commons/aria/attributes.js

@@ -4,15 +4,15 @@ describe('aria.requiredAttr', function () {
 
 	var orig;
 	beforeEach(function () {
-		orig = axe.commons.aria._lut.role;
+		orig = axe.commons.aria.lookupTable.role;
 	});
 
 	afterEach(function () {
-		axe.commons.aria._lut.role = orig;
+		axe.commons.aria.lookupTable.role = orig;
 	});
 
 	it('should returned the attributes property for the proper role', function () {
-		axe.commons.aria._lut.role = {
+		axe.commons.aria.lookupTable.role = {
 			'cats': {
 				attributes: {
 					required: 'yes'
@@ -24,7 +24,7 @@ describe('aria.requiredAttr', function () {
 	});
 
 	it('should return an empty array if there are no required attributes', function () {
-		axe.commons.aria._lut.role = {};
+		axe.commons.aria.lookupTable.role = {};
 		var result = axe.commons.aria.requiredAttr('cats');
 
 		assert.deepEqual(result, []);
@@ -37,16 +37,16 @@ describe('aria.allowedAttr', function () {
 
 	var orig;
 	beforeEach(function () {
-		orig = axe.commons.aria._lut.role;
+		orig = axe.commons.aria.lookupTable.role;
 	});
 
 	afterEach(function () {
-		axe.commons.aria._lut.role = orig;
+		axe.commons.aria.lookupTable.role = orig;
 	});
 
 	it('should returned the attributes property for the proper role', function () {
-		var orig = axe.commons.aria._lut.globalAttributes = ['world'];
-		axe.commons.aria._lut.role = {
+		var orig = axe.commons.aria.lookupTable.globalAttributes = ['world'];
+		axe.commons.aria.lookupTable.role = {
 			'cats': {
 				attributes: {
 					allowed: ['hello']
@@ -55,12 +55,12 @@ describe('aria.allowedAttr', function () {
 		};
 
 		assert.deepEqual(axe.commons.aria.allowedAttr('cats'), ['hello', 'world']);
-		axe.commons.aria._lut.globalAttributes = orig;
+		axe.commons.aria.lookupTable.globalAttributes = orig;
 	});
 
 	it('should also check required attributes', function () {
-		var orig = axe.commons.aria._lut.globalAttributes = ['world'];
-		axe.commons.aria._lut.role = {
+		var orig = axe.commons.aria.lookupTable.globalAttributes = ['world'];
+		axe.commons.aria.lookupTable.role = {
 			'cats': {
 				attributes: {
 					required: ['hello'],
@@ -70,18 +70,18 @@ describe('aria.allowedAttr', function () {
 		};
 
 		assert.deepEqual(axe.commons.aria.allowedAttr('cats'), ['ok', 'world', 'hello']);
-		axe.commons.aria._lut.globalAttributes = orig;
+		axe.commons.aria.lookupTable.globalAttributes = orig;
 	});
 
 	it('should return an array with globally allowed attributes', function () {
 		var result,
-			orig = axe.commons.aria._lut.globalAttributes = ['world'];
+			orig = axe.commons.aria.lookupTable.globalAttributes = ['world'];
 
-		axe.commons.aria._lut.role = {};
+		axe.commons.aria.lookupTable.role = {};
 		result = axe.commons.aria.allowedAttr('cats');
 
 		assert.deepEqual(result, ['world']);
-		axe.commons.aria._lut.globalAttributes = orig;
+		axe.commons.aria.lookupTable.globalAttributes = orig;
 
 	});
 });
@@ -91,23 +91,23 @@ describe('aria.validateAttr', function () {
 
 	var orig;
 	beforeEach(function () {
-		orig = axe.commons.aria._lut.attributes;
+		orig = axe.commons.aria.lookupTable.attributes;
 	});
 
 	afterEach(function () {
-		axe.commons.aria._lut.attributes = orig;
+		axe.commons.aria.lookupTable.attributes = orig;
 	});
 
 	it('should return true if attribute is found in lut', function () {
-		axe.commons.aria._lut.attributes = {
+		axe.commons.aria.lookupTable.attributes = {
 			'cats': {}
 		};
 
 		assert.isTrue(axe.commons.aria.validateAttr('cats'));
 	});
 
 	it('should return false if attribute is found in lut', function () {
-		axe.commons.aria._lut.attributes = {};
+		axe.commons.aria.lookupTable.attributes = {};
 
 		assert.isFalse(axe.commons.aria.validateAttr('cats'));
 	});
@@ -116,11 +116,11 @@ describe('aria.validateAttr', function () {
 describe('aria.validateAttrValue', function () {
 	'use strict';
 
-	var orig = axe.commons.aria._lut.attributes,
+	var orig = axe.commons.aria.lookupTable.attributes,
 		fixture = document.getElementById('fixture');
 
 	afterEach(function () {
-		axe.commons.aria._lut.attributes = orig;
+		axe.commons.aria.lookupTable.attributes = orig;
 		fixture.innerHTML = '';
 	});
 
@@ -135,7 +135,7 @@ describe('aria.validateAttrValue', function () {
 
 		describe('enumerated values', function () {
 			it('should validate against enumerated .values if present', function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'nmtoken',
 						values: ['valid']
@@ -152,7 +152,7 @@ describe('aria.validateAttrValue', function () {
 
 			});
 			it('should be case-insensitive for enumerated values', function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'nmtoken',
 						values: ['valid']
@@ -165,7 +165,7 @@ describe('aria.validateAttrValue', function () {
 
 			});
 			it('should reject empty strings', function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'nmtoken',
 						values: ['valid']
@@ -179,7 +179,7 @@ describe('aria.validateAttrValue', function () {
 		});
 		describe('idref', function () {
 			it('should validate the referenced node exists', function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'idref'
 					}
@@ -198,7 +198,7 @@ describe('aria.validateAttrValue', function () {
 
 			var node = document.createElement('div');
 			beforeEach(function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'idrefs'
 					}
@@ -236,7 +236,7 @@ describe('aria.validateAttrValue', function () {
 
 		describe('string', function () {
 			it('should always return true', function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'string'
 					}
@@ -250,7 +250,7 @@ describe('aria.validateAttrValue', function () {
 		describe('decimal', function () {
 			var node = document.createElement('div');
 			beforeEach(function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'decimal'
 					}
@@ -351,7 +351,7 @@ describe('aria.validateAttrValue', function () {
 		describe('int', function () {
 			var node = document.createElement('div');
 			beforeEach(function () {
-				axe.commons.aria._lut.attributes = {
+				axe.commons.aria.lookupTable.attributes = {
 					cats: {
 						type: 'int'
 					}