fix(toast): onRemove doesn't return a Promise in some cases

- this results in an exception
- add types for `$q`
- improve JSDoc

Fixes #10379

Author: Splaktar

package-lock.json

@@ -34,6 +34,7 @@
   "devDependencies": {
     "@octokit/rest": "^17.0.1",
     "@types/angular": "~1.6.57",
+    "@types/q": "^1.5.4",
     "acorn": "^7.1.1",
     "add-stream": "^1.0.0",
     "ajv": "^6.12.0",

package.json

@@ -416,7 +416,7 @@ function MdToastProvider($$interimElementProvider) {
   }
 
   /* @ngInject */
-  function toastDefaultOptions($animate, $mdToast, $mdUtil, $mdMedia, $document) {
+  function toastDefaultOptions($animate, $mdToast, $mdUtil, $mdMedia, $document, $q) {
     var SWIPE_EVENTS = '$md.swipeleft $md.swiperight $md.swipeup $md.swipedown';
     return {
       onShow: onShow,
@@ -518,6 +518,12 @@ function MdToastProvider($$interimElementProvider) {
       });
     }
 
+    /**
+     * @param {object} scope the toast's scope
+     * @param {JQLite} element the toast to be removed
+     * @param {object} options
+     * @return {Promise<*>} a Promise to remove the element immediately or to animate it out.
+     */
     function onRemove(scope, element, options) {
       if (scope.toast && scope.toast.actionKey) {
         removeActionKeyListener();
@@ -526,7 +532,8 @@ function MdToastProvider($$interimElementProvider) {
       if (options.parent) options.parent.addClass('md-toast-animating');
       if (options.openClass) options.parent.removeClass(options.openClass);
 
-      return ((options.$destroy === true) ? element.remove() : $animate.leave(element))
+      // Don't run the leave animation if the element has already been destroyed.
+      return ((options.$destroy === true) ? $q.when(element.remove()) : $animate.leave(element))
         .then(function () {
           if (options.parent) options.parent.removeClass('md-toast-animating');
           if ($mdUtil.hasComputedStyle(options.parent, 'position', 'static')) {