diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 015aeb86a8..be2602ea30 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -70,21 +70,7 @@ Please see our [Contributor Code of Conduct](https://github.com/ionic-team/ionic #### Adding Documentation -1. To add or modify API Documentation for a component, it should be added/changed in the component's TypeScript (`*.ts`) file, prior to the Class definition. For example, `Badge` looks similar to this: - - ``` - /** - * @name Badge - * @module ionic - * @description - * Badges are simple components in Ionic containing numbers or text. - * - * @see {@link /docs/v2/components/#badges Badges Component Docs} - * @demo /docs/v2/demos/badge/ - **/ - ``` - - where `@name` is the Class name, `@description` is the description displayed on the documentation page, `@see` links to any related pages, and `@demo` links to the API demo located in the `demos` folder. +1. To add or modify API Documentation for a component, it should be added/changed in the `readme.md` file in the component's directory. If the updates are to a specific `@Prop`, `@Event` or `@Method`, then please make the changes to the component's TypeScript (`*.ts`). Properties, events and methods information within the `readme.md` file are auto generated directly from the JSDoc comments within the TypeScript file. 2. In order to run API documentation locally, you will need to clone the `ionic-site` repo as a sibling to the `ionic` repo and then run it: https://github.com/ionic-team/ionic-site#local-build 3. Then, run `gulp docs` in the `ionic` repo every time you make a change and the site will update. 4. If the change affects the component documentation, create an issue on the `ionic-site` repo: https://github.com/ionic-team/ionic-site/issues diff --git a/packages/core/src/components/avatar/avatar.tsx b/packages/core/src/components/avatar/avatar.tsx index 1af8f3be86..b1da84d680 100644 --- a/packages/core/src/components/avatar/avatar.tsx +++ b/packages/core/src/components/avatar/avatar.tsx @@ -1,14 +1,6 @@ import { Component } from '@stencil/core'; -/** - * @name Avatar - * @module ionic - * @description - * An Avatar is a component that creates a circular image for an item. - * Avatars can be placed on the left or right side of an item with the `item-start` or `item-end` directive. - * @see {@link /docs/components/#avatar-list Avatar Component Docs} - */ @Component({ tag: 'ion-avatar', styleUrls: { diff --git a/packages/core/src/components/avatar/readme.md b/packages/core/src/components/avatar/readme.md index 159bb7f14b..362c20c044 100644 --- a/packages/core/src/components/avatar/readme.md +++ b/packages/core/src/components/avatar/readme.md @@ -1,5 +1,7 @@ # ion-avatar +An Avatar is a component that creates a circular image for an item. +Avatars can be placed on the left or right side of an item with the `item-start` or `item-end` directive. diff --git a/packages/core/src/components/badge/badge.tsx b/packages/core/src/components/badge/badge.tsx index fa3b249025..52fe127d6a 100644 --- a/packages/core/src/components/badge/badge.tsx +++ b/packages/core/src/components/badge/badge.tsx @@ -1,32 +1,6 @@ import { Component, Prop } from '@stencil/core'; -/** - * @name Badge - * @module ionic - * @description - * Badges are simple components in Ionic containing numbers or text. You can display a - * badge to indicate that there is new information associated with the item it is on. - * - * @usage - * - * ```html - * - * - * - * - * 34 - * - * My Item - * - * 2 - * - * - * - * - * ``` - * - * @see {@link /docs/components/#badges Badges Component Docs} - */ + @Component({ tag: 'ion-badge', styleUrls: { diff --git a/packages/core/src/components/badge/readme.md b/packages/core/src/components/badge/readme.md index 3dd190267a..8eaa1ea941 100644 --- a/packages/core/src/components/badge/readme.md +++ b/packages/core/src/components/badge/readme.md @@ -1,5 +1,23 @@ # ion-badge +Badges are simple components in Ionic containing numbers or text. You can display a +badge to indicate that there is new information associated with the item it is on. + +```html + + + + + 34 + + My Item + + 2 + + + + +``` diff --git a/packages/core/src/components/button/button.tsx b/packages/core/src/components/button/button.tsx index f586d6d37b..f144c9b7bc 100644 --- a/packages/core/src/components/button/button.tsx +++ b/packages/core/src/components/button/button.tsx @@ -1,67 +1,7 @@ import { Component, CssClassMap, Element, Prop } from '@stencil/core'; - import { getElementClassObject } from '../../utils/theme'; -/** - * @name Button - * @module ionic - * @description - * Buttons are simple components in Ionic. They can consist of text and icons - * and be enhanced by a wide range of attributes. - * - * @usage - * - * ```html - * - * - * Default - * - * Secondary - * - * Danger - * - * Light - * - * Dark - * - * - * Full Button - * - * Block Button - * - * Round Button - * - * - * Outline + Full - * - * Outline + Block - * - * Outline + Round - * - * - * - * - * Left Icon - * - * - * - * Right Icon - * - * - * - * - * - * - * - * - * Large - * - * Default - * - * Small - * ``` - * - */ + @Component({ tag: 'ion-button', styleUrls: { diff --git a/packages/core/src/components/button/readme.md b/packages/core/src/components/button/readme.md index 9703d6ce16..d03005836c 100644 --- a/packages/core/src/components/button/readme.md +++ b/packages/core/src/components/button/readme.md @@ -1,5 +1,57 @@ # ion-button +Buttons are simple components in Ionic. They can consist of text and icons +and be enhanced by a wide range of attributes. + +```html + + +Default + +Secondary + +Danger + +Light + +Dark + + +Full Button + +Block Button + +Round Button + + +Outline + Full + +Outline + Block + +Outline + Round + + + + + Left Icon + + + + Right Icon + + + + + + + + +Large + +Default + +Small +``` diff --git a/packages/core/src/components/checkbox/checkbox.tsx b/packages/core/src/components/checkbox/checkbox.tsx index 4161683ae2..18fbe2f2d6 100644 --- a/packages/core/src/components/checkbox/checkbox.tsx +++ b/packages/core/src/components/checkbox/checkbox.tsx @@ -1,71 +1,7 @@ import { BlurEvent, CheckboxInput, CheckedInputChangeEvent, FocusEvent, StyleEvent } from '../../utils/input-interfaces'; import { Component, CssClassMap, Event, EventEmitter, Listen, Prop, PropDidChange } from '@stencil/core'; -/** - * @name Checkbox - * @module ionic - * - * @description - * placed in an `ion-item` or used as a stand-alone checkbox. - * - * See the [Angular Docs](https://angular.io/docs/ts/latest/guide/forms.html) - * for more info on forms and inputs. - * - * - * @usage - * ```html - * - * - * - * - * Pepperoni - * - * - * - * - * Sausage - * - * - * - * - * Mushrooms - * - * - * - * - * ``` - * - * @advanced - * - * ```html - * - * - * - * - * - * Cucumber - * - * - * - * - * ``` - * - * ```ts - * @Component({ - * templateUrl: 'main.html' - * }) - * class SaladPage { - * cucumber: boolean; - * - * updateCucumber() { - * console.log('Cucumbers new state:' + this.cucumber); - * } - * } - * ``` - * - * @demo /docs/demos/src/checkbox/ - * @see {@link /docs/components#checkbox Checkbox Component Docs} - */ + @Component({ tag: 'ion-checkbox', styleUrls: { diff --git a/packages/core/src/components/checkbox/readme.md b/packages/core/src/components/checkbox/readme.md index dd6ecfd87d..48a58f1a60 100644 --- a/packages/core/src/components/checkbox/readme.md +++ b/packages/core/src/components/checkbox/readme.md @@ -1,6 +1,59 @@ # ion-checkbox +Placed in an `ion-item` or used as a stand-alone checkbox. + + +```html + + + + + Pepperoni + + + + + Sausage + + + + + Mushrooms + + + + +``` + +@advanced + +```html + + + + + + Cucumber + + + + +``` + +```ts +@Component({ + templateUrl: 'main.html' +}) +class SaladPage { + cucumber: boolean; + + updateCucumber() { + console.log('Cucumbers new state:' + this.cucumber); + } +} +``` + diff --git a/packages/core/src/components/chip/chip.tsx b/packages/core/src/components/chip/chip.tsx index e1916969bc..3ddaaa86a9 100644 --- a/packages/core/src/components/chip/chip.tsx +++ b/packages/core/src/components/chip/chip.tsx @@ -1,92 +1,6 @@ import { Component, Prop } from '@stencil/core'; -/** - * @name Chip - * @module ionic - * @description - * Chips represent complex entities in small blocks, such as a contact. - * - * - * @usage - * - * ```html - * - * Default - * - * - * - * Secondary Label - * - * - * - * Secondary w/ Dark label - * - * - * - * Danger - * - * - * - * - * Default - * - * - * - * - * Default - * - * - * - * - * - * - * Default - * - * ``` - * - * - * @advanced - * - * ```html - * - * Default - * - * - * - * - * - * - * - * With Icon - * - * - * - * - * - * - * - * - * - * With Avatar - * - * - * - * - * ``` - * - * ```ts - * @Component({ - * templateUrl: 'main.html' - * }) - * class E2EPage { - * delete(chip: Element) { - * chip.remove(); - * } - * } - * ``` - * - * @demo /docs/demos/src/chip/ - **/ + @Component({ tag: 'ion-chip', styleUrls: { diff --git a/packages/core/src/components/chip/readme.md b/packages/core/src/components/chip/readme.md index ee4c1ddbf4..6c6b4d5985 100644 --- a/packages/core/src/components/chip/readme.md +++ b/packages/core/src/components/chip/readme.md @@ -1,5 +1,70 @@ # ion-chip +Chips represent complex entities in small blocks, such as a contact. + + +```html + + Default + + + + Secondary Label + + + + Secondary w/ Dark label + + + + Danger + + + + + Default + + + + + Default + + + + + + + Default + +``` + + +```html + + Default + + + + + + + + With Icon + + + + + + + + + + With Avatar + + + + +``` diff --git a/packages/core/src/components/datetime/datetime.tsx b/packages/core/src/components/datetime/datetime.tsx index 872885d5bc..3ff294eeec 100644 --- a/packages/core/src/components/datetime/datetime.tsx +++ b/packages/core/src/components/datetime/datetime.tsx @@ -17,248 +17,10 @@ import { renderTextFormat, updateDate } from './datetime-util'; - import { clamp, isBlank, isObject } from '../../utils/helpers'; - import { Picker, PickerColumn, PickerController, PickerOptions } from '../../index'; -/** - * @name Datetime - * @description - * The Datetime component is used to present an interface which makes it easy for - * users to select dates and times. Tapping on `` will display a picker - * interface that slides up from the bottom of the page. The picker then displays - * scrollable columns that can be used to individually select years, months, days, - * hours and minute values. The Datetime component is similar to the native - * `` element, however, Ionic's Datetime component makes - * it easy to display the date and time in a preferred format, and manage the datetime - * values. - * - * ```html - * - * Date - * - * - * ``` - * - * - * ## Display and Picker Formats - * - * The Datetime component displays the values in two places: in the `` - * component, and in the interface that is presented from the bottom of the screen. - * The following chart lists all of the formats that can be used. - * - * | Format | Description | Example | - * |---------|--------------------------------|-------------------------| - * | `YYYY` | Year, 4 digits | `2018` | - * | `YY` | Year, 2 digits | `18` | - * | `M` | Month | `1` ... `12` | - * | `MM` | Month, leading zero | `01` ... `12` | - * | `MMM` | Month, short name | `Jan` | - * | `MMMM` | Month, full name | `January` | - * | `D` | Day | `1` ... `31` | - * | `DD` | Day, leading zero | `01` ... `31` | - * | `DDD` | Day, short name | `Fri` | - * | `DDDD` | Day, full name | `Friday` | - * | `H` | Hour, 24-hour | `0` ... `23` | - * | `HH` | Hour, 24-hour, leading zero | `00` ... `23` | - * | `h` | Hour, 12-hour | `1` ... `12` | - * | `hh` | Hour, 12-hour, leading zero | `01` ... `12` | - * | `a` | 12-hour time period, lowercase | `am` `pm` | - * | `A` | 12-hour time period, uppercase | `AM` `PM` | - * | `m` | Minute | `1` ... `59` | - * | `mm` | Minute, leading zero | `01` ... `59` | - * | `s` | Second | `1` ... `59` | - * | `ss` | Second, leading zero | `01` ... `59` | - * | `Z` | UTC Timezone Offset | `Z or +HH:mm or -HH:mm` | - * - * **Important**: See the [Month Names and Day of the Week Names](#month-names-and-day-of-the-week-names) - * section below on how to use different names for the month and day. - * - * ### Display Format - * - * The `displayFormat` input property specifies how a datetime's value should be - * printed, as formatted text, within the `ion-datetime` component. - * - * In the following example, the display in the `` will use the - * month's short name, the numerical day with a leading zero, a comma and the - * four-digit year. In addition to the date, it will display the time with the hours - * in the 24-hour format and the minutes. Any character can be used as a separator. - * An example display using this format is: `Jun 17, 2005 11:06`. - * - * ```html - * - * Date - * - * - * ``` - * - * ### Picker Format - * - * The `pickerFormat` input property determines which columns should be shown in the - * interface, the order of the columns, and which format to use within each column. - * If the `pickerFormat` input is not provided then it will default to the `displayFormat`. - * - * In the following example, the display in the `` will use the - * `MM/YYYY` format, such as `06/2020`. However, the picker interface - * will display two columns with the month's long name, and the four-digit year. - * - * ```html - * - * Date - * - * - * ``` - * - * ### Datetime Data - * - * Historically, handling datetime values within JavaScript, or even within HTML - * inputs, has always been a challenge. Specifically, JavaScript's `Date` object is - * notoriously difficult to correctly parse apart datetime strings or to format - * datetime values. Even worse is how different browsers and JavaScript versions - * parse various datetime strings differently, especially per locale. - * - * But no worries, all is not lost! Ionic's datetime input has been designed so - * developers can avoid the common pitfalls, allowing developers to easily format - * datetime values within the input, and give the user a simple datetime picker for a - * great user experience. - * - * ##### ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ - * - * Ionic uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime) - * for its value. The value is simply a string, rather than using JavaScript's `Date` - * object. Additionally, when using the ISO datetime format, it makes it easier - * to serialize and pass within JSON objects, and sending databases a standardized - * format which it can be easily parsed if need be. - * - * An ISO format can be used as a simple year, or just the hour and minute, or get more - * detailed down to the millisecond and timezone. Any of the ISO formats below can be used, - * and after a user selects a new value, Ionic will continue to use the same ISO format - * which datetime value was originally given as. - * - * | Description | Format | Datetime Value Example | - * |----------------------|------------------------|------------------------------| - * | Year | YYYY | 1994 | - * | Year and Month | YYYY-MM | 1994-12 | - * | Complete Date | YYYY-MM-DD | 1994-12-15 | - * | Date and Time | YYYY-MM-DDTHH:mm | 1994-12-15T13:47 | - * | UTC Timezone | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20.789Z | - * | Timezone Offset | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20.789+5:00 | - * | Hour and Minute | HH:mm | 13:47 | - * | Hour, Minute, Second | HH:mm:ss | 13:47:20 | - * - * Note that the year is always four-digits, milliseconds (if it's added) is always - * three-digits, and all others are always two-digits. So the number representing - * January always has a leading zero, such as `01`. Additionally, the hour is always - * in the 24-hour format, so `00` is `12am` on a 12-hour clock, `13` means `1pm`, - * and `23` means `11pm`. - * - * It's also important to note that neither the `displayFormat` or `pickerFormat` can - * set the datetime value's output, which is the value that is set by the component's - * `ngModel`. The format's are merely for displaying the value as text and the picker's - * interface, but the datetime's value is always persisted as a valid ISO 8601 datetime - * string. - * - * - * ## Min and Max Datetimes - * - * Dates are infinite in either direction, so for a user's selection there should be at - * least some form of restricting the dates that can be selected. By default, the maximum - * date is to the end of the current year, and the minimum date is from the beginning - * of the year that was 100 years ago. - * - * To customize the minimum and maximum datetime values, the `min` and `max` component - * inputs can be provided which may make more sense for the app's use-case, rather - * than the default of the last 100 years. Following the same IS0 8601 format listed - * in the table above, each component can restrict which dates can be selected by the - * user. Below is an example of restricting the date selection between the beginning - * of 2016, and October 31st of 2020: - * - * ```html - * - * Date - * - * - * - * ``` - * - * - * ## Month Names and Day of the Week Names - * - * At this time, there is no one-size-fits-all standard to automatically choose the correct - * language/spelling for a month name, or day of the week name, depending on the language - * or locale. Good news is that there is an - * [Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) - * standard which *most* browsers have adopted. However, at this time the standard has not - * been fully implemented by all popular browsers so Ionic is unavailable to take advantage - * of it *yet*. Additionally, Angular also provides an internationalization service, but it - * is still under heavy development so Ionic does not depend on it at this time. - * - * All things considered, the by far easiest solution is to just provide an array of names - * if the app needs to use names other than the default English version of month and day - * names. The month names and day names can be either configured at the app level, or - * individual `ion-datetime` level. - * - * ### App Config Level - * - * ```ts - * //app.module.ts - * @NgModule({ - * ..., - * imports: [ - * IonicModule.forRoot(MyApp, { - * monthNames: ['janeiro', 'fevereiro', 'mar\u00e7o', ... ], - * monthShortNames: ['jan', 'fev', 'mar', ... ], - * dayNames: ['domingo', 'segunda-feira', 'ter\u00e7a-feira', ... ], - * dayShortNames: ['dom', 'seg', 'ter', ... ], - * }) - * ], - * ... - * }) - * ``` - * - * ### Component Input Level - * - * ```html - * - * Período - * - * - * ``` - * - * - * ### Advanced Datetime Validation and Manipulation - * - * The datetime picker provides the simplicity of selecting an exact format, and persists - * the datetime values as a string using the standardized - * [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime). - * However, it's important to note that `ion-datetime` does not attempt to solve all - * situtations when validating and manipulating datetime values. If datetime values need - * to be parsed from a certain format, or manipulated (such as adding 5 days to a date, - * subtracting 30 minutes, etc.), or even formatting data to a specific locale, then we highly - * recommend using [moment.js](http://momentjs.com/) to "Parse, validate, manipulate, and - * display dates in JavaScript". [Moment.js](http://momentjs.com/) has quickly become - * our goto standard when dealing with datetimes within JavaScript, but Ionic does not - * prepackage this dependency since most apps will not require it, and its locale - * configuration should be decided by the end-developer. - * - * - * @usage - * ```html - * - * Date - * - * - * - * ``` - * - * - * @demo /docs/demos/src/datetime/ - */ + @Component({ tag: 'ion-datetime', styleUrls: { diff --git a/packages/core/src/components/datetime/readme.md b/packages/core/src/components/datetime/readme.md index f80d1654a9..bbdc08c65f 100644 --- a/packages/core/src/components/datetime/readme.md +++ b/packages/core/src/components/datetime/readme.md @@ -1,5 +1,234 @@ # ion-datetime +The Datetime component is used to present an interface which makes it easy for +users to select dates and times. Tapping on `` will display a picker +interface that slides up from the bottom of the page. The picker then displays +scrollable columns that can be used to individually select years, months, days, +hours and minute values. The Datetime component is similar to the native +`` element, however, Ionic's Datetime component makes +it easy to display the date and time in a preferred format, and manage the datetime +values. + +```html + + Date + + +``` + + +## Display and Picker Formats + +The Datetime component displays the values in two places: in the `` +component, and in the interface that is presented from the bottom of the screen. +The following chart lists all of the formats that can be used. + +| Format | Description | Example | +|---------|--------------------------------|-------------------------| +| `YYYY` | Year, 4 digits | `2018` | +| `YY` | Year, 2 digits | `18` | +| `M` | Month | `1` ... `12` | +| `MM` | Month, leading zero | `01` ... `12` | +| `MMM` | Month, short name | `Jan` | +| `MMMM` | Month, full name | `January` | +| `D` | Day | `1` ... `31` | +| `DD` | Day, leading zero | `01` ... `31` | +| `DDD` | Day, short name | `Fri` | +| `DDDD` | Day, full name | `Friday` | +| `H` | Hour, 24-hour | `0` ... `23` | +| `HH` | Hour, 24-hour, leading zero | `00` ... `23` | +| `h` | Hour, 12-hour | `1` ... `12` | +| `hh` | Hour, 12-hour, leading zero | `01` ... `12` | +| `a` | 12-hour time period, lowercase | `am` `pm` | +| `A` | 12-hour time period, uppercase | `AM` `PM` | +| `m` | Minute | `1` ... `59` | +| `mm` | Minute, leading zero | `01` ... `59` | +| `s` | Second | `1` ... `59` | +| `ss` | Second, leading zero | `01` ... `59` | +| `Z` | UTC Timezone Offset | `Z or +HH:mm or -HH:mm` | + +**Important**: See the [Month Names and Day of the Week Names](#month-names-and-day-of-the-week-names) +section below on how to use different names for the month and day. + +### Display Format + +The `displayFormat` input property specifies how a datetime's value should be +printed, as formatted text, within the `ion-datetime` component. + +In the following example, the display in the `` will use the +month's short name, the numerical day with a leading zero, a comma and the +four-digit year. In addition to the date, it will display the time with the hours +in the 24-hour format and the minutes. Any character can be used as a separator. +An example display using this format is: `Jun 17, 2005 11:06`. + +```html + + Date + + +``` + +### Picker Format + +The `pickerFormat` input property determines which columns should be shown in the +interface, the order of the columns, and which format to use within each column. +If the `pickerFormat` input is not provided then it will default to the `displayFormat`. + +In the following example, the display in the `` will use the +`MM/YYYY` format, such as `06/2020`. However, the picker interface +will display two columns with the month's long name, and the four-digit year. + +```html + + Date + + +``` + +### Datetime Data + +Historically, handling datetime values within JavaScript, or even within HTML +inputs, has always been a challenge. Specifically, JavaScript's `Date` object is +notoriously difficult to correctly parse apart datetime strings or to format +datetime values. Even worse is how different browsers and JavaScript versions +parse various datetime strings differently, especially per locale. + +But no worries, all is not lost! Ionic's datetime input has been designed so +developers can avoid the common pitfalls, allowing developers to easily format +datetime values within the input, and give the user a simple datetime picker for a +great user experience. + +##### ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ + +Ionic uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime) +for its value. The value is simply a string, rather than using JavaScript's `Date` +object. Additionally, when using the ISO datetime format, it makes it easier +to serialize and pass within JSON objects, and sending databases a standardized +format which it can be easily parsed if need be. + +An ISO format can be used as a simple year, or just the hour and minute, or get more +detailed down to the millisecond and timezone. Any of the ISO formats below can be used, +and after a user selects a new value, Ionic will continue to use the same ISO format +which datetime value was originally given as. + +| Description | Format | Datetime Value Example | +|----------------------|------------------------|------------------------------| +| Year | YYYY | 1994 | +| Year and Month | YYYY-MM | 1994-12 | +| Complete Date | YYYY-MM-DD | 1994-12-15 | +| Date and Time | YYYY-MM-DDTHH:mm | 1994-12-15T13:47 | +| UTC Timezone | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20.789Z | +| Timezone Offset | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20.789+5:00 | +| Hour and Minute | HH:mm | 13:47 | +| Hour, Minute, Second | HH:mm:ss | 13:47:20 | + +Note that the year is always four-digits, milliseconds (if it's added) is always +three-digits, and all others are always two-digits. So the number representing +January always has a leading zero, such as `01`. Additionally, the hour is always +in the 24-hour format, so `00` is `12am` on a 12-hour clock, `13` means `1pm`, +and `23` means `11pm`. + +It's also important to note that neither the `displayFormat` or `pickerFormat` can +set the datetime value's output, which is the value that is set by the component's +`ngModel`. The format's are merely for displaying the value as text and the picker's +interface, but the datetime's value is always persisted as a valid ISO 8601 datetime +string. + + +## Min and Max Datetimes + +Dates are infinite in either direction, so for a user's selection there should be at +least some form of restricting the dates that can be selected. By default, the maximum +date is to the end of the current year, and the minimum date is from the beginning +of the year that was 100 years ago. + +To customize the minimum and maximum datetime values, the `min` and `max` component +inputs can be provided which may make more sense for the app's use-case, rather +than the default of the last 100 years. Following the same IS0 8601 format listed +in the table above, each component can restrict which dates can be selected by the +user. Below is an example of restricting the date selection between the beginning +of 2016, and October 31st of 2020: + +```html + + Date + + + +``` + + +## Month Names and Day of the Week Names + +At this time, there is no one-size-fits-all standard to automatically choose the correct +language/spelling for a month name, or day of the week name, depending on the language +or locale. Good news is that there is an +[Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) +standard whichmost* browsers have adopted. However, at this time the standard has not +been fully implemented by all popular browsers so Ionic is unavailable to take advantage +of ityet*. Additionally, Angular also provides an internationalization service, but it +is still under heavy development so Ionic does not depend on it at this time. + +All things considered, the by far easiest solution is to just provide an array of names +if the app needs to use names other than the default English version of month and day +names. The month names and day names can be either configured at the app level, or +individual `ion-datetime` level. + +### App Config Level + +```ts +//app.module.ts +@NgModule({ +..., +imports: [ + IonicModule.forRoot(MyApp, { + monthNames: ['janeiro', 'fevereiro', 'mar\u00e7o', ... ], + monthShortNames: ['jan', 'fev', 'mar', ... ], + dayNames: ['domingo', 'segunda-feira', 'ter\u00e7a-feira', ... ], + dayShortNames: ['dom', 'seg', 'ter', ... ], +}) +], +... +}) +``` + +### Component Input Level + +```html + + Período + + +``` + + +### Advanced Datetime Validation and Manipulation + +The datetime picker provides the simplicity of selecting an exact format, and persists +the datetime values as a string using the standardized +[ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime). +However, it's important to note that `ion-datetime` does not attempt to solve all +situtations when validating and manipulating datetime values. If datetime values need +to be parsed from a certain format, or manipulated (such as adding 5 days to a date, +subtracting 30 minutes, etc.), or even formatting data to a specific locale, then we highly +recommend using [moment.js](http://momentjs.com/) to "Parse, validate, manipulate, and +display dates in JavaScript". [Moment.js](http://momentjs.com/) has quickly become +our goto standard when dealing with datetimes within JavaScript, but Ionic does not +prepackage this dependency since most apps will not require it, and its locale +configuration should be decided by the end-developer. + + +```html + + Date + + + +``` diff --git a/packages/core/src/components/infinite-scroll/infinite-scroll.tsx b/packages/core/src/components/infinite-scroll/infinite-scroll.tsx index 6ca72785af..d639768705 100644 --- a/packages/core/src/components/infinite-scroll/infinite-scroll.tsx +++ b/packages/core/src/components/infinite-scroll/infinite-scroll.tsx @@ -6,140 +6,7 @@ const enum Position { Bottom = 'bottom', } -/** - * @name InfiniteScroll - * @description - * The Infinite Scroll allows you to perform an action when the user - * scrolls a specified distance from the bottom or top of the page. - * - * The expression assigned to the `infinite` event is called when - * the user scrolls to the specified distance. When this expression - * has finished its tasks, it should call the `complete()` method - * on the infinite scroll instance. - * - * @usage - * ```html - * - * - * - * {% raw %}{{i}}{% endraw %} - * - * - * - * - * - * - * - * ``` - * - * ```ts - * @Component({...}) - * export class NewsFeedPage { - * items = []; - * - * constructor() { - * for (let i = 0; i < 30; i++) { - * this.items.push( this.items.length ); - * } - * } - * - * doInfinite(infiniteScroll) { - * console.log('Begin async operation'); - * - * setTimeout(() => { - * for (let i = 0; i < 30; i++) { - * this.items.push( this.items.length ); - * } - * - * console.log('Async operation has ended'); - * infiniteScroll.complete(); - * }, 500); - * } - * - * } - * ``` - * - * ## `waitFor` method of InfiniteScroll - * - * In case if your async operation returns promise you can utilize - * `waitFor` method inside your template. - * - * ```html - * - * - * - * {{item}} - * - * - * - * - * - * - * - * ``` - * - * ```ts - * @Component({...}) - * export class NewsFeedPage { - * items = []; - * - * constructor() { - * for (var i = 0; i < 30; i++) { - * this.items.push( this.items.length ); - * } - * } - * - * doInfinite(): Promise { - * console.log('Begin async operation'); - * - * return new Promise((resolve) => { - * setTimeout(() => { - * for (var i = 0; i < 30; i++) { - * this.items.push( this.items.length ); - * } - * - * console.log('Async operation has ended'); - * resolve(); - * }, 500); - * }) - * } - * } - * ``` - * - * ## Infinite Scroll Content - * - * By default, Ionic uses the infinite scroll spinner that looks - * best for the platform the user is on. However, you can change the - * default spinner or add text by adding properties to the - * `ion-infinite-scroll-content` component. - * - * ```html - * - * - * - * - * - * - * - * - * ``` - * - * - * ## Further Customizing Infinite Scroll Content - * - * The `ion-infinite-scroll` component holds the infinite scroll logic. - * It requires a child component in order to display the content. - * Ionic uses `ion-infinite-scroll-content` by default. This component - * displays the infinite scroll and changes the look depending - * on the infinite scroll's state. Separating these components allows - * developers to create their own infinite scroll content components. - * You could replace our default content with custom SVG or CSS animations. - * - * @demo /docs/demos/src/infinite-scroll/ - * - */ + @Component({ tag: 'ion-infinite-scroll', styleUrl: 'infinite-scroll.scss' diff --git a/packages/core/src/components/infinite-scroll/readme.md b/packages/core/src/components/infinite-scroll/readme.md index 445820d4e2..12330c7cb4 100644 --- a/packages/core/src/components/infinite-scroll/readme.md +++ b/packages/core/src/components/infinite-scroll/readme.md @@ -1,5 +1,131 @@ # ion-infinite-scroll-content +The Infinite Scroll allows you to perform an action when the user +scrolls a specified distance from the bottom or top of the page. + +The expression assigned to the `infinite` event is called when +the user scrolls to the specified distance. When this expression +has finished its tasks, it should call the `complete()` method +on the infinite scroll instance. + +```html + + + + {% raw %}{{i}}{% endraw %} + + + + + + + +``` + +```ts +@Component({...}) +export class NewsFeedPage { + items = []; + + constructor() { + for (let i = 0; i < 30; i++) { + this.items.push( this.items.length ); + } + } + + doInfinite(infiniteScroll) { + console.log('Begin async operation'); + + setTimeout(() => { + for (let i = 0; i < 30; i++) { + this.items.push( this.items.length ); + } + + console.log('Async operation has ended'); + infiniteScroll.complete(); + }, 500); + } + +} +``` + +## `waitFor` method of InfiniteScroll + +In case if your async operation returns promise you can utilize +`waitFor` method inside your template. + +```html + + + + {{item}} + + + + + + + +``` + +```ts +@Component({...}) +export class NewsFeedPage { + items = []; + + constructor() { + for (var i = 0; i < 30; i++) { + this.items.push( this.items.length ); + } + } + + doInfinite(): Promise { + console.log('Begin async operation'); + + return new Promise((resolve) => { + setTimeout(() => { + for (var i = 0; i < 30; i++) { + this.items.push( this.items.length ); + } + + console.log('Async operation has ended'); + resolve(); + }, 500); + }) + } +} +``` + +## Infinite Scroll Content + +By default, Ionic uses the infinite scroll spinner that looks +best for the platform the user is on. However, you can change the +default spinner or add text by adding properties to the +`ion-infinite-scroll-content` component. + + ```html + + + + + + + + + ``` + + +## Further Customizing Infinite Scroll Content + +The `ion-infinite-scroll` component holds the infinite scroll logic. +It requires a child component in order to display the content. +Ionic uses `ion-infinite-scroll-content` by default. This component +displays the infinite scroll and changes the look depending +on the infinite scroll's state. Separating these components allows +developers to create their own infinite scroll content components. +You could replace our default content with custom SVG or CSS animations. diff --git a/packages/core/src/components/note/note.tsx b/packages/core/src/components/note/note.tsx index da9f611892..951b348857 100644 --- a/packages/core/src/components/note/note.tsx +++ b/packages/core/src/components/note/note.tsx @@ -1,33 +1,6 @@ import { Component, Prop } from '@stencil/core'; -/** - * @name Note - * @module ionic - * @description - * A note is detailed item in an ion-item. It creates greyed out element that can be on - * the left or right side of an item. - * - * @usage - * - * ```html - * - * - * - * - * Left Note - * - * My Item - * - * Right Note - * - * - * - * - * ``` - * - * {@link /docs/api/components/api/components/item/item ion-item} - */ @Component({ tag: 'ion-note', styleUrls: { diff --git a/packages/core/src/components/note/readme.md b/packages/core/src/components/note/readme.md index 50ebfe1637..ff0c35fb64 100644 --- a/packages/core/src/components/note/readme.md +++ b/packages/core/src/components/note/readme.md @@ -1,5 +1,23 @@ # ion-note +A note is detailed item in an ion-item. It creates greyed out element that can be on +the left or right side of an item. + +```html + + + + + Left Note + + My Item + + Right Note + + + + +``` diff --git a/packages/core/src/components/router/route-link.tsx b/packages/core/src/components/router/route-link.tsx index 6b979690fd..ba1c7f3d53 100644 --- a/packages/core/src/components/router/route-link.tsx +++ b/packages/core/src/components/router/route-link.tsx @@ -1,10 +1,6 @@ import { Component, Prop } from '@stencil/core'; -/** - * @name Route - * @module ionic - * @description - */ + @Component({ tag: 'ion-route-link' }) diff --git a/packages/core/src/components/router/route.tsx b/packages/core/src/components/router/route.tsx index 5d31705633..3c9b2bd145 100644 --- a/packages/core/src/components/router/route.tsx +++ b/packages/core/src/components/router/route.tsx @@ -1,11 +1,7 @@ import { Component, Event, EventEmitter, Prop } from '@stencil/core'; import { RouterEntry, parseURL } from './router-utils'; -/** - * @name Route - * @module ionic - * @description - */ + @Component({ tag: 'ion-route' }) diff --git a/packages/core/src/components/searchbar/readme.md b/packages/core/src/components/searchbar/readme.md index aa196dff5e..05bb2a4d22 100644 --- a/packages/core/src/components/searchbar/readme.md +++ b/packages/core/src/components/searchbar/readme.md @@ -1,6 +1,15 @@ # ion-searchbar +Manages the display of a Searchbar which can be used to search or filter items. +```html + + +``` diff --git a/packages/core/src/components/searchbar/searchbar.tsx b/packages/core/src/components/searchbar/searchbar.tsx index bfc05b6fb3..b01c87d5f2 100644 --- a/packages/core/src/components/searchbar/searchbar.tsx +++ b/packages/core/src/components/searchbar/searchbar.tsx @@ -1,25 +1,6 @@ import { Component, Element, Event, EventEmitter, Prop, State } from '@stencil/core'; -/** - * @name Searchbar - * @module ionic - * @description - * Manages the display of a Searchbar which can be used to search or filter items. - * - * @usage - * ```html - * - * - * ``` - * - * @demo /docs/demos/src/searchbar/ - * @see {@link /docs/components#searchbar Searchbar Component Docs} - */ @Component({ tag: 'ion-searchbar', styleUrls: { diff --git a/packages/core/src/components/segment-button/readme.md b/packages/core/src/components/segment-button/readme.md index 0d3b6f67b9..a1a28d6c1f 100644 --- a/packages/core/src/components/segment-button/readme.md +++ b/packages/core/src/components/segment-button/readme.md @@ -1,6 +1,30 @@ # ion-segment-button +The child buttons of the `ion-segment` component. Each `ion-segment-button` must have a value. +```html + + + + + + + + + + + + + + + Friends + + + Enemies + + + +``` diff --git a/packages/core/src/components/segment-button/segment-button.tsx b/packages/core/src/components/segment-button/segment-button.tsx index 5ec36f484d..efc145bd07 100644 --- a/packages/core/src/components/segment-button/segment-button.tsx +++ b/packages/core/src/components/segment-button/segment-button.tsx @@ -1,45 +1,8 @@ import { Component, Element, Event, EventEmitter, Prop, State } from '@stencil/core'; - import { CssClassMap } from '../../index'; import { createThemedClasses, getElementClassObject } from '../../utils/theme'; -/** - * @name SegmentButton - * @description - * The child buttons of the `ion-segment` component. Each `ion-segment-button` must have a value. - * - * @usage - * - * ```html - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * Friends - * - * - * Enemies - * - * - * - * ``` - * - * - * @demo /docs/demos/src/segment/ - * @see {@link /docs/components#segment Segment Component Docs} - * @see {@link /docs/api/components/segment/Segment/ Segment API Docs} - */ @Component({ tag: 'ion-segment-button' }) diff --git a/packages/core/src/components/segment/readme.md b/packages/core/src/components/segment/readme.md index df77be4afa..122613ef99 100644 --- a/packages/core/src/components/segment/readme.md +++ b/packages/core/src/components/segment/readme.md @@ -1,5 +1,52 @@ # ion-segment +A Segment is a group of buttons, sometimes known as Segmented Controls, that allow the user to interact with a compact group of a number of controls. + +Segments provide functionality similar to tabs, selecting one will unselect all others. You should use a tab bar instead of a segmented control when you want to let the user move back and forth between distinct pages in your app. + + +```html + + + + + + + + + + + + + + + + + + + Friends + + + Enemies + + + + +
+ + + Standard + + + Hybrid + + + Satellite + + +
+ +``` diff --git a/packages/core/src/components/segment/segment.tsx b/packages/core/src/components/segment/segment.tsx index 260e43b355..1118ede375 100644 --- a/packages/core/src/components/segment/segment.tsx +++ b/packages/core/src/components/segment/segment.tsx @@ -1,64 +1,6 @@ import { Component, Element, Event, EventEmitter, Listen, Prop, PropDidChange } from '@stencil/core'; -import { SegmentButtonEvent } from '../../index'; - -/** - * @name Segment - * @description - * A Segment is a group of buttons, sometimes known as Segmented Controls, that allow the user to interact with a compact group of a number of controls. - * Segments provide functionality similar to tabs, selecting one will unselect all others. You should use a tab bar instead of a segmented control when you want to let the user move back and forth between distinct pages in your app. - * You could use Angular's `ngModel` or `FormBuilder` API. For an overview on how `FormBuilder` works, checkout [Angular Forms](http://learnangular2.com/forms/), or [Angular FormBuilder](https://angular.io/docs/ts/latest/api/forms/index/FormBuilder-class.html) - * - * - * ```html - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * Friends - * - * - * Enemies - * - * - * - * - *
- * - * - * Standard - * - * - * Hybrid - * - * - * Satellite - * - * - *
- * - * ``` - * - * - * @demo /docs/demos/src/segment/ - * @see {@link /docs/components#segment Segment Component Docs} - * @see [Angular Forms](http://learnangular2.com/forms/) - */ @Component({ tag: 'ion-segment', styleUrls: { diff --git a/packages/core/src/components/spinner/readme.md b/packages/core/src/components/spinner/readme.md index d819303746..dde8b5bb8f 100644 --- a/packages/core/src/components/spinner/readme.md +++ b/packages/core/src/components/spinner/readme.md @@ -1,5 +1,93 @@ # ion-spinner +The `ion-spinner` component provides a variety of animated SVG spinners. +Spinners enables you to give users feedback that the app is actively +processing/thinking/waiting/chillin’ out, or whatever you’d like it to indicate. +By default, the `ion-refresher` feature uses this spinner component while it's +the refresher is in the `refreshing` state. + +Ionic offers a handful of spinners out of the box, and by default, it will use +the appropriate spinner for the platform on which it’s running. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The following code would use the default spinner for the platform it's +running from. If it's neither iOS or Android, it'll default to use `ios`. + +```html + +``` + +By setting the `name` property, you can specify which predefined spinner to +use, no matter what the platform is. + +```html + +``` + +## Styling SVG with CSS +One cool thing about SVG is its ability to be styled with CSS! One thing to note +is that some of the CSS properties on an SVG element have different names. For +example, SVG uses the term `stroke` instead of `border`, and `fill` instead +of `background-color`. + +```css +ion-spinner{ + width: 28px; + height: 28px; + stroke: #444; + fill: #222; +} +``` diff --git a/packages/core/src/components/spinner/spinner.tsx b/packages/core/src/components/spinner/spinner.tsx index 260574551c..af95501951 100644 --- a/packages/core/src/components/spinner/spinner.tsx +++ b/packages/core/src/components/spinner/spinner.tsx @@ -4,99 +4,6 @@ import { Config } from '../../index'; import { SPINNERS, SpinnerConfig } from './spinner-configs'; -/** - * @name Spinner - * @description - * The `ion-spinner` component provides a variety of animated SVG spinners. - * Spinners enables you to give users feedback that the app is actively - * processing/thinking/waiting/chillin’ out, or whatever you’d like it to indicate. - * By default, the `ion-refresher` feature uses this spinner component while it's - * the refresher is in the `refreshing` state. - * - * Ionic offers a handful of spinners out of the box, and by default, it will use - * the appropriate spinner for the platform on which it’s running. - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * @usage - * The following code would use the default spinner for the platform it's - * running from. If it's neither iOS or Android, it'll default to use `ios`. - * - * ```html - * - * ``` - * - * By setting the `name` property, you can specify which predefined spinner to - * use, no matter what the platform is. - * - * ```html - * - * ``` - * - * ## Styling SVG with CSS - * One cool thing about SVG is its ability to be styled with CSS! One thing to note - * is that some of the CSS properties on an SVG element have different names. For - * example, SVG uses the term `stroke` instead of `border`, and `fill` instead - * of `background-color`. - * - * ```css - * ion-spinner * { - * width: 28px; - * height: 28px; - * stroke: #444; - * fill: #222; - * } - * ``` - */ @Component({ tag: 'ion-spinner', styleUrls: { diff --git a/packages/core/src/components/title/readme.md b/packages/core/src/components/title/readme.md index 19c0581ff9..2d4ffdfac0 100644 --- a/packages/core/src/components/title/readme.md +++ b/packages/core/src/components/title/readme.md @@ -1,5 +1,16 @@ # ion-title +`ion-title` is a component that sets the title of the `Toolbar`. + +```html + + + + Settings + + + +``` diff --git a/packages/core/src/components/title/title.tsx b/packages/core/src/components/title/title.tsx index b32cfb0ae2..3f3c9ee86e 100644 --- a/packages/core/src/components/title/title.tsx +++ b/packages/core/src/components/title/title.tsx @@ -2,41 +2,6 @@ import { Component } from '@stencil/core'; import { createThemedClasses } from '../../utils/theme'; -/** - * @name Title - * @description - * `ion-title` is a component that sets the title of the `Toolbar` or `Navbar`. - * - * @usage - * - * ```html - * - * - * - * Settings - * - * - * - * ``` - * - * Or to create a navbar with a toolbar as a subheader: - * - * ```html - * - * - * - * Main Header - * - * - * - * Subheader - * - * - * - * ``` - * - * @demo /docs/demos/src/title/ - */ @Component({ tag: 'ion-title', styleUrls: { diff --git a/packages/core/src/components/toolbar/readme.md b/packages/core/src/components/toolbar/readme.md index 8dea652414..1eb91d4945 100644 --- a/packages/core/src/components/toolbar/readme.md +++ b/packages/core/src/components/toolbar/readme.md @@ -1,5 +1,85 @@ # ion-navbar +A Toolbar is a generic bar that is positioned above or below content. +Unlike a [Navbar](../../navbar/Navbar), a toolbar can be used as a subheader. +When toolbars are placed within an `` or ``, +the toolbars stay fixed in their respective location. When placed within +``, toolbars will scroll with the content. + + +### Buttons in a Toolbar +Buttons placed in a toolbar should be placed inside of the `` +element. An exception to this is a [menuToggle](../../menu/MenuToggle) button. +It should not be placed inside of the `` element. Both the +`` element and the `menuToggle` can be positioned inside of the +toolbar using different properties. The below chart has a description of each +property. + +| Property | Description | +|-------------|-----------------------------------------------------------------------------------------------------------------------| +| `start` | Positions element to the left of the content in `ios` mode, and directly to the right in `md` mode. | +| `end` | Positions element to the right of the content in `ios` mode, and to the far right in `md` mode. | +| `left` | Positions element to the left of all other elements. | +| `right` | Positions element to the right of all other elements. | + + +### Header / Footer Box Shadow and Border +In `md` mode, the `` will receive a box-shadow on the bottom, and the +`` will receive a box-shadow on the top. In `ios` mode, the `` +will receive a border on the bottom, and the `` will receive a border on the +top. Both the `md` box-shadow and the `ios` border can be removed by adding the `no-border` +attribute to the element. + +```html + + + Header + + + + + ... + + + + + Footer + + +``` + +```html + + + + + My Toolbar Title + + + + I'm a subheader + + + + + + + + + Scrolls with the content + + + + + + + + + I'm a footer + + + + ``` diff --git a/packages/core/src/components/toolbar/toolbar.tsx b/packages/core/src/components/toolbar/toolbar.tsx index 905c0e80ad..b9e254a3ae 100644 --- a/packages/core/src/components/toolbar/toolbar.tsx +++ b/packages/core/src/components/toolbar/toolbar.tsx @@ -2,94 +2,7 @@ import { Component, Element, Prop } from '@stencil/core'; import { createThemedClasses } from '../../utils/theme'; import { Config } from '../../index'; -/** - * @name Toolbar - * @description - * A Toolbar is a generic bar that is positioned above or below content. - * Unlike a [Navbar](../../navbar/Navbar), a toolbar can be used as a subheader. - * When toolbars are placed within an `` or ``, - * the toolbars stay fixed in their respective location. When placed within - * ``, toolbars will scroll with the content. - * - * - * ### Buttons in a Toolbar - * Buttons placed in a toolbar should be placed inside of the `` - * element. An exception to this is a [menuToggle](../../menu/MenuToggle) button. - * It should not be placed inside of the `` element. Both the - * `` element and the `menuToggle` can be positioned inside of the - * toolbar using different properties. The below chart has a description of each - * property. - * - * | Property | Description | - * |-------------|-----------------------------------------------------------------------------------------------------------------------| - * | `start` | Positions element to the left of the content in `ios` mode, and directly to the right in `md` mode. | - * | `end` | Positions element to the right of the content in `ios` mode, and to the far right in `md` mode. | - * | `left` | Positions element to the left of all other elements. | - * | `right` | Positions element to the right of all other elements. | - * - * - * ### Header / Footer Box Shadow and Border - * In `md` mode, the `` will receive a box-shadow on the bottom, and the - * `` will receive a box-shadow on the top. In `ios` mode, the `` - * will receive a border on the bottom, and the `` will receive a border on the - * top. Both the `md` box-shadow and the `ios` border can be removed by adding the `no-border` - * attribute to the element. - * - * ```html - * - * - * Header - * - * - * - * - * - * - * - * - * Footer - * - * - * ``` - * - * @usage - * - * ```html - * - * - * - * - * My Toolbar Title - * - * - * - * I'm a subheader - * - * - * - * - * - * - * - * - * Scrolls with the content - * - * - * - * - * - * - * - * - * I'm a footer - * - * - * - * ``` - * - * @demo /docs/demos/src/toolbar/ - * @see {@link ../../navbar/Navbar/ Navbar API Docs} - */ + @Component({ tag: 'ion-toolbar', styleUrls: {