docs(modal): add docs, usage, fix style guide and use ion-backdrop

packages/core/src/components.d.ts

@@ -1772,7 +1772,6 @@ declare global {
       enableBackdropDismiss?: boolean;
       enterAnimation?: AnimationBuilder;
       leaveAnimation?: AnimationBuilder;
-      modalId?: number;
       mode?: 'ios' | 'md';
       showBackdrop?: boolean;
       willAnimate?: boolean;

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

@@ -2,8 +2,12 @@
 
 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.
 
+### Creating
+
 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`.
 
+### Buttons
+
 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.
 
 ```javascript

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

@@ -5,17 +5,17 @@ An Alert is a dialog that presents users with information or collects informatio
 
 ### Creating
 
-Alerts can be created using a [Alert Controller](../../alert-controller/AlertController). They can be customized by passing alert options in the first argument of the alert controller's create method.
+Alerts can be created using a [Alert Controller](../../alert-controller/AlertController). They can be customized by passing alert options in the alert controller's create method.
 
 
-### Alert Buttons
+### 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
+### 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.
 

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

@@ -5,7 +5,7 @@ An overlay that can be used to indicate activity while blocking user interaction
 
 ### Creating
 
-Loading indicators can be created using a [Loading Controller](../../loading-controller/LoadingController). They can be customized by passing loading options in the first argument of the loading controller's create method. The spinner name should be passed in the `spinner` property, and any optional HTML can be passed in the `content` property. If a value is not passed to `spinner` the loading indicator will use the spinner specified by the platform.
+Loading indicators can be created using a [Loading Controller](../../loading-controller/LoadingController). They can be customized by passing loading options in the loading controller's create method. The spinner name should be passed in the `spinner` property, and any optional HTML can be passed in the `content` property. If a value is not passed to `spinner` the loading indicator will use the spinner specified by the platform.
 
 
 ### Dismissing

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

@@ -1,7 +1,43 @@
 # ion-modal-controller
 
+Modal controllers programmatically control the modal component. Modals can be created and dismissed from the modal controller. View the [Modal](../../modal/Modal) documentation for a full list of options to pass upon creation.
 
 
+```javascript
+async function presentModal() {
+  // initialize controller
+  const modalController = document.querySelector('ion-modal-controller');
+  await modalController.componentOnReady();
+
+  // create component to open
+  const element = document.createElement('ion-page');
+  element.innerHTML = `
+  <ion-header>
+    <ion-toolbar>
+      <ion-title>Super Modal</ion-title>
+    </ion-toolbar>
+  </ion-header>
+  <ion-content>
+    <h1>Content of doom</h1>
+    <div>Here's some more content</div>
+    <ion-button class="dismiss">Dismiss Modal</ion-button>
+  </ion-content>
+  `;
+
+  // listen for close event
+  const button = element.querySelector('ion-button');
+  button.addEventListener('click', () => {
+    modalController.dismiss();
+  });
+
+  // present the modal
+  const modalElement = await modalController.create({
+    component: element
+  });
+  modalElement.present();
+}
+```
+
 <!-- Auto Generated Below -->
 
 

packages/core/src/components/modal/modal.tsx

@@ -1,14 +1,5 @@
 import { Component, Element, Event, EventEmitter, Listen, Method, Prop } from '@stencil/core';
-import {
+import { Animation, AnimationBuilder, AnimationController, Config, DomController, FrameworkDelegate, OverlayDismissEvent, OverlayDismissEventDetail } from '../../index';
-  Animation,
-  AnimationBuilder,
-  AnimationController,
-  Config,
-  DomController,
-  FrameworkDelegate,
-  OverlayDismissEvent,
-  OverlayDismissEventDetail
-} from '../../index';
 
 import { DomFrameworkDelegate } from '../../utils/dom-framework-delegate';
 import { domControllerAsync, playAnimationAsync } from '../../utils/helpers';
@@ -19,6 +10,7 @@ import iosLeaveAnimation from './animations/ios.leave';
 
 import mdEnterAnimation from './animations/md.enter';
 import mdLeaveAnimation from './animations/md.leave';
+
 @Component({
   tag: 'ion-modal',
   styleUrls: {
@@ -30,8 +22,74 @@ import mdLeaveAnimation from './animations/md.leave';
   }
 })
 export class Modal {
+  modalId: number;
+
+  private animation: Animation;
+  private usersComponentElement: HTMLElement;
+
   @Element() private el: HTMLElement;
 
+  @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
+  @Prop({ context: 'config' }) config: Config;
+  @Prop({ context: 'dom' }) dom: DomController;
+
+  @Prop({ mutable: true }) delegate: FrameworkDelegate;
+
+  /**
+   * The color to use from your Sass `$colors` map.
+   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+   * For more information, see [Theming your App](/docs/theming/theming-your-app).
+   */
+  @Prop() color: string;
+
+  /**
+   * The mode determines which platform styles to use.
+   * Possible values are: `"ios"` or `"md"`.
+   * For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
+   */
+  @Prop() mode: 'ios' | 'md';
+
+  /**
+   * Animation to use when the modal is presented.
+   */
+  @Prop() enterAnimation: AnimationBuilder;
+
+  /**
+   * Animation to use when the modal is dismissed.
+   */
+  @Prop() leaveAnimation: AnimationBuilder;
+
+  /**
+   * The component to display inside of the modal.
+   */
+  @Prop() component: any;
+
+  /**
+   * The data to pass to the modal component.
+   */
+  @Prop() data: any = {};
+
+  /**
+   * Additional classes to apply for custom CSS. If multiple classes are
+   * provided they should be separated by spaces.
+   */
+  @Prop() cssClass: string;
+
+  /**
+   * If true, the modal will be dismissed when the backdrop is clicked. Defaults to `true`.
+   */
+  @Prop() enableBackdropDismiss = true;
+
+  /**
+   * If true, a backdrop will be displayed behind the modal. Defaults to `true`.
+   */
+  @Prop() showBackdrop = true;
+
+  /**
+   * If true, the modal will animate. Defaults to `true`.
+   */
+  @Prop() willAnimate = true;
+
   /**
    * Emitted after the modal has loaded.
    */
@@ -62,40 +120,9 @@ export class Modal {
    */
   @Event() ionModalDidUnload: EventEmitter<ModalEventDetail>;
 
-  @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
-  @Prop({ context: 'config' }) config: Config;
-  @Prop({ context: 'dom' }) dom: DomController;
-
   /**
-   * The color to use from your Sass `$colors` map.
+   * Present the modal overlay after it has been created.
-   * Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
-   * For more information, see [Theming your App](/docs/theming/theming-your-app).
    */
-  @Prop() color: string;
-
-  /**
-   * The mode determines which platform styles to use.
-   * Possible values are: `"ios"` or `"md"`.
-   * For more information, see [Platform Styles](/docs/theming/platform-specific-styles).
-   */
-  @Prop() mode: 'ios' | 'md';
-
-  @Prop() component: any;
-  @Prop() data: any = {};
-  @Prop() cssClass: string;
-  @Prop() enableBackdropDismiss = true;
-
-  @Prop() modalId: number;
-  @Prop() showBackdrop = true;
-
-  @Prop() enterAnimation: AnimationBuilder;
-  @Prop() leaveAnimation: AnimationBuilder;
-  @Prop() willAnimate = true;
-  @Prop({ mutable: true }) delegate: FrameworkDelegate;
-
-  private animation: Animation;
-  private usersComponentElement: HTMLElement;
-
   @Method()
   present() {
     if (this.animation) {
@@ -140,6 +167,9 @@ export class Modal {
     });
   }
 
+  /**
+   * Dismiss the modal overlay after it has been presented.
+   */
   @Method()
   dismiss(data?: any, role?: string) {
     if (this.animation) {
@@ -208,21 +238,17 @@ export class Modal {
   }
 
   render() {
-    const backdropClasses = createThemedClasses(this.mode, this.color, 'modal-backdrop'),
+    const backdropClasses = createThemedClasses(this.mode, this.color, 'modal-backdrop');
-      dialogClasses = createThemedClasses(this.mode, this.color, 'modal-wrapper');
+    const dialogClasses = createThemedClasses(this.mode, this.color, 'modal-wrapper');
+
     return [
-      <div
+      <ion-backdrop
         onClick={this.backdropClick.bind(this)}
         class={{
           ...backdropClasses,
           'hide-backdrop': !this.showBackdrop
-        }}
+        }}></ion-backdrop>,
-      ></div>,
+      <div role='dialog' class={dialogClasses}></div>
-      <div
-        role='dialog'
-        class={dialogClasses}
-      >
-      </div>
     ];
   }
 }

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

@@ -1,7 +1,48 @@
 # ion-modal
 
+A Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.
 
 
+### Creating
+
+Modals can be created using a [Modal Controller](../../modal-controller/ModalController). They can be customized by passing modal options in the modal controller's create method.
+
+
+```javascript
+async function presentModal() {
+  // initialize controller
+  const modalController = document.querySelector('ion-modal-controller');
+  await modalController.componentOnReady();
+
+  // create component to open
+  const element = document.createElement('ion-page');
+  element.innerHTML = `
+  <ion-header>
+    <ion-toolbar>
+      <ion-title>Super Modal</ion-title>
+    </ion-toolbar>
+  </ion-header>
+  <ion-content>
+    <h1>Content of doom</h1>
+    <div>Here's some more content</div>
+    <ion-button class="dismiss">Dismiss Modal</ion-button>
+  </ion-content>
+  `;
+
+  // listen for close event
+  const button = element.querySelector('ion-button');
+  button.addEventListener('click', () => {
+    modalController.dismiss();
+  });
+
+  // present the modal
+  const modalElement = await modalController.create({
+    component: element
+  });
+  modalElement.present();
+}
+```
+
 <!-- Auto Generated Below -->
 
 
@@ -20,16 +61,23 @@ For more information, see [Theming your App](/docs/theming/theming-your-app).
 
 any
 
+The component to display inside of the modal.
+
 
 #### cssClass
 
 string
 
+Additional classes to apply for custom CSS. If multiple classes are
+provided they should be separated by spaces.
+
 
 #### data
 
 any
 
+The data to pass to the modal component.
+
 
 #### delegate
 
@@ -40,20 +88,21 @@ any
 
 boolean
 
+If true, the modal will be dismissed when the backdrop is clicked. Defaults to `true`.
+
 
 #### enterAnimation
 
 
 
+Animation to use when the modal is presented.
+
 
 #### leaveAnimation
 
 
 
-
+Animation to use when the modal is dismissed.
-#### modalId
-
-number
 
 
 #### mode
@@ -69,11 +118,15 @@ For more information, see [Platform Styles](/docs/theming/platform-specific-styl
 
 boolean
 
+If true, a backdrop will be displayed behind the modal. Defaults to `true`.
+
 
 #### willAnimate
 
 boolean
 
+If true, the modal will animate. Defaults to `true`.
+
 
 ## Attributes
 
@@ -90,16 +143,23 @@ For more information, see [Theming your App](/docs/theming/theming-your-app).
 
 any
 
+The component to display inside of the modal.
+
 
 #### css-class
 
 string
 
+Additional classes to apply for custom CSS. If multiple classes are
+provided they should be separated by spaces.
+
 
 #### data
 
 any
 
+The data to pass to the modal component.
+
 
 #### delegate
 
@@ -110,20 +170,21 @@ any
 
 boolean
 
+If true, the modal will be dismissed when the backdrop is clicked. Defaults to `true`.
+
 
 #### enter-animation
 
 
 
+Animation to use when the modal is presented.
+
 
 #### leave-animation
 
 
 
-
+Animation to use when the modal is dismissed.
-#### modal-id
-
-number
 
 
 #### mode
@@ -139,11 +200,15 @@ For more information, see [Platform Styles](/docs/theming/platform-specific-styl
 
 boolean
 
+If true, a backdrop will be displayed behind the modal. Defaults to `true`.
+
 
 #### will-animate
 
 boolean
 
+If true, the modal will animate. Defaults to `true`.
+
 
 ## Events
 
@@ -181,12 +246,16 @@ Emitted before the modal has presented.
 
 #### dismiss()
 
+Dismiss the modal overlay after it has been presented.
+
 
 #### getUserComponentContainer()
 
 
 #### present()
 
+Present the modal overlay after it has been created.
+
 
 
 ----------------------------------------------

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

@@ -4,7 +4,7 @@ A Popover is a dialog that appears on top of the current page. It can be used fo
 
 ### Creating
 
-Popovers can be created using a [Popover Controller](../../popover-controller/PopoverController). They can be customized by passing popover options in the first argument of the popover controller's create method.
+Popovers can be created using a [Popover Controller](../../popover-controller/PopoverController). They can be customized by passing popover options in the popover controller's create method.
 
 ### Presenting
 

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

@@ -4,7 +4,7 @@ A Toast is a subtle notification commonly used in modern applications. It can be
 
 ### Creating
 
-All of the toast options should be passed in the first argument of the create method: `create(opts)`. The message to display should be passed in the `message` property. The `showCloseButton` option can be set to true in order to display a close button on the toast. See the properties below for all available options.
+All of the toast options should be passed in the create method. The message to display should be passed in the `message` property. The `showCloseButton` option can be set to true in order to display a close button on the toast. See the properties below for all available options.
 
 ### Positioning