docs(bottomsheet): Add notes about .catch() usage. (#10378)

Newer versions of Angular will throw a `Possibly unhandled rejection`
exception if you show a bottom sheet without providing a `.catch()`
clause to handle the rejection.

Add notes to `$mdBottomSheet` documentation and demos to show
proper usage.

Author: topherfangio

src/components/bottomSheet/bottom-sheet.js

@@ -56,9 +56,26 @@ function MdBottomSheetDirective($mdBottomSheet) {
  * app.controller('MyController', function($scope, $mdBottomSheet) {
  *   $scope.openBottomSheet = function() {
  *     $mdBottomSheet.show({
- *       template: '<md-bottom-sheet>Hello!</md-bottom-sheet>'
+ *       template: '<md-bottom-sheet>' +
+ *       'Hello! <md-button ng-click="closeBottomSheet()">Close</md-button>' +
+ *       '</md-bottom-sheet>'
+ *     })
+ *
+ *     // Fires when the hide() method is used
+ *     .then(function() {
+ *       console.log('You clicked the button to close the bottom sheet!');
+ *     })
+ *
+ *     // Fires when the cancel() method is used
+ *     .catch(function() {
+ *       console.log('You hit escape or clicked the backdrop to close.');
  *     });
  *   };
+ *
+ *   $scope.closeBottomSheet = function($scope, $mdBottomSheet) {
+ *     $mdBottomSheet.hide();
+ *   }
+ *
  * });
  * </hljs>
  */
@@ -70,6 +87,14 @@ function MdBottomSheetDirective($mdBottomSheet) {
  * @description
  * Show a bottom sheet with the specified options.
  *
+ * <em><b>Note:</b> You should <b>always</b> provide a `.catch()` method in case the user hits the
+ * `esc` key or clicks the background to close. In this case, the `cancel()` method will
+ * automatically be called on the bottom sheet which will `reject()` the promise. See the @usage
+ * section above for an example.
+ *
+ * Newer versions of Angular will throw a `Possibly unhandled rejection` exception if you forget
+ * this.</em>
+ *
  * @param {object} options An options object, with the following properties:
  *
  *   - `templateUrl` - `{string=}`: The url of an html template file that will
@@ -110,7 +135,10 @@ function MdBottomSheetDirective($mdBottomSheet) {
  *
  * @description
  * Hide the existing bottom sheet and resolve the promise returned from
- * `$mdBottomSheet.show()`. This call will close the most recently opened/current bottomsheet (if any).
+ * `$mdBottomSheet.show()`. This call will close the most recently opened/current bottomsheet (if
+ * any).
+ *
+ * <em><b>Note:</b> Use a `.then()` on your `.show()` to handle this callback.</em>
  *
  * @param {*=} response An argument for the resolved promise.
  *
@@ -124,6 +152,8 @@ function MdBottomSheetDirective($mdBottomSheet) {
  * Hide the existing bottom sheet and reject the promise returned from
  * `$mdBottomSheet.show()`.
  *
+ * <em><b>Note:</b> Use a `.catch()` on your `.show()` to handle this callback.</em>
+ *
  * @param {*=} response An argument for the rejected promise.
  *
  */

src/components/bottomSheet/demoBasicUsage/script.js

@@ -22,6 +22,8 @@ angular.module('bottomSheetDemo1', ['ngMaterial'])
       controller: 'ListBottomSheetCtrl'
     }).then(function(clickedItem) {
       $scope.alert = clickedItem['name'] + ' clicked!';
+    }).catch(function(error) {
+      // User clicked outside or hit escape
     });
   };
 
@@ -38,6 +40,8 @@ angular.module('bottomSheetDemo1', ['ngMaterial'])
               .position('top right')
               .hideDelay(1500)
           );
+    }).catch(function(error) {
+      // User clicked outside or hit escape
     });
   };
 })