javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-23 14:01:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): move jsdoc descriptions to readme.md

Browse Source
This commit is contained in:
Adam Bradley
2017-11-21 21:16:49 -06:00
parent f7c1d04d34
commit 2e83084867
31 changed files with 832 additions and 1003 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.github/CONTRIBUTING.md vendored
View File

@ -70,21 +70,7 @@ Please see our [Contributor Code of Conduct](https://github.com/ionic-team/ionic
#### Adding Documentation #### 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: 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.
```
/**
* @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.
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 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. 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 4. If the change affects the component documentation, create an issue on the `ionic-site` repo: https://github.com/ionic-team/ionic-site/issues

8
packages/core/src/components/avatar/avatar.tsx
View File

@ -1,14 +1,6 @@
import { Component } from '@stencil/core'; 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({ @Component({
tag: 'ion-avatar', tag: 'ion-avatar',
styleUrls: { styleUrls: {

2
packages/core/src/components/avatar/readme.md
View File

@ -1,5 +1,7 @@
# ion-avatar # 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.
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

28
packages/core/src/components/badge/badge.tsx
View File

@ -1,32 +1,6 @@
import { Component, Prop } from '@stencil/core'; 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
* <ion-content>
* <ion-list>
* <ion-item>
* <ion-badge slot="start">
* 34
* </ion-badge>
* My Item
* <ion-badge slot="end">
* 2
* </ion-badge>
* </ion-item>
* </ion-list>
* </ion-content>
* ```
*
* @see {@link /docs/components/#badges Badges Component Docs}
*/
@Component({ @Component({
tag: 'ion-badge', tag: 'ion-badge',
styleUrls: { styleUrls: {

18
packages/core/src/components/badge/readme.md
View File

@ -1,5 +1,23 @@
# ion-badge # 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
<ion-content>
<ion-list>
<ion-item>
<ion-badge slot="start">
34
</ion-badge>
My Item
<ion-badge slot="end">
2
</ion-badge>
</ion-item>
</ion-list>
</ion-content>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

62
packages/core/src/components/button/button.tsx
View File

@ -1,67 +1,7 @@
import { Component, CssClassMap, Element, Prop } from '@stencil/core'; import { Component, CssClassMap, Element, Prop } from '@stencil/core';
import { getElementClassObject } from '../../utils/theme'; 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
*
* <!-- Colors -->
* <ion-button>Default</ion-button>
*
* <ion-button color="secondary">Secondary</ion-button>
*
* <ion-button color="danger">Danger</ion-button>
*
* <ion-button color="light">Light</ion-button>
*
* <ion-button color="dark">Dark</ion-button>
*
* <!-- Shapes -->
* <ion-button full>Full Button</ion-button>
*
* <ion-button block>Block Button</ion-button>
*
* <ion-button round>Round Button</ion-button>
*
* <!-- Outline -->
* <ion-button full outline>Outline + Full</ion-button>
*
* <ion-button block outline>Outline + Block</ion-button>
*
* <ion-button round outline>Outline + Round</ion-button>
*
* <!-- Icons -->
* <ion-button>
* <ion-icon slot="start" name="star"></ion-icon>
* Left Icon
* </ion-button>
*
* <ion-button>
* Right Icon
* <ion-icon slot="end" name="star"></ion-icon>
* </ion-button>
*
* <ion-button>
* <ion-icon slot="icon-only" name="star"></ion-icon>
* </ion-button>
*
* <!-- Sizes -->
* <ion-button large>Large</ion-button>
*
* <ion-button>Default</ion-button>
*
* <ion-button small>Small</ion-button>
* ```
*
*/
@Component({ @Component({
tag: 'ion-button', tag: 'ion-button',
styleUrls: { styleUrls: {

52
packages/core/src/components/button/readme.md
View File

@ -1,5 +1,57 @@
# ion-button # 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
<!-- Colors -->
<ion-button>Default</ion-button>
<ion-button color="secondary">Secondary</ion-button>
<ion-button color="danger">Danger</ion-button>
<ion-button color="light">Light</ion-button>
<ion-button color="dark">Dark</ion-button>
<!-- Shapes -->
<ion-button full>Full Button</ion-button>
<ion-button block>Block Button</ion-button>
<ion-button round>Round Button</ion-button>
<!-- Outline -->
<ion-button full outline>Outline + Full</ion-button>
<ion-button block outline>Outline + Block</ion-button>
<ion-button round outline>Outline + Round</ion-button>
<!-- Icons -->
<ion-button>
<ion-icon slot="start" name="star"></ion-icon>
Left Icon
</ion-button>
<ion-button>
Right Icon
<ion-icon slot="end" name="star"></ion-icon>
</ion-button>
<ion-button>
<ion-icon slot="icon-only" name="star"></ion-icon>
</ion-button>
<!-- Sizes -->
<ion-button large>Large</ion-button>
<ion-button>Default</ion-button>
<ion-button small>Small</ion-button>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

66
packages/core/src/components/checkbox/checkbox.tsx
View File

@ -1,71 +1,7 @@
import { BlurEvent, CheckboxInput, CheckedInputChangeEvent, FocusEvent, StyleEvent } from '../../utils/input-interfaces'; import { BlurEvent, CheckboxInput, CheckedInputChangeEvent, FocusEvent, StyleEvent } from '../../utils/input-interfaces';
import { Component, CssClassMap, Event, EventEmitter, Listen, Prop, PropDidChange } from '@stencil/core'; 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
*
* <ion-list>
*
* <ion-item>
* <ion-label>Pepperoni</ion-label>
* <ion-checkbox [(ngModel)]="pepperoni"></ion-checkbox>
* </ion-item>
*
* <ion-item>
* <ion-label>Sausage</ion-label>
* <ion-checkbox [(ngModel)]="sausage" disabled="true"></ion-checkbox>
* </ion-item>
*
* <ion-item>
* <ion-label>Mushrooms</ion-label>
* <ion-checkbox [(ngModel)]="mushrooms"></ion-checkbox>
* </ion-item>
*
* </ion-list>
* ```
*
* @advanced
*
* ```html
*
* <!-- Call function when state changes -->
* <ion-list>
*
* <ion-item>
* <ion-label>Cucumber</ion-label>
* <ion-checkbox [(ngModel)]="cucumber" (ionChange)="updateCucumber()"></ion-checkbox>
* </ion-item>
*
* </ion-list>
* ```
*
* ```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({ @Component({
tag: 'ion-checkbox', tag: 'ion-checkbox',
styleUrls: { styleUrls: {

53
packages/core/src/components/checkbox/readme.md
View File

@ -1,6 +1,59 @@
# ion-checkbox # ion-checkbox
Placed in an `ion-item` or used as a stand-alone checkbox.
```html
<ion-list>
<ion-item>
<ion-label>Pepperoni</ion-label>
<ion-checkbox [(ngModel)]="pepperoni"></ion-checkbox>
</ion-item>
<ion-item>
<ion-label>Sausage</ion-label>
<ion-checkbox [(ngModel)]="sausage" disabled="true"></ion-checkbox>
</ion-item>
<ion-item>
<ion-label>Mushrooms</ion-label>
<ion-checkbox [(ngModel)]="mushrooms"></ion-checkbox>
</ion-item>
</ion-list>
```
@advanced
```html
<!-- Call function when state changes -->
<ion-list>
<ion-item>
<ion-label>Cucumber</ion-label>
<ion-checkbox [(ngModel)]="cucumber" (ionChange)="updateCucumber()"></ion-checkbox>
</ion-item>
</ion-list>
```
```ts
@Component({
templateUrl: 'main.html'
})
class SaladPage {
cucumber: boolean;
updateCucumber() {
console.log('Cucumbers new state:' + this.cucumber);
}
}
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

88
packages/core/src/components/chip/chip.tsx
View File

@ -1,92 +1,6 @@
import { Component, Prop } from '@stencil/core'; import { Component, Prop } from '@stencil/core';
/**
* @name Chip
* @module ionic
* @description
* Chips represent complex entities in small blocks, such as a contact.
*
*
* @usage
*
* ```html
* <ion-chip>
* <ion-label>Default</ion-label>
* </ion-chip>
*
* <ion-chip>
* <ion-label color="secondary">Secondary Label</ion-label>
* </ion-chip>
*
* <ion-chip color="secondary">
* <ion-label color="dark">Secondary w/ Dark label</ion-label>
* </ion-chip>
*
* <ion-chip color="danger">
* <ion-label>Danger</ion-label>
* </ion-chip>
*
* <ion-chip>
* <ion-icon name="pin"></ion-icon>
* <ion-label>Default</ion-label>
* </ion-chip>
*
* <ion-chip>
* <ion-icon name="heart" color="dark"></ion-icon>
* <ion-label>Default</ion-label>
* </ion-chip>
*
* <ion-chip>
* <ion-avatar>
* <img src="assets/img/my-img.png">
* </ion-avatar>
* <ion-label>Default</ion-label>
* </ion-chip>
* ```
*
*
* @advanced
*
* ```html
* <ion-chip #chip1>
* <ion-label>Default</ion-label>
* <ion-button clear color="light" (click)="delete(chip1)">
* <ion-icon name="close-circle"></ion-icon>
* </ion-button>
* </ion-chip>
*
* <ion-chip #chip2>
* <ion-icon name="pin" color="primary"></ion-icon>
* <ion-label>With Icon</ion-label>
* <ion-button (click)="delete(chip2)">
* <ion-icon name="close"></ion-icon>
* </ion-button>
* </ion-chip>
*
* <ion-chip #chip3>
* <ion-avatar>
* <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
* </ion-avatar>
* <ion-label>With Avatar</ion-label>
* <ion-button clear color="dark" (click)="delete(chip3)">
* <ion-icon name="close-circle"></ion-icon>
* </ion-button>
* </ion-chip>
* ```
*
* ```ts
* @Component({
* templateUrl: 'main.html'
* })
* class E2EPage {
* delete(chip: Element) {
* chip.remove();
* }
* }
* ```
*
* @demo /docs/demos/src/chip/
**/
@Component({ @Component({
tag: 'ion-chip', tag: 'ion-chip',
styleUrls: { styleUrls: {

65
packages/core/src/components/chip/readme.md
View File

@ -1,5 +1,70 @@
# ion-chip # ion-chip
Chips represent complex entities in small blocks, such as a contact.
```html
<ion-chip>
<ion-label>Default</ion-label>
</ion-chip>
<ion-chip>
<ion-label color="secondary">Secondary Label</ion-label>
</ion-chip>
<ion-chip color="secondary">
<ion-label color="dark">Secondary w/ Dark label</ion-label>
</ion-chip>
<ion-chip color="danger">
<ion-label>Danger</ion-label>
</ion-chip>
<ion-chip>
<ion-icon name="pin"></ion-icon>
<ion-label>Default</ion-label>
</ion-chip>
<ion-chip>
<ion-icon name="heart" color="dark"></ion-icon>
<ion-label>Default</ion-label>
</ion-chip>
<ion-chip>
<ion-avatar>
<img src="assets/img/my-img.png">
</ion-avatar>
<ion-label>Default</ion-label>
</ion-chip>
```
```html
<ion-chip #chip1>
<ion-label>Default</ion-label>
<ion-button clear color="light" (click)="delete(chip1)">
<ion-icon name="close-circle"></ion-icon>
</ion-button>
</ion-chip>
<ion-chip #chip2>
<ion-icon name="pin" color="primary"></ion-icon>
<ion-label>With Icon</ion-label>
<ion-button (click)="delete(chip2)">
<ion-icon name="close"></ion-icon>
</ion-button>
</ion-chip>
<ion-chip #chip3>
<ion-avatar>
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAAAAACH5BAAAAAAALAAAAAABAAEAAAICTAEAOw==">
</ion-avatar>
<ion-label>With Avatar</ion-label>
<ion-button clear color="dark" (click)="delete(chip3)">
<ion-icon name="close-circle"></ion-icon>
</ion-button>
</ion-chip>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

240
packages/core/src/components/datetime/datetime.tsx
View File

@ -17,248 +17,10 @@ import {
renderTextFormat, renderTextFormat,
updateDate updateDate
} from './datetime-util'; } from './datetime-util';
import { clamp, isBlank, isObject } from '../../utils/helpers'; import { clamp, isBlank, isObject } from '../../utils/helpers';
import { Picker, PickerColumn, PickerController, PickerOptions } from '../../index'; 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 `<ion-datetime>` 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
* `<input type="datetime-local">` 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
* <ion-item>
* <ion-label>Date</ion-label>
* <ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate"></ion-datetime>
* </ion-item>
* ```
*
*
* ## Display and Picker Formats
*
* The Datetime component displays the values in two places: in the `<ion-datetime>`
* 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 `<ion-datetime>` 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
* <ion-item>
* <ion-label>Date</ion-label>
* <ion-datetime displayFormat="MMM DD, YYYY HH:mm" [(ngModel)]="myDate"></ion-datetime>
* </ion-item>
* ```
*
* ### 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 `<ion-datetime>` 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
* <ion-item>
* <ion-label>Date</ion-label>
* <ion-datetime displayFormat="MM/YYYY" pickerFormat="MMMM YYYY" [(ngModel)]="myDate"></ion-datetime>
* </ion-item>
* ```
*
* ### 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
* <ion-item>
* <ion-label>Date</ion-label>
* <ion-datetime displayFormat="MMMM YYYY" min="2016" max="2020-10-31" [(ngModel)]="myDate">
* </ion-datetime>
* </ion-item>
* ```
*
*
* ## 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
* <ion-item>
* <ion-label>Período</ion-label>
* <ion-datetime displayFormat="DDDD MMM D, YYYY" [(ngModel)]="myDate"
* monthNames="janeiro, fevereiro, mar\u00e7o, ..."
* monthShortNames="jan, fev, mar, ..."
* dayNames="domingo, segunda-feira, ter\u00e7a-feira, ..."
* dayShortNames="dom, seg, ter, ..."></ion-datetime>
* </ion-item>
* ```
*
*
* ### 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
* <ion-item>
* <ion-label>Date</ion-label>
* <ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate">
* </ion-datetime>
* </ion-item>
* ```
*
*
* @demo /docs/demos/src/datetime/
*/
@Component({ @Component({
tag: 'ion-datetime', tag: 'ion-datetime',
styleUrls: { styleUrls: {

229
packages/core/src/components/datetime/readme.md
View File

@ -1,5 +1,234 @@
# ion-datetime # ion-datetime
The Datetime component is used to present an interface which makes it easy for
users to select dates and times. Tapping on `<ion-datetime>` 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
`<input type="datetime-local">` 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
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate"></ion-datetime>
</ion-item>
```
## Display and Picker Formats
The Datetime component displays the values in two places: in the `<ion-datetime>`
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 `<ion-datetime>` 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
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MMM DD, YYYY HH:mm" [(ngModel)]="myDate"></ion-datetime>
</ion-item>
```
### 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 `<ion-datetime>` 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
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/YYYY" pickerFormat="MMMM YYYY" [(ngModel)]="myDate"></ion-datetime>
</ion-item>
```
### 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
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MMMM YYYY" min="2016" max="2020-10-31" [(ngModel)]="myDate">
</ion-datetime>
</ion-item>
```
## 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
<ion-item>
<ion-label>Período</ion-label>
<ion-datetime displayFormat="DDDD MMM D, YYYY" [(ngModel)]="myDate"
monthNames="janeiro, fevereiro, mar\u00e7o, ..."
monthShortNames="jan, fev, mar, ..."
dayNames="domingo, segunda-feira, ter\u00e7a-feira, ..."
dayShortNames="dom, seg, ter, ..."></ion-datetime>
</ion-item>
```
### 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
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate">
</ion-datetime>
</ion-item>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

135
packages/core/src/components/infinite-scroll/infinite-scroll.tsx
View File

@ -6,140 +6,7 @@ const enum Position {
Bottom = 'bottom', 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
* <ion-content>
*
* <ion-list>
* <ion-item *ngFor="let i of items">{% raw %}{{i}}{% endraw %}</ion-item>
* </ion-list>
*
* <ion-infinite-scroll (ionInfinite)="doInfinite($event)">
* <ion-infinite-scroll-content></ion-infinite-scroll-content>
* </ion-infinite-scroll>
*
* </ion-content>
* ```
*
* ```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
* <ion-content>
*
* <ion-list>
* <ion-item *ngFor="let item of items">{{item}}</ion-item>
* </ion-list>
*
* <ion-infinite-scroll (ionInfinite)="$event.waitFor(doInfinite())">
* <ion-infinite-scroll-content></ion-infinite-scroll-content>
* </ion-infinite-scroll>
*
* </ion-content>
* ```
*
* ```ts
* @Component({...})
* export class NewsFeedPage {
* items = [];
*
* constructor() {
* for (var i = 0; i < 30; i++) {
* this.items.push( this.items.length );
* }
* }
*
* doInfinite(): Promise<any> {
* 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
* <ion-content>
*
* <ion-infinite-scroll (ionInfinite)="doInfinite($event)">
* <ion-infinite-scroll-content
* loadingSpinner="bubbles"
* loadingText="Loading more data...">
* </ion-infinite-scroll-content>
* </ion-infinite-scroll>
*
* </ion-content>
* ```
*
*
* ## 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({ @Component({
tag: 'ion-infinite-scroll', tag: 'ion-infinite-scroll',
styleUrl: 'infinite-scroll.scss' styleUrl: 'infinite-scroll.scss'

126
packages/core/src/components/infinite-scroll/readme.md
View File

@ -1,5 +1,131 @@
# ion-infinite-scroll-content # 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
<ion-content>
<ion-list>
<ion-itemngFor="let i of items">{% raw %}{{i}}{% endraw %}</ion-item>
</ion-list>
<ion-infinite-scroll (ionInfinite)="doInfinite($event)">
<ion-infinite-scroll-content></ion-infinite-scroll-content>
</ion-infinite-scroll>
</ion-content>
```
```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
<ion-content>
<ion-list>
<ion-itemngFor="let item of items">{{item}}</ion-item>
</ion-list>
<ion-infinite-scroll (ionInfinite)="$event.waitFor(doInfinite())">
<ion-infinite-scroll-content></ion-infinite-scroll-content>
</ion-infinite-scroll>
</ion-content>
```
```ts
@Component({...})
export class NewsFeedPage {
items = [];
constructor() {
for (var i = 0; i < 30; i++) {
this.items.push( this.items.length );
}
}
doInfinite(): Promise<any> {
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
<ion-content>
<ion-infinite-scroll (ionInfinite)="doInfinite($event)">
<ion-infinite-scroll-content
loadingSpinner="bubbles"
loadingText="Loading more data...">
</ion-infinite-scroll-content>
</ion-infinite-scroll>
</ion-content>
```
## 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.
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

27
packages/core/src/components/note/note.tsx
View File

@ -1,33 +1,6 @@
import { Component, Prop } from '@stencil/core'; 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
* <ion-content>
* <ion-list>
* <ion-item>
* <ion-note slot="start">
* Left Note
* </ion-note>
* My Item
* <ion-note slot="end">
* Right Note
* </ion-note>
* </ion-item>
* </ion-list>
* </ion-content>
* ```
*
* {@link /docs/api/components/api/components/item/item ion-item}
*/
@Component({ @Component({
tag: 'ion-note', tag: 'ion-note',
styleUrls: { styleUrls: {

18
packages/core/src/components/note/readme.md
View File

@ -1,5 +1,23 @@
# ion-note # 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
<ion-content>
<ion-list>
<ion-item>
<ion-note slot="start">
Left Note
</ion-note>
My Item
<ion-note slot="end">
Right Note
</ion-note>
</ion-item>
</ion-list>
</ion-content>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

6
packages/core/src/components/router/route-link.tsx
View File

@ -1,10 +1,6 @@
import { Component, Prop } from '@stencil/core'; import { Component, Prop } from '@stencil/core';
/**
* @name Route
* @module ionic
* @description
*/
@Component({ @Component({
tag: 'ion-route-link' tag: 'ion-route-link'
}) })

6
packages/core/src/components/router/route.tsx
View File

@ -1,11 +1,7 @@
import { Component, Event, EventEmitter, Prop } from '@stencil/core'; import { Component, Event, EventEmitter, Prop } from '@stencil/core';
import { RouterEntry, parseURL } from './router-utils'; import { RouterEntry, parseURL } from './router-utils';
/**
* @name Route
* @module ionic
* @description
*/
@Component({ @Component({
tag: 'ion-route' tag: 'ion-route'
}) })

9
packages/core/src/components/searchbar/readme.md
View File

@ -1,6 +1,15 @@
# ion-searchbar # ion-searchbar
Manages the display of a Searchbar which can be used to search or filter items.
```html
<ion-searchbar
[(ngModel)]="myInput"
[showCancelButton]="shouldShowCancel"
(ionInput)="onInput($event)"
(ionCancel)="onCancel($event)">
</ion-searchbar>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

19
packages/core/src/components/searchbar/searchbar.tsx
View File

@ -1,25 +1,6 @@
import { Component, Element, Event, EventEmitter, Prop, State } from '@stencil/core'; 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
* <ion-searchbar
* [(ngModel)]="myInput"
* [showCancelButton]="shouldShowCancel"
* (ionInput)="onInput($event)"
* (ionCancel)="onCancel($event)">
* </ion-searchbar>
* ```
*
* @demo /docs/demos/src/searchbar/
* @see {@link /docs/components#searchbar Searchbar Component Docs}
*/
@Component({ @Component({
tag: 'ion-searchbar', tag: 'ion-searchbar',
styleUrls: { styleUrls: {

24
packages/core/src/components/segment-button/readme.md
View File

@ -1,6 +1,30 @@
# ion-segment-button # ion-segment-button
The child buttons of the `ion-segment` component. Each `ion-segment-button` must have a value.
```html
<ion-content>
<!-- Segment buttons with icons -->
<ion-segment [(ngModel)]="icons" color="secondary">
<ion-segment-button value="camera">
<ion-icon name="camera"></ion-icon>
</ion-segment-button>
<ion-segment-button value="bookmark">
<ion-icon name="bookmark"></ion-icon>
</ion-segment-button>
</ion-segment>
<!-- Segment buttons with text -->
<ion-segment [(ngModel)]="relationship" color="primary">
<ion-segment-button value="friends" (ionSelect)="selectedFriends()">
Friends
</ion-segment-button>
<ion-segment-button value="enemies" (ionSelect)="selectedEnemies()">
Enemies
</ion-segment-button>
</ion-segment>
</ion-content>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

37
packages/core/src/components/segment-button/segment-button.tsx
View File

@ -1,45 +1,8 @@
import { Component, Element, Event, EventEmitter, Prop, State } from '@stencil/core'; import { Component, Element, Event, EventEmitter, Prop, State } from '@stencil/core';
import { CssClassMap } from '../../index'; import { CssClassMap } from '../../index';
import { createThemedClasses, getElementClassObject } from '../../utils/theme'; 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
* <ion-content>
* <!-- Segment buttons with icons -->
* <ion-segment [(ngModel)]="icons" color="secondary">
* <ion-segment-button value="camera">
* <ion-icon name="camera"></ion-icon>
* </ion-segment-button>
* <ion-segment-button value="bookmark">
* <ion-icon name="bookmark"></ion-icon>
* </ion-segment-button>
* </ion-segment>
*
* <!-- Segment buttons with text -->
* <ion-segment [(ngModel)]="relationship" color="primary">
* <ion-segment-button value="friends" (ionSelect)="selectedFriends()">
* Friends
* </ion-segment-button>
* <ion-segment-button value="enemies" (ionSelect)="selectedEnemies()">
* Enemies
* </ion-segment-button>
* </ion-segment>
* </ion-content>
* ```
*
*
* @demo /docs/demos/src/segment/
* @see {@link /docs/components#segment Segment Component Docs}
* @see {@link /docs/api/components/segment/Segment/ Segment API Docs}
*/
@Component({ @Component({
tag: 'ion-segment-button' tag: 'ion-segment-button'
}) })

47
packages/core/src/components/segment/readme.md
View File

@ -1,5 +1,52 @@
# ion-segment # 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
<!-- Segment in a header -->
<ion-header>
<ion-toolbar>
<ion-segment [(ngModel)]="icons" color="secondary">
<ion-segment-button value="camera">
<ion-icon name="camera"></ion-icon>
</ion-segment-button>
<ion-segment-button value="bookmark">
<ion-icon name="bookmark"></ion-icon>
</ion-segment-button>
</ion-segment>
</ion-toolbar>
</ion-header>
<ion-content>
<!-- Segment in content -->
<ion-segment [(ngModel)]="relationship" color="primary" (ionChange)="segmentChanged($event)">
<ion-segment-button value="friends">
Friends
</ion-segment-button>
<ion-segment-button value="enemies">
Enemies
</ion-segment-button>
</ion-segment>
<!-- Segment in a form -->
<form [formGroup]="myForm">
<ion-segment formControlName="mapStyle" color="danger">
<ion-segment-button value="standard">
Standard
</ion-segment-button>
<ion-segment-button value="hybrid">
Hybrid
</ion-segment-button>
<ion-segment-button value="sat">
Satellite
</ion-segment-button>
</ion-segment>
</form>
</ion-content>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

58
packages/core/src/components/segment/segment.tsx
View File

@ -1,64 +1,6 @@
import { Component, Element, Event, EventEmitter, Listen, Prop, PropDidChange } from '@stencil/core'; 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
* <!-- Segment in a header -->
* <ion-header>
* <ion-toolbar>
* <ion-segment [(ngModel)]="icons" color="secondary">
* <ion-segment-button value="camera">
* <ion-icon name="camera"></ion-icon>
* </ion-segment-button>
* <ion-segment-button value="bookmark">
* <ion-icon name="bookmark"></ion-icon>
* </ion-segment-button>
* </ion-segment>
* </ion-toolbar>
* </ion-header>
*
* <ion-content>
* <!-- Segment in content -->
* <ion-segment [(ngModel)]="relationship" color="primary" (ionChange)="segmentChanged($event)">
* <ion-segment-button value="friends">
* Friends
* </ion-segment-button>
* <ion-segment-button value="enemies">
* Enemies
* </ion-segment-button>
* </ion-segment>
*
* <!-- Segment in a form -->
* <form [formGroup]="myForm">
* <ion-segment formControlName="mapStyle" color="danger">
* <ion-segment-button value="standard">
* Standard
* </ion-segment-button>
* <ion-segment-button value="hybrid">
* Hybrid
* </ion-segment-button>
* <ion-segment-button value="sat">
* Satellite
* </ion-segment-button>
* </ion-segment>
* </form>
* </ion-content>
* ```
*
*
* @demo /docs/demos/src/segment/
* @see {@link /docs/components#segment Segment Component Docs}
* @see [Angular Forms](http://learnangular2.com/forms/)
*/
@Component({ @Component({
tag: 'ion-segment', tag: 'ion-segment',
styleUrls: { styleUrls: {

88
packages/core/src/components/spinner/readme.md
View File

@ -1,5 +1,93 @@
# ion-spinner # 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.
<table class="table spinner-table">
<tr>
<th>
<code>lines</code>
</th>
<td>
<ion-spinner name="lines"></ion-spinner>
</td>
</tr>
<tr>
<th>
<code>lines-small</code>
</th>
<td>
<ion-spinner name="lines-small"></ion-spinner>
</td>
</tr>
<tr>
<th>
<code>bubbles</code>
</th>
<td>
<ion-spinner name="bubbles"></ion-spinner>
</td>
</tr>
<tr>
<th>
<code>circles</code>
</th>
<td>
<ion-spinner name="circles"></ion-spinner>
</td>
</tr>
<tr>
<th>
<code>crescent</code>
</th>
<td>
<ion-spinner name="crescent"></ion-spinner>
</td>
</tr>
<tr>
<th>
<code>dots</code>
</th>
<td>
<ion-spinner name="dots"></ion-spinner>
</td>
</tr>
</table>
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
<ion-spinner></ion-spinner>
```
By setting the `name` property, you can specify which predefined spinner to
use, no matter what the platform is.
```html
<ion-spinner name="bubbles"></ion-spinner>
```
## 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;
}
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

93
packages/core/src/components/spinner/spinner.tsx
View File

@ -4,99 +4,6 @@ import { Config } from '../../index';
import { SPINNERS, SpinnerConfig } from './spinner-configs'; 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.
*
* <table class="table spinner-table">
* <tr>
* <th>
* <code>lines</code>
* </th>
* <td>
* <ion-spinner name="lines"></ion-spinner>
* </td>
* </tr>
* <tr>
* <th>
* <code>lines-small</code>
* </th>
* <td>
* <ion-spinner name="lines-small"></ion-spinner>
* </td>
* </tr>
* <tr>
* <th>
* <code>bubbles</code>
* </th>
* <td>
* <ion-spinner name="bubbles"></ion-spinner>
* </td>
* </tr>
* <tr>
* <th>
* <code>circles</code>
* </th>
* <td>
* <ion-spinner name="circles"></ion-spinner>
* </td>
* </tr>
* <tr>
* <th>
* <code>crescent</code>
* </th>
* <td>
* <ion-spinner name="crescent"></ion-spinner>
* </td>
* </tr>
* <tr>
* <th>
* <code>dots</code>
* </th>
* <td>
* <ion-spinner name="dots"></ion-spinner>
* </td>
* </tr>
* </table>
*
* @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
* <ion-spinner></ion-spinner>
* ```
*
* By setting the `name` property, you can specify which predefined spinner to
* use, no matter what the platform is.
*
* ```html
* <ion-spinner name="bubbles"></ion-spinner>
* ```
*
* ## 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({ @Component({
tag: 'ion-spinner', tag: 'ion-spinner',
styleUrls: { styleUrls: {

11
packages/core/src/components/title/readme.md
View File

@ -1,5 +1,16 @@
# ion-title # ion-title
`ion-title` is a component that sets the title of the `Toolbar`.
```html
<ion-header>
<ion-toolbar>
<ion-title>Settings</ion-title>
</ion-toolbar>
</ion-header>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

35
packages/core/src/components/title/title.tsx
View File

@ -2,41 +2,6 @@ import { Component } from '@stencil/core';
import { createThemedClasses } from '../../utils/theme'; import { createThemedClasses } from '../../utils/theme';
/**
* @name Title
* @description
* `ion-title` is a component that sets the title of the `Toolbar` or `Navbar`.
*
* @usage
*
* ```html
* <ion-header>
*
* <ion-navbar>
* <ion-title>Settings</ion-title>
* </ion-navbar>
*
* </ion-header>
* ```
*
* Or to create a navbar with a toolbar as a subheader:
*
* ```html
* <ion-header>
*
* <ion-navbar>
* <ion-title>Main Header</ion-title>
* </ion-navbar>
*
* <ion-toolbar>
* <ion-title>Subheader</ion-title>
* </ion-toolbar>
*
* </ion-header>
* ```
*
* @demo /docs/demos/src/title/
*/
@Component({ @Component({
tag: 'ion-title', tag: 'ion-title',
styleUrls: { styleUrls: {

80
packages/core/src/components/toolbar/readme.md
View File

@ -1,5 +1,85 @@
# ion-navbar # 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 `<ion-header>` or `<ion-footer>`,
the toolbars stay fixed in their respective location. When placed within
`<ion-content>`, toolbars will scroll with the content.
### Buttons in a Toolbar
Buttons placed in a toolbar should be placed inside of the `<ion-buttons>`
element. An exception to this is a [menuToggle](../../menu/MenuToggle) button.
It should not be placed inside of the `<ion-buttons>` element. Both the
`<ion-buttons>` 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 `<ion-header>` will receive a box-shadow on the bottom, and the
`<ion-footer>` will receive a box-shadow on the top. In `ios` mode, the `<ion-header>`
will receive a border on the bottom, and the `<ion-footer>` 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
<ion-header no-border>
<ion-toolbar>
<ion-title>Header</ion-title>
</ion-toolbar>
</ion-header>
<ion-content>
...
</ion-content>
<ion-footer no-border>
<ion-toolbar>
<ion-title>Footer</ion-title>
</ion-toolbar>
</ion-footer>
```
```html
<ion-header no-border>
<ion-toolbar>
<ion-title>My Toolbar Title</ion-title>
</ion-toolbar>
<ion-toolbar>
<ion-title>I'm a subheader</ion-title>
</ion-toolbar>
<ion-header>
<ion-content>
<ion-toolbar>
<ion-title>Scrolls with the content</ion-title>
</ion-toolbar>
</ion-content>
<ion-footer no-border>
<ion-toolbar>
<ion-title>I'm a footer</ion-title>
</ion-toolbar>
</ion-footer>
```
<!-- Auto Generated Below --> <!-- Auto Generated Below -->

89
packages/core/src/components/toolbar/toolbar.tsx
View File

@ -2,94 +2,7 @@ import { Component, Element, Prop } from '@stencil/core';
import { createThemedClasses } from '../../utils/theme'; import { createThemedClasses } from '../../utils/theme';
import { Config } from '../../index'; 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 `<ion-header>` or `<ion-footer>`,
* the toolbars stay fixed in their respective location. When placed within
* `<ion-content>`, toolbars will scroll with the content.
*
*
* ### Buttons in a Toolbar
* Buttons placed in a toolbar should be placed inside of the `<ion-buttons>`
* element. An exception to this is a [menuToggle](../../menu/MenuToggle) button.
* It should not be placed inside of the `<ion-buttons>` element. Both the
* `<ion-buttons>` 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 `<ion-header>` will receive a box-shadow on the bottom, and the
* `<ion-footer>` will receive a box-shadow on the top. In `ios` mode, the `<ion-header>`
* will receive a border on the bottom, and the `<ion-footer>` 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
* <ion-header no-border>
* <ion-toolbar>
* <ion-title>Header</ion-title>
* </ion-toolbar>
* </ion-header>
*
* <ion-content>
* </ion-content>
*
* <ion-footer no-border>
* <ion-toolbar>
* <ion-title>Footer</ion-title>
* </ion-toolbar>
* </ion-footer>
* ```
*
* @usage
*
* ```html
*
* <ion-header no-border>
*
* <ion-toolbar>
* <ion-title>My Toolbar Title</ion-title>
* </ion-toolbar>
*
* <ion-toolbar>
* <ion-title>I'm a subheader</ion-title>
* </ion-toolbar>
*
* <ion-header>
*
*
* <ion-content>
*
* <ion-toolbar>
* <ion-title>Scrolls with the content</ion-title>
* </ion-toolbar>
*
* </ion-content>
*
*
* <ion-footer no-border>
*
* <ion-toolbar>
* <ion-title>I'm a footer</ion-title>
* </ion-toolbar>
*
* </ion-footer>
* ```
*
* @demo /docs/demos/src/toolbar/
* @see {@link ../../navbar/Navbar/ Navbar API Docs}
*/
@Component({ @Component({
tag: 'ion-toolbar', tag: 'ion-toolbar',
styleUrls: { styleUrls: {