diff --git a/.editorconfig b/.editorconfig index 82da0b16e75..0981b55d9ad 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,6 +10,6 @@ end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true -[*.md] +[{*.md,*.mdx}] insert_final_newline = false trim_trailing_whitespace = false \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf3eb243153..ed18ea9546d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,10 +118,10 @@ Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The c The content of the Ionic docs is written as [Markdown](https://commonmark.org/) in `docs/`. Each Markdown file corresponds to a route unless explicitly changed in the frontmatter. ``` -/docs/ => src/pages/index.md -/docs/intro/cli => src/pages/intro/cli.md -/docs/theming/advanced => src/pages/theming/advanced.md -/docs/theming => src/pages/theming.md +/docs/ => src/pages/index.mdx +/docs/intro/cli => src/pages/intro/cli.mdx +/docs/theming/advanced => src/pages/theming/advanced.mdx +/docs/theming => src/pages/theming.mdx ``` You can make copy edits to the site by [editing the Markdown files directly on GitHub](https://help.github.com/articles/editing-files-in-another-user-s-repository/). In your pull request, please explain what was missing from or inaccurate about the content. diff --git a/_templates/README.md b/_templates/README.md index 60a3ebef83d..77790a47b4d 100644 --- a/_templates/README.md +++ b/_templates/README.md @@ -21,12 +21,12 @@ If you need a component for multiple versions of Ionic Framework, you (currently ## Usage -Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.md](../docs/api/button.md)) by doing something similar to the following example: +Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.mdx](../docs/api/button.mdx)) by doing something similar to the following example: ``` ## Feature -import Feature from '@site/static/usage/v8/button/feature/index.md'; +import Feature from '@site/static/usage/v8/button/feature/index.mdx'; ``` diff --git a/docs/angular/build-options.md b/docs/angular/build-options.mdx similarity index 100% rename from docs/angular/build-options.md rename to docs/angular/build-options.mdx diff --git a/docs/angular/lifecycle.md b/docs/angular/lifecycle.mdx similarity index 100% rename from docs/angular/lifecycle.md rename to docs/angular/lifecycle.mdx diff --git a/docs/angular/navigation.md b/docs/angular/navigation.mdx similarity index 100% rename from docs/angular/navigation.md rename to docs/angular/navigation.mdx diff --git a/docs/angular/overview.md b/docs/angular/overview.mdx similarity index 100% rename from docs/angular/overview.md rename to docs/angular/overview.mdx diff --git a/docs/angular/performance.md b/docs/angular/performance.md deleted file mode 100644 index 62877e6e4dd..00000000000 --- a/docs/angular/performance.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Angular Performance -sidebar_label: Performance ---- - - - Angular Performance: Manage App Component Change with ngFor - - - -## \*ngFor with Ionic Components - -When using `*ngFor` with Ionic components, we recommend using Angular's `trackBy` option. This allows Angular to manage change propagation in a much more efficient way and only update the content inside of the component rather than re-create the component altogether. - -By using `trackBy` you can provide a stable identity for each loop element so Angular can track insertions and deletions within the iterator. Below is an example of how to use `trackBy`: - -**home.page.html** - -```html - - {{ item.value }} - -``` - -**home.component.ts** - -```tsx - -items = [ - { id: 0, value: 'Item 0' }, - { id: 1, value: 'Item 1' }, - ... -] - -trackItems(index: number, itemObject: any) { - return itemObject.id; -} -``` - -In this example, we have an array of objects called `items`. Each object contains a `value` and an `id`. Using `trackBy`, we pass a `trackItems` function which returns the `id` of each object. This `id` is used to provide a stable identity for each loop element. - -For more information on how Angular manages change propagation with `ngFor` see https://angular.io/api/common/NgForOf#change-propagation. - -## From the Ionic Team - -[How to Lazy Load in Ionic Angular](https://ionicframework.com/blog/how-to-lazy-load-in-ionic-angular/) - -[Improved Perceived Performance with Skeleton Screens](https://ionicframework.com/blog/improved-perceived-performance-with-skeleton-screens/) - -## From the Angular Team - -[Build performant and progressive Angular apps](https://web.dev/angular) - web.dev - -## From the Community - - - -[High Performance Animations in Ionic](https://www.joshmorony.com/high-performance-animations-in-ionic/) - Josh Morony - -[High Performance List Filtering in Ionic](https://www.joshmorony.com/high-performance-list-filtering-in-ionic-2/) - Josh Morony - -[Increasing Performance with Efficient DOM Writes in Ionic](https://www.joshmorony.com/increasing-performance-with-efficient-dom-writes-in-ionic-2/) - Josh Morony - -[Ionic Framework is Fast (But Your Code Might Not Be)](https://www.joshmorony.com/ionic-framework-is-fast-but-your-code-might-not-be/) - Josh Morony - - - -:::note -Do you have a guide you'd like to share? Click the _Edit this page_ button below. -::: diff --git a/docs/angular/performance.mdx b/docs/angular/performance.mdx new file mode 100644 index 00000000000..c4f7760e318 --- /dev/null +++ b/docs/angular/performance.mdx @@ -0,0 +1,73 @@ +--- +title: Angular Performance +sidebar_label: Performance +--- + + + Angular Performance: Manage App Component Change with ngFor + + + +## \*ngFor with Ionic Components + +When using `*ngFor` with Ionic components, we recommend using Angular's `trackBy` option. This allows Angular to manage change propagation in a much more efficient way and only update the content inside of the component rather than re-create the component altogether. + +By using `trackBy` you can provide a stable identity for each loop element so Angular can track insertions and deletions within the iterator. Below is an example of how to use `trackBy`: + +**home.page.html** + +```html + + {{ item.value }} + +``` + +**home.component.ts** + +```tsx + +items = [ + { id: 0, value: 'Item 0' }, + { id: 1, value: 'Item 1' }, + ... +] + +trackItems(index: number, itemObject: any) { + return itemObject.id; +} +``` + +In this example, we have an array of objects called `items`. Each object contains a `value` and an `id`. Using `trackBy`, we pass a `trackItems` function which returns the `id` of each object. This `id` is used to provide a stable identity for each loop element. + +For more information on how Angular manages change propagation with `ngFor` see https://angular.io/api/common/NgForOf#change-propagation. + +## From the Ionic Team + +[How to Lazy Load in Ionic Angular](https://ionicframework.com/blog/how-to-lazy-load-in-ionic-angular/) + +[Improved Perceived Performance with Skeleton Screens](https://ionicframework.com/blog/improved-perceived-performance-with-skeleton-screens/) + +## From the Angular Team + +[Build performant and progressive Angular apps](https://web.dev/angular) - web.dev + +## From the Community + +{/* cspell:disable */} + +[High Performance Animations in Ionic](https://www.joshmorony.com/high-performance-animations-in-ionic/) - Josh Morony + +[High Performance List Filtering in Ionic](https://www.joshmorony.com/high-performance-list-filtering-in-ionic-2/) - Josh Morony + +[Increasing Performance with Efficient DOM Writes in Ionic](https://www.joshmorony.com/increasing-performance-with-efficient-dom-writes-in-ionic-2/) - Josh Morony + +[Ionic Framework is Fast (But Your Code Might Not Be)](https://www.joshmorony.com/ionic-framework-is-fast-but-your-code-might-not-be/) - Josh Morony + +{/* cspell:enable */} + +:::note +Do you have a guide you'd like to share? Click the _Edit this page_ button below. +::: diff --git a/docs/angular/platform.md b/docs/angular/platform.mdx similarity index 100% rename from docs/angular/platform.md rename to docs/angular/platform.mdx diff --git a/docs/angular/pwa.md b/docs/angular/pwa.mdx similarity index 100% rename from docs/angular/pwa.md rename to docs/angular/pwa.mdx diff --git a/docs/angular/slides.md b/docs/angular/slides.mdx similarity index 100% rename from docs/angular/slides.md rename to docs/angular/slides.mdx diff --git a/docs/angular/storage.md b/docs/angular/storage.mdx similarity index 100% rename from docs/angular/storage.md rename to docs/angular/storage.mdx diff --git a/docs/angular/testing.md b/docs/angular/testing.mdx similarity index 100% rename from docs/angular/testing.md rename to docs/angular/testing.mdx diff --git a/docs/angular/virtual-scroll.md b/docs/angular/virtual-scroll.mdx similarity index 100% rename from docs/angular/virtual-scroll.md rename to docs/angular/virtual-scroll.mdx diff --git a/docs/angular/your-first-app.md b/docs/angular/your-first-app.md deleted file mode 100644 index b876e2f66c4..00000000000 --- a/docs/angular/your-first-app.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: 'Your First Ionic App: Angular' -sidebar_label: Build Your First App ---- - - - Build Your First Ionic Mobile App: Angular Development Tutorial - - - -The great thing about Ionic is that with one codebase, you can build for any platform using just HTML, CSS, and JavaScript. Follow along as we learn the fundamentals of Ionic app development by creating a realistic app step by step. - -Here’s the finished app running on all 3 platforms: - - - -:::note -Looking for the previous version of this guide that covered Ionic 4 and Cordova? [See here.](../developer-resources/guides/first-app-v4/intro.md) -::: - -## What We'll Build - -We'll create a Photo Gallery app that offers the ability to take photos with your device's camera, display them in a grid, and store them permanently on the device. - -Highlights include: - -- One Angular-based codebase that runs on the web, iOS, and Android using Ionic Framework [UI components](https://ionicframework.com/docs/components). -- Deployed as a native iOS and Android mobile app using [Capacitor](https://capacitorjs.com), Ionic's official native app runtime. -- Photo Gallery functionality powered by the Capacitor [Camera](https://capacitorjs.com/docs/apis/camera), [Filesystem](https://capacitorjs.com/docs/apis/filesystem), and [Preferences](https://capacitorjs.com/docs/apis/preferences) APIs. - -Find the complete app code referenced in this guide [on GitHub](https://github.com/ionic-team/photo-gallery-capacitor-ng). - -## Download Required Tools - -Download and install these right away to ensure an optimal Ionic development experience: - -- **Node.js** for interacting with the Ionic ecosystem. [Download the LTS version here](https://nodejs.org/en/). -- **A code editor** for... writing code! We are fans of [Visual Studio Code](https://code.visualstudio.com/). -- **Command-line interface/terminal (CLI)**: - - **Windows** users: for the best Ionic experience, we recommend the built-in command line (cmd) or the Powershell - CLI, running in Administrator mode. - - **Mac/Linux** users, virtually any terminal will work. - -## Install Ionic Tooling - -Run the following in the command line terminal to install the Ionic CLI (`ionic`), `native-run`, used to run native binaries on devices and simulators/emulators, and `cordova-res`, used to generate native app icons and splash screens: - -:::note -To open a terminal in Visual Studio Code, go to Terminal -> New Terminal. -::: - -```shell -npm install -g @ionic/cli native-run cordova-res -``` - -:::note -The `-g` option means _install globally_. When packages are installed globally, `EACCES` permission errors can occur. - -Consider setting up npm to operate globally without elevated permissions. See [Resolving Permission Errors](../developing/tips.md#resolving-permission-errors) for more information. -::: - -## Create an App - -Next, create an Ionic Angular app that uses the “Tabs” starter template and adds Capacitor for native functionality: - -```shell -ionic start photo-gallery tabs --type=angular --capacitor -``` - -:::note - -When prompted to choose between `NgModules` and `Standalone`, opt for `NgModules` as this tutorial follows the `NgModules` approach. - -::: - -This starter project comes complete with three pre-built pages and best practices for Ionic development. With common building blocks already in place, we can add more features easily! - -Next, change into the app folder: - -```shell -cd photo-gallery -``` - -Next we'll need to install the necessary Capacitor plugins to make the app's native functionality work: - -```shell -npm install @capacitor/camera @capacitor/preferences @capacitor/filesystem -``` - -### PWA Elements - -Some Capacitor plugins, including the Camera API, provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/ionic-pwa-elements). - -It's a separate dependency, so install it next: - -```shell -npm install @ionic/pwa-elements -``` - -Next, import `@ionic/pwa-elements` by editing `src/main.ts`. - -```tsx -import { defineCustomElements } from '@ionic/pwa-elements/loader'; - -// Call the element loader before the bootstrapModule/bootstrapApplication call -defineCustomElements(window); -``` - -That’s it! Now for the fun part - let’s see the app in action. - -## Run the App - -Run this command next: - -```shell -ionic serve -``` - -And voilà! Your Ionic app is now running in a web browser. Most of your app can be built and tested right in the browser, greatly increasing development and testing speed. - -## Photo Gallery!!! - -There are three tabs. Click on the Tab2 tab. It’s a blank canvas, aka the perfect spot to transform into a Photo Gallery. The Ionic CLI features Live Reload, so when you make changes and save them, the app is updated immediately! - -![Before and after going through this tutorial](/img/guides/first-app-cap-ng/email-photogallery.gif) - -Open the photo-gallery app folder in your code editor of choice, then navigate to `/src/app/tab2/tab2.page.html`. We see: - -```html - - - Tab 2 - - - - - - - Tab 2 - - - -``` - -`ion-header` represents the top navigation and toolbar, with "Tab 2" as the title (there are two of them due to iOS [Collapsible Large Title](https://ionicframework.com/docs/api/title#collapsible-large-titles) support). Rename both `ion-title` elements to: - -```html -Photo Gallery -``` - -We put the visual aspects of our app into ``. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. Start by adding a [floating action button](https://ionicframework.com/docs/api/fab) (FAB) to the bottom of the page and set the camera image as the icon. - -```html - - - - - - - -``` - -Next, open `src/app/tabs/tabs.page.html`. Change the label to “Photos” and the icon name to “images”: - -```html - - - Photos - -``` - -Save all changes to see them automatically applied in the browser. That’s just the start of all the cool things we can do with Ionic. Up next, implement camera taking functionality on the web, then build it for iOS and Android. diff --git a/docs/angular/your-first-app.mdx b/docs/angular/your-first-app.mdx new file mode 100644 index 00000000000..915976f4c48 --- /dev/null +++ b/docs/angular/your-first-app.mdx @@ -0,0 +1,182 @@ +--- +title: 'Your First Ionic App: Angular' +sidebar_label: Build Your First App +--- + + + Build Your First Ionic Mobile App: Angular Development Tutorial + + + +The great thing about Ionic is that with one codebase, you can build for any platform using just HTML, CSS, and JavaScript. Follow along as we learn the fundamentals of Ionic app development by creating a realistic app step by step. + +Here’s the finished app running on all 3 platforms: + + + +:::note +Looking for the previous version of this guide that covered Ionic 4 and Cordova? [See here.](../developer-resources/guides/first-app-v4/intro.mdx) +::: + +## What We'll Build + +We'll create a Photo Gallery app that offers the ability to take photos with your device's camera, display them in a grid, and store them permanently on the device. + +Highlights include: + +- One Angular-based codebase that runs on the web, iOS, and Android using Ionic Framework [UI components](https://ionicframework.com/docs/components). +- Deployed as a native iOS and Android mobile app using [Capacitor](https://capacitorjs.com), Ionic's official native app runtime. +- Photo Gallery functionality powered by the Capacitor [Camera](https://capacitorjs.com/docs/apis/camera), [Filesystem](https://capacitorjs.com/docs/apis/filesystem), and [Preferences](https://capacitorjs.com/docs/apis/preferences) APIs. + +Find the complete app code referenced in this guide [on GitHub](https://github.com/ionic-team/photo-gallery-capacitor-ng). + +## Download Required Tools + +Download and install these right away to ensure an optimal Ionic development experience: + +- **Node.js** for interacting with the Ionic ecosystem. [Download the LTS version here](https://nodejs.org/en/). +- **A code editor** for... writing code! We are fans of [Visual Studio Code](https://code.visualstudio.com/). +- **Command-line interface/terminal (CLI)**: + - **Windows** users: for the best Ionic experience, we recommend the built-in command line (cmd) or the Powershell + CLI, running in Administrator mode. + - **Mac/Linux** users, virtually any terminal will work. + +## Install Ionic Tooling + +Run the following in the command line terminal to install the Ionic CLI (`ionic`), `native-run`, used to run native binaries on devices and simulators/emulators, and `cordova-res`, used to generate native app icons and splash screens: + +:::note +To open a terminal in Visual Studio Code, go to Terminal -> New Terminal. +::: + +```shell +npm install -g @ionic/cli native-run cordova-res +``` + +:::note +The `-g` option means _install globally_. When packages are installed globally, `EACCES` permission errors can occur. + +Consider setting up npm to operate globally without elevated permissions. See [Resolving Permission Errors](../developing/tips.mdx#resolving-permission-errors) for more information. +::: + +## Create an App + +Next, create an Ionic Angular app that uses the “Tabs” starter template and adds Capacitor for native functionality: + +```shell +ionic start photo-gallery tabs --type=angular --capacitor +``` + +:::note + +When prompted to choose between `NgModules` and `Standalone`, opt for `NgModules` as this tutorial follows the `NgModules` approach. + +::: + +This starter project comes complete with three pre-built pages and best practices for Ionic development. With common building blocks already in place, we can add more features easily! + +Next, change into the app folder: + +```shell +cd photo-gallery +``` + +Next we'll need to install the necessary Capacitor plugins to make the app's native functionality work: + +```shell +npm install @capacitor/camera @capacitor/preferences @capacitor/filesystem +``` + +### PWA Elements + +Some Capacitor plugins, including the Camera API, provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/ionic-pwa-elements). + +It's a separate dependency, so install it next: + +```shell +npm install @ionic/pwa-elements +``` + +Next, import `@ionic/pwa-elements` by editing `src/main.ts`. + +```tsx +import { defineCustomElements } from '@ionic/pwa-elements/loader'; + +// Call the element loader before the bootstrapModule/bootstrapApplication call +defineCustomElements(window); +``` + +That’s it! Now for the fun part - let’s see the app in action. + +## Run the App + +Run this command next: + +```shell +ionic serve +``` + +And voilà! Your Ionic app is now running in a web browser. Most of your app can be built and tested right in the browser, greatly increasing development and testing speed. + +## Photo Gallery!!! + +There are three tabs. Click on the Tab2 tab. It’s a blank canvas, aka the perfect spot to transform into a Photo Gallery. The Ionic CLI features Live Reload, so when you make changes and save them, the app is updated immediately! + +![Before and after going through this tutorial](/img/guides/first-app-cap-ng/email-photogallery.gif) + +Open the photo-gallery app folder in your code editor of choice, then navigate to `/src/app/tab2/tab2.page.html`. We see: + +```html + + + Tab 2 + + + + + + + Tab 2 + + + +``` + +`ion-header` represents the top navigation and toolbar, with "Tab 2" as the title (there are two of them due to iOS [Collapsible Large Title](https://ionicframework.com/docs/api/title#collapsible-large-titles) support). Rename both `ion-title` elements to: + +```html +Photo Gallery +``` + +We put the visual aspects of our app into ``. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. Start by adding a [floating action button](https://ionicframework.com/docs/api/fab) (FAB) to the bottom of the page and set the camera image as the icon. + +```html + + + + + + + +``` + +Next, open `src/app/tabs/tabs.page.html`. Change the label to “Photos” and the icon name to “images”: + +```html + + + Photos + +``` + +Save all changes to see them automatically applied in the browser. That’s just the start of all the cool things we can do with Ionic. Up next, implement camera taking functionality on the web, then build it for iOS and Android. diff --git a/docs/angular/your-first-app/2-taking-photos.md b/docs/angular/your-first-app/2-taking-photos.mdx similarity index 100% rename from docs/angular/your-first-app/2-taking-photos.md rename to docs/angular/your-first-app/2-taking-photos.mdx diff --git a/docs/angular/your-first-app/3-saving-photos.md b/docs/angular/your-first-app/3-saving-photos.mdx similarity index 100% rename from docs/angular/your-first-app/3-saving-photos.md rename to docs/angular/your-first-app/3-saving-photos.mdx diff --git a/docs/angular/your-first-app/4-loading-photos.md b/docs/angular/your-first-app/4-loading-photos.mdx similarity index 100% rename from docs/angular/your-first-app/4-loading-photos.md rename to docs/angular/your-first-app/4-loading-photos.mdx diff --git a/docs/angular/your-first-app/5-adding-mobile.md b/docs/angular/your-first-app/5-adding-mobile.mdx similarity index 100% rename from docs/angular/your-first-app/5-adding-mobile.md rename to docs/angular/your-first-app/5-adding-mobile.mdx diff --git a/docs/angular/your-first-app/6-deploying-mobile.md b/docs/angular/your-first-app/6-deploying-mobile.mdx similarity index 100% rename from docs/angular/your-first-app/6-deploying-mobile.md rename to docs/angular/your-first-app/6-deploying-mobile.mdx diff --git a/docs/angular/your-first-app/7-live-reload.md b/docs/angular/your-first-app/7-live-reload.mdx similarity index 100% rename from docs/angular/your-first-app/7-live-reload.md rename to docs/angular/your-first-app/7-live-reload.mdx diff --git a/docs/angular/your-first-app/8-distribute.md b/docs/angular/your-first-app/8-distribute.mdx similarity index 100% rename from docs/angular/your-first-app/8-distribute.md rename to docs/angular/your-first-app/8-distribute.mdx diff --git a/docs/api.mdx b/docs/api.mdx new file mode 100644 index 00000000000..79303157760 --- /dev/null +++ b/docs/api.mdx @@ -0,0 +1,17 @@ +--- +title: API Index +--- + +import APIList from '@components/page/api/APIList'; + + + API Index | Ionic Docs API Index for all API Custom Elements + + + +Each Ionic [component](components.mdx) consists of one or more [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Each custom element, in turn, may expose properties, methods, events, and CSS custom properties. + + diff --git a/docs/api/accordion-group.md b/docs/api/accordion-group.mdx similarity index 100% rename from docs/api/accordion-group.md rename to docs/api/accordion-group.mdx diff --git a/docs/api/accordion.md b/docs/api/accordion.mdx similarity index 100% rename from docs/api/accordion.md rename to docs/api/accordion.mdx diff --git a/docs/api/action-sheet.md b/docs/api/action-sheet.md deleted file mode 100644 index afbec37e566..00000000000 --- a/docs/api/action-sheet.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -title: "ion-action-sheet" ---- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -import Props from '@ionic-internal/component-api/v8/action-sheet/props.md'; -import Events from '@ionic-internal/component-api/v8/action-sheet/events.md'; -import Methods from '@ionic-internal/component-api/v8/action-sheet/methods.md'; -import Parts from '@ionic-internal/component-api/v8/action-sheet/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/action-sheet/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/action-sheet/slots.md'; - - - ion-action-sheet: Action Sheet Dialog for iOS and Android - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - - -An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. - -## Inline Action Sheets (Recommended) - -`ion-action-sheet` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Action Sheet. - -import Trigger from '@site/static/usage/v8/action-sheet/inline/trigger/index.md'; - - - -### Using `isOpen` - -The `isOpen` property on `ion-action-sheet` allows developers to control the presentation state of the Action Sheet from their application state. This means when `isOpen` is set to `true` the Action Sheet will be presented, and when `isOpen` is set to `false` the Action Sheet will be dismissed. - -`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Action Sheet is dismissed. Developers should listen for the `ionActionSheetDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-action-sheet` from being tightly coupled with the state of the application. With a one way data binding, the Action Sheet only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Action Sheet needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug. - -import IsOpen from '@site/static/usage/v8/action-sheet/inline/isOpen/index.md'; - - - -## Controller Action Sheets - -The `actionSheetController` can be used in situations where more control is needed over when the Action Sheet is presented and dismissed. - -import Controller from '@site/static/usage/v8/action-sheet/controller/index.md'; - - - -## Buttons - -A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role. - -A button can also be passed data via the `data` property on `ActionSheetButton`. This will populate the `data` field in the return value of the `onDidDismiss` method. - -## Collecting Role Information on Dismiss - -When the `didDismiss` event is fired, the `data` and `role` fields of the event detail can be used to gather information about how the Action Sheet was dismissed. - -import RoleInfo from '@site/static/usage/v8/action-sheet/role-info-on-dismiss/index.md'; - - - -## Theming - -Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. - -### Styling - -We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. - -```css -/* DOES NOT WORK - not specific enough */ -.action-sheet-group { - background: #e5e5e5; -} - -/* Works - pass "my-custom-class" in cssClass to increase specificity */ -.my-custom-class .action-sheet-group { - background: #e5e5e5; -} -``` - -import Styling from '@site/static/usage/v8/action-sheet/theming/styling/index.md'; - - - -### CSS Custom Properties - -Any of the defined [CSS Custom Properties](#css-custom-properties-1) can be used to style the Action Sheet without needing to target individual elements. - -import CssCustomProperties from '@site/static/usage/v8/action-sheet/theming/css-properties/index.md'; - - - -## Accessibility - -### Screen Readers - -Action Sheets set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app. - -#### Role - -Action Sheets are given a `role` of [`dialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role). In order to align with the ARIA spec, either the `aria-label` or `aria-labelledby` attribute must be set. - -#### Action Sheet Description - -It is strongly recommended that every Action Sheet have the `header` property defined, as Ionic will automatically set `aria-labelledby` to point to the header element. However, if you choose not to include a `header`, an alternative is to use the `htmlAttributes` property to provide a descriptive `aria-label` or set a custom `aria-labelledby` value. - - - - - -```javascript -const actionSheet = await this.actionSheetController.create({ - htmlAttributes: { - 'aria-label': 'action sheet dialog', - }, -}); -``` - - - - - -```javascript -const actionSheet = await this.actionSheetController.create({ - htmlAttributes: { - 'aria-label': 'action sheet dialog', - }, -}); -``` - - - - - -```javascript -useIonActionSheet({ - htmlAttributes: { - 'aria-label': 'action sheet dialog', - }, -}); -``` - - - - - -```javascript -const actionSheet = await actionSheetController.create({ - htmlAttributes: { - 'aria-label': 'action sheet dialog', - }, -}); -``` - - - - - -#### Action Sheet Buttons Description - -Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing `aria-label` to the `htmlAttributes` property on the button. - - - - - -```javascript -const actionSheet = await this.actionSheetController.create({ - header: 'Header', - buttons: [ - { - icon: 'close', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -const actionSheet = await this.actionSheetController.create({ - header: 'Header', - buttons: [ - { - icon: 'close', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -useIonActionSheet({ - header: 'Header', - buttons: [ - { - icon: 'close', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -const actionSheet = await actionSheetController.create({ - header: 'Header', - buttons: [ - { - icon: 'close', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -## Interfaces - -### ActionSheetButton - -```typescript -interface ActionSheetButton { - text?: string; - role?: 'cancel' | 'destructive' | 'selected' | string; - icon?: string; - cssClass?: string | string[]; - id?: string; - htmlAttributes?: { [key: string]: any }; - handler?: () => boolean | void | Promise; - data?: T; -} -``` - -### ActionSheetOptions - -```typescript -interface ActionSheetOptions { - header?: string; - subHeader?: string; - cssClass?: string | string[]; - buttons: (ActionSheetButton | string)[]; - backdropDismiss?: boolean; - translucent?: boolean; - animated?: boolean; - mode?: Mode; - keyboardClose?: boolean; - id?: string; - htmlAttributes?: { [key: string]: any }; - - enterAnimation?: AnimationBuilder; - leaveAnimation?: AnimationBuilder; -} -``` - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/action-sheet.mdx b/docs/api/action-sheet.mdx new file mode 100644 index 00000000000..767667ceae8 --- /dev/null +++ b/docs/api/action-sheet.mdx @@ -0,0 +1,298 @@ +--- +title: "ion-action-sheet" +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Props from '@ionic-internal/component-api/v8/action-sheet/props.md'; +import Events from '@ionic-internal/component-api/v8/action-sheet/events.md'; +import Methods from '@ionic-internal/component-api/v8/action-sheet/methods.md'; +import Parts from '@ionic-internal/component-api/v8/action-sheet/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/action-sheet/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/action-sheet/slots.md'; + + + ion-action-sheet: Action Sheet Dialog for iOS and Android + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + + +An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. + +## Inline Action Sheets (Recommended) + +`ion-action-sheet` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Action Sheet. + +import Trigger from '@site/static/usage/v8/action-sheet/inline/trigger/index.md'; + + + +### Using `isOpen` + +The `isOpen` property on `ion-action-sheet` allows developers to control the presentation state of the Action Sheet from their application state. This means when `isOpen` is set to `true` the Action Sheet will be presented, and when `isOpen` is set to `false` the Action Sheet will be dismissed. + +`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Action Sheet is dismissed. Developers should listen for the `ionActionSheetDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-action-sheet` from being tightly coupled with the state of the application. With a one way data binding, the Action Sheet only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Action Sheet needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug. + +import IsOpen from '@site/static/usage/v8/action-sheet/inline/isOpen/index.md'; + + + +## Controller Action Sheets + +The `actionSheetController` can be used in situations where more control is needed over when the Action Sheet is presented and dismissed. + +import Controller from '@site/static/usage/v8/action-sheet/controller/index.md'; + + + +## Buttons + +A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role. + +A button can also be passed data via the `data` property on `ActionSheetButton`. This will populate the `data` field in the return value of the `onDidDismiss` method. + +## Collecting Role Information on Dismiss + +When the `didDismiss` event is fired, the `data` and `role` fields of the event detail can be used to gather information about how the Action Sheet was dismissed. + +import RoleInfo from '@site/static/usage/v8/action-sheet/role-info-on-dismiss/index.md'; + + + +## Theming + +Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. + +### Styling + +We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. + +```css +/* DOES NOT WORK - not specific enough */ +.action-sheet-group { + background: #e5e5e5; +} + +/* Works - pass "my-custom-class" in cssClass to increase specificity */ +.my-custom-class .action-sheet-group { + background: #e5e5e5; +} +``` + +import Styling from '@site/static/usage/v8/action-sheet/theming/styling/index.md'; + + + +### CSS Custom Properties + +Any of the defined [CSS Custom Properties](#css-custom-properties-1) can be used to style the Action Sheet without needing to target individual elements. + +import CssCustomProperties from '@site/static/usage/v8/action-sheet/theming/css-properties/index.md'; + + + +## Accessibility + +### Screen Readers + +Action Sheets set aria properties in order to be [accessible](../reference/glossary.mdx#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app. + +#### Role + +Action Sheets are given a `role` of [`dialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role). In order to align with the ARIA spec, either the `aria-label` or `aria-labelledby` attribute must be set. + +#### Action Sheet Description + +It is strongly recommended that every Action Sheet have the `header` property defined, as Ionic will automatically set `aria-labelledby` to point to the header element. However, if you choose not to include a `header`, an alternative is to use the `htmlAttributes` property to provide a descriptive `aria-label` or set a custom `aria-labelledby` value. + + + + + +```javascript +const actionSheet = await this.actionSheetController.create({ + htmlAttributes: { + 'aria-label': 'action sheet dialog', + }, +}); +``` + + + + + +```javascript +const actionSheet = await this.actionSheetController.create({ + htmlAttributes: { + 'aria-label': 'action sheet dialog', + }, +}); +``` + + + + + +```javascript +useIonActionSheet({ + htmlAttributes: { + 'aria-label': 'action sheet dialog', + }, +}); +``` + + + + + +```javascript +const actionSheet = await actionSheetController.create({ + htmlAttributes: { + 'aria-label': 'action sheet dialog', + }, +}); +``` + + + + + +#### Action Sheet Buttons Description + +Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing `aria-label` to the `htmlAttributes` property on the button. + + + + + +```javascript +const actionSheet = await this.actionSheetController.create({ + header: 'Header', + buttons: [ + { + icon: 'close', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +const actionSheet = await this.actionSheetController.create({ + header: 'Header', + buttons: [ + { + icon: 'close', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +useIonActionSheet({ + header: 'Header', + buttons: [ + { + icon: 'close', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +const actionSheet = await actionSheetController.create({ + header: 'Header', + buttons: [ + { + icon: 'close', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +## Interfaces + +### ActionSheetButton + +```typescript +interface ActionSheetButton { + text?: string; + role?: 'cancel' | 'destructive' | 'selected' | string; + icon?: string; + cssClass?: string | string[]; + id?: string; + htmlAttributes?: { [key: string]: any }; + handler?: () => boolean | void | Promise; + data?: T; +} +``` + +### ActionSheetOptions + +```typescript +interface ActionSheetOptions { + header?: string; + subHeader?: string; + cssClass?: string | string[]; + buttons: (ActionSheetButton | string)[]; + backdropDismiss?: boolean; + translucent?: boolean; + animated?: boolean; + mode?: Mode; + keyboardClose?: boolean; + id?: string; + htmlAttributes?: { [key: string]: any }; + + enterAnimation?: AnimationBuilder; + leaveAnimation?: AnimationBuilder; +} +``` + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/alert.md b/docs/api/alert.md deleted file mode 100644 index b35622c1faf..00000000000 --- a/docs/api/alert.md +++ /dev/null @@ -1,350 +0,0 @@ ---- -title: "ion-alert" ---- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -import Props from '@ionic-internal/component-api/v8/alert/props.md'; -import Events from '@ionic-internal/component-api/v8/alert/events.md'; -import Methods from '@ionic-internal/component-api/v8/alert/methods.md'; -import Parts from '@ionic-internal/component-api/v8/alert/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/alert/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/alert/slots.md'; - - - ion-alert: Ionic Alert Buttons with Custom Message Prompts - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - -An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a `header`, `subHeader` and `message`. - -## Inline Alerts (Recommended) - -`ion-alert` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Alert. - -import Trigger from '@site/static/usage/v8/alert/presenting/trigger/index.md'; - - - -### Using `isOpen` - -The `isOpen` property on `ion-alert` allows developers to control the presentation state of the Alert from their application state. This means when `isOpen` is set to `true` the Alert will be presented, and when `isOpen` is set to `false` the Alert will be dismissed. - -`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Alert is dismissed. Developers should listen for the `ionAlertDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-alert` from being tightly coupled with the state of the application. With a one way data binding, the Alert only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Alert needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug. - -import IsOpen from '@site/static/usage/v8/alert/presenting/isOpen/index.md'; - - - -## Controller Alerts - -The `alertController` can be used in situations where more control is needed over when the Alert is presented and dismissed. - -import Controller from '@site/static/usage/v8/alert/presenting/controller/index.md'; - - - -## Buttons - -In the array of `buttons`, each button includes properties for its `text`, and optionally a `handler`. If a handler returns `false` then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the `buttons` array from left to right. Note: The right most button (the last one in the array) is the main button. - -Optionally, a `role` property can be added to a button, such as `cancel`. If a `cancel` role is on one of the buttons, then if the alert is dismissed by tapping the backdrop, then it will fire the handler from the button with a cancel role. - -import Buttons from '@site/static/usage/v8/alert/buttons/index.md'; - - - - -## Inputs - -Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as `url`, `email`, `text`, `textarea` etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead. - -### Text Inputs Example - -import TextInputs from '@site/static/usage/v8/alert/inputs/text-inputs/index.md'; - - - -### Radio Example - -import Radios from '@site/static/usage/v8/alert/inputs/radios/index.md'; - - - -## Customization - -Alert uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. - -We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. - -```css -/* DOES NOT WORK - not specific enough */ -.alert-wrapper { - background: #e5e5e5; -} - -/* Works - pass "my-custom-class" in cssClass to increase specificity */ -.my-custom-class .alert-wrapper { - background: #e5e5e5; -} -``` - -Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Alert without needing to target individual elements: - -```css -.my-custom-class { - --background: #e5e5e5; -} -``` - -import Customization from '@site/static/usage/v8/alert/customization/index.md'; - - - -:::note - If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. -::: - -## Accessibility - -### Screen Readers - -Alerts set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the alert is being used in an app. - -#### Role - -Ionic automatically sets the Alert's `role` to either [`alertdialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) if there are any inputs or buttons included, or [`alert`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) if there are none. - -#### Alert Description - -If the `header` property is defined for the Alert, the `aria-labelledby` attribute will be automatically set to the header's ID. The `subHeader` element will be used as a fallback if `header` is not defined. Similarly, the `aria-describedby` attribute will be automatically set to the ID of the `message` element if that property is defined. - -It is strongly recommended that your Alert have a `message`, as well as either a `header` or `subHeader`, in order to align with the ARIA spec. If you choose not to include a `header` or `subHeader`, an alternative is to provide a descriptive `aria-label` using the `htmlAttributes` property. - - - - - -```javascript -const alert = await this.alertController.create({ - message: 'This is an alert with custom aria attributes.', - htmlAttributes: { - 'aria-label': 'alert dialog', - }, -}); -``` - - - - - -```javascript -const alert = await this.alertController.create({ - message: 'This is an alert with custom aria attributes.', - htmlAttributes: { - 'aria-label': 'alert dialog', - }, -}); -``` - - - - - -```javascript -useIonAlert({ - message: 'This is an alert with custom aria attributes.', - htmlAttributes: { - 'aria-label': 'alert dialog', - }, -}); -``` - - - - - -```javascript -const alert = await alertController.create({ - message: 'This is an alert with custom aria attributes.', - htmlAttributes: { - 'aria-label': 'alert dialog', - }, -}); -``` - - - - - - -All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert. - -#### Alert Buttons Description - -Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be set on the button by passing `aria-label` to the `htmlAttributes` property on the button. - - - - - -```javascript -const alert = await this.alertController.create({ - header: 'Header', - buttons: [ - { - text: 'Exit', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -const alert = await this.alertController.create({ - header: 'Header', - buttons: [ - { - text: 'Exit', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -useIonAlert({ - header: 'Header', - buttons: [ - { - text: 'Exit', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -```javascript -const alert = await alertController.create({ - header: 'Header', - buttons: [ - { - text: 'Exit', - htmlAttributes: { - 'aria-label': 'close', - }, - }, - ], -}); -``` - - - - - -## Interfaces - -### AlertButton - -```typescript -type AlertButtonOverlayHandler = boolean | void | { [key: string]: any }; - -interface AlertButton { - text: string; - role?: 'cancel' | 'destructive' | string; - cssClass?: string | string[]; - id?: string; - htmlAttributes?: { [key: string]: any }; - handler?: (value: any) => AlertButtonOverlayHandler | Promise; -} -``` - - -### AlertInput - -```typescript -interface AlertInput { - type?: TextFieldTypes | 'checkbox' | 'radio' | 'textarea'; - name?: string; - placeholder?: string; - value?: any; - /** - * The label text to display next to the input, if the input type is `radio` or `checkbox`. - */ - label?: string; - checked?: boolean; - disabled?: boolean; - id?: string; - handler?: (input: AlertInput) => void; - min?: string | number; - max?: string | number; - cssClass?: string | string[]; - attributes?: { [key: string]: any }; - tabindex?: number; -} -``` - - -### AlertOptions - -```typescript -interface AlertOptions { - header?: string; - subHeader?: string; - message?: string | IonicSafeString; - cssClass?: string | string[]; - inputs?: AlertInput[]; - buttons?: (AlertButton | string)[]; - backdropDismiss?: boolean; - translucent?: boolean; - animated?: boolean; - htmlAttributes?: { [key: string]: any }; - - mode?: Mode; - keyboardClose?: boolean; - id?: string; - - enterAnimation?: AnimationBuilder; - leaveAnimation?: AnimationBuilder; -} -``` - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/alert.mdx b/docs/api/alert.mdx new file mode 100644 index 00000000000..6a9d79dcc14 --- /dev/null +++ b/docs/api/alert.mdx @@ -0,0 +1,350 @@ +--- +title: "ion-alert" +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import Props from '@ionic-internal/component-api/v8/alert/props.md'; +import Events from '@ionic-internal/component-api/v8/alert/events.md'; +import Methods from '@ionic-internal/component-api/v8/alert/methods.md'; +import Parts from '@ionic-internal/component-api/v8/alert/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/alert/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/alert/slots.md'; + + + ion-alert: Ionic Alert Buttons with Custom Message Prompts + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + +An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a `header`, `subHeader` and `message`. + +## Inline Alerts (Recommended) + +`ion-alert` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Alert. + +import Trigger from '@site/static/usage/v8/alert/presenting/trigger/index.md'; + + + +### Using `isOpen` + +The `isOpen` property on `ion-alert` allows developers to control the presentation state of the Alert from their application state. This means when `isOpen` is set to `true` the Alert will be presented, and when `isOpen` is set to `false` the Alert will be dismissed. + +`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Alert is dismissed. Developers should listen for the `ionAlertDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-alert` from being tightly coupled with the state of the application. With a one way data binding, the Alert only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Alert needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug. + +import IsOpen from '@site/static/usage/v8/alert/presenting/isOpen/index.md'; + + + +## Controller Alerts + +The `alertController` can be used in situations where more control is needed over when the Alert is presented and dismissed. + +import Controller from '@site/static/usage/v8/alert/presenting/controller/index.md'; + + + +## Buttons + +In the array of `buttons`, each button includes properties for its `text`, and optionally a `handler`. If a handler returns `false` then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the `buttons` array from left to right. Note: The right most button (the last one in the array) is the main button. + +Optionally, a `role` property can be added to a button, such as `cancel`. If a `cancel` role is on one of the buttons, then if the alert is dismissed by tapping the backdrop, then it will fire the handler from the button with a cancel role. + +import Buttons from '@site/static/usage/v8/alert/buttons/index.md'; + + + + +## Inputs + +Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as `url`, `email`, `text`, `textarea` etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead. + +### Text Inputs Example + +import TextInputs from '@site/static/usage/v8/alert/inputs/text-inputs/index.md'; + + + +### Radio Example + +import Radios from '@site/static/usage/v8/alert/inputs/radios/index.md'; + + + +## Customization + +Alert uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. + +We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. + +```css +/* DOES NOT WORK - not specific enough */ +.alert-wrapper { + background: #e5e5e5; +} + +/* Works - pass "my-custom-class" in cssClass to increase specificity */ +.my-custom-class .alert-wrapper { + background: #e5e5e5; +} +``` + +Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Alert without needing to target individual elements: + +```css +.my-custom-class { + --background: #e5e5e5; +} +``` + +import Customization from '@site/static/usage/v8/alert/customization/index.md'; + + + +:::note + If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. +::: + +## Accessibility + +### Screen Readers + +Alerts set aria properties in order to be [accessible](../reference/glossary.mdx#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the alert is being used in an app. + +#### Role + +Ionic automatically sets the Alert's `role` to either [`alertdialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) if there are any inputs or buttons included, or [`alert`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) if there are none. + +#### Alert Description + +If the `header` property is defined for the Alert, the `aria-labelledby` attribute will be automatically set to the header's ID. The `subHeader` element will be used as a fallback if `header` is not defined. Similarly, the `aria-describedby` attribute will be automatically set to the ID of the `message` element if that property is defined. + +It is strongly recommended that your Alert have a `message`, as well as either a `header` or `subHeader`, in order to align with the ARIA spec. If you choose not to include a `header` or `subHeader`, an alternative is to provide a descriptive `aria-label` using the `htmlAttributes` property. + + + + + +```javascript +const alert = await this.alertController.create({ + message: 'This is an alert with custom aria attributes.', + htmlAttributes: { + 'aria-label': 'alert dialog', + }, +}); +``` + + + + + +```javascript +const alert = await this.alertController.create({ + message: 'This is an alert with custom aria attributes.', + htmlAttributes: { + 'aria-label': 'alert dialog', + }, +}); +``` + + + + + +```javascript +useIonAlert({ + message: 'This is an alert with custom aria attributes.', + htmlAttributes: { + 'aria-label': 'alert dialog', + }, +}); +``` + + + + + +```javascript +const alert = await alertController.create({ + message: 'This is an alert with custom aria attributes.', + htmlAttributes: { + 'aria-label': 'alert dialog', + }, +}); +``` + + + + + + +All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert. + +#### Alert Buttons Description + +Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be set on the button by passing `aria-label` to the `htmlAttributes` property on the button. + + + + + +```javascript +const alert = await this.alertController.create({ + header: 'Header', + buttons: [ + { + text: 'Exit', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +const alert = await this.alertController.create({ + header: 'Header', + buttons: [ + { + text: 'Exit', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +useIonAlert({ + header: 'Header', + buttons: [ + { + text: 'Exit', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +```javascript +const alert = await alertController.create({ + header: 'Header', + buttons: [ + { + text: 'Exit', + htmlAttributes: { + 'aria-label': 'close', + }, + }, + ], +}); +``` + + + + + +## Interfaces + +### AlertButton + +```typescript +type AlertButtonOverlayHandler = boolean | void | { [key: string]: any }; + +interface AlertButton { + text: string; + role?: 'cancel' | 'destructive' | string; + cssClass?: string | string[]; + id?: string; + htmlAttributes?: { [key: string]: any }; + handler?: (value: any) => AlertButtonOverlayHandler | Promise; +} +``` + + +### AlertInput + +```typescript +interface AlertInput { + type?: TextFieldTypes | 'checkbox' | 'radio' | 'textarea'; + name?: string; + placeholder?: string; + value?: any; + /** + * The label text to display next to the input, if the input type is `radio` or `checkbox`. + */ + label?: string; + checked?: boolean; + disabled?: boolean; + id?: string; + handler?: (input: AlertInput) => void; + min?: string | number; + max?: string | number; + cssClass?: string | string[]; + attributes?: { [key: string]: any }; + tabindex?: number; +} +``` + + +### AlertOptions + +```typescript +interface AlertOptions { + header?: string; + subHeader?: string; + message?: string | IonicSafeString; + cssClass?: string | string[]; + inputs?: AlertInput[]; + buttons?: (AlertButton | string)[]; + backdropDismiss?: boolean; + translucent?: boolean; + animated?: boolean; + htmlAttributes?: { [key: string]: any }; + + mode?: Mode; + keyboardClose?: boolean; + id?: string; + + enterAnimation?: AnimationBuilder; + leaveAnimation?: AnimationBuilder; +} +``` + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/app.md b/docs/api/app.mdx similarity index 100% rename from docs/api/app.md rename to docs/api/app.mdx diff --git a/docs/api/avatar.md b/docs/api/avatar.mdx similarity index 100% rename from docs/api/avatar.md rename to docs/api/avatar.mdx diff --git a/docs/api/back-button.md b/docs/api/back-button.mdx similarity index 100% rename from docs/api/back-button.md rename to docs/api/back-button.mdx diff --git a/docs/api/backdrop.md b/docs/api/backdrop.mdx similarity index 100% rename from docs/api/backdrop.md rename to docs/api/backdrop.mdx diff --git a/docs/api/badge.md b/docs/api/badge.mdx similarity index 100% rename from docs/api/badge.md rename to docs/api/badge.mdx diff --git a/docs/api/breadcrumb.md b/docs/api/breadcrumb.mdx similarity index 100% rename from docs/api/breadcrumb.md rename to docs/api/breadcrumb.mdx diff --git a/docs/api/breadcrumbs.md b/docs/api/breadcrumbs.mdx similarity index 100% rename from docs/api/breadcrumbs.md rename to docs/api/breadcrumbs.mdx diff --git a/docs/api/button.md b/docs/api/button.mdx similarity index 100% rename from docs/api/button.md rename to docs/api/button.mdx diff --git a/docs/api/buttons.md b/docs/api/buttons.md deleted file mode 100644 index 642354eefc8..00000000000 --- a/docs/api/buttons.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "ion-buttons" ---- -import Props from '@ionic-internal/component-api/v8/buttons/props.md'; -import Events from '@ionic-internal/component-api/v8/buttons/events.md'; -import Methods from '@ionic-internal/component-api/v8/buttons/methods.md'; -import Parts from '@ionic-internal/component-api/v8/buttons/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/buttons/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/buttons/slots.md'; - - - ion-buttons: Toolbar Element with Named Slots for Buttons - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - - -The Buttons component is a container element. It should be used inside of a [toolbar](./toolbar) and can contain several types of buttons, including standard [buttons](./button), [menu buttons](./menu-button), and [back buttons](./back-button). - -## Basic Usage - -import Basic from '@site/static/usage/v8/buttons/basic/index.md'; - - - - -## Buttons Placement - -Buttons can be positioned inside of the toolbar using a named slot. The below chart has a description of each slot. - -| Slot | Description | -|--------------|----------------------------------------------------------------------------------------------------------| -| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | -| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | -| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | -| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | - -import Placement from '@site/static/usage/v8/buttons/placement/index.md'; - - - - -## Types of Buttons - -A button in a toolbar is styled to be clear by default, but this can be changed using the [`fill`](./button#fill) property on the button. The properties included on [back button](./back-button) and [menu button](./menu-button) in this example are for display purposes; see their respective documentation for proper usage. - -import Types from '@site/static/usage/v8/buttons/types/index.md'; - - - - -## Collapsible Buttons - -The `collapse` property can be set on the buttons to collapse them when the header collapses. This is typically used with [collapsible large titles](./title#collapsible-large-titles). - -:::info - -This feature is only available for iOS. - -::: - - -import CollapsibleLargeTitleButtons from '@site/static/usage/v8/title/collapsible-large-title/buttons/index.md'; - - - - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/buttons.mdx b/docs/api/buttons.mdx new file mode 100644 index 00000000000..2c35af96efb --- /dev/null +++ b/docs/api/buttons.mdx @@ -0,0 +1,87 @@ +--- +title: "ion-buttons" +--- +import Props from '@ionic-internal/component-api/v8/buttons/props.md'; +import Events from '@ionic-internal/component-api/v8/buttons/events.md'; +import Methods from '@ionic-internal/component-api/v8/buttons/methods.md'; +import Parts from '@ionic-internal/component-api/v8/buttons/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/buttons/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/buttons/slots.md'; + + + ion-buttons: Toolbar Element with Named Slots for Buttons + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + + +The Buttons component is a container element. It should be used inside of a [toolbar](./toolbar) and can contain several types of buttons, including standard [buttons](./button), [menu buttons](./menu-button), and [back buttons](./back-button). + +## Basic Usage + +import Basic from '@site/static/usage/v8/buttons/basic/index.md'; + + + + +## Buttons Placement + +Buttons can be positioned inside of the toolbar using a named slot. The below chart has a description of each slot. + +| Slot | Description | +|--------------|----------------------------------------------------------------------------------------------------------| +| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | +| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | +| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | +| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | + +import Placement from '@site/static/usage/v8/buttons/placement/index.md'; + + + + +## Types of Buttons + +A button in a toolbar is styled to be clear by default, but this can be changed using the [`fill`](./button#fill) property on the button. The properties included on [back button](./back-button) and [menu button](./menu-button) in this example are for display purposes; see their respective documentation for proper usage. + +import Types from '@site/static/usage/v8/buttons/types/index.md'; + + + + +## Collapsible Buttons + +The `collapse` property can be set on the buttons to collapse them when the header collapses. This is typically used with [collapsible large titles](./title#collapsible-large-titles). + +:::info + +This feature is only available for iOS. + +::: + +{/* Reuse the playground from the Title directory */} +import CollapsibleLargeTitleButtons from '@site/static/usage/v8/title/collapsible-large-title/buttons/index.md'; + + + + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/card-content.md b/docs/api/card-content.mdx similarity index 100% rename from docs/api/card-content.md rename to docs/api/card-content.mdx diff --git a/docs/api/card-header.md b/docs/api/card-header.mdx similarity index 100% rename from docs/api/card-header.md rename to docs/api/card-header.mdx diff --git a/docs/api/card-subtitle.md b/docs/api/card-subtitle.mdx similarity index 100% rename from docs/api/card-subtitle.md rename to docs/api/card-subtitle.mdx diff --git a/docs/api/card-title.md b/docs/api/card-title.mdx similarity index 100% rename from docs/api/card-title.md rename to docs/api/card-title.mdx diff --git a/docs/api/card.md b/docs/api/card.mdx similarity index 100% rename from docs/api/card.md rename to docs/api/card.mdx diff --git a/docs/api/checkbox.md b/docs/api/checkbox.mdx similarity index 100% rename from docs/api/checkbox.md rename to docs/api/checkbox.mdx diff --git a/docs/api/chip.md b/docs/api/chip.mdx similarity index 100% rename from docs/api/chip.md rename to docs/api/chip.mdx diff --git a/docs/api/col.md b/docs/api/col.md deleted file mode 100644 index ebc54b7f02f..00000000000 --- a/docs/api/col.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "ion-col" ---- -import Props from '@ionic-internal/component-api/v8/col/props.md'; -import Events from '@ionic-internal/component-api/v8/col/events.md'; -import Methods from '@ionic-internal/component-api/v8/col/methods.md'; -import Parts from '@ionic-internal/component-api/v8/col/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/col/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/col/slots.md'; - - - ion-col: Column Component Padding and Other Properties - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - - -Columns are cellular components of the [grid](./grid) system and go inside of a [row](./row). They will expand to fill the row. All content within a grid should go inside of a column. - -See the [grid](./grid) documentation for more information. - - -## Column Alignment - -By default, columns will stretch to fill the entire height of the row. Columns are [flex items](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Item), so there are several [CSS classes](/docs/layout/css-utilities#flex-item-properties) that can be applied to a column to customize this behavior. - - - - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/col.mdx b/docs/api/col.mdx new file mode 100644 index 00000000000..0a201dfa091 --- /dev/null +++ b/docs/api/col.mdx @@ -0,0 +1,49 @@ +--- +title: "ion-col" +--- +import Props from '@ionic-internal/component-api/v8/col/props.md'; +import Events from '@ionic-internal/component-api/v8/col/events.md'; +import Methods from '@ionic-internal/component-api/v8/col/methods.md'; +import Parts from '@ionic-internal/component-api/v8/col/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/col/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/col/slots.md'; + + + ion-col: Column Component Padding and Other Properties + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + + +Columns are cellular components of the [grid](./grid) system and go inside of a [row](./row). They will expand to fill the row. All content within a grid should go inside of a column. + +See the [grid](./grid) documentation for more information. + + +## Column Alignment + +By default, columns will stretch to fill the entire height of the row. Columns are [flex items](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Item), so there are several [CSS classes](/docs/layout/css-utilities.mdx#flex-item-properties) that can be applied to a column to customize this behavior. + + + + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/content.md b/docs/api/content.md deleted file mode 100644 index 832e22cd9d1..00000000000 --- a/docs/api/content.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: "ion-content" ---- -import Props from '@ionic-internal/component-api/v8/content/props.md'; -import Events from '@ionic-internal/component-api/v8/content/events.md'; -import Methods from '@ionic-internal/component-api/v8/content/methods.md'; -import Parts from '@ionic-internal/component-api/v8/content/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/content/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/content/slots.md'; - - - ion-content: Scrollable Component for Ionic App Content - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - - -The content component provides an easy to use content area with some useful methods -to control the scrollable area. There should only be one content in a single -view. - -Content, along with many other Ionic components, can be customized to modify its padding, margin, and more using the global styles provided in the [CSS Utilities](/docs/layout/css-utilities) or by individually styling it using CSS and the available [CSS Custom Properties](#css-custom-properties). - - -## Basic Usage - -import Basic from '@site/static/usage/v8/content/basic/index.md'; - - - - -## Header & Footer - -Content can be the only top-level component in a page, or it can be used alongside a [header](./header), [footer](./footer), or both. When used with a header or footer, it will adjust its size to fill the remaining height. - -import HeaderFooter from '@site/static/usage/v8/content/header-footer/index.md'; - - - - -## Fullscreen Content - -By default, content fills the space between a [header](./header) and [footer](./footer) but does not go behind them. In certain cases, it may be desired to have the content scroll behind the header and footer, such as when the `translucent` property is set on either of them, or `opacity` is set on the toolbar. This can be achieved by setting the `fullscreen` property on the content to `true`. - -import Fullscreen from '@site/static/usage/v8/content/fullscreen/index.md'; - - - - -## Fixed Content - -To place elements outside of the scrollable area, assign them to the `fixed` slot. Doing so will [absolutely position](https://developer.mozilla.org/en-US/docs/Web/CSS/position#absolute_positioning) the element to the top left of the content. In order to change the position of the element, it can be styled using the [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS properties. - -import Fixed from '@site/static/usage/v8/content/fixed/index.md'; - - - -## Scroll Methods - -Content provides [methods](#methods) that can be called to scroll the content to the bottom, top, or to a specific point. They can be passed a `duration` in order to smoothly transition instead of instantly changing the position. - -import ScrollMethods from '@site/static/usage/v8/content/scroll-methods/index.md'; - - - -## Scroll Events - -Scroll events are disabled by default for content due to performance. However, they can be enabled by setting `scrollEvents` to `true`. This is necessary before listening to any of the scroll [events](#events). - -import ScrollEvents from '@site/static/usage/v8/content/scroll-events/index.md'; - - - - -## Theming - -### Colors - -import Colors from '@site/static/usage/v8/content/theming/colors/index.md'; - - - -### CSS Shadow Parts - -import CSSParts from '@site/static/usage/v8/content/theming/css-shadow-parts/index.md'; - - - -### CSS Custom Properties - -import CSSProps from '@site/static/usage/v8/content/theming/css-properties/index.md'; - - - -### Safe Area Padding - -The content component will not automatically apply padding to any of its sides to account for the [safe area](/docs/theming/advanced#safe-area-padding). This is because the content component is often used in conjunction with other components that apply their own padding, such as [headers](./header) and [footers](./footer). However, if the content component is being used on its own, it may be desired to apply padding to the safe area. This can be done through CSS by using the `--ion-safe-area-(dir)` variables described in [Application Variables](../theming/advanced.md#application-variables). - -The most common use case for this is to apply padding to the top of the content to account for the status bar. This can be done by setting the `padding-top` property to the value of the `--ion-safe-area-top` variable. - -```css -ion-content::part(scroll) { - padding-top: var(--ion-safe-area-top, 0); -} -``` - -Another common use case is to apply padding to the left side of the content to account for the notch when the device is in landscape mode and the notch is on the left side. This can be done by setting the `padding-left` property to the value of the `--ion-safe-area-left` variable. - -```css -ion-content::part(scroll) { - padding-left: var(--ion-safe-area-left, 0); -} -``` - -import SafeArea from '@site/static/usage/v8/content/theming/safe-area/index.md'; - - - -## Interfaces - -### ScrollBaseDetail - -```typescript -interface ScrollBaseDetail { - isScrolling: boolean; -} -``` - -### ScrollDetail - -```typescript -interface ScrollDetail extends GestureDetail, ScrollBaseDetail { - scrollTop: number; - scrollLeft: number; -} -``` - -### ScrollBaseCustomEvent - -While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScrollStart` and `ionScrollEnd` events. - -```typescript -interface ScrollBaseCustomEvent extends CustomEvent { - detail: ScrollBaseDetail; - target: HTMLIonContentElement; -} -``` - -### ScrollCustomEvent - -While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScroll` event. - -```typescript -interface ScrollCustomEvent extends ScrollBaseCustomEvent { - detail: ScrollDetail; -} -``` - - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/content.mdx b/docs/api/content.mdx new file mode 100644 index 00000000000..10219dec0dd --- /dev/null +++ b/docs/api/content.mdx @@ -0,0 +1,179 @@ +--- +title: "ion-content" +--- +import Props from '@ionic-internal/component-api/v8/content/props.md'; +import Events from '@ionic-internal/component-api/v8/content/events.md'; +import Methods from '@ionic-internal/component-api/v8/content/methods.md'; +import Parts from '@ionic-internal/component-api/v8/content/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/content/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/content/slots.md'; + + + ion-content: Scrollable Component for Ionic App Content + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + + +The content component provides an easy to use content area with some useful methods +to control the scrollable area. There should only be one content in a single +view. + +Content, along with many other Ionic components, can be customized to modify its padding, margin, and more using the global styles provided in the [CSS Utilities](/docs/layout/css-utilities.mdx) or by individually styling it using CSS and the available [CSS Custom Properties](#css-custom-properties). + + +## Basic Usage + +import Basic from '@site/static/usage/v8/content/basic/index.md'; + + + + +## Header & Footer + +Content can be the only top-level component in a page, or it can be used alongside a [header](./header), [footer](./footer), or both. When used with a header or footer, it will adjust its size to fill the remaining height. + +import HeaderFooter from '@site/static/usage/v8/content/header-footer/index.md'; + + + + +## Fullscreen Content + +By default, content fills the space between a [header](./header) and [footer](./footer) but does not go behind them. In certain cases, it may be desired to have the content scroll behind the header and footer, such as when the `translucent` property is set on either of them, or `opacity` is set on the toolbar. This can be achieved by setting the `fullscreen` property on the content to `true`. + +import Fullscreen from '@site/static/usage/v8/content/fullscreen/index.md'; + + + + +## Fixed Content + +To place elements outside of the scrollable area, assign them to the `fixed` slot. Doing so will [absolutely position](https://developer.mozilla.org/en-US/docs/Web/CSS/position#absolute_positioning) the element to the top left of the content. In order to change the position of the element, it can be styled using the [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS properties. + +import Fixed from '@site/static/usage/v8/content/fixed/index.md'; + + + +## Scroll Methods + +Content provides [methods](#methods) that can be called to scroll the content to the bottom, top, or to a specific point. They can be passed a `duration` in order to smoothly transition instead of instantly changing the position. + +import ScrollMethods from '@site/static/usage/v8/content/scroll-methods/index.md'; + + + +## Scroll Events + +Scroll events are disabled by default for content due to performance. However, they can be enabled by setting `scrollEvents` to `true`. This is necessary before listening to any of the scroll [events](#events). + +import ScrollEvents from '@site/static/usage/v8/content/scroll-events/index.md'; + + + + +## Theming + +### Colors + +import Colors from '@site/static/usage/v8/content/theming/colors/index.md'; + + + +### CSS Shadow Parts + +import CSSParts from '@site/static/usage/v8/content/theming/css-shadow-parts/index.md'; + + + +### CSS Custom Properties + +import CSSProps from '@site/static/usage/v8/content/theming/css-properties/index.md'; + + + +### Safe Area Padding + +The content component will not automatically apply padding to any of its sides to account for the [safe area](/docs/theming/advanced.mdx#safe-area-padding). This is because the content component is often used in conjunction with other components that apply their own padding, such as [headers](./header) and [footers](./footer). However, if the content component is being used on its own, it may be desired to apply padding to the safe area. This can be done through CSS by using the `--ion-safe-area-(dir)` variables described in [Application Variables](../theming/advanced.mdx#application-variables). + +The most common use case for this is to apply padding to the top of the content to account for the status bar. This can be done by setting the `padding-top` property to the value of the `--ion-safe-area-top` variable. + +```css +ion-content::part(scroll) { + padding-top: var(--ion-safe-area-top, 0); +} +``` + +Another common use case is to apply padding to the left side of the content to account for the notch when the device is in landscape mode and the notch is on the left side. This can be done by setting the `padding-left` property to the value of the `--ion-safe-area-left` variable. + +```css +ion-content::part(scroll) { + padding-left: var(--ion-safe-area-left, 0); +} +``` + +import SafeArea from '@site/static/usage/v8/content/theming/safe-area/index.md'; + + + +## Interfaces + +### ScrollBaseDetail + +```typescript +interface ScrollBaseDetail { + isScrolling: boolean; +} +``` + +### ScrollDetail + +```typescript +interface ScrollDetail extends GestureDetail, ScrollBaseDetail { + scrollTop: number; + scrollLeft: number; +} +``` + +### ScrollBaseCustomEvent + +While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScrollStart` and `ionScrollEnd` events. + +```typescript +interface ScrollBaseCustomEvent extends CustomEvent { + detail: ScrollBaseDetail; + target: HTMLIonContentElement; +} +``` + +### ScrollCustomEvent + +While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScroll` event. + +```typescript +interface ScrollCustomEvent extends ScrollBaseCustomEvent { + detail: ScrollDetail; +} +``` + + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/datetime-button.md b/docs/api/datetime-button.md deleted file mode 100644 index 361a1c9c8f1..00000000000 --- a/docs/api/datetime-button.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "ion-datetime-button" ---- -import Props from '@ionic-internal/component-api/v8/datetime-button/props.md'; -import Events from '@ionic-internal/component-api/v8/datetime-button/events.md'; -import Methods from '@ionic-internal/component-api/v8/datetime-button/methods.md'; -import Parts from '@ionic-internal/component-api/v8/datetime-button/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/datetime-button/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/datetime-button/slots.md'; - - - ion-datetime-button: Ionic Input for Datetime Picker - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - -Datetime Button links with a [Datetime](./datetime) component to display the formatted date and time. It also provides buttons to present the datetime in a modal, popover, and more. - -## Overview - -Datetime Button should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay. - -When using Datetime Button with a JavaScript framework such as Angular, React, or Vue be sure to use the [keepContentsMounted property on ion-modal](./modal#keepcontentsmounted) or the [keepContentsMounted property on ion-popover](./popover#keepcontentsmounted). This allows the linked datetime instance to be mounted even if the overlay has not been presented yet. - -## Basic Usage - -import Basic from '@site/static/usage/v8/datetime-button/basic/index.md'; - - - -## Localization - -The localized text on `ion-datetime-button` is determined by the `locale` property on the associated `ion-datetime` instance. See [Datetime Localization](./datetime#localization) for more details. - -## Format Options - -You can customize the format of the date and time in a Datetime Button by providing `formatOptions` on the associated Datetime instance. See [Datetime Format Options](./datetime#format-options) for more details. - -import FormatOptions from '@site/static/usage/v8/datetime-button/format-options/index.md'; - - - -## Usage with Modals and Popovers - -`ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used. - - - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - diff --git a/docs/api/datetime-button.mdx b/docs/api/datetime-button.mdx new file mode 100644 index 00000000000..cdb7aadc02c --- /dev/null +++ b/docs/api/datetime-button.mdx @@ -0,0 +1,78 @@ +--- +title: "ion-datetime-button" +--- +import Props from '@ionic-internal/component-api/v8/datetime-button/props.md'; +import Events from '@ionic-internal/component-api/v8/datetime-button/events.md'; +import Methods from '@ionic-internal/component-api/v8/datetime-button/methods.md'; +import Parts from '@ionic-internal/component-api/v8/datetime-button/parts.md'; +import CustomProps from '@ionic-internal/component-api/v8/datetime-button/custom-props.md'; +import Slots from '@ionic-internal/component-api/v8/datetime-button/slots.md'; + + + ion-datetime-button: Ionic Input for Datetime Picker + + + +import EncapsulationPill from '@components/page/api/EncapsulationPill'; + + + +Datetime Button links with a [Datetime](./datetime) component to display the formatted date and time. It also provides buttons to present the datetime in a modal, popover, and more. + +## Overview + +Datetime Button should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay. + +When using Datetime Button with a JavaScript framework such as Angular, React, or Vue be sure to use the [keepContentsMounted property on ion-modal](./modal#keepcontentsmounted) or the [keepContentsMounted property on ion-popover](./popover#keepcontentsmounted). This allows the linked datetime instance to be mounted even if the overlay has not been presented yet. + +## Basic Usage + +import Basic from '@site/static/usage/v8/datetime-button/basic/index.md'; + + + +## Localization + +The localized text on `ion-datetime-button` is determined by the `locale` property on the associated `ion-datetime` instance. See [Datetime Localization](./datetime#localization) for more details. + +## Format Options + +You can customize the format of the date and time in a Datetime Button by providing `formatOptions` on the associated Datetime instance. See [Datetime Format Options](./datetime#format-options) for more details. + +import FormatOptions from '@site/static/usage/v8/datetime-button/format-options/index.md'; + + + +## Usage with Modals and Popovers + +`ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used. + +{/* ## Customization + +TODO + +### Buttons + +TODO + +### Theming + +TODO */} + +## Properties + + +## Events + + +## Methods + + +## CSS Shadow Parts + + +## CSS Custom Properties + + +## Slots + diff --git a/docs/api/datetime.md b/docs/api/datetime.md deleted file mode 100644 index a820311f1b3..00000000000 --- a/docs/api/datetime.md +++ /dev/null @@ -1,492 +0,0 @@ ---- -title: "ion-datetime" ---- -import Props from '@ionic-internal/component-api/v8/datetime/props.md'; -import Events from '@ionic-internal/component-api/v8/datetime/events.md'; -import Methods from '@ionic-internal/component-api/v8/datetime/methods.md'; -import Parts from '@ionic-internal/component-api/v8/datetime/parts.md'; -import CustomProps from '@ionic-internal/component-api/v8/datetime/custom-props.md'; -import Slots from '@ionic-internal/component-api/v8/datetime/slots.md'; - -import Basic from '@site/static/usage/v8/datetime/basic/index.md'; - -import MaxMin from '@site/static/usage/v8/datetime/date-constraints/max-min/index.md'; -import Values from '@site/static/usage/v8/datetime/date-constraints/values/index.md'; -import Advanced from '@site/static/usage/v8/datetime/date-constraints/advanced/index.md'; - -import FormatOptions from '@site/static/usage/v8/datetime/format-options/index.md'; - -import CustomLocale from '@site/static/usage/v8/datetime/localization/custom-locale/index.md'; -import HourCycle from '@site/static/usage/v8/datetime/localization/hour-cycle/index.md'; -import FirstDayOfWeek from '@site/static/usage/v8/datetime/localization/first-day-of-week/index.md'; -import LocaleExtensionTags from '@site/static/usage/v8/datetime/localization/locale-extension-tags/index.md'; -import TimeLabel from '@site/static/usage/v8/datetime/localization/time-label/index.md'; - -import MonthAndYear from '@site/static/usage/v8/datetime/presentation/month-and-year/index.md'; -import Time from '@site/static/usage/v8/datetime/presentation/time/index.md'; -import Date from '@site/static/usage/v8/datetime/presentation/date/index.md'; - -import ShowingDefaultTitle from '@site/static/usage/v8/datetime/title/showing-default-title/index.md'; -import CustomizingTitle from '@site/static/usage/v8/datetime/title/customizing-title/index.md'; - -import ShowingConfirmationButtons from '@site/static/usage/v8/datetime/buttons/showing-confirmation-buttons/index.md'; -import CustomizingButtons from '@site/static/usage/v8/datetime/buttons/customizing-buttons/index.md'; -import CustomizingButtonTexts from '@site/static/usage/v8/datetime/buttons/customizing-button-texts/index.md'; - -import HighlightedDatesArray from '@site/static/usage/v8/datetime/highlightedDates/array/index.md'; -import HighlightedDatesCallback from '@site/static/usage/v8/datetime/highlightedDates/callback/index.md'; - -import MultipleDateSelection from '@site/static/usage/v8/datetime/multiple/index.md'; - -import GlobalTheming from '@site/static/usage/v8/datetime/styling/global-theming/index.md'; -import CalendarDaysStyling from '@site/static/usage/v8/datetime/styling/calendar-days/index.md'; -import WheelStyling from '@site/static/usage/v8/datetime/styling/wheel-styling/index.md'; - - - ion-datetime: Ionic API Input for Datetime Format Picker - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; - - - -Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values. - -## Overview - -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. - -Fortunately, Ionic Framework's datetime input has been designed so developers can avoid -the common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience. - -### ISO 8601 Datetime Format: `YYYY-MM-DDTHH:mmZ` - -Ionic Framework 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. Using the ISO datetime format makes it easy to serialize -and parse within JSON objects and databases. - -Below are some examples of ISO 8601 formats that can be used with `ion-datetime`: - -| 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:ssZ` | `1994-12-15T13:47:20Z` | -| Timezone Offset | `YYYY-MM-DDTHH:mm:ssTZD` | `1994-12-15T13:47:20+05:00` | -| Hour and Minute | `HH:mm` | `13:47` | - -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`. - -:::note -While seconds, milliseconds, and time zone can be specified using the ISO 8601 datetime format, `ion-datetime` does not provide an interface for second, millisecond, and time zone selection. Any second, millisecond, or time zone values provided will be ignored. -::: - -## Basic Usage - - - -## Usage with Datetime Button - -If you need to present a datetime in an overlay such as a modal or a popover, we recommend using [ion-datetime-button](./datetime-button). `ion-datetime-button` should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay. - -## Setting Values Asynchronously - -If its `value` is updated programmatically after a datetime has already been created, the datetime will automatically jump to the new date. However, it is recommended to avoid updating the `value` in this way when users are able to interact with the datetime, as this could be disorienting for those currently trying to select a date. For example, if a datetime's `value` is loaded by an asynchronous process, it is recommended to hide the datetime with CSS until the value has finished updating. - -## Date Constraints - -### Max and Min Dates - -To customize the minimum and maximum datetime values, the `min` and `max` component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. - -The following example restricts date selection to March 2022 through May 2022 only. - - - -### Selecting Specific Values - -While the `min` and `max` properties allow you to restrict date selection to a certain range, the `monthValues`, `dayValues`, `yearValues`, `hourValues`, and `minuteValues` properties allow you choose specific days and times that users can select. - -The following example allows minutes to be selected in increments of 15. It also allows for days to be selected in increments of 5. - - - -### Advanced Date Constraints - -With the `isDateEnabled` property, developers can customize the `ion-datetime` to disable a specific day, range of dates, weekends or any custom rule using an ISO 8601 date string. -The `isDateEnabled` property accepts a function returning a boolean, indicating if a date is enabled. The function is called for each rendered calendar day, for the previous, current and next month. Custom implementations should be optimized for performance to avoid jank. - -The following example shows how to disable all weekend dates. For more advanced date manipulation, we recommend using a date utility such as `date-fns`. - - - -## Localization - -Ionic Framework makes use of the [Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device. - -### Custom Locale - -For instances where you need a specific locale, you can use the `locale` property to set it. The locale controls both the language and the date and time formats that are displayed. - -The following example shows how to set the locale to Spanish (Spain). - - - -:::note -The time label is not automatically localized. See [Time Label](#time-label) for more information. -::: - -### Hour Cycle - -`ion-datetime` will use the hour cycle that is specified by the `locale` property by default. For example, if `locale` is set to `en-US`, then `ion-datetime` will use a 12 hour cycle. - -There are 4 primary hour cycle types: - -| Hour cycle type | Description | -| --------------- | ------------------------------------------------------------ | -| `'h12'` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. | -| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. | -| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. | -| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | - -:::note - Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle -::: - - -There may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help. - -In the following example, we can use the `hourCycle` property to force `ion-datetime` to use the 12 hour cycle even though the locale is `en-GB`, which uses a 24 hour cycle by default: - - - -### First Day of the Week - -For `ion-datetime`, the default first day of the week is Sunday. As of 2022, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (see: [TC39 GitHub](https://github.com/tc39/ecma402/issues/6)). - - - -### Time Label - -The time label is not automatically localized. Fortunately, Ionic makes it easy to provide custom localizations with the `time-label` slot. - - - -### Locale Extension Tags - -`ion-datetime` also supports [locale extension tags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) as part of the `Intl.Locale` API. These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the [Intl.Locale API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) in their apps. - -For example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you could provide extension tags instead of using both the `locale` and `hourCycle` properties: - - - -:::note -Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. -::: - -## Presentation - -By default, `ion-datetime` allows users to select both date and time. In addition, users have access to selecting the specific month, year, hour, and minute. - -Some use cases may call for only date selection or only time selection. The `presentation` property allows you to specify which pickers to show and the order to show them in. For example, setting `date-time` will have the calendar picker appear before the time picker. Setting `time-date` will have the calendar picker appear after the time picker. - -### Month and Year Selection - -Month and year selection is available by passing `month-year`, `year-month`, `month`, or `year` to the `presentation` property. - -This example shows a datetime with the `month-year` configuration. - - - -### Time Selection - -Time selection is available by passing `date-time`, `time-date`, or `time` to the `presentation` property. - -This example shows a datetime with the `time` configuration. - -