docs(react,angular): use ionPage prop for nested outlets and add navigation playgrounds

docs/angular/navigation.md

@@ -201,7 +201,9 @@ To get started with standalone components [visit Angular's official docs](https:
 
 ## Live Example
 
-If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-angular-routing?file=src/app/app-routing.module.ts) of the topics above on StackBlitz.
+import NavigationPlayground from '@site/static/usage/v9/navigation/index.md';
+
+<NavigationPlayground defaultFramework="angular" />
 
 ## Linear Routing versus Non-Linear Routing
 

docs/react/navigation.md

@@ -57,21 +57,19 @@ Inside the Dashboard page, we define more routes related to this specific sectio
 **DashboardPage.tsx**
 
 ```tsx
-const DashboardPage: React.FC = () => {
-  return (
-    <IonPage>
-      <IonRouterOutlet>
-        <Route index element={<UsersListPage />} />
-        <Route path="users/:id" element={<UserDetailPage />} />
-      </IonRouterOutlet>
-    </IonPage>
-  );
-};
+const DashboardPage: React.FC = () => (
+  <IonRouterOutlet ionPage>
+    <Route index element={<UsersListPage />} />
+    <Route path="users/:id" element={<UserDetailPage />} />
+  </IonRouterOutlet>
+);
 ```
 
 Since the parent route already matches `/dashboard/*`, the child routes use **relative paths**. The `index` route matches the parent path (`/dashboard`) and `"users/:id"` resolves to `/dashboard/users/:id`. Absolute paths (e.g., `path="/dashboard/users/:id"`) still work if you prefer explicit full paths.
 
-These routes are grouped in an `IonRouterOutlet`.
+Note the `ionPage` prop on `IonRouterOutlet`. When a component serves as a nested outlet rendered directly by a `Route` in a parent outlet, the inner `IonRouterOutlet` must include the `ionPage` prop. Without it, router outlets can overlap during navigation and cause broken transitions. Wrapping the outlet in an `IonPage` is not needed and should be avoided in this case.
+
+These routes are grouped in an `IonRouterOutlet`, let's discuss that next.
 
 ## Components
 
@@ -92,35 +90,27 @@ We can define a fallback route by placing a `Route` component with a `path` of `
 **DashboardPage.tsx**
 
 ```tsx
-const DashboardPage: React.FC = () => {
-  return (
-    <IonPage>
-      <IonRouterOutlet>
-        <Route index element={<UsersListPage />} />
-        <Route path="users/:id" element={<UserDetailPage />} />
-        <Route path="*" element={<Navigate to="/dashboard" replace />} />
-      </IonRouterOutlet>
-    </IonPage>
-  );
-};
+const DashboardPage: React.FC = () => (
+  <IonRouterOutlet ionPage>
+    <Route index element={<UsersListPage />} />
+    <Route path="users/:id" element={<UserDetailPage />} />
+    <Route path="*" element={<Navigate to="/dashboard" replace />} />
+  </IonRouterOutlet>
+);
 ```
 
 Here, we see that in the event a location does not match the first two `Route`s the `IonRouterOutlet` will redirect the Ionic React app to the `/dashboard` path.
 
 You can alternatively supply a component to render instead of providing a redirect.
 
 ```tsx
-const DashboardPage: React.FC = () => {
-  return (
-    <IonPage>
-      <IonRouterOutlet>
-        <Route index element={<UsersListPage />} />
-        <Route path="users/:id" element={<UserDetailPage />} />
-        <Route path="*" element={<NotFoundPage />} />
-      </IonRouterOutlet>
-    </IonPage>
-  );
-};
+const DashboardPage: React.FC = () => (
+  <IonRouterOutlet ionPage>
+    <Route index element={<UsersListPage />} />
+    <Route path="users/:id" element={<UserDetailPage />} />
+    <Route path="*" element={<NotFoundPage />} />
+  </IonRouterOutlet>
+);
 ```
 
 ### IonPage
@@ -353,12 +343,10 @@ const App: React.FC = () => (
 );
 
 const DashboardRouterOutlet: React.FC = () => (
-  <IonPage>
-    <IonRouterOutlet>
-      <Route index element={<DashboardMainPage />} />
-      <Route path="stats" element={<DashboardStatsPage />} />
-    </IonRouterOutlet>
-  </IonPage>
+  <IonRouterOutlet ionPage>
+    <Route index element={<DashboardMainPage />} />
+    <Route path="stats" element={<DashboardStatsPage />} />
+  </IonRouterOutlet>
 );
 ```
 
@@ -511,7 +499,9 @@ The example below shows how the Spotify app reuses the same album component to s
 
 ## Live Example
 
-If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-react-routing?file=src/index.tsx) of the topics above on StackBlitz.
+import NavigationPlayground from '@site/static/usage/v9/navigation/index.md';
+
+<NavigationPlayground defaultFramework="react" />
 
 ### IonRouterOutlet in a Tabs View
 

src/components/global/Playground/index.tsx

@@ -134,6 +134,7 @@ export default function Playground({
   showConsole,
   includeIonContent = true,
   version,
+  defaultFramework,
 }: {
   code: { [key in UsageTarget]?: MdxContent | UsageTargetOptions };
   title?: string;
@@ -154,6 +155,11 @@ export default function Playground({
    * This will also load assets for StackBlitz from the specified version directory.
    */
   version: string;
+  /**
+   * The framework to select by default when no user preference is stored.
+   * If not specified, defaults to Angular when available, then the first available framework.
+   */
+  defaultFramework?: UsageTarget;
 }) {
   if (!code || Object.keys(code).length === 0) {
     console.warn('No code usage examples provided for this Playground example.');
@@ -207,6 +213,13 @@ export default function Playground({
   };
 
   const getDefaultUsageTarget = () => {
+    /**
+     * If a default framework was specified and code exists for it, use that.
+     */
+    if (defaultFramework && code[defaultFramework] !== undefined) {
+      return defaultFramework;
+    }
+
     /**
      * If there is a saved target from previously clicking the
      * framework buttons, and there is code for it, use that.
@@ -431,10 +444,15 @@ export default function Playground({
 
         /**
          * Load the stored mode and/or usage target, if present
-         * from previously being toggled.
+         * from previously being toggled. Skip the usage target
+         * reset when defaultFramework is set, since the initial
+         * value is already correct and user tab clicks should
+         * be preserved.
          */
         setIonicMode(getDefaultMode());
-        setUsageTarget(getDefaultUsageTarget());
+        if (!defaultFramework) {
+          setUsageTarget(getDefaultUsageTarget());
+        }
 
         /**
          * If the iframes weren't already loaded, load them now.

static/usage/v9/navigation/angular/app_component_html.md

@@ -0,0 +1,5 @@
+```html
+<ion-app>
+  <ion-router-outlet></ion-router-outlet>
+</ion-app>
+```

static/usage/v9/navigation/angular/app_component_ts.md

@@ -0,0 +1,11 @@
+```ts
+import { Component } from '@angular/core';
+import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  imports: [IonApp, IonRouterOutlet],
+})
+export class AppComponent {}
+```

static/usage/v9/navigation/angular/app_routes_ts.md

@@ -0,0 +1,35 @@
+```ts
+import { Routes } from '@angular/router';
+import { ExampleComponent } from './example.component';
+
+export const routes: Routes = [
+  {
+    path: 'example',
+    component: ExampleComponent,
+    children: [
+      {
+        path: 'dashboard',
+        loadComponent: () => import('./dashboard/dashboard-page.component').then((m) => m.DashboardPageComponent),
+      },
+      {
+        path: 'dashboard/:id',
+        loadComponent: () => import('./item-detail/item-detail-page.component').then((m) => m.ItemDetailPageComponent),
+      },
+      {
+        path: 'settings',
+        loadComponent: () => import('./settings/settings-page.component').then((m) => m.SettingsPageComponent),
+      },
+      {
+        path: '',
+        redirectTo: '/example/dashboard',
+        pathMatch: 'full',
+      },
+    ],
+  },
+  {
+    path: '',
+    redirectTo: '/example/dashboard',
+    pathMatch: 'full',
+  },
+];
+```

static/usage/v9/navigation/angular/dashboard_page_component_html.md

@@ -0,0 +1,16 @@
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-title>Dashboard</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content>
+  <ion-list>
+    @for (item of items; track item.id) {
+    <ion-item [routerLink]="['/example/dashboard', item.id]">
+      <ion-label>{{ item.name }}</ion-label>
+    </ion-item>
+    }
+  </ion-list>
+</ion-content>
+```

static/usage/v9/navigation/angular/dashboard_page_component_ts.md

@@ -0,0 +1,27 @@
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  IonContent,
+  IonHeader,
+  IonItem,
+  IonLabel,
+  IonList,
+  IonTitle,
+  IonToolbar,
+  IonRouterLink,
+} from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-dashboard-page',
+  templateUrl: 'dashboard-page.component.html',
+  imports: [IonContent, IonHeader, IonItem, IonLabel, IonList, IonTitle, IonToolbar, IonRouterLink, RouterLink],
+})
+export class DashboardPageComponent {
+  items = [
+    { id: '1', name: 'Item One' },
+    { id: '2', name: 'Item Two' },
+    { id: '3', name: 'Item Three' },
+  ];
+}
+```

static/usage/v9/navigation/angular/example_component_html.md

@@ -0,0 +1,14 @@
+```html
+<ion-tabs>
+  <ion-tab-bar slot="bottom">
+    <ion-tab-button tab="dashboard" href="/example/dashboard">
+      <ion-icon name="grid-outline"></ion-icon>
+      <ion-label>Dashboard</ion-label>
+    </ion-tab-button>
+    <ion-tab-button tab="settings" href="/example/settings">
+      <ion-icon name="settings-outline"></ion-icon>
+      <ion-label>Settings</ion-label>
+    </ion-tab-button>
+  </ion-tab-bar>
+</ion-tabs>
+```

static/usage/v9/navigation/angular/example_component_ts.md

@@ -0,0 +1,17 @@
+```ts
+import { Component } from '@angular/core';
+import { IonIcon, IonLabel, IonTabBar, IonTabButton, IonTabs } from '@ionic/angular/standalone';
+import { addIcons } from 'ionicons';
+import { gridOutline, settingsOutline } from 'ionicons/icons';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+  imports: [IonIcon, IonLabel, IonTabBar, IonTabButton, IonTabs],
+})
+export class ExampleComponent {
+  constructor() {
+    addIcons({ gridOutline, settingsOutline });
+  }
+}
+```

static/usage/v9/navigation/angular/item_detail_page_component_html.md

@@ -0,0 +1,11 @@
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-buttons slot="start">
+      <ion-back-button defaultHref="/example/dashboard"></ion-back-button>
+    </ion-buttons>
+    <ion-title>Item {{ id }}</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">You navigated to item {{ id }}.</ion-content>
+```

static/usage/v9/navigation/angular/item_detail_page_component_ts.md

@@ -0,0 +1,20 @@
+```ts
+import { Component, OnInit } from '@angular/core';
+import { ActivatedRoute } from '@angular/router';
+import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-item-detail-page',
+  templateUrl: 'item-detail-page.component.html',
+  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar],
+})
+export class ItemDetailPageComponent implements OnInit {
+  id = '';
+
+  constructor(private route: ActivatedRoute) {}
+
+  ngOnInit() {
+    this.id = this.route.snapshot.paramMap.get('id') ?? '';
+  }
+}
+```

static/usage/v9/navigation/angular/settings_page_component_html.md

@@ -0,0 +1,8 @@
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-title>Settings</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">Settings content</ion-content>
+```

static/usage/v9/navigation/angular/settings_page_component_ts.md

@@ -0,0 +1,11 @@
+```ts
+import { Component } from '@angular/core';
+import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-settings-page',
+  templateUrl: 'settings-page.component.html',
+  imports: [IonContent, IonHeader, IonTitle, IonToolbar],
+})
+export class SettingsPageComponent {}
+```