diff --git a/docs/api/nav.md b/docs/api/nav.md index 5e649ae8912..90b3bf8114c 100644 --- a/docs/api/nav.md +++ b/docs/api/nav.md @@ -1,6 +1,5 @@ --- title: "ion-nav" -hide_table_of_contents: true --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -22,24 +21,10 @@ import APITOCInline from '@components/page/api/APITOCInline'; -

Contents

- - - - - Nav is a standalone component for loading arbitrary components and pushing new components on to the stack. Unlike Router Outlet, Nav is not tied to a particular router. This means that if we load a Nav component, and push other components to the stack, they will not affect the app's overall router. This fits use cases where you could have a modal, which needs its own sub-navigation, without making it tied to the apps URL. -## Using NavController - -TODO: Playground Example - ## Using NavLink NavLink is a simplified API when interacting with Nav. Developers can customize the component, pass along component properties, modify the direction of the route animation or define a custom animation when navigating. @@ -50,15 +35,17 @@ import NavLinkExample from '@site/static/usage/nav/nav-link/index.md'; ## Navigation within a Modal -TODO: Playground Example +Modal can use Nav to offer a linear navigation that is independent of the URL. + +:::note -## Animations +The example below uses a reference to Nav and the public method APIs to push and pop views. It is recommended to use NavLink in implementations that do not require this level of granular access and control. -TODO: Playground Example +::: -## Event Handling +import ModalNavigationExample from '@site/static/usage/nav/modal-navigation/index.md'; -TODO: Playground Example + ## Interfaces diff --git a/static/code/stackblitz/react/package-lock.json b/static/code/stackblitz/react/package-lock.json index 4531aeadb45..614b0d32709 100644 --- a/static/code/stackblitz/react/package-lock.json +++ b/static/code/stackblitz/react/package-lock.json @@ -8,7 +8,7 @@ "name": "create-react-app-typescript", "version": "0.1.0", "dependencies": { - "@ionic/react": "^6.0.0", + "@ionic/react": "^6.2.0", "@types/node": "^16.11.35", "@types/react": "^18.0.9", "@types/react-dom": "^18.0.4", @@ -2187,9 +2187,9 @@ "integrity": "sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA==" }, "node_modules/@ionic/core": { - "version": "6.1.10", - "resolved": "https://registry.npmjs.org/@ionic/core/-/core-6.1.10.tgz", - "integrity": "sha512-QmQvIe+IklQhNhbq438I3eCnL6XjfTxrgO1+paOdGNKk3R3o4mqJmV0YYT5r9iwnieHgDxKbo3ovs9UnTXhI7g==", + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/@ionic/core/-/core-6.2.2.tgz", + "integrity": "sha512-neE+JhtQ7Kb4nGoKR3e55edHQot5BZTw+woV9+pbyCXP1jGeyFeWWPYBYYOkm05TSEkHgh0v6NkV9y31k8GTNw==", "dependencies": { "@stencil/core": "^2.16.0", "ionicons": "^6.0.2", @@ -2197,11 +2197,11 @@ } }, "node_modules/@ionic/react": { - "version": "6.1.10", - "resolved": "https://registry.npmjs.org/@ionic/react/-/react-6.1.10.tgz", - "integrity": "sha512-3XivIon+43cD0QLBAkfi9+9BX0tFL1P0g34Og+DStHdXXtDBgSwqqVW8P96K45uRb7gZuBx9bccb9z9ntOCcig==", + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/@ionic/react/-/react-6.2.2.tgz", + "integrity": "sha512-CRuDJbNDn9bbDba37/5v9aZ2gd450XGklGqXmsxEfadh1iq7iWmqcgw14S0ZDAXQt0aE/J+TeKhTyjyutjsAww==", "dependencies": { - "@ionic/core": "^6.1.10", + "@ionic/core": "^6.2.2", "ionicons": "^6.0.2", "tslib": "*" }, @@ -3124,9 +3124,9 @@ } }, "node_modules/@stencil/core": { - "version": "2.16.1", - "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.16.1.tgz", - "integrity": "sha512-s/UJp9qxExL3DyQPT70kiuWeb3AdjbUZM+5lEIXn30I2DLcLYPOPXfsoWJODieQywq+3vPiLZeIdkoqjf6jcSw==", + "version": "2.17.3", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.17.3.tgz", + "integrity": "sha512-qw2DZzOpyaltLLEfYRTj3n+XbvRtkmv4QQimYDJubC6jMY0NXK9r6H2+VyszdbbVmvK1D9GqZtyvY0NmOrztsg==", "bin": { "stencil": "bin/stencil" }, @@ -8307,6 +8307,18 @@ "@stencil/core": "~2.16.0" } }, + "node_modules/ionicons/node_modules/@stencil/core": { + "version": "2.16.1", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.16.1.tgz", + "integrity": "sha512-s/UJp9qxExL3DyQPT70kiuWeb3AdjbUZM+5lEIXn30I2DLcLYPOPXfsoWJODieQywq+3vPiLZeIdkoqjf6jcSw==", + "bin": { + "stencil": "bin/stencil" + }, + "engines": { + "node": ">=12.10.0", + "npm": ">=6.0.0" + } + }, "node_modules/ipaddr.js": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-2.0.1.tgz", @@ -17539,9 +17551,9 @@ "integrity": "sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA==" }, "@ionic/core": { - "version": "6.1.10", - "resolved": "https://registry.npmjs.org/@ionic/core/-/core-6.1.10.tgz", - "integrity": "sha512-QmQvIe+IklQhNhbq438I3eCnL6XjfTxrgO1+paOdGNKk3R3o4mqJmV0YYT5r9iwnieHgDxKbo3ovs9UnTXhI7g==", + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/@ionic/core/-/core-6.2.2.tgz", + "integrity": "sha512-neE+JhtQ7Kb4nGoKR3e55edHQot5BZTw+woV9+pbyCXP1jGeyFeWWPYBYYOkm05TSEkHgh0v6NkV9y31k8GTNw==", "requires": { "@stencil/core": "^2.16.0", "ionicons": "^6.0.2", @@ -17549,11 +17561,11 @@ } }, "@ionic/react": { - "version": "6.1.10", - "resolved": "https://registry.npmjs.org/@ionic/react/-/react-6.1.10.tgz", - "integrity": "sha512-3XivIon+43cD0QLBAkfi9+9BX0tFL1P0g34Og+DStHdXXtDBgSwqqVW8P96K45uRb7gZuBx9bccb9z9ntOCcig==", + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/@ionic/react/-/react-6.2.2.tgz", + "integrity": "sha512-CRuDJbNDn9bbDba37/5v9aZ2gd450XGklGqXmsxEfadh1iq7iWmqcgw14S0ZDAXQt0aE/J+TeKhTyjyutjsAww==", "requires": { - "@ionic/core": "^6.1.10", + "@ionic/core": "^6.2.2", "ionicons": "^6.0.2", "tslib": "*" } @@ -18218,9 +18230,9 @@ } }, "@stencil/core": { - "version": "2.16.1", - "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.16.1.tgz", - "integrity": "sha512-s/UJp9qxExL3DyQPT70kiuWeb3AdjbUZM+5lEIXn30I2DLcLYPOPXfsoWJODieQywq+3vPiLZeIdkoqjf6jcSw==" + "version": "2.17.3", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.17.3.tgz", + "integrity": "sha512-qw2DZzOpyaltLLEfYRTj3n+XbvRtkmv4QQimYDJubC6jMY0NXK9r6H2+VyszdbbVmvK1D9GqZtyvY0NmOrztsg==" }, "@surma/rollup-plugin-off-main-thread": { "version": "2.2.3", @@ -21996,6 +22008,13 @@ "integrity": "sha512-AyKfFaUKVoBz4eB8XkU7H1R5HFnVsgq5ijqSdbXC0lES9PDK/J6LUQz6XUJq0mVVQF5k9kczSPOLMW3mszG0mQ==", "requires": { "@stencil/core": "~2.16.0" + }, + "dependencies": { + "@stencil/core": { + "version": "2.16.1", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.16.1.tgz", + "integrity": "sha512-s/UJp9qxExL3DyQPT70kiuWeb3AdjbUZM+5lEIXn30I2DLcLYPOPXfsoWJODieQywq+3vPiLZeIdkoqjf6jcSw==" + } } }, "ipaddr.js": { diff --git a/static/usage/nav/modal-navigation/angular/app_component_html.md b/static/usage/nav/modal-navigation/angular/app_component_html.md new file mode 100644 index 00000000000..0a41e05a60c --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/app_component_html.md @@ -0,0 +1,25 @@ +```html + + + Modal Navigation + + + + Open Modal + + + + + Modal + + Close + + + + + + + + + +``` diff --git a/static/usage/nav/modal-navigation/angular/app_component_ts.md b/static/usage/nav/modal-navigation/angular/app_component_ts.md new file mode 100644 index 00000000000..4d5bc2bd1c5 --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/app_component_ts.md @@ -0,0 +1,18 @@ +```ts +import { Component, ViewChild } from '@angular/core'; +import { IonNav } from '@ionic/angular'; + +import { PageOneComponent } from './page-one.component'; + +@Component({ + selector: 'app-root', + templateUrl: 'app.component.html', +}) +export class AppComponent { + @ViewChild('nav') private nav: IonNav; + + onWillPresent() { + this.nav.setRoot(PageOneComponent); + } +} +``` diff --git a/static/usage/nav/modal-navigation/angular/app_module_ts.md b/static/usage/nav/modal-navigation/angular/app_module_ts.md new file mode 100644 index 00000000000..17eb272293f --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/app_module_ts.md @@ -0,0 +1,20 @@ +```ts +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; +import { RouterModule } from '@angular/router'; + +import { IonicModule } from '@ionic/angular'; + +import { AppComponent } from './app.component'; + +import { PageOneComponent } from './page-one.component'; +import { PageTwoComponent } from './page-two.component'; +import { PageThreeComponent } from './page-three.component'; + +@NgModule({ + imports: [BrowserModule, RouterModule.forRoot([]), IonicModule.forRoot({})], + declarations: [AppComponent, PageOneComponent, PageTwoComponent, PageThreeComponent], + bootstrap: [AppComponent], +}) +export class AppModule {} +``` diff --git a/static/usage/nav/modal-navigation/angular/page_one_component_ts.md b/static/usage/nav/modal-navigation/angular/page_one_component_ts.md new file mode 100644 index 00000000000..3c9ec863d04 --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/page_one_component_ts.md @@ -0,0 +1,23 @@ +```ts +import { Component } from '@angular/core'; +import { IonNav } from '@ionic/angular'; + +import { PageTwoComponent } from './page-two.component'; + +@Component({ + selector: 'app-page-one', + template: ` + +

Page One

+ Go to Page Two + + `, +}) +export class PageOneComponent { + constructor(private nav: IonNav) {} + + navigateToPageTwo() { + this.nav.push(PageTwoComponent); + } +} +``` diff --git a/static/usage/nav/modal-navigation/angular/page_three_component_ts.md b/static/usage/nav/modal-navigation/angular/page_three_component_ts.md new file mode 100644 index 00000000000..5b1b70c3474 --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/page_three_component_ts.md @@ -0,0 +1,26 @@ +```ts +import { Component } from '@angular/core'; +import { IonNav } from '@ionic/angular'; + +@Component({ + selector: 'app-page-one', + template: ` + +

Page Three

+ Go Back + Go to Root + + `, +}) +export class PageThreeComponent { + constructor(private nav: IonNav) {} + + navigateBack() { + this.nav.pop(); + } + + navigateToRoot() { + this.nav.popToRoot(); + } +} +``` diff --git a/static/usage/nav/modal-navigation/angular/page_two_component_ts.md b/static/usage/nav/modal-navigation/angular/page_two_component_ts.md new file mode 100644 index 00000000000..0cd5713c062 --- /dev/null +++ b/static/usage/nav/modal-navigation/angular/page_two_component_ts.md @@ -0,0 +1,25 @@ +```ts +import { Component } from '@angular/core'; +import { IonNav } from '@ionic/angular'; + +import { PageThreeComponent } from './page-three.component'; + +@Component({ + selector: 'app-page-two', + template: ` + +

Page Two

+ Go to Page Three + + `, +}) +export class PageTwoComponent { + component = PageThreeComponent; + + constructor(private nav: IonNav) {} + + navigateToPageThree() { + this.nav.push(PageThreeComponent); + } +} +``` diff --git a/static/usage/nav/modal-navigation/demo.html b/static/usage/nav/modal-navigation/demo.html new file mode 100644 index 00000000000..9ef92b54a39 --- /dev/null +++ b/static/usage/nav/modal-navigation/demo.html @@ -0,0 +1,106 @@ + + + + + + + + Nav | Modal Navigation + + + + + + + + + + + Modal Navigation + + + + Open Modal + + + + Modal + + + Close + + + + + + + + + + + + + + + + diff --git a/static/usage/nav/modal-navigation/index.md b/static/usage/nav/modal-navigation/index.md new file mode 100644 index 00000000000..5821f957c0c --- /dev/null +++ b/static/usage/nav/modal-navigation/index.md @@ -0,0 +1,54 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; + +import angular_app_module_ts from './angular/app_module_ts.md'; +import angular_app_component_ts from './angular/app_component_ts.md'; +import angular_app_component_html from './angular/app_component_html.md'; +import angular_page_one_component_ts from './angular/page_one_component_ts.md'; +import angular_page_two_component_ts from './angular/page_two_component_ts.md'; +import angular_page_three_component_ts from './angular/page_three_component_ts.md'; + +import react_main_tsx from './react/main_tsx.md'; +import react_page_one_tsx from './react/page_one_tsx.md'; +import react_page_two_tsx from './react/page_two_tsx.md'; +import react_page_three_tsx from './react/page_three_tsx.md'; + +import vue_example from './vue/example_vue.md'; +import vue_page_one from './vue/page_one_vue.md'; +import vue_page_two from './vue/page_two_vue.md'; +import vue_page_three from './vue/page_three_vue.md'; + + diff --git a/static/usage/nav/modal-navigation/javascript.md b/static/usage/nav/modal-navigation/javascript.md new file mode 100644 index 00000000000..c6e571959a5 --- /dev/null +++ b/static/usage/nav/modal-navigation/javascript.md @@ -0,0 +1,86 @@ +```html + + + + Modal Navigation + + + + Open Modal + + + + Modal + + Close + + + + + + + + + + + +``` diff --git a/static/usage/nav/modal-navigation/react/main_tsx.md b/static/usage/nav/modal-navigation/react/main_tsx.md new file mode 100644 index 00000000000..be4c01e1972 --- /dev/null +++ b/static/usage/nav/modal-navigation/react/main_tsx.md @@ -0,0 +1,60 @@ +```tsx +import React, { useRef } from 'react'; +import { + IonNav, + IonPage, + IonHeader, + IonToolbar, + IonTitle, + IonButton, + IonButtons, + IonContent, + IonModal, +} from '@ionic/react'; + +import PageOne from './page-one'; + +function Example() { + const nav = useRef(null); + const modal = useRef(null); + + const didPresent = () => { + if (nav.current) { + nav.current.setRoot(PageOne, { nav: nav.current }); + } + }; + + const dismiss = () => { + if (modal.current) { + modal.current.dismiss(); + } + }; + + return ( + + + + Modal Navigation + + + + Open Modal + + + + Modal + + Close + + + + + + + + + + ); +} +export default Example; +``` diff --git a/static/usage/nav/modal-navigation/react/page_one_tsx.md b/static/usage/nav/modal-navigation/react/page_one_tsx.md new file mode 100644 index 00000000000..ce5c266e21b --- /dev/null +++ b/static/usage/nav/modal-navigation/react/page_one_tsx.md @@ -0,0 +1,18 @@ +```tsx +import React from 'react'; +import { IonButton, IonContent } from '@ionic/react'; + +import PageTwo from './page-two'; + +function PageOne({ nav }: { nav: HTMLIonNavElement }) { + const navigateToPageTwo = () => nav.push(PageTwo, { nav }); + return ( + +

Page One

+ Go to Page Two + + ); +} + +export default PageOne; +``` diff --git a/static/usage/nav/modal-navigation/react/page_three_tsx.md b/static/usage/nav/modal-navigation/react/page_three_tsx.md new file mode 100644 index 00000000000..3613967edfd --- /dev/null +++ b/static/usage/nav/modal-navigation/react/page_three_tsx.md @@ -0,0 +1,19 @@ +```tsx +import React from 'react'; +import { IonButton, IonContent } from '@ionic/react'; + +function PageThree({ nav }: { nav: HTMLIonNavElement }) { + const navigateBack = () => nav.pop(); + const navigateToRoot = () => nav.popToRoot(); + + return ( + +

Page Three

+ Go Back + Go to Root + + ); +} + +export default PageThree; +``` diff --git a/static/usage/nav/modal-navigation/react/page_two_tsx.md b/static/usage/nav/modal-navigation/react/page_two_tsx.md new file mode 100644 index 00000000000..48562bd23cd --- /dev/null +++ b/static/usage/nav/modal-navigation/react/page_two_tsx.md @@ -0,0 +1,19 @@ +```tsx +import React from 'react'; +import { IonButton, IonContent } from '@ionic/react'; + +import PageThree from './page-three'; + +function PageTwo({ nav }: { nav: HTMLIonNavElement }) { + const navigateToPageThree = () => nav.push(PageThree, { nav }); + + return ( + +

Page Two

+ Go to Page Three + + ); +} + +export default PageTwo; +``` diff --git a/static/usage/nav/modal-navigation/vue/example_vue.md b/static/usage/nav/modal-navigation/vue/example_vue.md new file mode 100644 index 00000000000..018fb3369d2 --- /dev/null +++ b/static/usage/nav/modal-navigation/vue/example_vue.md @@ -0,0 +1,60 @@ +```html + + + +``` diff --git a/static/usage/nav/modal-navigation/vue/page_one_vue.md b/static/usage/nav/modal-navigation/vue/page_one_vue.md new file mode 100644 index 00000000000..94613725139 --- /dev/null +++ b/static/usage/nav/modal-navigation/vue/page_one_vue.md @@ -0,0 +1,24 @@ +```html + + + +``` diff --git a/static/usage/nav/modal-navigation/vue/page_three_vue.md b/static/usage/nav/modal-navigation/vue/page_three_vue.md new file mode 100644 index 00000000000..9dde8817996 --- /dev/null +++ b/static/usage/nav/modal-navigation/vue/page_three_vue.md @@ -0,0 +1,28 @@ +```html + + + +``` diff --git a/static/usage/nav/modal-navigation/vue/page_two_vue.md b/static/usage/nav/modal-navigation/vue/page_two_vue.md new file mode 100644 index 00000000000..737fa71158b --- /dev/null +++ b/static/usage/nav/modal-navigation/vue/page_two_vue.md @@ -0,0 +1,24 @@ +```html + + + +```