docs(ngAria): Add Usage Details and Examples

Author: Marcy Sutton

docs/content/api/index.ngdoc

@@ -161,6 +161,27 @@ or JavaScript callbacks.
   </tr>
 </table>
 
+## {@link ngAria ngAria}
+
+Use ngAria to inject common accessibility attributes into directives and improve the experience for users with disabilities.
+
+<div class="alert alert-info">Include the **angular-aria.js** file and set ngAria as a dependency for this to work in your application.</div>
+
+<table class="definition-table spaced">
+  <tr>
+    <td>
+      {@link ngAria#service Services}
+    </td>
+    <td>
+      <p>
+          The {@link ngAria.$aria $aria} service contains helper methods for applying ARIA attributes to HTML.
+      <p>
+      <p>
+          {@link ngAria.$ariaProvider $ariaProvider} is used for configuring ARIA attributes.
+      </p>
+    </td>
+  </tr>
+</table>
 
 ## {@link ngResource ngResource}
 

docs/content/guide/accessibility.ngdoc

@@ -12,14 +12,23 @@ assistive technologies used by persons with disabilities.
 
 ##Including ngAria
 
-Using ngAria is as simple as requiring the ngAria module in your application. ngAria hooks into
+Using {@link ngAria ngAria} is as simple as requiring the ngAria module in your application. ngAria hooks into
 standard AngularJS directives and quietly injects accessibility support into your application
 at runtime.
 
 ```js
 angular.module('myApp', ['ngAria'])...
 ```
 
+###Using ngAria
+Most of what ngAria does is only visible "under the hood". To see the module in action, once you've
+added it as a dependency, you can test a few things:
+ * Using your favorite element inspector, look for ngAria attributes in your own code.
+ * Test using your keyboard to ensure `tabindex` is used correctly.
+ * Fire up a screen reader such as VoiceOver to listen for ARIA support.
+[Helpful screen reader tips.](http://webaim.org/articles/screenreader_testing/)
+
+##Supported directives
 Currently, ngAria interfaces with the following directives:
 
  * <a href="#ngmodel">ngModel</a>
@@ -31,7 +40,7 @@ Currently, ngAria interfaces with the following directives:
 
 <h2 id="ngmodel">ngModel</h2>
 
-Most of ngAria's heavy lifting happens in the [ngModel](https://docs.angularjs.org/api/ng/directive/ngModel)
+Most of ngAria's heavy lifting happens in the {@link ngModel ngModel}
 directive.  For elements using ngModel, special attention is paid by ngAria if that element also
 has a a role or type of `checkbox`, `radio`, `range` or `textbox`.
 
@@ -47,15 +56,41 @@ attributes (if they have not been explicitly specified by the developer):
 
 ###Example
 
-```html
-<md-checkbox ng-model="val" required>
-```
-
-Becomes:
-
-```html
-<md-checkbox ng-model="val" required aria-required="true" tabIndex="0">
-```
+<example module="ngAria_ngModelExample" deps="angular-aria.js">
+ <file name="index.html">
+  <style>
+    some-checkbox {
+      background-color: black;
+      color: white;
+    }
+  </style>
+ <div print-markup>
+ <form>
+  <some-checkbox ng-model="user.subscribe" required>
+    Fake Checkbox
+  </some-checkbox>
+ </form>
+ </div>
+ <script>
+  var app = angular.module('ngAria_ngModelExample', ['ngAria']);
+
+  app.directive('printMarkup', function() {
+    return {
+      restrict: 'A',
+      link: function($scope, $el, $attrs) {
+        var el = $el[0].querySelector('form');
+        var newEl = document.createElement('div');
+        var output = 'Becomes: <pre><code>' +
+          el.innerHTML.replace(/&/g, '&amp;').replace(/</g, '&lt;') +
+        '</code></pre>';
+        newEl.innerHTML = output;
+        el.parentNode.insertBefore(newEl, el.nextSibling);
+      }
+    }
+  });
+ </script>
+ </file>
+</example>
 
 ngAria will also add `tabIndex`, ensuring custom elements with these roles will be reachable from
 the keyboard. It is still up to **you** as a developer to **ensure custom controls will be
@@ -106,6 +141,24 @@ screen reader users won't accidentally focus on "mystery elements". Managing tab
 child control can be complex and affect performance, so it’s best to just stick with the default
 `display: none` CSS. See the [fourth rule of ARIA use](http://www.w3.org/TR/aria-in-html/#fourth-rule-of-aria-use).
 
+###Example
+```css
+.ng-hide {
+  display: block;
+  opacity: 0;
+}
+```
+```html
+<div ng-show="false" class="ng-hide" aria-hidden="true"></div>
+```
+
+Becomes:
+
+```html
+<div ng-show="true" aria-hidden="false"></div>
+```
+*Note: Child links, buttons or other interactive controls must also be removed from the tab order.*
+
 <h2 id="nghide">ngHide</h2>
 
 >The [ngHide](https://docs.angularjs.org/api/ng/directive/ngHide) directive shows or hides the
@@ -116,33 +169,86 @@ The default CSS for `ngHide`, the inverse method to `ngShow`, makes ngAria redun
 `aria-hidden` on the directive when it is hidden or shown, but the content is already hidden with
 `display: none`. See explanation for <a href="#ngshow">ngShow</a> when overriding the default CSS.
 
-<h2 id="ngclick">ngClick and ngDblClick</h2>
-If `ngClick` or `ngDblClick` is encountered, ngAria will add `tabIndex` if it isn't there already.
-Even with this, you must currently still add `ng-keypress` to non-interactive elements such as
-`<div>` or `<taco-button>` to enable keyboard access. Conversation is
-[currently ongoing](https://github.com/angular/angular.js/issues/9254) about whether ngAria
-should also bind `ng-keypress` to be more useful.
+<h2 id="ngclick">ngClick and ngDblclick</h2>
+If `ng-click` or `ng-dblclick` is encountered, ngAria will add `tabindex` if it isn't there already.
+Even with this, you must currently still add `ng-keypress` to non-interactive elements such as `div`
+or `taco-button` to enable keyboard access. Conversation is currently ongoing about whether ngAria
+should also bind `ng-keypress`.
+
+###Example
+```html
+<div ng-click="toggleMenu()"></div>
+```
+
+Becomes:
+```html
+<div ng-click="toggleMenu()" tabindex="0"></div>
+```
+*Note: ngAria still requires `ng-keypress` to be added manually to non-native controls like divs.*
 
 <h2 id="ngmessages">ngMessages</h2>
 
 The new ngMessages module makes it easy to display form validation or other messages with priority
 sequencing and animation. To expose these visual messages to screen readers,
 ngAria injects `aria-live="polite"`, causing them to be read aloud any time a message is shown,
 regardless of the user's focus location.
+###Example
 
-* * *
+```html
+<div ng-messages="myForm.myName.$error">
+  <div ng-message="required">You did not enter a field</div>
+  <div ng-message="maxlength">Your field is too long</div>
+</div>
+```
 
-##Disabling attributes
-The attribute magic of ngAria may not work for every scenario. To disable individual attributes,
-you can use the {@link ngAria.$ariaProvider#config config} method:
+Becomes:
 
+```html
+<div ng-messages="myForm.myName.$error" aria-live="polite">
+  <div ng-message="required">You did not enter a field</div>
+  <div ng-message="maxlength">Your field is too long</div>
+</div>
 ```
-angular.module('myApp', ['ngAria'], function config($ariaProvider) {
-  $ariaProvider.config({
-    tabindex: false
+
+##Disabling attributes
+The attribute magic of ngAria may not work for every scenario. To disable individual attributes,
+you can use the {@link ngAria.$ariaProvider#config config} method. Just keep in mind this will
+tell ngAria to ignore the attribute globally.
+
+<example module="ngAria_ngDisabledExample" deps="angular-aria.js">
+ <file name="index.html">
+ <form>
+  <div ng-model="someModel" show-attrs>
+    Div with ngModel, aria-invalid and tabindex disabled
+  </div>
+ </form>
+ <script>
+  angular.module('ngAria_ngDisabledExample', ['ngAria'], function config($ariaProvider) {
+    $ariaProvider.config({
+      ariaInvalid: false,
+      tabindex: false
+    });
+  })
+  .directive('showAttrs', function() {
+    return function(scope, el, attrs) {
+      var pre = document.createElement('pre');
+      el.after(pre);
+      scope.$watch(function() {
+        var attrs = {};
+        Array.prototype.slice.call(el[0].attributes, 0).forEach(function(item) {
+          if (item.name !== 'show-attrs') {
+            attrs[item.name] = item.value;
+          }
+        });
+        return attrs;
+      }, function(newAttrs, oldAttrs) {
+        pre.innerText = JSON.stringify(newAttrs, null, 2);
+      }, true);
+    }
   });
-});
-```
+ </script>
+ </file>
+</example>
 
 ##Common Accessibility Patterns
 
@@ -171,6 +277,7 @@ Accessibility best practices that apply to web apps in general also apply to Ang
 
  * [Using ARIA in HTML](http://www.w3.org/TR/aria-in-html/)
  * [AngularJS Accessibility at ngEurope](https://www.youtube.com/watch?v=dmYDggEgU-s&list=UUEGUP3TJJfMsEM_1y8iviSQ)
+ * [Testing with Screen Readers](http://webaim.org/articles/screenreader_testing/)
  * [Chrome Accessibility Developer Tools](https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb?hl=en)
  * [W3C Accessibility Testing](http://www.w3.org/wiki/Accessibility_testing)
  * [WebAIM](http://webaim.org)

src/ngAria/aria.js

@@ -5,33 +5,49 @@
  * @name ngAria
  * @description
  *
- * The `ngAria` module provides support for adding <abbr title="Accessible Rich Internet Applications">ARIA</abbr>
- * attributes that convey state or semantic information about the application in order to allow assistive technologies
- * to convey appropriate information to persons with disabilities.
+ * The `ngAria` module provides support for common
+ * [<abbr title="Accessible Rich Internet Applications">ARIA</abbr>](http://www.w3.org/TR/wai-aria/)
+ * attributes that convey state or semantic information about the application for users
+ * of assistive technologies, such as screen readers.
  *
  * <div doc-module-components="ngAria"></div>
  *
- * # Usage
- * To enable the addition of the ARIA tags, just require the module into your application and the tags will
- * hook into your ng-show/ng-hide, input, textarea, button, select and ng-required directives and adds the
- * appropriate ARIA attributes.
+ * ## Usage
  *
- * Currently, the following ARIA attributes are implemented:
+ * For ngAria to do its magic, simply include the module as a dependency. The directives supported
+ * by ngAria are:
+ * `ngModel`, `ngDisabled`, `ngShow`, `ngHide`, `ngClick`, `ngDblClick`, and `ngMessages`.
  *
- * + aria-hidden
- * + aria-checked
- * + aria-disabled
- * + aria-required
- * + aria-invalid
- * + aria-multiline
- * + aria-valuenow
- * + aria-valuemin
- * + aria-valuemax
- * + tabindex
+ * Below is a more detailed breakdown of the attributes handled by ngAria:
  *
- * You can disable individual ARIA attributes by using the {@link ngAria.$ariaProvider#config config} method.
+ * | Directive                                   | Supported Attributes                                                                   |
+ * |---------------------------------------------|----------------------------------------------------------------------------------------|
+ * | {@link ng.directive:ngModel ngModel}        | aria-checked, aria-valuemin, aria-valuemax, aria-valuenow, aria-invalid, aria-required |
+ * | {@link ng.directive:ngDisabled ngDisabled}  | aria-disabled                                                                          |
+ * | {@link ng.directive:ngShow ngShow}          | aria-hidden                                                                            |
+ * | {@link ng.directive:ngHide ngHide}          | aria-hidden                                                                            |
+ * | {@link ng.directive:ngClick ngClick}        | tabindex                                                                               |
+ * | {@link ng.directive:ngDblclick ngDblclick}  | tabindex                                                                               |
+ * | {@link module:ngMessages ngMessages}        | aria-live                                                                              |
+ *
+ * Find out more information about each directive by reading the
+ * {@link guide/accessibility ngAria Developer Guide}.
+ *
+ * ##Example
+ * Using ngDisabled with ngAria:
+ * ```html
+ * <md-checkbox ng-disabled="disabled">
+ * ```
+ * Becomes:
+ * ```html
+ * <md-checkbox ng-disabled="disabled" aria-disabled="true">
+ * ```
+ *
+ * ##Disabling Attributes
+ * It's possible to disable individual attributes added by ngAria with the
+ * {@link ngAria.$ariaProvider#config config} method. For more details, see the
+ * {@link guide/accessibility Developer Guide}.
  */
-
  /* global -ngAriaModule */
 var ngAriaModule = angular.module('ngAria', ['ng']).
                         provider('$aria', $AriaProvider);
@@ -42,10 +58,20 @@ var ngAriaModule = angular.module('ngAria', ['ng']).
  *
  * @description
  *
- * Used for configuring ARIA attributes.
+ * Used for configuring the ARIA attributes injected and managed by ngAria.
+ *
+ * ```js
+ * angular.module('myApp', ['ngAria'], function config($ariaProvider) {
+ *   $ariaProvider.config({
+ *     ariaValue: true,
+ *     tabindex: false
+ *   });
+ * });
+ *```
  *
  * ## Dependencies
  * Requires the {@link ngAria} module to be installed.
+ *
  */
 function $AriaProvider() {
   var config = {
@@ -108,7 +134,41 @@ function $AriaProvider() {
    *
    * @description
    *
-   * Contains helper methods for applying ARIA attributes to HTML
+   * The $aria service contains helper methods for applying common
+   * [ARIA](http://www.w3.org/TR/wai-aria/) attributes to HTML directives.
+   *
+   * ngAria injects common accessibility attributes that tell assistive technologies when HTML
+   * elements are enabled, selected, hidden, and more. To see how this is performed with ngAria,
+   * let's review a code snippet from ngAria itself:
+   *
+   *```js
+   * ngAriaModule.directive('ngDisabled', ['$aria', function($aria) {
+   *   return $aria.$$watchExpr('ngDisabled', 'aria-disabled');
+   * }])
+   *```
+   * Shown above, the ngAria module creates a directive with the same signature as the
+   * traditional `ng-disabled` directive. But this ngAria version is dedicated to
+   * solely managing accessibility attributes. The internal `$aria` service is used to watch the
+   * boolean attribute `ngDisabled`. If it has not been explicitly set by the developer,
+   * `aria-disabled` is injected as an attribute with its value synchronized to the value in
+   * `ngDisabled`.
+   *
+   * Because ngAria hooks into the `ng-disabled` directive, developers do not have to do
+   * anything to enable this feature. The `aria-disabled` attribute is automatically managed
+   * simply as a silent side-effect of using `ng-disabled` with the ngAria module.
+   *
+   * The full list of directives that interface with ngAria:
+   * * **ngModel**
+   * * **ngShow**
+   * * **ngHide**
+   * * **ngClick**
+   * * **ngDblclick**
+   * * **ngMessages**
+   * * **ngDisabled**
+   *
+   * Read the {@link guide/accessibility ngAria Developer Guide} for a thorough explanation of each
+   * directive.
+   *
    *
    * ## Dependencies
    * Requires the {@link ngAria} module to be installed.