fix(toast): improve a11y support for $mdToast.simple(). improve docs

move the role="alert" up a level - makes action button visible to screen readers add support for defining an actionKey to assign a hot key to an action - this enables Control-actionKey to activate the action add support for defining a dismissHint for screen readers add support for defining an actionHint for screen readers align custom toast demo with Material Design guidelines enhance custom toast demo to demonstrate an accessible custom toast Fixes #349
angular · Aug 24, 2018 · fa51cec · fa51cec
1 parent a25a7df
commit fa51cec
Show file tree

Hide file tree

Showing 7 changed files with 223 additions and 91 deletions.
diff --git a/src/components/toast/demoBasicUsage/script.js b/src/components/toast/demoBasicUsage/script.js
@@ -1,5 +1,4 @@
-
-angular.module('toastDemo1', ['ngMaterial'])
+angular.module('toastBasicDemo', ['ngMaterial'])
 
 .controller('AppCtrl', function($scope, $mdToast) {
   var last = {
@@ -36,7 +35,7 @@ angular.module('toastDemo1', ['ngMaterial'])
     $mdToast.show(
       $mdToast.simple()
         .textContent('Simple Toast!')
-        .position(pinTo )
+        .position(pinTo)
         .hideDelay(3000)
     );
   };
@@ -45,14 +44,18 @@ angular.module('toastDemo1', ['ngMaterial'])
     var pinTo = $scope.getToastPosition();
     var toast = $mdToast.simple()
       .textContent('Marked as read')
+      .actionKey('z')
+      .actionHint('Press the Control-"z" key combination to ')
       .action('UNDO')
+      .dismissHint('Activate the Escape key to dismiss this toast.')
       .highlightAction(true)
-      .highlightClass('md-accent')// Accent is used by default, this just demonstrates the usage.
-      .position(pinTo);
+      .highlightClass('md-accent') // Accent is used by default, this just demonstrates the usage.
+      .position(pinTo)
+      .hideDelay(6000);
 
     $mdToast.show(toast).then(function(response) {
-      if ( response == 'ok' ) {
-        alert('You clicked the \'UNDO\' action.');
+      if (response === 'ok') {
+        alert('You selected the \'UNDO\' action.');
       }
     });
   };

diff --git a/src/components/toast/demoCustomUsage/index.html b/src/components/toast/demoCustomUsage/index.html
@@ -1,13 +1,6 @@
-<div ng-controller="AppCtrl" class="inset" ng-cloak style="height:300px; padding: 25px;">
-  <div layout="row">
-
-    <p>
-      Toast can have multiple actions:
-    </p>
-
-    <md-button ng-click="showCustomToast()" class="md-raised" style="padding-left: 10px;padding-right: 10px;">
-      Show Custom Toast
-    </md-button>
-
-  </div>
+<div ng-controller="AppCtrl as ctrl" id="custom-toast-container" class="inset" ng-cloak>
+  <span>Toast can have multiple actions:</span>
+  <md-button ng-click="ctrl.showCustomToast()" class="md-raised">
+    Show Custom Toast
+  </md-button>
 </div>
diff --git a/src/components/toast/demoCustomUsage/script.js b/src/components/toast/demoCustomUsage/script.js
@@ -1,48 +1,100 @@
 (function() {
-
   var isDlgOpen;
+  var ACTION_RESOLVE = 'undo';
+  var UNDO_KEY = 'z';
+  var DIALOG_KEY = 'd';
+
+  angular.module('toastCustomDemo', ['ngMaterial'])
+  .controller('AppCtrl', AppCtrl)
+  .controller('ToastCtrl', ToastCtrl);
+
+  function AppCtrl($mdToast, $log) {
+    var ctrl = this;
+
+    ctrl.showCustomToast = function() {
+      $mdToast.show({
+        hideDelay: 6000,
+        position: 'top right',
+        controller: 'ToastCtrl',
+        controllerAs: 'ctrl',
+        templateUrl: 'toast-template.html'
+      }).then(function(result) {
+        if (result === ACTION_RESOLVE) {
+          $log.log('Undo action triggered by button.');
+        } else if (result === 'key') {
+          $log.log('Undo action triggered by hot key: Control-' + UNDO_KEY + '.');
+        } else if (result === false) {
+          $log.log('Custom toast dismissed by Escape key.');
+        } else {
+          $log.log('Custom toast hidden automatically.');
+        }
+      }).catch(function(error) {
+        $log.error('Custom toast failure:', error);
+      });
+    };
+  }
+
+  function ToastCtrl($mdToast, $mdDialog, $document) {
+    var ctrl = this;
+    ctrl.keyListenerConfigured = false;
+    ctrl.undoKey = UNDO_KEY;
+    ctrl.dialogKey = DIALOG_KEY;
+    setupActionKeyListener();
+
+    ctrl.closeToast = function() {
+      if (isDlgOpen) {
+        return;
+      }
+
+      $mdToast.hide(ACTION_RESOLVE).then(function() {
+        isDlgOpen = false;
+      });
+    };
+
+    ctrl.openMoreInfo = function(e) {
+      if (isDlgOpen) {
+        return;
+      }
+      isDlgOpen = true;
+
+      $mdDialog.show(
+        $mdDialog.alert()
+        .title('More info goes here.')
+        .textContent('Something witty.')
+        .ariaLabel('More info')
+        .ok('Got it')
+        .targetEvent(e)
+      ).then(function() {
+        isDlgOpen = false;
+      });
+    };
+
+    /**
+     * @param {KeyboardEvent} event
+     */
+    function handleKeyDown(event) {
+      if (event.key === 'Escape') {
+        $mdToast.hide(false);
+      }
+      if (event.key === UNDO_KEY && event.ctrlKey) {
+        $mdToast.hide('key');
+      }
+      if (event.key === DIALOG_KEY && event.ctrlKey) {
+        ctrl.openMoreInfo(event);
+      }
+    }
+
+    function setupActionKeyListener() {
+      if (!ctrl.keyListenerConfigured) {
+        $document.on('keydown', handleKeyDown);
+        ctrl.keyListenerConfigured = true;
+      }
+    }
 
-  angular
-    .module('toastDemo2', ['ngMaterial'])
-    .controller('AppCtrl', function($scope, $mdToast) {
-      $scope.showCustomToast = function() {
-        $mdToast.show({
-          hideDelay   : 3000,
-          position    : 'top right',
-          controller  : 'ToastCtrl',
-          templateUrl : 'toast-template.html'
-        });
-      };
-    })
-    .controller('ToastCtrl', function($scope, $mdToast, $mdDialog) {
-
-      $scope.closeToast = function() {
-        if (isDlgOpen) return;
-
-        $mdToast
-          .hide()
-          .then(function() {
-            isDlgOpen = false;
-          });
-      };
-
-      $scope.openMoreInfo = function(e) {
-        if ( isDlgOpen ) return;
-        isDlgOpen = true;
-
-        $mdDialog
-          .show($mdDialog
-            .alert()
-            .title('More info goes here.')
-            .textContent('Something witty.')
-            .ariaLabel('More info')
-            .ok('Got it')
-            .targetEvent(e)
-          )
-          .then(function() {
-            isDlgOpen = false;
-          });
-      };
-    });
+    function removeActionKeyListener() {
+      $document.off('keydown');
+      ctrl.keyListenerConfigured = false;
+    }
+  }
 
 })();
diff --git a/src/components/toast/demoCustomUsage/style.scss b/src/components/toast/demoCustomUsage/style.scss
@@ -0,0 +1,9 @@
+#custom-toast-container {
+  height: 300px;
+  padding: 25px;
+
+  .md-button.md-raised {
+    padding-left: 10px;
+    padding-right: 10px;
+  }
+}
diff --git a/src/components/toast/demoCustomUsage/toast-template.html b/src/components/toast/demoCustomUsage/toast-template.html
@@ -1,9 +1,15 @@
-<md-toast>
-  <span class="md-toast-text" flex>Custom toast!</span>
-  <md-button class="md-highlight" ng-click="openMoreInfo($event)">
+<md-toast role="alert" aria-relevant="all">
+  <span class="md-toast-text" flex>Custom toast</span>
+  <span class="md-visually-hidden">
+    Press Escape to dismiss. Press Control-"{{ctrl.dialogKey}}" for
+  </span>
+  <md-button class="md-highlight" ng-click="ctrl.openMoreInfo($event)">
     More info
   </md-button>
-  <md-button ng-click="closeToast()">
-    Close
+  <span class="md-visually-hidden">
+    Press Control-"{{ctrl.undoKey}}" to
+  </span>
+  <md-button ng-click="ctrl.closeToast()">
+    Undo
   </md-button>
 </md-toast>