docs(actionsheet): dismissing and async navigation

ionic/components/action-sheet/action-sheet.ts

@@ -75,6 +75,62 @@ import {ViewController} from '../nav/view-controller';
  * }
  * ```
  *
+ *
+ * ### Dismissing And Async Navigation
+ *
+ * After an action sheet has been dismissed, the app may need to also transition
+ * to another page depending on the handler's logic. However, because multiple
+ * transitions were fired at roughly the same time, it's difficult for the
+ * nav controller to cleanly animate multiple transitions that may
+ * have been kicked off asynchronously. This is further described in the
+ * [`Nav Transition Promises`](../../nav/NavController) section. For action sheets,
+ * this means it's best to wait for the action sheet to finish its transition
+ * out before starting a new transition on the same nav controller.
+ *
+ * In the example below, after the button has been clicked, its handler
+ * waits on async operation to complete, *then* it uses `pop` to navigate
+ * back a page in the same stack. The potential problem is that the async operation
+ * may have been completed before the action sheet has even finished its transition
+ * out. In this case, it's best to ensure the action sheet has finished its transition
+ * out first, *then* start the next transition.
+ *
+ * ```ts
+ * let actionSheet = ActionSheet.create({
+ *   title: 'Hello',
+ *   buttons: [{
+ *     text: 'Ok',
+ *     handler: () => {
+ *       // user has clicked the action sheet button
+ *       // begin the action sheet's dimiss transition
+ *       let navTransition = actionSheet.dismiss();
+ *
+ *       // start some async method
+ *       someAsyncOperation().then(() => {
+ *         // once the async operation has completed
+ *         // then run the next nav transition after the
+ *         // first transition has finished animating out
+ *
+ *         navTransition.then(() => {
+ *           this.nav.pop();
+ *         });
+ *       });
+ *       return false;
+ *     }
+ *   }]
+ * });
+ *
+ * this.nav.present(actionSheet);
+ * ```
+ *
+ * It's important to note that the the handler returns `false`. A feature of
+ * button handlers is that they automatically dismiss the action sheet when their button
+ * was clicked, however, we'll need more control regarding the transition. Because
+ * the handler returns `false`, then the action sheet does not automatically dismiss
+ * itself. Instead, you now have complete control of when the action sheet has finished
+ * transitioning, and the ability to wait for the action sheet to finish transitioning
+ * out before starting a new transition.
+ *
+ *
  * @demo /docs/v2/demos/action-sheet/
  * @see {@link /docs/v2/components#action-sheets ActionSheet Component Docs}
  */
@@ -234,7 +290,7 @@ class ActionSheetCmp {
 
       // deprecated warning
       if (button.style) {
-        console.warn('Alert "style" property has been renamed to "role"');
+        console.warn('Action sheet "style" property has been renamed to "role"');
         button.role = button.style;
       }
 

ionic/components/alert/alert.ts

@@ -158,7 +158,7 @@ import {ViewController} from '../nav/view-controller';
  *       let navTransition = alert.dismiss();
  *
  *       // start some async method
- *       someAsyncOperation(() => {
+ *       someAsyncOperation().then(() => {
  *         // once the async operation has completed
  *         // then run the next nav transition after the
  *         // first transition has finished animating out