docs(nav): component playground examples

docs/api/nav-link.md

@@ -36,6 +36,8 @@ A navigation link is used to navigate to a specified component. The component ca
 
 It is the element form of calling the `push()`, `pop()`, and `setRoot()` methods on the navigation controller.
 
+For an example of how to use `ion-nav-link`, visit the [`ion-nav` docs](./nav#using-navlink).
+
 
 
 

docs/api/nav.md

@@ -1,8 +1,5 @@
 ---
 title: "ion-nav"
-hide_table_of_contents: true
-demoUrl: "/docs/demos/api/nav/index.html"
-demoSourceUrl: "https://github.com/ionic-team/ionic-docs/tree/main/static/demos/api/nav/index.html"
 ---
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -24,19 +21,31 @@ import APITOCInline from '@components/page/api/APITOCInline';
 
 <EncapsulationPill type="shadow" />
 
-<h2 className="table-of-contents__title">Contents</h2>
+Nav is a standalone component for loading arbitrary components and pushing new components on to the stack.
 
-<APITOCInline
-  toc={toc}
-  maxHeadingLevel={2}
-  autogenerated={[Props, Events, Methods, Parts, CustomProps, Slots]}
-/>
+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 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. 
 
-Nav is a standalone component for loading arbitrary components and pushing new components on to the stack.
+import NavLinkExample from '@site/static/usage/nav/nav-link/index.md';
 
-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.
+<NavLinkExample />
+
+## Navigation within a Modal
+
+Modal can use Nav to offer a linear navigation that is independent of the URL.
+
+:::note
+
+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.
+
+:::
+
+import ModalNavigationExample from '@site/static/usage/nav/modal-navigation/index.md';
+
+<ModalNavigationExample />
 
 ## Interfaces
 

static/usage/nav/modal-navigation/angular/app_module_ts.md

@@ -0,0 +1,21 @@
+```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 { ExampleComponent } from './example.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, ExampleComponent, PageOneComponent, PageTwoComponent, PageThreeComponent],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```

static/usage/nav/modal-navigation/angular/example_component_html.md

@@ -0,0 +1,25 @@
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-title>Modal Navigation</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">
+  <ion-button id="openModal">Open Modal</ion-button>
+  <ion-modal #modal trigger="openModal" (willPresent)="onWillPresent()">
+    <ng-template>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>Modal</ion-title>
+          <ion-buttons slot="end">
+            <ion-button (click)="modal.dismiss()"> Close </ion-button>
+          </ion-buttons>
+        </ion-toolbar>
+      </ion-header>
+      <ion-content>
+        <ion-nav #nav></ion-nav>
+      </ion-content>
+    </ng-template>
+  </ion-modal>
+</ion-content>
+```

static/usage/nav/modal-navigation/angular/example_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-example',
+  templateUrl: 'example.component.html',
+})
+export class ExampleComponent {
+  @ViewChild('nav') private nav: IonNav;
+
+  onWillPresent() {
+    this.nav.setRoot(PageOneComponent);
+  }
+}
+```

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: `
+    <ion-content class="ion-padding">
+      <h1>Page One</h1>
+      <ion-button (click)="navigateToPageTwo()">Go to Page Two</ion-button>
+    </ion-content>
+  `,
+})
+export class PageOneComponent {
+  constructor(private nav: IonNav) {}
+
+  navigateToPageTwo() {
+    this.nav.push(PageTwoComponent);
+  }
+}
+```

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: `
+    <ion-content class="ion-padding">
+      <h1>Page Three</h1>
+      <ion-button (click)="navigateBack()">Go Back</ion-button>
+      <ion-button (click)="navigateToRoot()">Go to Root</ion-button>
+    </ion-content>
+  `,
+})
+export class PageThreeComponent {
+  constructor(private nav: IonNav) {}
+
+  navigateBack() {
+    this.nav.pop();
+  }
+
+  navigateToRoot() {
+    this.nav.popToRoot();
+  }
+}
+```

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: `
+    <ion-content class="ion-padding">
+      <h1>Page Two</h1>
+      <ion-button (click)="navigateToPageThree()">Go to Page Three</ion-button>
+    </ion-content>
+  `,
+})
+export class PageTwoComponent {
+  component = PageThreeComponent;
+
+  constructor(private nav: IonNav) {}
+
+  navigateToPageThree() {
+    this.nav.push(PageThreeComponent);
+  }
+}
+```