docs(action-sheet): copy editing, add usage and fix style

packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx

@@ -9,6 +9,26 @@ const actionSheets = new Map<number, HTMLIonActionSheetElement>();
 })
 export class ActionSheetController implements OverlayController {
 
+  @Listen('body:ionActionSheetWillPresent')
+  protected actionSheetWillPresent(ev: ActionSheetEvent) {
+    actionSheets.set(ev.target.actionSheetId, ev.target);
+  }
+
+
+  @Listen('body:ionActionSheetWillDismiss, body:ionActionSheetDidUnload')
+  protected actionSheetWillDismiss(ev: ActionSheetEvent) {
+    actionSheets.delete(ev.target.actionSheetId);
+  }
+
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastActionSheet();
+  }
+
+  /*
+   * Create an action sheet overlay with action sheet options.
+   */
   @Method()
   create(opts?: ActionSheetOptions): Promise<HTMLIonActionSheetElement> {
     // create ionic's wrapping ion-actionSheet component
@@ -28,6 +48,9 @@ export class ActionSheetController implements OverlayController {
     return actionSheetElement.componentOnReady();
   }
 
+  /*
+   * Dismiss the open action sheet overlay.
+   */
   @Method()
   dismiss(data?: any, role?: any, actionSheetId = -1) {
     actionSheetId = actionSheetId >= 0 ? actionSheetId : getHighestId();
@@ -38,27 +61,13 @@ export class ActionSheetController implements OverlayController {
     return actionSheet.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened action sheet overlay.
+   */
   @Method()
   getTop() {
     return actionSheets.get(getHighestId());
   }
-
-  @Listen('body:ionActionSheetWillPresent')
-  protected actionSheetWillPresent(ev: ActionSheetEvent) {
-    actionSheets.set(ev.target.actionSheetId, ev.target);
-  }
-
-
-  @Listen('body:ionActionSheetWillDismiss, body:ionActionSheetDidUnload')
-  protected actionSheetWillDismiss(ev: ActionSheetEvent) {
-    actionSheets.delete(ev.target.actionSheetId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastActionSheet();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/action-sheet-controller/readme.md

@@ -1,28 +1,51 @@
 # ion-action-sheet-controller
 
- An Action Sheet is a dialog that lets the user choose from a set of
+Action Sheet controllers programmatically control the action sheet component. Action Sheets can be created and dismissed from the action sheet controller. View the [Action Sheet](../../action-sheet/ActionSheet) documentation for a full list of options to pass upon creation.
- options. It appears on top of the app's content, and must be manually
- dismissed by the user before they can resume interaction with the app.
- Dangerous (destructive) options are made obvious in `ios` mode. There are easy
- ways to cancel the action sheet, such as tapping the backdrop or
- hitting the escape key on desktop.
 
- An action sheet is created from an array of `buttons`, with each button
+```javascript
- including properties for its `text`, and optionally a `handler` and `role`.
+async function presentBasic() {
- If a handler returns `false` then the action sheet will not be dismissed. An
+  const actionSheetController = document.querySelector('ion-action-sheet-controller');
- action sheet can also optionally have a `title`, `subTitle` and an `icon`.
+  await actionSheetController.componentOnReady();
 
- A button's `role` property can either be `destructive` or `cancel`. Buttons
+  const actionSheetElement = await actionSheetController.create({
- without a role property will have the default look for the platform. Buttons
+    title: "Albums",
- with the `cancel` role will always load as the bottom button, no matter where
+    buttons: [{
- they are in the array. All other buttons will be displayed in the order they
+      text: 'Delete',
- have been added to the `buttons` array. Note: We recommend that `destructive`
+      role: 'destructive',
- buttons are always the first button in the array, making them the top button.
+      icon: 'trash',
- Additionally, if the action sheet is dismissed by tapping the backdrop, then
+      handler: () => {
- it will call the handler from the button with the cancel role.
+        console.log('Delete clicked');
-
+      }
- You can pass all of the action sheet's options in the first argument of
+    }, {
- the create method: `ActionSheet.create(opts)`.
+      text: 'Share',
+      icon: 'share',
+      handler: () => {
+        console.log('Share clicked');
+      }
+    }, {
+      text: 'Play (open modal)',
+      icon: 'arrow-dropright-circle',
+      handler: () => {
+        console.log('Play clicked');
+      }
+    }, {
+      text: 'Favorite',
+      icon: 'heart',
+      handler: () => {
+        console.log('Favorite clicked');
+      }
+    }, {
+      text: 'Cancel',
+      icon: 'close',
+      role: 'cancel',
+      handler: () => {
+        console.log('Cancel clicked');
+      }
+    }]
+  });
+  await actionSheetElement.present();
+}
+```
 
 
 <!-- Auto Generated Below -->

packages/core/src/components/action-sheet/readme.md

@@ -2,18 +2,10 @@
 
 An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop.
 
-An action sheet is created from an array of `buttons`, with each button including properties for its `text`, and optionally a `handler` and `role`. If a handler returns `false` then the action sheet will not be dismissed. An action sheet can also optionally have a `title`, `subTitle` and an `icon`.
+An action sheet can be created by the [Action Sheet Controller](../../action-sheet-controller/ActionSheetController) from an array of `buttons`, with each button including properties for its `text`, and optionally a `handler` and `role`. If a handler returns `false` then the action sheet will not be dismissed. An action sheet can also optionally have a `title`, `subTitle` and an `icon`.
 
 A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role.
 
-You can pass all of the action sheet's options in the first argument of the create method.
-
-```html
-<ion-button onClick="presentBasic()">
-  Present Action Sheet
-</ion-button>
-```
-
 ```javascript
 async function presentBasic() {
   const actionSheetController = document.querySelector('ion-action-sheet-controller');