docs(alert): update documentation, style and add usage

packages/core/src/components/alert-controller/alert-controller.tsx

@@ -9,6 +9,24 @@ const alerts = new Map<number, HTMLIonAlertElement>();
 })
 export class AlertController implements OverlayController {
 
+  @Listen('body:ionAlertWillPresent')
+  protected alertWillPresent(ev: AlertEvent) {
+    alerts.set(ev.target.alertId, ev.target);
+  }
+
+  @Listen('body:ionAlertWillDismiss, body:ionAlertDidUnload')
+  protected alertWillDismiss(ev: AlertEvent) {
+    alerts.delete(ev.target.alertId);
+  }
+
+  @Listen('body:keyup.escape')
+  protected escapeKeyUp() {
+    removeLastAlert();
+  }
+
+  /*
+   * Create an alert with optional titles, buttons and inputs.
+   */
   @Method()
   create(opts?: AlertOptions): Promise<HTMLIonAlertElement> {
     // create ionic's wrapping ion-alert component
@@ -28,6 +46,9 @@ export class AlertController implements OverlayController {
     return alertElement.componentOnReady();
   }
 
+  /*
+   * Dismiss an open alert.
+   */
   @Method()
   dismiss(data?: any, role?: any, alertId = -1) {
     alertId = alertId >= 0 ? alertId : getHighestId();
@@ -38,27 +59,13 @@ export class AlertController implements OverlayController {
     return alert.dismiss(data, role);
   }
 
+  /*
+   * Get the most recently opened alert.
+   */
   @Method()
   getTop() {
     return alerts.get(getHighestId());
   }
-
-  @Listen('body:ionAlertWillPresent')
-  protected alertWillPresent(ev: AlertEvent) {
-    alerts.set(ev.target.alertId, ev.target);
-  }
-
-
-  @Listen('body:ionAlertWillDismiss, body:ionAlertDidUnload')
-  protected alertWillDismiss(ev: AlertEvent) {
-    alerts.delete(ev.target.alertId);
-  }
-
-
-  @Listen('body:keyup.escape')
-  protected escapeKeyUp() {
-    removeLastAlert();
-  }
 }
 
 function getHighestId() {

packages/core/src/components/alert-controller/readme.md

@@ -1,42 +1,22 @@
 # ion-alert-controller
 
-An Alert is a dialog that presents users with information or collects
+Alert controllers programmatically control the alert component. Alerts can be created and dismissed from the alert controller. View the [Alert](../../alert/Alert) documentation for a full list of options to pass upon creation.
-information from the user using inputs. An alert appears on top
-of the app's content, and must be manually dismissed by the user before
-they can resume interaction with the app. It can also optionally have a
-`title`, `subTitle` and `message`.
-
-You can pass all of the alert's options in the first argument of
-the create method: `create(opts)`. Otherwise the alert's instance
-has methods to add options, such as `setTitle()` or `addButton()`.
 
 
-### Alert Buttons
+```javascript
+async function presentAlert() {
+  const alertController = document.querySelector('ion-alert-controller');
+  await alertController.componentOnReady();
 
-In the array of `buttons`, each button includes properties for its `text`,
+  const alert = await alertController.create({
-and optionally a `handler`. If a handler returns `false` then the alert
+    title: 'Alert',
-will not automatically be dismissed when the button is clicked. All
+    subTitle: 'Subtitle',
-buttons will show up in the order they have been added to the `buttons`
+    message: 'This is an alert message.',
-array, from left to right. Note: The right most button (the last one in
+    buttons: ['OK']
-the array) is the main button.
+  });
-
+  return await alert.present();
-Optionally, a `role` property can be added to a button, such as `cancel`.
+}
-If a `cancel` role is on one of the buttons, then if the alert is
+```
-dismissed by tapping the backdrop, then it will call the handler from
-the button with a cancel role.
-
-
-### Alert Inputs
-
-Alerts can also include several different inputs whose data can be passed
-back to the app. Inputs can be used as a simple way to prompt users for
-information. Radios, checkboxes and text inputs are all accepted, but they
-cannot be mixed. For example, an alert could have all radio button inputs,
-or all checkbox inputs, but the same alert cannot mix radio and checkbox
-inputs. Do note however, different types of "text" inputs can be mixed,
-such as `url`, `email`, `text`, etc. If you require a complex form UI
-which doesn't fit within the guidelines of an alert then we recommend
-building the form within a modal instead.
 
 
 <!-- Auto Generated Below -->

packages/core/src/components/alert/alert.tsx

@@ -22,9 +22,9 @@ import mdLeaveAnimation from './animations/md.leave';
   }
 })
 export class Alert {
+  alertId: number;
   mode: string;
   color: string;
-  alertId: number;
 
   private animation: Animation | null = null;
   private activeId: string;
@@ -33,6 +33,66 @@ export class Alert {
 
   @Element() private el: HTMLElement;
 
+  @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
+  @Prop({ context: 'config' }) config: Config;
+  @Prop({ context: 'dom' }) dom: DomController;
+
+  /**
+   * Animation to use when the alert is presented.
+   */
+  @Prop() enterAnimation: AnimationBuilder;
+
+  /**
+   * Animation to use when the alert is dismissed.
+   */
+  @Prop() leaveAnimation: AnimationBuilder;
+
+  /**
+   * Additional classes to apply for custom CSS. If multiple classes are
+   * provided they should be separated by spaces.
+   */
+  @Prop() cssClass: string;
+
+  /**
+   * The main title in the heading of the alert.
+   */
+  @Prop() title: string;
+
+  /**
+   * The subtitle in the heading of the alert. Displayed under the title.
+   */
+  @Prop() subTitle: string;
+
+  /**
+   * The main message to be displayed in the alert.
+   */
+  @Prop() message: string;
+
+  /**
+   * Array of buttons to be added to the alert.
+   */
+  @Prop() buttons: AlertButton[] = [];
+
+  /**
+   * Array of input to show in the alert.
+   */
+  @Prop({ mutable: true }) inputs: AlertInput[] = [];
+
+  /**
+   * If true, the alert will be dismissed when the backdrop is clicked. Defaults to `true`.
+   */
+  @Prop() enableBackdropDismiss = true;
+
+  /**
+   * If true, the alert will be translucent. Defaults to `false`.
+   */
+  @Prop() translucent = false;
+
+  /**
+   * If true, the alert will animate. Defaults to `true`.
+   */
+  @Prop() willAnimate = true;
+
   /**
    * Emitted after the alert has loaded.
    */
@@ -63,69 +123,11 @@ export class Alert {
    */
   @Event() ionAlertDidUnload: EventEmitter<AlertEventDetail>;
 
-  @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
-  @Prop({ context: 'config' }) config: Config;
-  @Prop({ context: 'dom' }) dom: DomController;
-
   /**
-   * Additional class or classes to apply to the alert
+   * Present the alert overlay after it has been created.
    */
-  @Prop() cssClass: string;
+  @Method()
-
+  present() {
-  /**
-   * Title for the alert
-   */
-  @Prop() title: string;
-
-  /**
-   * Subtitle for the alert
-   */
-  @Prop() subTitle: string;
-
-  /**
-   * Message to be shown in the alert
-   */
-  @Prop() message: string;
-
-  /**
-   * Array of buttons to be added to the alert. See AlertButton type for valid options
-   */
-  @Prop() buttons: AlertButton[] = [];
-
-  /**
-   * Array of input to show in the alert. See AlertInput type for valid options
-   */
-  @Prop({ mutable: true }) inputs: AlertInput[] = [];
-
-  /**
-   * If true, the alert will be dismissed when the backdrop is clicked.
-   */
-  @Prop() enableBackdropDismiss = true;
-
-  /**
-   * If true, alert will become translucent. Requires support for backdrop-filters.
-   */
-  @Prop() translucent = false;
-
-  /**
-   * Enable alert animations. If false, alert will not animate in
-   */
-  @Prop() willAnimate = true;
-
-  /**
-   * Animation to be used when the alert is shown
-   */
-  @Prop() enterAnimation: AnimationBuilder;
-
-  /**
-   * Animation to be used when the alert is dismissed
-   */
-  @Prop() leaveAnimation: AnimationBuilder;
-
-  /**
-   * Present the alert after is has been created
-   */
-  @Method() present() {
     if (this.animation) {
       this.animation.destroy();
       this.animation = null;
@@ -158,9 +160,10 @@ export class Alert {
   }
 
   /**
-   * Dismiss the alert
+   * Dismiss the alert overlay after it has been presented.
    */
-  @Method() dismiss(data?: any, role?: string) {
+  @Method()
+  dismiss(data?: any, role?: string) {
     if (this.animation) {
       this.animation.destroy();
       this.animation = null;
@@ -418,8 +421,7 @@ export class Alert {
     return [
       <ion-backdrop
         onClick={this.backdropClick.bind(this)}
-        class='alert-backdrop'
+        class='alert-backdrop'></ion-backdrop>,
-      />,
       <div class='alert-wrapper'>
         <div class='alert-head'>
           {this.title

packages/core/src/components/alert/readme.md

@@ -1,6 +1,36 @@
 # ion-alert
 
+An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a `title`, `subTitle` and `message`.
 
+Alerts can be programmatically opened using an [Alert Controller](../../alert-controller/AlertController). They can be customized by passing alert options in the first argument of the alert controller's create method.
+
+
+### Alert Buttons
+
+In the array of `buttons`, each button includes properties for its `text`, and optionally a `handler`. If a handler returns `false` then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the `buttons` array from left to right. Note: The right most button (the last one in the array) is the main button.
+
+Optionally, a `role` property can be added to a button, such as `cancel`. If a `cancel` role is on one of the buttons, then if the alert is dismissed by tapping the backdrop, then it will fire the handler from the button with a cancel role.
+
+
+### Alert Inputs
+
+Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text"" inputs can be mixed, such as `url`, `email`, `text`, etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead.
+
+
+```javascript
+async function presentAlert() {
+  const alertController = document.querySelector('ion-alert-controller');
+  await alertController.componentOnReady();
+
+  const alert = await alertController.create({
+    title: 'Alert',
+    subTitle: 'Subtitle',
+    message: 'This is an alert message.',
+    buttons: ['OK']
+  });
+  return await alert.present();
+}
+```
 
 <!-- Auto Generated Below -->
 
@@ -11,77 +41,78 @@
 
 
 
-Array of buttons to be added to the alert. See AlertButton type for valid options
+Array of buttons to be added to the alert.
 
 
 #### cssClass
 
 string
 
-Additional class or classes to apply to the alert
+Additional classes to apply for custom CSS. If multiple classes are
+provided they should be separated by spaces.
 
 
 #### enableBackdropDismiss
 
 boolean
 
-If true, the alert will be dismissed when the backdrop is clicked.
+If true, the alert will be dismissed when the backdrop is clicked. Defaults to `true`.
 
 
 #### enterAnimation
 
 
 
-Animation to be used when the alert is shown
+Animation to use when the alert is presented.
 
 
 #### inputs
 
 
 
-Array of input to show in the alert. See AlertInput type for valid options
+Array of input to show in the alert.
 
 
 #### leaveAnimation
 
 
 
-Animation to be used when the alert is dismissed
+Animation to use when the alert is dismissed.
 
 
 #### message
 
 string
 
-Message to be shown in the alert
+The main message to be displayed in the alert.
 
 
 #### subTitle
 
 string
 
-Subtitle for the alert
+The subtitle in the heading of the alert. Displayed under the title.
 
 
 #### title
 
 string
 
-Title for the alert
+The main title in the heading of the alert.
 
 
 #### translucent
 
 boolean
 
-If true, alert will become translucent. Requires support for backdrop-filters.
+If true, the alert will be translucent. Defaults to `false`.
 
 
 #### willAnimate
 
 boolean
 
-Enable alert animations. If false, alert will not animate in
+If true, the alert will animate. Defaults to `true`.
 
 
 ## Attributes
@@ -90,77 +121,78 @@ Enable alert animations. If false, alert will not animate in
 
 
 
-Array of buttons to be added to the alert. See AlertButton type for valid options
+Array of buttons to be added to the alert.
 
 
 #### css-class
 
 string
 
-Additional class or classes to apply to the alert
+Additional classes to apply for custom CSS. If multiple classes are
+provided they should be separated by spaces.
 
 
 #### enable-backdrop-dismiss
 
 boolean
 
-If true, the alert will be dismissed when the backdrop is clicked.
+If true, the alert will be dismissed when the backdrop is clicked. Defaults to `true`.
 
 
 #### enter-animation
 
 
 
-Animation to be used when the alert is shown
+Animation to use when the alert is presented.
 
 
 #### inputs
 
 
 
-Array of input to show in the alert. See AlertInput type for valid options
+Array of input to show in the alert.
 
 
 #### leave-animation
 
 
 
-Animation to be used when the alert is dismissed
+Animation to use when the alert is dismissed.
 
 
 #### message
 
 string
 
-Message to be shown in the alert
+The main message to be displayed in the alert.
 
 
 #### sub-title
 
 string
 
-Subtitle for the alert
+The subtitle in the heading of the alert. Displayed under the title.
 
 
 #### title
 
 string
 
-Title for the alert
+The main title in the heading of the alert.
 
 
 #### translucent
 
 boolean
 
-If true, alert will become translucent. Requires support for backdrop-filters.
+If true, the alert will be translucent. Defaults to `false`.
 
 
 #### will-animate
 
 boolean
 
-Enable alert animations. If false, alert will not animate in
+If true, the alert will animate. Defaults to `true`.
 
 
 ## Events
@@ -199,12 +231,12 @@ Emitted before the alert has presented.
 
 #### dismiss()
 
-Dismiss the alert
+Dismiss the alert overlay after it has been presented.
 
 
 #### present()
 
-Present the alert after is has been created
+Present the alert overlay after it has been created.
 
 
 

packages/core/src/components/alert/test/basic/index.html

@@ -39,8 +39,9 @@
     window.addEventListener('ionAlertWillDismiss', function(e){console.log('willDismiss', e)})
 
     async function presentAlert() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
+
       const alert = await alertController.create({
         title: 'Alert',
         subTitle: 'Subtitle',
@@ -51,7 +52,7 @@
     }
 
     async function presentAlertLongMessage() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Alert',
@@ -62,7 +63,7 @@
     }
 
     async function presentAlertMultipleButtons() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Alert',
@@ -74,7 +75,7 @@
     }
 
     async function presentAlertNoMessage() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Alert',
@@ -84,7 +85,7 @@
     }
 
     async function presentAlertConfirm() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Confirm!',
@@ -109,7 +110,7 @@
     }
 
     async function presentAlertPrompt() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Prompt!',
@@ -172,7 +173,7 @@
     }
 
     async function presentAlertRadio() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Radio',
@@ -231,7 +232,7 @@
     async function presentAlertCheckbox() {
 
 
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Checkbox',
@@ -293,7 +294,7 @@
     }
 
     async function presentWithCssClass() {
-      var alertController = document.querySelector('ion-alert-controller');
+      const alertController = document.querySelector('ion-alert-controller');
       await alertController.componentOnReady();
       const alert = await alertController.create({
         title: 'Alert',