diff --git a/packages/core/src/components.d.ts b/packages/core/src/components.d.ts index 2bee93e185..208836f96a 100644 --- a/packages/core/src/components.d.ts +++ b/packages/core/src/components.d.ts @@ -104,7 +104,6 @@ declare global { animate?: boolean; enterAnimation?: AnimationBuilder; leaveAnimation?: AnimationBuilder; - actionSheetId?: string; } } } @@ -173,7 +172,6 @@ declare global { enableBackdropDismiss?: boolean; translucent?: boolean; animate?: boolean; - alertId?: string; enterAnimation?: AnimationBuilder; leaveAnimation?: AnimationBuilder; } diff --git a/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx b/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx index e8081fda2f..60156f591e 100644 --- a/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx +++ b/packages/core/src/components/action-sheet-controller/action-sheet-controller.tsx @@ -1,34 +1,6 @@ import { Component, Listen, Method } from '@stencil/core'; import { ActionSheetEvent, ActionSheetOptions } from '../../index'; - -/** - * @name ActionSheetController - * @description - * An Action Sheet is a dialog that lets the user choose from 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. - * Dangerous (destructive) options are made obvious in `ios` mode. There are easy - * ways to cancel out of 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 - * 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: `ActionSheet.create(opts)`. - */ @Component({ tag: 'ion-action-sheet-controller' }) @@ -38,7 +10,7 @@ export class ActionSheetController { private actionSheets: HTMLIonActionSheetElement[] = []; /** - * Open an action sheet with a title, subTitle, and an array of buttons + * Open an action-sheet with a title, subTitle, and an array of buttons * @param {ActionSheetOptions} opts Action sheet options */ @Method() diff --git a/packages/core/src/components/action-sheet-controller/readme.md b/packages/core/src/components/action-sheet-controller/readme.md index defcf963ea..59d01d08f6 100644 --- a/packages/core/src/components/action-sheet-controller/readme.md +++ b/packages/core/src/components/action-sheet-controller/readme.md @@ -1,5 +1,28 @@ # ion-action-sheet-controller + An Action Sheet is a dialog that lets the user choose from 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. + Dangerous (destructive) options are made obvious in `ios` mode. There are easy + ways to cancel out of 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 + 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: `ActionSheet.create(opts)`. diff --git a/packages/core/src/components/action-sheet/action-sheet.tsx b/packages/core/src/components/action-sheet/action-sheet.tsx index 62631252e7..1df3619c1e 100644 --- a/packages/core/src/components/action-sheet/action-sheet.tsx +++ b/packages/core/src/components/action-sheet/action-sheet.tsx @@ -23,6 +23,7 @@ import mdLeaveAnimation from './animations/md.leave'; export class ActionSheet { mode: string; color: string; + actionSheetId: string; private animation: Animation; @@ -61,19 +62,54 @@ export class ActionSheet { @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController; @Prop({ context: 'config' }) config: Config; + /** + * Additional class or classes to apply to the action-sheet + */ @Prop() cssClass: string; + + /** + * Title for the action-sheet + */ @Prop() title: string; + + /** + * Subtitle for the action-sheet + */ @Prop() subTitle: string; + + /** + * An array of buttons for the action-sheet. See ActionsheetButton type for accepted values + */ @Prop() buttons: ActionSheetButton[]; + + /** + * If true, the action-sheet will be dismissed when the backdrop is clicked. + */ @Prop() enableBackdropDismiss: boolean = true; + + /** + * If true, action-sheet will become translucent. Requires support for backdrop-filters. + */ @Prop() translucent: boolean = false; + /** + * Enable action-sheet animations. If false, action-sheet will not animate in + */ @Prop() animate: boolean = true; + + /** + * Animation to use when the action-sheet is created + */ @Prop() enterAnimation: AnimationBuilder; + + /** + * Animation to use when the action-sheet is dismissed + */ @Prop() leaveAnimation: AnimationBuilder; - @Prop() actionSheetId: string; - + /** + * Present the action-sheet after is has been created + */ @Method() present() { if (this.animation) { @@ -100,6 +136,9 @@ export class ActionSheet { }); } + /** + * Dismiss the action-sheet programatically + */ @Method() dismiss() { if (this.animation) { diff --git a/packages/core/src/components/action-sheet/readme.md b/packages/core/src/components/action-sheet/readme.md index 9581aaf694..25e6991f66 100644 --- a/packages/core/src/components/action-sheet/readme.md +++ b/packages/core/src/components/action-sheet/readme.md @@ -7,11 +7,6 @@ ## Properties -#### actionSheetId - -string - - #### animate boolean @@ -59,11 +54,6 @@ boolean ## Attributes -#### actionSheetId - -string - - #### animate boolean diff --git a/packages/core/src/components/alert-controller/alert-controller.tsx b/packages/core/src/components/alert-controller/alert-controller.tsx index 2a35c5f3b9..7e3758cedf 100644 --- a/packages/core/src/components/alert-controller/alert-controller.tsx +++ b/packages/core/src/components/alert-controller/alert-controller.tsx @@ -10,6 +10,10 @@ export class AlertController { private alertResolves: { [alertId: string]: Function } = {}; private alerts: HTMLIonAlertElement[] = []; + /** + * Open an alert with a title, subTitle, and an array of buttons + * @param {AlertOptions} opts Action sheet options + */ @Method() create(opts?: AlertOptions): Promise { // create ionic's wrapping ion-alert component diff --git a/packages/core/src/components/alert-controller/readme.md b/packages/core/src/components/alert-controller/readme.md index ab5310d058..a4fba59df7 100644 --- a/packages/core/src/components/alert-controller/readme.md +++ b/packages/core/src/components/alert-controller/readme.md @@ -1,5 +1,42 @@ # ion-alert-controller +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`. + +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 + +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. diff --git a/packages/core/src/components/alert/alert.tsx b/packages/core/src/components/alert/alert.tsx index 2d495f7551..27074e2628 100644 --- a/packages/core/src/components/alert/alert.tsx +++ b/packages/core/src/components/alert/alert.tsx @@ -25,6 +25,7 @@ import mdLeaveAnimation from './animations/md.leave'; export class Alert { mode: string; color: string; + alertId: string; private animation: Animation; private activeId: string; @@ -66,21 +67,64 @@ export class Alert { @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController; @Prop({ context: 'config' }) config: Config; + /** + * Additional class or classes to apply to the alert + */ @Prop() cssClass: string; + + /** + * 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: boolean = true; + + /** + * If true, alert will become translucent. Requires support for backdrop-filters. + */ @Prop() translucent: boolean = false; + /** + * Enable alert animations. If false, alert will not animate in + */ @Prop() animate: boolean = true; - @Prop() alertId: string; + /** + * 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(); @@ -111,6 +155,9 @@ export class Alert { }); } + /** + * Dismiss the alert programatically + */ @Method() dismiss(data?: any, role?: string) { if (this.animation) { this.animation.destroy(); @@ -440,7 +487,6 @@ export class Alert { } - export interface AlertOptions { title?: string; subTitle?: string; diff --git a/packages/core/src/components/alert/readme.md b/packages/core/src/components/alert/readme.md index be77fe2d9d..bfbfbf14d5 100644 --- a/packages/core/src/components/alert/readme.md +++ b/packages/core/src/components/alert/readme.md @@ -7,11 +7,6 @@ ## Properties -#### alertId - -string - - #### animate boolean @@ -69,11 +64,6 @@ boolean ## Attributes -#### alertId - -string - - #### animate boolean diff --git a/packages/core/src/components/loading-controller/loading-controller.tsx b/packages/core/src/components/loading-controller/loading-controller.tsx index fa6b45f149..d00cde2925 100644 --- a/packages/core/src/components/loading-controller/loading-controller.tsx +++ b/packages/core/src/components/loading-controller/loading-controller.tsx @@ -10,6 +10,9 @@ export class LoadingController { private loadingResolves: {[loadingId: string]: Function} = {}; private loadings: Loading[] = []; + /** + * Create a loading overlay and pass options to it + */ @Method() create(opts?: LoadingOptions): Promise { // create ionic's wrapping ion-loading component diff --git a/packages/core/src/components/loading-controller/readme.md b/packages/core/src/components/loading-controller/readme.md index 164b898e4a..0ed17c9c0b 100644 --- a/packages/core/src/components/loading-controller/readme.md +++ b/packages/core/src/components/loading-controller/readme.md @@ -1,5 +1,36 @@ # ion-loading-controller +An overlay that can be used to indicate activity while blocking user +interaction. The loading indicator appears on top of the app's content, +and can be dismissed by the app to resume user interaction with +the app. It includes an optional backdrop, which can be disabled +by setting `showBackdrop: false` upon creation. + +### Creating +You can pass all of the loading options in the first argument of +the create method: `create(opts)`. The spinner name should be +passed in the `spinner` property, and any optional HTML can be passed +in the `content` property. If you do not pass a value to `spinner` +the loading indicator will use the spinner specified by the mode. To +set the spinner name across the app, set the value of `loadingSpinner` +in your app's config. To hide the spinner, set `loadingSpinner: 'hide'` +in the app's config or pass `spinner: 'hide'` in the loading +options. See the [create](#create) method below for all available options. + +### Dismissing +The loading indicator can be dismissed automatically after a specific +amount of time by passing the number of milliseconds to display it in +the `duration` of the loading options. By default the loading indicator +will show even during page changes, but this can be disabled by setting +`dismissOnPageChange` to `true`. To dismiss the loading indicator after +creation, call the `dismiss()` method on the Loading instance. The +`onDidDismiss` function can be called to perform an action after the loading +indicator is dismissed. + +>Note that after the component is dismissed, it will not be usable anymore +and another one must be created. This can be avoided by wrapping the +creation and presentation of the component in a reusable function as shown +in the `usage` section below. diff --git a/packages/core/src/components/loading/loading.tsx b/packages/core/src/components/loading/loading.tsx index c51531180c..42505dec17 100644 --- a/packages/core/src/components/loading/loading.tsx +++ b/packages/core/src/components/loading/loading.tsx @@ -1,11 +1,9 @@ import { Animation, AnimationBuilder, AnimationController, Config } from '../../index'; import { Component, Element, Event, EventEmitter, Listen, Prop, State } from '@stencil/core'; - import { createThemedClasses } from '../../utils/theme'; import iosEnterAnimation from './animations/ios.enter'; import iosLeaveAnimation from './animations/ios.leave'; - import mdEnterAnimation from './animations/md.enter'; import mdLeaveAnimation from './animations/md.leave'; @@ -22,6 +20,7 @@ import mdLeaveAnimation from './animations/md.leave'; export class Loading { color: string; mode: string; + loadingId: string; private animation: Animation; private durationTimeout: any; @@ -63,17 +62,50 @@ export class Loading { @Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController; @Prop({ context: 'config' }) config: Config; + + /** + * Additional classes to apply for custom CSS + */ @Prop() cssClass: string; + + /** + * Optional text content to display in the loading indicator + */ @Prop() content: string; + + /** + * Dismiss the loading indicator if the page is changed + */ @Prop() dismissOnPageChange: boolean = false; + + /** + * Number of milliseconds to wait before dismissing the loading indicator + */ @Prop() duration: number; + + /** + * If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect + */ @Prop() translucent: boolean = false; - @Prop() loadingId: string; + + /** + * Show the backdrop of not + */ @Prop() showBackdrop: boolean = true; + /** + * Animation to use when loading indicator is presented + */ @Prop() enterAnimation: AnimationBuilder; + + /** + * Animation to use when a loading indicator is dismissed + */ @Prop() leaveAnimation: AnimationBuilder; + /** + * Present a loading overlay after it has been created + */ present() { return new Promise(resolve => { this._present(resolve); @@ -104,6 +136,9 @@ export class Loading { }); } + /** + * Dismiss a loading indicator programatically + */ dismiss() { clearTimeout(this.durationTimeout); @@ -228,7 +263,6 @@ export class Loading { } } - export interface LoadingOptions { spinner?: string; content?: string; @@ -239,7 +273,6 @@ export interface LoadingOptions { translucent?: boolean; } - export interface LoadingEvent extends Event { detail: { loading: Loading;